# Cyrus HTTP (RSS, CalDAV, CardDAV, iSchedule, Timezone Service)

Note that the HTTP service and associated modules in Cyrus are still under development. This release should be considered beta quality.

## Introduction

Cyrus `http` service has the ability to:

- Serve IMAP mailboxes as RSS feeds.
- Act as a calendar and scheduling (CalDAV) server by using IMAP mailboxes as calendar collections and RFC 5322 messages to store iCalendar data.
- Act as a contacts (CardDAV) server by using IMAP mailboxes as addressbook collections and RFC 5322 messages to store vCard data.
- Allow scheduling transactions between separate calendaring and scheduling systems via the iSchedule protocol (currently only used within a Cyrus Murder).
- Act as a Timezone Service by serving iCalendar (VTIMEZONE) data to client systems.
- Serve static content (such as the RSS feed list template and/or the CalDAV/CardDAV JavaScript clients mentioned below).

Unlike the Apache HTTP Server, Cyrus HTTP is NOT a general purpose HTTP server. Its feature set is limited to what is required to support the facilities listed above.

This document assumes that you are familiar with building and configuring a Cyrus server. If you have not already done so, please read and understand the rest of the installation documentation before continuing. Note: The "Installation" section below augments the "Compiling the IMAP Server" document. The remaining sections assume that your Cyrus server has already been successfully configured.

This document also assumes that you are familiar with RSS, WebDAV, calendaring, and contacts.

## Installation

You will need to build Cyrus with the `--enable-http` configure option. This builds httpd and the associated modules and utilities based on the availability of the prerequisites listed below.

### General Requirements

- Must have libxml2 installed.
- Must have a recent SASL release (v2.1.26 or later) in order to support HTTP Digest, Negotiate, and NTLM authentication. Otherwise, only HTTP Basic authentication will be available.

### Additional CalDAV / CardDAV Requirements

- Must have libical installed.
- Must have SQLite v3.x (or later) installed.
- Optionally install Jansson for jCal/jCard support.

### Additional Timezone Service Requirements

- Must have libical installed.
- Must have Jansson installed.

## General Configuration

The Cyrus `httpd` service is configurable via several options in `imapd.conf`. Several of those options are discussed in the sections below. Admins should consult the `imapd.conf(5)` manpage for the full list of options used by the `httpd` service and its various modules.

The support for RSS, CalDAV, and CardDAV is divided into separate modules which run as part of the Cyrus `httpd` service. Selection of which module(s) are enabled is done by setting the `httpmodules` option accordingly. By default, no modules are enabled.

Cyrus `httpd` also can serve static content, the location of which is set by the `httpdocroot` option. Any content contained in the specified directory (including sub-directories) will be served as static content only. Cyrus `httpd` does NOT have the ability to execute any server-side scripts.

### HTTP Authentication

As with other Cyrus services, the Cyrus `httpd` service uses Cyrus SASL to perform its authentication. Cyrus supports the following HTTP authentication schemes: Basic, Digest, Negotiate (Kerberos only), and NTLM. While Basic is available in all versions of SASL, the remaining schemes are only available in Cyrus SASL 2.1.16 (and higher).

Similar to plaintext login commands supported by the other Cyrus services (IMAP LOGIN, POP3 USER/PASS), the Cyrus `httpd` service determines whether to advertise the HTTP Basic authentication scheme based on the `allowplaintext` option and whether the client has connected over a TLS protected connection (HTTPS).

The availability of the other HTTP authentication schemes is controlled by the `sasl_mech_list` option. For Cyrus `httpd` the `DIGEST-MD5`, `GSS-SPNEGO`, and `NTLM` SASL plugins support the Digest, Negotiate, and NTLM authentication schemes respectively, provided that these plugins are installed on the server.

## RSS Module

### Configuration

When enabled, the RSS module will default to serving ALL mailboxes to which the authenticated user has access as RSS feeds. The `rss_feeds` option can be used to limit the set of mailboxes that can be served as RSS feeds. For example, setting `rss_feeds` to `*,!user` will serve all shared mailboxes, but no personal mailboxes.

The list of available RSS feeds can be obtained by clients by accessing the `/rss/` URL on the Cyrus server. By default, the server will present the list as a simple unordered list in an HTML document. To customize the look and feel of the feed list, the `rss_feedlist_template` option can be used to point to a HTML template file. This file can utilize Cascading Style Sheets, JavaScript, etc. Any and all content that the template file references MUST reside under the `httpdocroot` as set above. Consult the `imapd.conf(5)` manpage for specifics on the required contents of this custom file. Note that for sites running Cyrus Murder, `rss_feedlist_template` only needs to be set on frontend servers, since only those servers have the complete mailbox list.

## CalDAV Module

### Configuration

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`.

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 be returned by Cyrus `imapd` in response to an IMAP client's request for the available mailbox list, but Cyrus `imapd` will not otherwise prevent an IMAP client from accessing them.

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

#### Calendar provisioning

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.

#### Calendar access controls

The CalDAV module uses the same access controls as the other Cyrus services. The `cyradm(1)` 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 right | WebDAV privilege | HTTP methods
--- | --- | ---
l - lookup | DAV:read (aggregates DAV:read-current-user-privilege-set, CALDAV:read-free-busy) | GET/HEAD, PROPFIND, REPORT, COPY/MOVE (on target)
r - read
s - seen |
w - write | DAV:write-properties | PROPPATCH, COPY/MOVE (on target)
i - insert | DAV:write-content | PUT, LOCK, COPY/MOVE (on target)
p - post | CYRUS:add-resource (aggregated under DAV:bind) | POST
k - create mailbox | CYRUS:make-collection (aggregated under DAV:bind) | MKCOL, MKCALENDAR
x - delete mailbox | CYRUS:remove-collection (aggregated under DAV:unbind) | DELETE
t - delete message | CYRUS:remove-resource (aggregated under DAV:unbind) | DELETE, MOVE (on source)
e - expunge |
a - admin | CYRUS:admin (aggregates DAV:read-acl, DAV:write-acl, DAV:unlock) | ACL, UNLOCK, PROPFIND (DAV:acl only)
9 - free/busy | CALDAV:read-free-busy (regular calendar collection only) | REPORT (CALDAV:free-busy-query only) |
CALDAV:schedule-query-freebusy (Scheduling Inbox only) |
CALDAV:schedule-send-freebusy (Scheduling Outbox only)
8 - invite | CALDAV:schedule-deliver-invite (Scheduling Inbox only)
CALDAV:schedule-send-invite (Scheduling Outbox only)
7 - reply | CALDAV:schedule-deliver-reply (Scheduling Inbox only)
CALDAV:schedule-send-reply (Scheduling Outbox only)

Default WebDAV Privileges by Collection
Collection | ACL
--- | ---
Regular Calendar | owner - DAV:all + CALDAV:read-free-busy (lrwipkxta9) anyone - CALDAV:read-free-busy (9)
Scheduling Inbox | owner - DAV:all + CALDAV:schedule-deliver (lrwipkxta789) anyone - CALDAV:schedule-deliver (789)
Scheduling Outbox | owner - DAV:all + CALDAV:schedule-send (lrwipkxta789)

### Client Setup

#### Mozilla Lightning

For each calendar that you would like to add to this client, perform the following steps:

1. Select the "File -> New -> Calendar..." menu option.
2. Select the "On the Network" option and click Continue.
3. Select "CalDAV" as the Format.
4. Enter a URL of the following form as the Location: `https://<servername>/dav/calendars/user/<userid>/<calendar>/`

Cyrus will auto-provision a calendar with name "Default" which can be used in the URL above.

#### Apple iCal

This client will autodetect all available calendars on a server. To add a Cyrus server to this client, perform the following steps:

1. Select the "Calendar -> Preferences" menu option.
2. Select the "Accounts" tab.
3. Click the "+" button.
4. Select "CalDAV" as the Account Type.
5. Fill in User Name, Password, and Server Address accordingly.
6. Click Create.

#### Apple iOS Calendar

This client will autodetect all available calendars on a server. To add a Cyrus server to this client, perform the following steps:

1. Run the "Settings" app.
2. Select the "Mail, Contacts, Calendars" menu.
3. Select the "Add Account..." menu.
4. Select the "Other" menu.
5. Select the "Add CalDAV Account" menu.
6. Fill in Server, User Name, Password, and Description accordingly.
7. Click Next.

#### Evolution

This client will autodetect all available calendars on a server. For each calendar that you would like to add to this client, perform the following steps:

1. Select the "New -> Calendar" menu option.
2. Select "CalDAV" as the Type.
3. Fill in Server and User accordingly.
4. Click "Find Calendars".
5. Select the desired calendar from the list.
6. Click "Apply".
7. Click "OK".

#### aCal

This client will autodetect all available calendars on a server. To add a Cyrus server to this client, perform the following steps:

1. Press the Andoid "Menu" button.
2. Select "Settings".
3. Select "Servers".
4. Select "Add Server".
5. Select "Manual Configuration".
6. Fill in Username, Password, and User URL (servername) accordingly.
7. Press "Apply".

#### CalDavZAP

This client will autodetect all available calendars on a server. To configure this client for a Cyrus server, edit `config.js` as follows:

1. Set the `href` value in the `globalNetworkCheckSettings` array to a URL of the following form: `https://<servername>/dav/principals/user/`
   Note that the trailing "/" is REQUIRED.
2. Set the `globalSettingsType` option to `calendar-home-set`
3. Set any other options as desired (e.g. `globalDatepickerFirstDayOfWeek`, `globalTimeZone`).

## CardDAV Module

### Configuration

When enabled, the CardDAV module allows Cyrus to function as a contacts server. This module uses a subset of the mailbox hierarchy as addressbook collections, the toplevel of which is specified by the `addressbookprefix` option. The public addressbook hierarchy will reside at the toplevel of the shared mailbox namespace. A user's personal addressbook hierarchy will be a child of their Inbox. For example, using the default value for `addressbookprefix`, an addressbook named `Default` for user `murch` would reside in the mailbox named `user.murch.#addressbooks.Default`.

Note that mailboxes in the addressbook hierarchies (those under `addressbookprefix`) SHOULD NOT be accessed with an IMAP client as doing so will leave a mailbox in a state unsuitable for CardDAV. To this end, addressbook mailboxes will not returned by Cyrus `imapd` in response to an IMAP client's request for the available mailbox list, but Cyrus `imapd` will not otherwise prevent an IMAP client from accessing them.

### Administration

#### Addressbook provisioning

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

#### Addressbook access controls

Cyrus uses the same access controls for addressbooks as it does for calendars, except that the scheduling rights (7, 8, 9) have no use with addressbooks and are ignored.

### Client Setup

#### Apple Contacts

This client will autodetect all available addressbooks on a server. To add a Cyrus server to this client, perform the following steps:

1. Select the "Contacts -> Preferences" menu option.
2. Select the "Accounts" tab.
3. Click the "+" button.
4. Select "CardDAV" as the Account Type.
5. Fill in User Name, Password, and Server Address accordingly.
6. Click Create.

#### Apple iOS Contacts

This client will autodetect all available addressbooks on a server. To add a Cyrus server to this client, perform the following steps:

1. Run the "Settings" app.
2. Select the "Mail, Contacts, Calendars" menu.
3. Select the "Add Account..." menu.
4. Select the "Other" menu.
5. Select the "Add CardDAV Account" menu.
6. Fill in Server, User Name, Password, and Description accordingly.
7. Click Next.

#### CardDavMATE

This client will autodetect all available addressbooks on a server. To configure this client for a Cyrus server, edit `config.js` as follows:

1. Set the `href` value in the `globalNetworkCheckSettings` array to a URL of the following form: `https://<servername>/dav/principals/user/`
   Note that the trailing "/" is REQUIRED.
2. Set the `globalSettingsType` option to `addressbook-home-set`
3. Set any other options as desired.

## Timezone Service Module

### Configuration

When enabled, the Timezone module allows Cyrus to function as a timezone service, providing timezone data to client systems. This module stores timezone data in the `zoneinfo/` subdirectory of the Cyrus configuration directory (as specified by the `configdir` option). 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

This module is designed to use the Time Zone Database data (a.k.a. Olson Database) converted to the iCalendar format. The steps to populate the Cyrus `zoneinfo/` directory are as follows:

0. Build the `vzic` utility located in the `tools/vzic/` subdirectory of the Cyrus source code. Simply running `make` in the `tools/vzic/` subdirectory should suffice.
1. Download the latest version of the Time Zone Database data from IANA. Only the data is required, NOT the code.
2. Expand the downloaded timezone data into the temporary directory of your choice.
3. Populate `configdir/zoneinfo/` 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 <configdir>/zoneinfo`

      This will create and install iCalendar data directly into the `configdir/zoneinfo/` 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 (preferably `tools/vzic/`).

   2. Merge new/updated iCalendar data into the `configdir/zoneinfo/` directory by running `vzic-merge.pl` in your current location:

      `vzic-merge.pl`

4. Rebuild the Cyrus zoneinfo index by running `ctl_zoneinfo` as follows:

   `ctl_zoneinfo -r <version-string>`

   where `<version-string>` describes the recently downloaded timezone data (e.g. "Time Zone Database v.2013h").

5. Verify that the zoneinfo index database and all iCalendar data files/links are readable by the `cyrus` user.

## iSchedule Module

This module will be automatically enabled if and only if both the CalDAV module and the `caldav_allowscheduling` options are enabled in a Cyrus Murder.

Support for scheduling with external servers is currently under development and will require a future release of OpenDKIM.

## DomainKey Module

Currently unavailable. Will be available once iSchedule support to external servers is available.