NAME

icald - iCal to WCAP calendar publish and subscribe gateway

SYNOPSIS

icald [-d] [-r authentication realm] [-a listen address] [-p listen port] [-s calendar server address] [-u user to run as] [-e SSL port]

DESCRIPTION

icald is a simple HTTP server that implements the basic components needed to subscribe to and publish calendars with any of the Sun calendar servers that implement the WCAP protocol (including iPlanet, Sun ONE, and Sun Java). Other servers that implement WCAP may work but have not been tested.

-a listen address

The address on which to listen. Default is empty, indicating that the server will listen on all addresses on the host.

-d

Turn on debugging mode. Server will not fork and will write some debugging information to /tmp/ical.log.

-e SSL port

Specifies the port number that an SSL tunnel for the icald daemon listens on. If, for example, stunnel or Apache is configured to proxy SSL to icald and a request for a loginssl URL is found, a 301 redirect is sent back to iCal on non-SSL requests. This allows iCal to use SSL transport, even though https URLs are not supported in iCal.

-p listen port

The TCP port to bind to. The default is 7080.

-r authentication realm

The realm used in HTTP Basic auth. The default is icald wcap gateway.

-s calendar server address

The name or IP address of the WCAP-capable calendar server. The server is assumed to be listening for HTTP on port 80 and URLs within icald are constructed as such:

    http://CALENDAR-SERVER/command.wcap...

-u user to run as

When started as root, the server will change its UID and GID to that of the user specified after it has bound to the port (in case a port less than 1024 is specified). The default is to run as the user invoking the program.

URI SCHEMA

icald maps subscribe and publish requests to calendar server calendars using the URI of the request. The following mappings are used.

/CALENDAR: If the URI includes only CALENDAR, then that is taken as the calendar name and anonymous access is attempted to the calendar server. If the calendar server response indicates that read access is not allowed for anonymous users, Basic authentication will be attempted. This method aldo works in the case of users' default calendars, where the calendar name is the same as the user name.
/USERNAME/CALENDAR: If the URI includes one intermdiate slash, the first part is taken as the username of the calendar to view and the second part is taken as the calendar name. As with the previous method, if read access is not permitted, access is attempted again after Basic authentication.
/login/CALENDAR
/login/USERNAME/CALENDAR: In the case where one would like to force authentication for subscribing to a calendar, login can be specified as the first path component of the URI. This will force Basic authentication even if anonymous users have read access to the calendar. This is useful in the case where anonymous users may not see as much detail in event information as certain authenticated users.; In all other respects, these two methods work as the first two.
/loginssl/CALENDAR
/loginssl/USERNAME/CALENDAR: These are identical to the login URLs, except that if they are found in a non-https connection, a 301 redirect is sent back to iCal. The redirect specifies an SSL connection on an alternate port (defaulting to 7443). This gets around an apparent bug in iCal that makes it unable to handle https URLs in subscribing to calendars. If the subscription address redirects through https, however, iCal has no problems.

Publish

All calendar publish requests require authentication, so there is no concept of an anonymous user. The user to publish as is taken from the HTTP Basic authentication information.

In Apple iCal, the calendar is published using a name specified by the user. The URI that is sent to the server includes this name with .ics appended as the final part of the URI. The following mappings are what is seen within icald.

/CALENDAR

When only a calendar name is specified by the user, it is taken as the calendar name on the WCAP server. This also works in the case where the calendar name is the same as the user name. In iCal, one would specify this as

    Publish name:  CALENDAR or USERNAME
    Base URL:      http://server:port/

/USERNAME/CALENDAR

When there are two path components of the URI, the first is taken as the user name for the calendar and the second is taken as the calendar name. The user name may be different than that used in authentication. In iCal, one would specify this as

    Publish name:  CALENDAR
    Base URL:      http://server:port/USERNAME/

/USERNAME/USERNAME

If both path components are the same, they are taken as the default calendar of a user that may be different from that used for authentication. As an example for iCal, one would specify

    Publish name:  USERNAME
    Base URL:      http://server:port/USERNAME/
    Login:         OTHERUSER

It is of course possible to make USERNAME and OTHERUSER identical, in which case this method is no different from the first when the user is specifying their own default calendar.

BUGS & LIMITATIONS

The only interface for Sun ONE Calendar that utilizies the full features of the product is the Sun ONE Calendar Express web interface. All other interfaces, including this one, present limitations. In particular, the following limitations are known:

Publish Mode

When using icald to publish calendars, there is no concept of multiple owners of a calendar. That is to say, Sun ONE will happily allow multiple people to publish to the same calendar, but it will make no attempt to synchronize differences among the calendars it receives. If one person publishes a set of events to a calendar and another person publishes a different set of events to the same calendar, the first set will be lost. It is up to the multiple calendar owners to manually synchronize events, either by hand or by a multi-step subscribe, copy, publish process.

In addition, other features that pertain to the calendar's originating system are not transferred -- in particular this includes alarms. It only makes sense for one system to control alarms, and whn the originator of the calendar is iCal, it will retain this control and strip alarm tags from the published calendar.

Other group interaction features available within Sun calendars (including invitations and event privacy options) are not present in iCal and thus cannot be published through icald. If you have need of these features, the Sun ONE Calendar Express web interface is the only interface that supports them. Be aware than any changes made through the web interface to a calendar published via icald will be lost the next time the calendar is published.

Subscribe Mode

Subscribed calendars in iCal are read-only; you can not make changes to the events or add new ones. To Do items will be transferred (if so checked on the iCal subscription preferences), however e-mail reminders are not transferred, as they would have no place outside of the server environment (while VALARM tags within the export file are passed to iCal, iCal will strip these from the calendar).

Other

icald is essentially just a gateway between iCal or something that uses that protocol and the Sun family of WCAP-capabale calendar servers. No attempt is made to translate the calendar data passed between the two, only to present it to each side in a form they understand. Any problems in how the data is interpreted by either side are the responsibility of the end programs.

COPYRIGHT

Redistribution of this script, either in source or any compiled binary format, with or without modificiation, is permitted provided the following conditions are met:

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THIS SOFTWARE IS PROVIDED WITHOUT ANY OBLIGATION ON THE PART OF THE AUTHOR TO ASSIST IN ITS USE, CORRECTION, MODIFICATION, OR ENHANCEMENT.

TRADEMARKS

iCal is a registered trademark of Apple Computer, Inc.

Sun ONE, Sun Java, and iPlanet are registered trademarks of Sun Microsystems, Inc.

AUTHOR

John ``Rowan'' Littell - littejo at earlham dot edu