| 1 |
.. _manage-dav: |
| 2 |
|
| 3 |
============ |
| 4 |
HTTP modules |
| 5 |
============ |
| 6 |
|
| 7 |
About http module support |
| 8 |
========================= |
| 9 |
|
| 10 |
This assumes you already have the relevant modules enabled in your Cyrus |
| 11 |
:ref:`installation <setup>`, either via packages, or through a |
| 12 |
manual installation. |
| 13 |
|
| 14 |
CalDAV, CardDAV and WebDAV all provide their functionality through an http |
| 15 |
server. Cyrus HTTP is NOT a general purpose HTTP server (such as Apache httpd). |
| 16 |
Its feature set is limited to: |
| 17 |
|
| 18 |
* Calendaring (CalDAV) |
| 19 |
* Acts as a calendar and scheduling server by using IMAP mailboxes as calendar |
| 20 |
collections and :rfc:`5322` messages to store iCalendar data. |
| 21 |
* Allows non-CalDAV/remote calendar clients to query freebusy information of |
| 22 |
Cyrus CalDAV users via freebusy URLs. |
| 23 |
* Allows scheduling transactions between separate calendaring and |
| 24 |
scheduling systems via the iSchedule protocol (currently only |
| 25 |
used within a Cyrus Murder). |
| 26 |
* Acts as a Time Zone Distribution Service by serving iCalendar |
| 27 |
(VTIMEZONE) data to client systems. |
| 28 |
* Contacts (CardDAV) |
| 29 |
* Acts as a contacts server by using IMAP mailboxes as addressbook |
| 30 |
collections and :rfc:`5322` messages to store vCard data. |
| 31 |
* File Storage (WebDAV) |
| 32 |
* Acts as a remote storage server server by using IMAP mailboxes as |
| 33 |
collections and :rfc:`5322` message to store files. |
| 34 |
* JMAP support |
| 35 |
* Allows synchronization of mail clients via the JSON Mail Access Protocol (JMAP). |
| 36 |
* Other (RSS, static content) |
| 37 |
* Serves static content (such as the RSS feed list template and the |
| 38 |
CalDAV/CardDAV web GUIs). |
| 39 |
* Serves IMAP mailboxes as RSS feeds. |
| 40 |
|
| 41 |
HTTPD Configuration |
| 42 |
=================== |
| 43 |
|
| 44 |
General configuration |
| 45 |
--------------------- |
| 46 |
|
| 47 |
The Cyrus httpd service is configured using options in :cyrusman:`imapd.conf(5)`. |
| 48 |
|
| 49 |
.. sidebar:: httpmodules |
| 50 |
|
| 51 |
.. include:: /imap/reference/manpages/configs/imapd.conf.rst |
| 52 |
:start-after: startblob httpmodules |
| 53 |
:end-before: endblob httpmodules |
| 54 |
|
| 55 |
The support for RSS, CalDAV, and CardDAV is divided into separate modules which |
| 56 |
run as part of the Cyrus httpd service. Selection of which module(s) are enabled |
| 57 |
is done by setting the ``httpmodules`` option. **By default, no modules |
| 58 |
are enabled.** |
| 59 |
|
| 60 |
Cyrus httpd also can serve static content, the location of which is set by the |
| 61 |
``httpdocroot`` option. Any content contained in the specified directory (including |
| 62 |
sub-directories) will be served as static content only. Cyrus httpd does NOT |
| 63 |
have the ability to execute any server-side scripts. |
| 64 |
|
| 65 |
|
| 66 |
Authentication |
| 67 |
-------------- |
| 68 |
|
| 69 |
As with other Cyrus services, the Cyrus httpd service uses |
| 70 |
:ref:`Cyrus SASL <cyrussasl:sasl-index>` to perform its authentication. |
| 71 |
|
| 72 |
.. sidebar:: allowplaintext |
| 73 |
|
| 74 |
|change-default-config| |
| 75 |
|
| 76 |
.. include:: /imap/reference/manpages/configs/imapd.conf.rst |
| 77 |
:start-after: startblob allowplaintext |
| 78 |
:end-before: endblob allowplaintext |
| 79 |
|
| 80 |
Similar to plaintext login commands supported by the other Cyrus services (IMAP |
| 81 |
LOGIN, POP3 USER/PASS), the Cyrus httpd service determines whether to advertise |
| 82 |
the HTTP Basic authentication scheme based on the ``allowplaintext`` option and |
| 83 |
whether the client has connected over a TLS protected connection (HTTPS). BASIC |
| 84 |
authentication does not depend on a Cyrus SASL plugin. |
| 85 |
|
| 86 |
The advertisement of the other HTTP authentication schemes is controlled by the |
| 87 |
:ref:`SASL mech_list option <cyrussasl:options>` option. For Cyrus httpd |
| 88 |
the GSS-SPNEGO, SCRAM-SHA-1, and SCRAM-SHA-256 values enable |
| 89 |
support for the Negotiate (Kerberos only), SCRAM-SHA-1, and |
| 90 |
SCRAM-SHA-256 authentication schemes respectively, provided that the plugins |
| 91 |
are installed on the server. |
| 92 |
|
| 93 |
Module-specific information |
| 94 |
=========================== |
| 95 |
|
| 96 |
.. toctree:: |
| 97 |
:maxdepth: 2 |
| 98 |
|
| 99 |
http/caldav |
| 100 |
http/carddav |
| 101 |
http/webdav |
| 102 |
http/jmap |
| 103 |
http/rss |
| 104 |
|
| 105 |
For end users |
| 106 |
============= |
| 107 |
|
| 108 |
Some information must be passed on to your end users so that they know how to |
| 109 |
configure their clients in order to access their data on Cyrus. The list below |
| 110 |
needs to be customized to your specific hostnames. |
| 111 |
|
| 112 |
* CalDAV |
| 113 |
* Many clients find calendars automatically if you provide the correct server, username and password. |
| 114 |
* Otherwise, use the direct URL: ``https://<servername>/dav/calendars/user/<userid>/<calendar>/`` |
| 115 |
* Freebusy |
| 116 |
* ``https://<servername>/freebusy/user/<userid>`` - considers all CalDAV collections of the user |
| 117 |
* ``https://<servername>/freebusy/user/<userid>/<collection-name>`` - considers a single CalDAV collection |
| 118 |
* Query parameters can be added to the URL per Section 4 of |
| 119 |
`Freebusy Read URL <http://www.calconnect.org/pubdocs/CD0903%20Freebusy%20Read%20URL.pdf>`_. |
| 120 |
* CardDAV |
| 121 |
* Many clients find addressbooks automatically if you provide the correct server, username and password. |
| 122 |
* Otherwise, use the direct URL:``https://<servername>/dav/addressbooks/<userid>/<addressbook>`` |
| 123 |
* The address book(s) are automatically filtered based on the username and password supplied. |
| 124 |
* WebDAV |
| 125 |
* ``https://<servername>/dav/drive/user/<userid>`` |
| 126 |
* RSS |
| 127 |
* ``https://<servername>/rss/`` |
| 128 |
* Serves up all mailboxes (read-only) that the authenticated user has access to. |