Cyrus HTTP (RSS, CalDAV,
  CardDAV, iSchedule,
  TimeZone)

    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 Time Zone Distribution 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. 
      * Optionally install OpenSSL for HTTPS support. 
      * Optionally install Zlib for compression support. 

Additional CalDAV / CardDAV Requirements

      * Must have Libical installed. 
      * Must have SQLite v3.x (or later) installed. 
      * Optionally install Jansson for jCal/jCard support. 
      * Optionally install ICU4C for non-Gregorian calendar support, if
        Libical has support for the RSCALE extension. 

Additional iSchedule Requirements

      * Must meet CalDAV requirements above. 
      * Must have OpenDKIM with support for iSchedule canonicalization
        installed (currently requires a CMU patch). 

Additional Time Zone Distribution 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. 
