CalDAV

Configuration

calendarprefix

This shows the default value: change it in imapd.conf to suit your needs.

calendarprefix: #calendars

The prefix for the calendar mailboxes hierarchies. The hierarchy delimiter will be automatically appended. The public calendar hierarchy will be at the toplevel of the shared namespace. A user’s personal calendar hierarchy will be a child of their Inbox.

When enabled, the CalDAV module allows Cyrus to function as a calendar and scheduling server. This module uses a subset of the mailbox hierarchy as calendar collections, the toplevel of which is specified by the calendarprefix option. The public calendar hierarchy will reside at the toplevel of the shared mailbox namespace. A user’s personal calendar hierarchy will be a child of their Inbox.

For example, using the default value for calendarprefix, a calendar named Default for user “murch” would reside in the mailbox named user.murch.#calendars.Default.

Warning

Note that mailboxes in the calendar hierarchies (those under calendarprefix) should not be accessed with an IMAP client as doing so will leave a mailbox in a state unsuitable for CalDAV. To this end, calendar mailboxes will not returned by Cyrus imapd in response to an IMAP client’s request for the available calendar list, but Cyrus imapd can not otherwise prevent an IMAP client from accessing them.

caldav_allowscheduling

This shows the default value: change it in imapd.conf to suit your needs.

caldav_allowscheduling: on

Enable calendar scheduling operations. If set to “apple”, the server will emulate Apple CalendarServer behavior as closely as possible. Allowed values: off, on, apple

By default, the CalDAV module will automatically perform scheduling operations when a scheduling object (invite or reply) is stored on or deleted from the server. Support for the calendar-auto-schedule feature can be disabled with the caldav_allowscheduling option.

Administration

The CalDAV module will automatically create the required calendars for a user the first time that the user authenticates to the CalDAV server. Note that the user MUST have an existing IMAP Inbox in order for the calendars to be created.

autocreate options

This shows the default value: change it in imapd.conf to suit your needs.

caldav_create_default: 1

Create the ‘Default’ calendar if it doesn’t already exist

caldav_create_attach: 1

Create the ‘Attachments’ collection if it doesn’t already exist

caldav_create_sched: 1

Create the ‘Inbox’ and ‘Outbox’ calendars if they don’t already exist

Autocreate of the various calendars can be disabled with the “caldav_create_default/sched/attach” options, if you have an alternate mechanism to create calendars.

There is also a Cyrus web GUI for managing calendar resources. It allows you to:

  • Create new collections, with whichever components are required

  • Alter existing collections with different components

  • Subscribe or download existing collections via prepared URLs

  • Set visibility attributes such as Public or Transparent

  • Delete existing collections

The Cyrus web GUI for CalDAV Collection Management is disabled by default, but can be enabled with the “caldav_allowcalendaradmin” option.

caldav_allowcalendaradmin

This shows the default value: change it in imapd.conf to suit your needs.

caldav_allowcalendaradmin: 0

Enable per-user calendar administration web UI on the CalDAV server.

To access the Cyrus web GUI for CalDAV Collection Management, point a web browser at https://<servername>/dav/calendars/user/<username>

Calendar access controls

The CalDAV module uses the same access controls as the other Cyrus services. The cyradm(8) tool can be used to adjust ACLs on calendars as needed. The tables below show how the access controls are used by the CalDAV module.

Mapping of IMAP Rights to WebDAV Privileges & HTTP Methods
IMAP rights WebDAV privileges HTTP methods
l - lookup
r - read		 DAV:read DAV:read-current-user-privilege-set
CALDAV:read-free-busy		 GET/HEAD
COPY/MOVE (on source)
PROPFIND
REPORT
s - seen
w - write
n - write shared annotation		 DAV:write-properties PROPPATCH
COPY/MOVE (on destination)
i - insert DAV:write-content PUT
PATCH
COPY/MOVE (on destination resource)
LOCK
UNLOCK (lock owner ONLY)
p - post DAV:bind CYRUS:add-resource POST
k - create mailbox CYRUS:make-collection MKCOL
MKCALENDAR
COPY/MOVE (on destination collection)
x - delete mailbox DAV:unbind CYRUS:remove-collection DELETE (collection)
MOVE (on source collection)
t - delete message
e - expunge		 CYRUS:remove-resource DELETE (resource)
MOVE (on source resource)
a - admin CYRUS:admin DAV:read-acl
DAV:write-acl
DAV:share
DAV:unlock		 ACL
PROPFIND (DAV:acl property ONLY)
UNLOCK (ANY lock)
Regular Calendar Collections ONLY — read freebusy time?
9 - freebusy CALDAV:read-free-busy REPORT (CALDAV:free-busy-query ONLY)
GET/HEAD (Freebusy URLs ONLY)
Scheduling Outbox ONLY — implicitly create/send iTIP message?
9 - freebusy CALDAV:schedule-send CALDAV:schedule-send-freebusy POST
(by organizer on scheduling Outbox)
8 - invite CALDAV:schedule-send-invite PUT/PATCH/DELETE
(by organizer on calendar resource/collection)
7 - reply CALDAV:schedule-send-reply PUT/PATCH/DELETE
(by attendee on calendar resource/collection)
Scheduling Inbox ONLY — implicitly deliver/process incoming iTIP message?
9 - freebusy CALDAV:schedule-deliver CALDAV:schedule-query-freebusy
8 - invite CALDAV:schedule-deliver-invite
7 - reply CALDAV:schedule-deliver-reply


Default WebDAV Privileges by Collection
Collection User ID WebDAV Privileges IMAP rights
Regular Calendar Collection owner DAV:all + CALDAV:read-free-busy lrwipkxtan9
anyone CALDAV:read-free-busy 9
Managed Attachments Collection owner DAV:all lrwipkxtan
anyone DAV:read lr
Scheduling Inbox owner DAV:all + CALDAV:schedule-deliver lrwipkxtan789
anyone CALDAV:schedule-deliver 789
Scheduling Outbox owner DAV:all + CALDAV:schedule-send lrwipkxtan789

Freebusy URL

When enabled in conjunction with the CalDAV module, the Freebusy URL module allows non-CalDAV and/or remote calendaring clients to query the freebusy information of Cyrus CalDAV users.

Access to the freebusy information is controlled by the “freebusy” ACL (9) on a user’s home calendar collection. (e.g. a mailbox named user.murch.#calendars). To enable unauthenticated users (non-Cyrus) to access freebusy information, the freebusy ACL must be given to “anyone”.

Freebusy information, consolidating the data of all user’s calendars, is accessed via URLs of the following form: https://<servername>/freebusy/user/<userid>. Querying individual CalDAV collections, when they have explicitly “freebusy” ACL (9) set, is done via https://<servername>/freebusy/user/<userid>/<collection>.

Query parameters can be added to the URL per Section 4 of Freebusy Read URL, allowing the user to choose to set the start, end, period and format of their query results.

Time Zone Distribution Service (TZDist)

What is TZDist

The TZDist module allows Cyrus to function as a Time Zone Distribution Service (RFC 7808 and RFC 7809), providing time zone data for CalDAV and calendaring clients, without having to wait for their client vendor and/or OS vendor to update the timezone information. The responsibility for keeping the time zone information up to date then falls upon the Cyrus administrator.

TZDist is optional: without Cyrus having TZDist enabled, calendar clients should still be able to get their timezone information from their client or their OS.

TZDist strips known VTIMEZONEs from incoming iCalendar data (as advertised by the calendar-no-timezone DAV option from RFC 7809).

Configuration

zoneinfo config

This shows the default value: change it in imapd.conf to suit your needs.

zoneinfo_db_path: <none>

The absolute path to the zoneinfo db file. If not specified, will be configdirectory/zoneinfo.db


zoneinfo_db: twoskip

The cyrusdb backend to use for zoneinfo. This database is used by the “tzdist” httpmodules, and is managed by ctl_zoneinfo(8). Allowed values: flat, skiplist, twoskip, zeroskip


zoneinfo_dir: <none>

The absolute path to the zoneinfo directory, containing timezone definitions as generated by the vzic tool. If not specified, whatever definitions libical finds will be used.

If you are providing a Time Zone Data Distribution Service (i.e. you have “tzdist” listed in httpmodules), then this configuration option MUST be specified.

The TZDist module requires the zoneinfo_dir setting in imapd.conf(5) to be set to the directory where your time zone data is stored.

The data is indexed by a database whose location is specified by the zoneinfo_db_path option, using the format specified by the zoneinfo_db option.

Administration

The TZDist module is designed to use the IANA Time Zone Database data (a.k.a. Olson Database) converted to the iCalendar format.

vzic does convert the IANA TZ DB to iCalendar format. For each time zone it creates a separate file with its own TZID property. The TZID property can have a vendor prefix, that is fixed when compiling vzic by the TZID_PREFIX Makefile variable, which defaults to /citadel.org/%D_1/. Cyrus IMAP requires that the vendor prefix is the empty string.

The cyrus-timezones package provides a vzic, which sets TZID_PREFIX to the emtpy string.

The steps to populate the zoneinfo_dir directory are:

  1. Acquire and build your choice of vzic tool.

  2. Download the latest version of the Time Zone Database data from IANA. Note you only need the data, not the code.

  3. Expand the downloaded time zone data into a temporary directory of your choice.

  4. Copy leap-seconds.list from the temporary directory to <zoneinfo_dir>.

  5. Populate zoneinfo_dir with iCalendar data:

    Initial Install Only

    1. Convert the raw data into iCalendar format by running vzic as follows: vzic --pure --olson-dir <location-of-raw-data> --output-dir <zoneinfo_dir>

      This will create and install iCalendar data directly into the <zoneinfo_dir> directory.

    Updating Data Only

    1. Convert the raw data into iCalendar format by running vzic as follows: vzic --pure --olson-dir <location-of-raw-data>

      This will create a zoneinfo/ subdirectory in your current location

    2. Merge new/updated iCalendar data into the <zoneinfo_dir> directory by running vzic-merge.pl in your current location: vzic-merge.pl

  6. Rebuild the Cyrus zoneinfo index by running ctl_zoneinfo(8) as follows: ctl_zoneinfo -r <version-string>

    where <version-string> contains description of the recently downloaded time zone data, colon, and the version of the data (e.g. “IANA Time Zone Database:2020a”).

  7. Check that the zoneinfo index database and all iCalendar data files/links are readable by the cyrus user.

iSchedule

About iSchedule

Note

iSchedule support in Cyrus is a work in progress.

iSchedule allows CalDAV servers to:

  • query an event participant’s free/busy status prior to invitation in order to set up a good meeting time, which cannot be done over email.

  • keep participant’s local event current by updating the status of other participants automatically. This is not done when scheduling over email as it would result in too much mail traffic and extra manual overhead for the users.

caldav_allowscheduling

This shows the default value: change it in imapd.conf to suit your needs.

caldav_allowscheduling: on

Enable calendar scheduling operations. If set to “apple”, the server will emulate Apple CalendarServer behavior as closely as possible. Allowed values: off, on, apple

iSchedule is automatically enabled in Cyrus if both the CalDAV module and the caldav_allowscheduling options are enabled in a Cyrus Murder. In this instance, Cyrus uses iSchedule to move scheduling messages from frontend to backend servers.

Support for scheduling with external servers is currently under development as there is the burden of authorization to verify the authenticity and integrity of these messages to prevent inadvertent or malicious data leaks or corruption.

What mechanism to use for authorization is under discussion with the CalConnect standards body, whether this is DKIM or some other type of message signature.