<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
<title>Cyrus HTTP</title>
</head>
<body>
<h1>Cyrus HTTP (<a href="#RSS">RSS</a>, <a href="#CalDAV">CalDAV</a>,
<a href="#CardDAV">CardDAV</a>, <a href="#iSchedule">iSchedule</a>,
<a href="#TimeZone">TimeZone</a>)</h1>
<b><i>Note that the HTTP service and associated modules in Cyrus are
still under development. This release should be considered beta
quality.</i></b>
<h2 id="Intro">Introduction</h2>
<p>Cyrus <tt>http</tt> service has the ability to:</p>
<ul>
<li>Serve IMAP mailboxes as RSS feeds.</li>
<li>Act as a calendar and scheduling (CalDAV) server by using IMAP
mailboxes as calendar collections and RFC 5322 messages to store
iCalendar data.</li>
<li>Act as a contacts (CardDAV) server by using IMAP mailboxes as
addressbook collections and RFC 5322 messages to store vCard
data.</li>
<li>Allow scheduling transactions between separate calendaring and
scheduling systems via the iSchedule protocol <i>(currently only used
within a Cyrus Murder)</i>.</li>
<li>Act as a Time Zone Distribution Service by serving iCalendar (VTIMEZONE)
data to client systems.</li>
<li>Serve static content (such as the RSS feed list template and/or
the CalDAV/CardDAV JavaScript clients mentioned below).</li>
</ul>
<i>Unlike the <a href="http://httpd.apache.org/">Apache HTTP
Server</a>, Cyrus HTTP is NOT a general purpose HTTP server. Its
feature set is limited to what is required to support the
facilities listed above.</i>
<p>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 <a href="install.html">installation</a>
documentation before continuing. Note: The
"<a href="#Install">Installation</a>" section below augments the
"<a href="install-compile.html">Compiling the IMAP Server</a>"
document. The remaining sections assume that your Cyrus server has
already been
successfully <a href="install-configure.html">configured</a>.</p>
<p>This document also assumes that you are familiar with RSS, WebDAV,
calendaring, and contacts.</p>
<h2 id="Install">Installation</h2>
<p>You will need to build Cyrus with
the <tt>--enable-http</tt> configure option. This builds httpd
and the associated modules and utilities based on the availability
of the prerequisites listed below.</p>
<h3>General Requirements</h3>
<ul>
<li>Must have <a href="http://xmlsoft.org/">LibXML2</a>
installed.</li>
<li>Must have a recent <a href="http://www.cyrusimap.org/">SASL</a>
release (v2.1.26 or later) in order to support HTTP Digest,
Negotiate, and NTLM authentication. Otherwise, only HTTP Basic
authentication will be available.</li>
<li>Optionally install <a href="http://www.openssl.org/">OpenSSL</a>
for HTTPS support.</li>
<li>Optionally install <a href="http://www.zlib.net/">Zlib</a> for
compression support.</li>
</ul>
<h3>Additional CalDAV / CardDAV Requirements</h3>
<ul>
<li>Must
have <a href="http://libical.github.io/libical/">Libical</a>
installed.</li>
<li>Must have <a href="http://www.sqlite.org/">SQLite</a> v3.x (or
later) installed.</li>
<li>Optionally
install <a href="http://www.digip.org/jansson/">Jansson</a> for
jCal/jCard support.</li>
<li>Optionally
install <a href="http://site.icu-project.org/">ICU4C</a> for
non-Gregorian calendar support,
if <a href="http://libical.github.io/libical/">Libical</a> has
support for the RSCALE extension.</li>
</ul>
<h3>Additional iSchedule Requirements</h3>
<ul>
<li>Must meet CalDAV requirements above.</li>
<li>Must
have <a href="http://www.opendkim.org/">OpenDKIM</a> with support
for iSchedule canonicalization installed (currently requires a
<a href="http://git.cyrusimap.org/cyrus-imapd/plain/contrib/dkim_canon_ischedule.patch?h=caldav-2.4"/>
CMU patch</a>).</li>
</ul>
<h3>Additional Time Zone Distribution Service Requirements</h3>
<ul>
<li>Must
have <a href="http://libical.github.io/libical/">Libical</a>
installed.</li>
<li>Must have <a href="http://www.digip.org/jansson/">Jansson</a>
installed.</li>
</ul>
<h2 id="config">General Configuration</h2>
<p>The Cyrus <tt>httpd</tt> service is configurable via several
options in <tt>imapd.conf</tt>. Several of those options are
discussed in the sections below. Admins should consult
the <tt>imapd.conf(5)</tt> manpage for the full list of options used
by the <tt>httpd</tt> service and its various modules.<p>
<p>The support for RSS, CalDAV, and CardDAV is divided into separate
modules which run as part of the Cyrus <tt>httpd</tt>
service. Selection of which module(s) are enabled is
done by setting the <tt>httpmodules</tt> option accordingly. By
default, no modules are enabled.</p>
<p>Cyrus <tt>httpd</tt> also can serve <i>static</i> content, the
location of which is set by the <tt>httpdocroot</tt> option. Any
content contained in the specified directory (including
sub-directories) will be served as static content only.
Cyrus <tt>httpd</tt> does NOT have the ability to execute any
server-side scripts.</p>
<h3>HTTP Authentication</h3>
<p>As with other Cyrus services, the Cyrus <tt>httpd</tt> 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).</p>
<p>Similar to plaintext login commands supported by the other Cyrus
services (IMAP LOGIN, POP3 USER/PASS), the Cyrus <tt>httpd</tt>
service determines whether to advertise the HTTP Basic
authentication scheme based on the <tt>allowplaintext</tt> option
and whether the client has connected over a TLS protected connection
(HTTPS).</p>
<p>The availability of the other HTTP authentication schemes is
controlled by the <tt>sasl_mech_list</tt> option. For
Cyrus <tt>httpd</tt> the <tt>DIGEST-MD5</tt>, <tt>GSS-SPNEGO</tt>,
and <tt>NTLM</tt> SASL plugins support the Digest, Negotiate,
and NTLM authentication schemes respectively, provided that these
plugins are installed on the server.</p>
<h2 id="RSS">RSS Module</h2>
<h3>Configuration</h3>
<p>When enabled, the RSS module will default to serving ALL mailboxes
to which the authenticated user has access as RSS feeds.
The <tt>rss_feeds</tt> option can be used to limit the set of
mailboxes that can be served as RSS feeds. For example,
setting <tt>rss_feeds</tt> to <tt>*,!user</tt> will serve all shared
mailboxes, but no personal mailboxes.</p>
<p>The list of available RSS feeds can be obtained by clients by
accessing the <tt>/rss/</tt> 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 <tt>rss_feedlist_template</tt> 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 <tt>httpdocroot</tt> as set above.
Consult the <tt>imapd.conf(5)</tt> manpage for specifics on the
required contents of this custom file. Note that for sites
running Cyrus Murder, <tt>rss_feedlist_template</tt> only needs to
be set on frontend servers, since only those servers have the
complete mailbox list.</p>
<h2 id="CalDAV">CalDAV Module</h2>
<h3>Configuration</h3>
<p>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 <tt>calendarprefix</tt> 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 <tt>calendarprefix</tt>, a calendar named <tt>Default</tt> for
user <tt>murch</tt> would reside in the mailbox
named <tt>user.murch.#calendars.Default</tt>.<p>
<p><i>Note that mailboxes in the calendar hierarchies (those
under <tt>calendarprefix</tt>) <b>SHOULD NOT</b> 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 <tt>imapd</tt> in response to an IMAP client's request for the
available mailbox list, but Cyrus <tt>imapd</tt> will not otherwise
prevent an IMAP client from accessing them.</i></p>
<p>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 <tt>caldav_allowscheduling</tt>
option.</p>
<h3>Administration</h3>
<h4>Calendar provisioning</h4>
<p>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 <a href="install-admin-mb.html">IMAP Inbox</a> in order for
the calendars to be created.</p>
<h4 id="ACLs">Calendar access controls</h4>
<p>The CalDAV module uses the same access controls as the other Cyrus
services. The <tt>cyradm(1)</tt> 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.</p>
<br>
<table border>
<caption>Mapping of IMAP Rights to WebDAV Privileges & HTTP Methods</caption>
<tr>
<th>IMAP right</th>
<th>WebDAV privilege</th>
<th>HTTP methods</th>
</tr>
<tr>
<td>l - lookup</td>
<td rowspan=2>DAV:read
<br><i>(aggregates DAV:read-current-user-privilege-set,
<br>CALDAV:read-free-busy)</i></td>
<td rowspan=2>GET/HEAD, PROPFIND, REPORT,
<br>COPY/MOVE <i>(on target)</i></td>
</tr>
<tr>
<td>r - read</td>
</tr>
<tr>
<td>s - seen</td>
<td colspan=2/>
</tr>
<tr>
<td>w - write</td>
<td>DAV:write-properties</i></td>
<td>PROPPATCH, COPY/MOVE <i>(on target)</i></td>
</tr>
<tr>
<td>i - insert</td>
<td>DAV:write-content</td>
<td>PUT, LOCK, COPY/MOVE <i>(on target)</i></td>
</tr>
<tr>
<td>p - post</td>
<td>CYRUS:add-resource <i>(aggregated under DAV:bind)</i></td>
<td>POST</td>
</tr>
<tr>
<td>k - create mailbox</td>
<td>CYRUS:make-collection <i>(aggregated under DAV:bind)</i></td>
<td>MKCOL, MKCALENDAR</td>
</tr>
<tr>
<td>x - delete mailbox</td>
<td>CYRUS:remove-collection <i>(aggregated under DAV:unbind)</i></td>
<td>DELETE</td>
</tr>
<tr>
<td>t - delete message</td>
<td>CYRUS:remove-resource <i>(aggregated under DAV:unbind)</i></td>
<td>DELETE, MOVE <i>(on source)</i></td>
</tr>
<tr>
<td>e - expunge</td>
<td colspan=2/>
</tr>
<tr>
<td>a - admin</td>
<td>CYRUS:admin
<br><i>(aggregates DAV:read-acl, DAV:write-acl, DAV:unlock)</i></td>
<td>ACL, UNLOCK, PROPFIND <i>(DAV:acl only)</i></td>
</tr>
<tr>
<td rowspan=3>9 - free/busy</td>
<td>CALDAV:read-free-busy <i>(regular calendar collection only)</i></td>
<td>REPORT <i>(CALDAV:free-busy-query only)</i><td/>
</tr>
<tr>
<td>CALDAV:schedule-query-freebusy <i>(Scheduling Inbox only)</i></td>
<td rowspan=6/>
</tr>
<tr>
<td>CALDAV:schedule-send-freebusy <i>(Scheduling Outbox only)</i></td>
<tr>
<td rowspan=2>8 - invite</td>
<td>CALDAV:schedule-deliver-invite <i>(Scheduling Inbox only)</i></td>
</tr>
<tr>
<td>CALDAV:schedule-send-invite <i>(Scheduling Outbox only)</i></td>
</tr>
<tr>
<td rowspan=2>7 - reply</td>
<td>CALDAV:schedule-deliver-reply <i>(Scheduling Inbox only)</i></td>
</tr>
<tr>
<td>CALDAV:schedule-send-reply <i>(Scheduling Outbox only)</i></td>
</tr>
</table>
<br>
<br>
<table border>
<caption>Default WebDAV Privileges by Collection</caption>
<tr>
<th>Collection</th>
<th>ACL</th>
</tr>
<tr>
<td>Regular Calendar</td>
<td>owner - DAV:all + CALDAV:read-free-busy (lrwipkxta9)
<br>anyone - CALDAV:read-free-busy (9)</td>
</tr>
<tr>
<td>Scheduling Inbox</td>
<td>owner - DAV:all + CALDAV:schedule-deliver (lrwipkxta789)
<br>anyone - CALDAV:schedule-deliver (789)</td>
</tr>
<tr>
<td>Scheduling Outbox</td>
<td>owner - DAV:all + CALDAV:schedule-send (lrwipkxta789)</td>
</tr>
</table>
<br>
<h3>Client Setup</h3>
<h4>Mozilla Lightning</h4>
<p>For each calendar that you would like to add to this client,
perform the following steps:
<ol>
<li>Select the "File -> New -> Calendar..." menu option.</li>
<li>Select the "On the Network" option and click Continue.</li>
<li>Select "CalDAV" as the Format.</li>
<li>Enter a URL of the following form as
the Location: <tt>https://<servername>/dav/calendars/user/<userid>/<calendar>/</tt></li>
</ol>
</p>
<p>Cyrus will auto-provision a calendar with name "Default" which can
be used in the URL above.</p>
<h4>Apple iCal</h4>
<p>This client will autodetect all available calendars on a server.
To add a Cyrus server to this client, perform the following steps:
<ol>
<li>Select the "Calendar -> Preferences" menu option.</li>
<li>Select the "Accounts" tab.</li>
<li>Click the "+" button.</li>
<li>Select "CalDAV" as the Account Type.
<li>Fill in User Name, Password, and Server Address accordingly.</li>
<li>Click Create.</li>
</ol>
</p>
<h4>Apple iOS Calendar</h4>
<p>This client will autodetect all available calendars on a server.
To add a Cyrus server to this client, perform the following steps:
<ol>
<li>Run the "Settings" app.</li>
<li>Select the "Mail, Contacts, Calendars" menu.</li>
<li>Select the "Add Account..." menu.</li>
<li>Select the "Other" menu.</li>
<li>Select the "Add CalDAV Account" menu.</li>
<li>Fill in Server, User Name, Password, and Description accordingly.</li>
<li>Click Next.</li>
</ol>
</p>
<h4>Evolution</h4>
<p>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:
<ol>
<li>Select the "New -> Calendar" menu option.</li>
<li>Select "CalDAV" as the Type.</li>
<li>Fill in Server and User accordingly.</li>
<li>Click "Find Calendars".</li>
<li>Select the desired calendar from the list.</li>
<li>Click "Apply".</li>
<li>Click "OK".</li>
</ol>
</p>
<h4><a href="http://www.acal.me">aCal</a></h4>
<p>This client will autodetect all available calendars on a server.
To add a Cyrus server to this client, perform the following steps:
<ol>
<li>Press the Andoid "Menu" button.</li>
<li>Select "Settings".</li>
<li>Select "Servers".</li>
<li>Select "Add Server".</li>
<li>Select "Manual Configuration".</li>
<li>Fill in Username, Password, and User URL (servername) accordingly.</li>
<li>Press "Apply".</li>
</ol>
</p>
<h4><a href="http://www.inf-it.com/open-source/clients/caldavzap/">
CalDavZAP</a></h4>
<p>This client will autodetect all available calendars on a server.
To configure this client for a Cyrus server, edit <tt>config.js</tt> as
follows:
<ol>
<li>Set the <tt>href</tt> value in
the <tt>globalNetworkCheckSettings</tt> array to a URL of the following
form: <tt>https://<servername>/dav/principals/user/</tt>
<br>Note that the trailing "/" is REQUIRED.</li>
<li>Set the <tt>globalSettingsType</tt> option
to <tt>calendar-home-set</tt></li>
<li>Set any other options as desired
(e.g. <tt>globalDatepickerFirstDayOfWeek</tt>, <tt>globalTimeZone</tt>).</li>
</ol>
</p>
<h2 id="CardDAV">CardDAV Module</h2>
<h3>Configuration</h3>
<p>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 <tt>addressbookprefix</tt> 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 <tt>addressbookprefix</tt>, an addressbook named <tt>Default</tt> for
user <tt>murch</tt> would reside in the mailbox
named <tt>user.murch.#addressbooks.Default</tt>.<p>
<p><i>Note that mailboxes in the addressbook hierarchies (those
under <tt>addressbookprefix</tt>) <b>SHOULD NOT</b> 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 <tt>imapd</tt> in response to an IMAP client's request for the
available mailbox list, but Cyrus <tt>imapd</tt> will not otherwise
prevent an IMAP client from accessing them.</i></p>
<h3>Administration</h3>
<h4>Addressbook provisioning</h4>
<p>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 <a href="install-admin-mb.html">IMAP Inbox</a> in order for
the addressbook to be created.</p>
<h4>Addressbook access controls</h4>
<p>Cyrus uses the same access controls for addressbooks as it does for
<a href="#ACLs">calendars</a>, except that the scheduling rights (7,
8, 9) have no use with addressbooks and are ignored.</p>
<h3>Client Setup</h3>
<h4>Apple Contacts</h4>
<p>This client will autodetect all available addressbooks on a server.
To add a Cyrus server to this client, perform the following steps:
<ol>
<li>Select the "Contacts -> Preferences" menu option.</li>
<li>Select the "Accounts" tab.</li>
<li>Click the "+" button.</li>
<li>Select "CardDAV" as the Account Type.
<li>Fill in User Name, Password, and Server Address accordingly.</li>
<li>Click Create.</li>
</ol>
</p>
<h4>Apple iOS Contacts</h4>
<p>This client will autodetect all available addressbooks on a server.
To add a Cyrus server to this client, perform the following steps:
<ol>
<li>Run the "Settings" app.</li>
<li>Select the "Mail, Contacts, Calendars" menu.</li>
<li>Select the "Add Account..." menu.</li>
<li>Select the "Other" menu.</li>
<li>Select the "Add CardDAV Account" menu.</li>
<li>Fill in Server, User Name, Password, and Description accordingly.</li>
<li>Click Next.</li>
</ol>
</p>
<h4><a href="http://www.inf-it.com/open-source/clients/carddavmate/">
CardDavMATE</a></h4>
<p>This client will autodetect all available addressbooks on a server.
To configure this client for a Cyrus server, edit <tt>config.js</tt> as
follows:
<ol>
<li>Set the <tt>href</tt> value in
the <tt>globalNetworkCheckSettings</tt> array to a URL of the following
form: <tt>https://<servername>/dav/principals/user/</tt>
<br>Note that the trailing "/" is REQUIRED.</li>
<li>Set the <tt>globalSettingsType</tt> option
to <tt>addressbook-home-set</tt></li>
<li>Set any other options as desired.</li>
</ol>
</p>
<h2 id="TimeZone">Time Zone Distribution Service Module</h2>
<h3>Configuration</h3>
<p>When enabled, the Time Zone module allows Cyrus to function as a
Time Zone Distribution Service, providing time zone data to client systems. This
module stores time zone data in the <tt>zoneinfo/</tt> subdirectory of
the Cyrus configuration directory (as specified by
the <tt>configdir</tt> option). The data is indexed by a database
whose location is specified by the <tt>zoneinfo_db_path</tt> option,
using the format specified by the <tt>zoneinfo_db</tt> option.</p>
<h3>Administration</h3>
<p>This module is designed to use the <i>IANA Time Zone Database</i> data
(a.k.a. <i>Olson Database</i>) converted to the iCalendar format. The
steps to populate the Cyrus <tt>zoneinfo/</tt> directory are as follows:
<ol start=0>
<li>Build the <tt>vzic</tt> utility located in
the <tt>tools/vzic/</tt> subdirectory of the Cyrus source code.
Simply running <tt>make</tt> in the <tt>tools/vzic/</tt>
subdirectory should suffice.</li>
<li>Download the latest version of the Time Zone Database data
from <a href="http://www.iana.org/time-zones">IANA</a>. <i>Only the
data is required, NOT the code</i>.</li>
<li>Expand the downloaded time zone data into the temporary directory
of your choice.</li>
<li>Populate <tt>configdir/zoneinfo/</tt> with iCalendar data:
<p><i>Initial Install Only</i></p>
<ol type=a>
<li>Convert the raw data into iCalendar format by
running <tt>vzic</tt> as follows:
<p><tt>vzic --pure --olson-dir <location-of-raw-data>
--output-dir <configdir>/zoneinfo</tt></p>
<p>This will create and install iCalendar data directly into
the <tt>configdir/zoneinfo/</tt> directory.</p>
</li>
</ol>
<p><i>Updating Data Only</i></p>
<ol type=a>
<li>Convert the raw data into iCalendar format by
running <tt>vzic</tt> as follows:
<p><tt>vzic --pure --olson-dir <location-of-raw-data></tt></p>
<p>This will create a <tt>zoneinfo/</tt> subdirectory in your
current location (preferably <tt>tools/vzic/</tt>).</p>
</li>
<li>Merge new/updated iCalendar data into
the <tt>configdir/zoneinfo/</tt> directory by
running <tt>vzic-merge.pl</tt> in your current location:
<p><tt>vzic-merge.pl</tt></p>
</li>
</ol>
</li>
<li>Rebuild the Cyrus zoneinfo index by
running <tt>ctl_zoneinfo</tt> as follows:
<p><tt>ctl_zoneinfo -r <version-string></tt></p>
<p>where <tt><version-string></tt> describes the recently
downloaded time zone data (e.g. "IANA Time Zone Database
v.2013h").</p></li>
<li>Verify that the zoneinfo index database and all iCalendar data
files/links are readable by the <tt>cyrus</tt> user.</li>
</ol>
</p>
<h2 id="iSchedule">iSchedule Module</h2>
<p>This module will be automatically enabled if and only if both the
CalDAV module and the <tt>caldav_allowscheduling</tt> options are
enabled in a Cyrus Murder.</p>
<p><i>Support for scheduling with external servers is currently under
development and will require a future release of OpenDKIM.</i></p>
<!--
<h3>Configuration</h3>
<h3>Administration</h3>
-->
<h2>DomainKey Module</h2>
<p><i>Currently unavailable. Will be available once iSchedule support to
external servers is available.</i></p>
</body></html>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
<title>Cyrus HTTP</title>
</head>
<body>
<h1>Cyrus HTTP (RSS, CalDAV, CardDAV, iSchedule, DomainKey)</h1>
<b><i>Note that the HTTP service and associated modules in Cyrus are
still under development. This release should be considered beta
quality.</i></b>
<h2>Introduction</h2>
<p>Cyrus <tt>http</tt> service has the ability to:</p>
<ul>
<li>Serve IMAP mailboxes as RSS feeds.</li>
<li>Act as a calendar and scheduling (CalDAV) server by using IMAP
mailboxes as calendar collections and RFC 5322 messages to store
iCalendar data.</li>
<li>Act as a contacts (CardDAV) server by using IMAP mailboxes as
addressbook collections and RFC 5322 messages to store vCard
data.</li>
<li>Allow scheduling transactions between separate calendaring and
scheduling systems via the iSchedule protocol <i>(currently only used
within a Cyrus Murder)</i>.</li>
</ul>
<i>Unlike the <a href="http://httpd.apache.org/">Apache HTTP
Server</a>, Cyrus HTTP is NOT a general purpose HTTP server. Its
feature set is limited to what is required to support the
facilities listed above.</i>
<p>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 <a href="install.html">installation</a>
documentation before continuing. Note: The
"<a href="#install">Installation</a>" section below augments the
"<a href="install-compile.html">Compiling the IMAP Server</a>"
document. The remaining sections assume that your Cyrus server has
already been
successfully <a href="install-configure.html">configured</a>.</p>
<p>This document also assumes that you are familiar with RSS, WebDAV,
calendaring, and contacts.</p>
<h2 id="install">Installation</h2>
<p>You will need to build Cyrus with
the <tt>--enable-http</tt> configure option. This builds httpd
and the associated modules and utilities based on the availability
of the prerequisites listed below.</p>
<h3>General Requirements</h3>
<ul>
<li>Must have <a href="http://xmlsoft.org/">libxml2</a>
installed.</li>
<li>Must have a recent SASL build (v2.1.26 or later) in order to
support HTTP Digest, Negotiate, and NTLM authentication.
Otherwise, only HTTP Basic authentication will be available</li>
</ul>
<h3>CalDAV / CardDAV Requirements</h3>
<ul>
<li>Must
have <a href="http://freeassociation.sourceforge.net/">libical</a>
installed.</li>
<li>Must have <a href="http://www.sqlite.org/">SQLite</a> v3.x (or
later) installed.</li>
<li>Optionally
install <a href="https://github.com/jehiah/json-c">json-c</a> for
jCal/jCard support.</li>
</ul>
<!--
<h3>iSchedule Requirements</h3>
<ul>
<li>Must
have <a href="http://www.opendkim.org/">OpenDKIM v2.9.x (or higher)</a>
installed.</li>
</ul>
-->
<h2 id="config">General Configuration</h2>
<p>The Cyrus <tt>httpd</tt> service is configurable via several
options in <tt>imapd.conf</tt>. Several of those options are
discussed in the sections below. Admins should consult
the <tt>imapd.conf(5)</tt> manpage for the full list of options used
by the <tt>httpd</tt> service and its various modules.<p>
<p>The support for RSS, CalDAV, and CardDAV is divided into separate
modules which run as part of the Cyrus <tt>httpd</tt>
service. Selection of which module(s) are enabled is
done by setting the <tt>httpmodules</tt> option accordingly. By
default, no modules are enabled.</p>
<p>Cyrus <tt>httpd</tt> also can serve <i>static</i> content, the
location of which is set by the <tt>httpdocroot</tt> option. Any
content contained in the specified directory (including
sub-directories) will be served as static content only.
Cyrus <tt>httpd</tt> does NOT have the ability to execute any
server-side scripts.</p>
<h3>HTTP Authentication</h3>
<p>As with other Cyrus services, the Cyrus <tt>httpd</tt> 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).</p>
<p>Similar to plaintext login commands supported by the other Cyrus
services (IMAP LOGIN, POP3 USER/PASS), the Cyrus <tt>httpd</tt>
service determines whether to advertise the HTTP Basic
authentication scheme based on the <tt>allowplaintext</tt> option
and whether the client has connected over a TLS protected connection
(HTTPS).</p>
<p>The availability of the other HTTP authentication schemes is
controlled by the <tt>sasl_mech_list</tt> option. For
Cyrus <tt>httpd</tt> the <tt>DIGEST-MD5</tt>, <tt>GSS-SPNEGO</tt>,
and <tt>NTLM</tt> SASL plugins support the Digest, Negotiate,
and NTLM authentication schemes respectively, provided that these
plugins are installed on the server.</p>
<h2>RSS Module</h2>
<h3>Configuration</h3>
<p>When enabled, the RSS module will default to serving ALL mailboxes
to which the authenticated user has access as RSS feeds.
The <tt>rss_feeds</tt> option can be used to limit the set of
mailboxes that can be served as RSS feeds. For example,
setting <tt>rss_feeds</tt> to <tt>*,!user</tt> will serve all shared
mailboxes, but no personal mailboxes.</p>
<p>The list of available RSS feeds can be obtained by clients by
accessing the <tt>/rss/</tt> 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 <tt>rss_feedlist_template</tt> 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 <tt>httpdocroot</tt> as set above.
Consult the <tt>imapd.conf(5)</tt> manpage for specifics on the
required contents of this custom file. Note that for sites
running Cyrus Murder, <tt>rss_feedlist_template</tt> only needs to
be set on frontend servers, since only those servers have the
complete mailbox list.</p>
<h2>CalDAV Module</h2>
<h3>Configuration</h3>
<p>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 <tt>calendarprefix</tt> 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 <tt>calendarprefix</tt>, a calendar named <tt>Default</tt> for
user <tt>murch</tt> would reside in the mailbox
named <tt>user.murch.#calendars.Default</tt>.<p>
<p><i>Note that mailboxes in the calendar hierarchies (those
under <tt>calendarprefix</tt>) <b>SHOULD NOT</b> 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 <tt>imapd</tt> in response to an IMAP client's request for the
available mailbox list, but Cyrus <tt>imapd</tt> will not otherwise
prevent an IMAP client from accessing them.</i></p>
<p>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 <tt>caldav_allowscheduling</tt>
option.</p>
<h3>Administration</h3>
<h4>Calendar provisioning</h4>
<p>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 <a href="install-admin-mb.html">IMAP Inbox</a> in order for
the calendars to be created.</p>
<h4 id="ACLs">Calendar access controls</h4>
<p>The CalDAV module uses the same access controls as the other Cyrus
services. The <tt>cyradm(1)</tt> 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.</p>
<br>
<table border>
<caption>Mapping of IMAP Rights to WebDAV Privileges & HTTP Methods</caption>
<tr>
<th>IMAP right</th>
<th>WebDAV privilege</th>
<th>HTTP methods</th>
</tr>
<tr>
<td>l - lookup</td>
<td rowspan=2>DAV:read
<br><i>(aggregates DAV:read-current-user-privilege-set,
<br>CALDAV:read-free-busy)</i></td>
<td rowspan=2>GET/HEAD, PROPFIND, REPORT,
<br>COPY/MOVE <i>(on target)</i></td>
</tr>
<tr>
<td>r - read</td>
</tr>
<tr>
<td>s - seen</td>
<td colspan=2/>
</tr>
<tr>
<td>w - write</td>
<td>DAV:write-properties</i></td>
<td>PROPPATCH, COPY/MOVE <i>(on target)</i></td>
</tr>
<tr>
<td>i - insert</td>
<td>DAV:write-content</td>
<td>PUT, LOCK, COPY/MOVE <i>(on target)</i></td>
</tr>
<tr>
<td>p - post</td>
<td>CYRUS:add-resource <i>(aggregated under DAV:bind)</i></td>
<td>POST</td>
</tr>
<tr>
<td>k - create mailbox</td>
<td>CYRUS:make-collection <i>(aggregated under DAV:bind)</i></td>
<td>MKCOL, MKCALENDAR</td>
</tr>
<tr>
<td>x - delete mailbox</td>
<td>CYRUS:remove-collection <i>(aggregated under DAV:unbind)</i></td>
<td>DELETE</td>
</tr>
<tr>
<td>t - delete message</td>
<td>CYRUS:remove-resource <i>(aggregated under DAV:unbind)</i></td>
<td>DELETE, MOVE <i>(on source)</i></td>
</tr>
<tr>
<td>e - expunge</td>
<td colspan=2/>
</tr>
<tr>
<td>a - admin</td>
<td>CYRUS:admin
<br><i>(aggregates DAV:read-acl, DAV:write-acl, DAV:unlock)</i></td>
<td>ACL, UNLOCK, PROPFIND <i>(DAV:acl only)</i></td>
</tr>
<tr>
<td rowspan=3>9 - free/busy</td>
<td>CALDAV:read-free-busy <i>(regular calendar collection only)</i></td>
<td>REPORT <i>(CALDAV:free-busy-query only)</i><td/>
</tr>
<tr>
<td>CALDAV:schedule-query-freebusy <i>(Scheduling Inbox only)</i></td>
<td rowspan=6/>
</tr>
<tr>
<td>CALDAV:schedule-send-freebusy <i>(Scheduling Outbox only)</i></td>
<tr>
<td rowspan=2>8 - invite</td>
<td>CALDAV:schedule-deliver-invite <i>(Scheduling Inbox only)</i></td>
</tr>
<tr>
<td>CALDAV:schedule-send-invite <i>(Scheduling Outbox only)</i></td>
</tr>
<tr>
<td rowspan=2>7 - reply</td>
<td>CALDAV:schedule-deliver-reply <i>(Scheduling Inbox only)</i></td>
</tr>
<tr>
<td>CALDAV:schedule-send-reply <i>(Scheduling Outbox only)</i></td>
</tr>
</table>
<br>
<br>
<table border>
<caption>Default WebDAV Privileges by Collection</caption>
<tr>
<th>Collection</th>
<th>ACL</th>
</tr>
<tr>
<td>Regular Calendar</td>
<td>owner - DAV:all + CALDAV:read-free-busy (lrwipkxta9)
<br>anyone - CALDAV:read-free-busy (9)</td>
</tr>
<tr>
<td>Scheduling Inbox</td>
<td>owner - DAV:all + CALDAV:schedule-deliver (lrwipkxta789)
<br>anyone - CALDAV:schedule-deliver (789)</td>
</tr>
<tr>
<td>Scheduling Outbox</td>
<td>owner - DAV:all + CALDAV:schedule-send (lrwipkxta789)</td>
</tr>
</table>
<br>
<h3>Client Setup</h3>
<h4>Mozilla Lightning</h4>
<p>For each calendar that you would like to add to this client,
perform the following steps:
<ol>
<li>Select the "File -> New -> Calendar..." menu option.</li>
<li>Select the "On the Network" option and click Continue.</li>
<li>Select "CalDAV" as the Format.</li>
<li>Enter a URL of the following form as
the Location: <tt>https://<servername>/dav/calendars/user/<userid>/<calendar>/</tt></li>
</ol>
</p>
<p>Cyrus will auto-provision a calendar with name "Default" which can
be used in the URL above.</p>
<h4>Apple iCal</h4>
<p>This client will autodetect all available calendars on a server.
To add a Cyrus server to this client, perform the following steps:
<ol>
<li>Select the "Calendar -> Preferences" menu option.</li>
<li>Select the "Accounts" tab.</li>
<li>Click the "+" button.</li>
<li>Select "CalDAV" as the Account Type.
<li>Fill in User Name, Password, and Server Address accordingly.</li>
<li>Click Create.</li>
</ol>
</p>
<h4>Apple iOS Calendar</h4>
<p>This client will autodetect all available calendars on a server.
To add a Cyrus server to this client, perform the following steps:
<ol>
<li>Run the "Settings" app.</li>
<li>Select the "Mail, Contacts, Calendars" menu.</li>
<li>Select the "Add Account..." menu.</li>
<li>Select the "Other" menu.</li>
<li>Select the "Add CalDAV Account" menu.</li>
<li>Fill in Server, User Name, Password, and Description accordingly.</li>
<li>Click Next.</li>
</ol>
</p>
<h4>Evolution</h4>
<p>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:
<ol>
<li>Select the "New -> Calendar" menu option.</li>
<li>Select "CalDAV" as the Type.</li>
<li>Fill in Server and User accordingly.</li>
<li>Click "Find Calendars".</li>
<li>Select the desired calendar from the list.</li>
<li>Click "Apply".</li>
<li>Click "OK".</li>
</ol>
</p>
<h4><a href="http://www.acal.me">aCal</a></h4>
<p>This client will autodetect all available calendars on a server.
To add a Cyrus server to this client, perform the following steps:
<ol>
<li>Press the Andoid "Menu" button.</li>
<li>Select "Settings".</li>
<li>Select "Servers".</li>
<li>Select "Add Server".</li>
<li>Select "Manual Configuration".</li>
<li>Fill in Username, Password, and User URL (servername) accordingly.</li>
<li>Press "Apply".</li>
</ol>
</p>
<h4><a href="http://www.inf-it.com/open-source/clients/caldavzap/">
CalDavZAP</a></h4>
<p>This client will autodetect all available calendars on a server.
To configure this client for a Cyrus server, edit <tt>config.js</tt> as
follows:
<ol>
<li>Set the <tt>href</tt> value in
the <tt>globalNetworkCheckSettings</tt> array to a URL of the following
form: <tt>https://<servername>/dav/principals/user/</tt>
<br>Note that the trailing "/" is REQUIRED.</li>
<li>Set the <tt>globalSettingsType</tt> option
to <tt>calendar-home-set</tt></li>
<li>Set any other options as desired
(e.g. <tt>globalDatepickerFirstDayOfWeek</tt>, <tt>globalTimeZone</tt>).</li>
</ol>
</p>
<h2>CardDAV Module</h2>
<h3>Configuration</h3>
<p>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 <tt>addressbookprefix</tt> 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 <tt>addressbookprefix</tt>, an addressbook named <tt>Default</tt> for
user <tt>murch</tt> would reside in the mailbox
named <tt>user.murch.#addressbooks.Default</tt>.<p>
<p><i>Note that mailboxes in the addressbook hierarchies (those
under <tt>addressbookprefix</tt>) <b>SHOULD NOT</b> 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 <tt>imapd</tt> in response to an IMAP client's request for the
available mailbox list, but Cyrus <tt>imapd</tt> will not otherwise
prevent an IMAP client from accessing them.</i></p>
<h3>Administration</h3>
<h4>Addressbook provisioning</h4>
<p>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 <a href="install-admin-mb.html">IMAP Inbox</a> in order for
the addressbook to be created.</p>
<h4>Addressbook access controls</h4>
<p>Cyrus uses the same access controls for addressbooks as it does for
<a href="#ACLs">calendars</a>, except that the scheduling rights (7,
8, 9) have no use with addressbooks and are ignored.</p>
<h3>Client Setup</h3>
<h4>Apple Contacts</h4>
<p>This client will autodetect all available addressbooks on a server.
To add a Cyrus server to this client, perform the following steps:
<ol>
<li>Select the "Contacts -> Preferences" menu option.</li>
<li>Select the "Accounts" tab.</li>
<li>Click the "+" button.</li>
<li>Select "CardDAV" as the Account Type.
<li>Fill in User Name, Password, and Server Address accordingly.</li>
<li>Click Create.</li>
</ol>
</p>
<h4>Apple iOS Contacts</h4>
<p>This client will autodetect all available addressbooks on a server.
To add a Cyrus server to this client, perform the following steps:
<ol>
<li>Run the "Settings" app.</li>
<li>Select the "Mail, Contacts, Calendars" menu.</li>
<li>Select the "Add Account..." menu.</li>
<li>Select the "Other" menu.</li>
<li>Select the "Add CardDAV Account" menu.</li>
<li>Fill in Server, User Name, Password, and Description accordingly.</li>
<li>Click Next.</li>
</ol>
</p>
<h4><a href="http://www.inf-it.com/open-source/clients/carddavmate/">
CardDavMATE</a></h4>
<p>This client will autodetect all available addressbooks on a server.
To configure this client for a Cyrus server, edit <tt>config.js</tt> as
follows:
<ol>
<li>Set the <tt>href</tt> value in
the <tt>globalNetworkCheckSettings</tt> array to a URL of the following
form: <tt>https://<servername>/dav/principals/user/</tt>
<br>Note that the trailing "/" is REQUIRED.</li>
<li>Set the <tt>globalSettingsType</tt> option
to <tt>addressbook-home-set</tt></li>
<li>Set any other options as desired.</li>
</ol>
</p>
<h2>iSchedule Module</h2>
<p>This module will be automatically enabled if and only if both the
CalDAV module and the <tt>caldav_allowscheduling</tt> options are
enabled in a Cyrus Murder.</p>
<p><i>Support for scheduling with external servers is currently under
development and will require a future release of OpenDKIM.</i></p>
<!--
<h3>Configuration</h3>
<h3>Administration</h3>
-->
<h2>DomainKey Module</h2>
<p><i>Currently unavailable. Will be available once iSchedule support to
external servers is available.</i></p>
</body></html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-updates
>
by-pkgid
>
c43d99b5f4a2e8d76a58d7d3790db733
>
files
>
249
