
CardDAV
*******


Configuration
=============


addressbookprefix
^^^^^^^^^^^^^^^^^

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

   "addressbookprefix:" #addressbooks

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

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

Warning: 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 can not otherwise prevent an
  IMAP client from accessing them.


Administration
==============

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.


carddav_allowaddressbookadmin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

   "carddav_allowaddressbookadmin:" 0

      Enable per-user addressbook administration web UI on the CardDAV
      server.

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

   * Create new collections

   * Delete existing collections

   * Download existing collections via prepared URLs

The Cyrus web GUI for addressbook management is disabled by default,
but can be enabled with the "carddav_allowaddressbookadmin" option.

To access the Cyrus web GUI for addressbook management, point a web
browser at "https://<servername>/dav/addressbooks/user/<username>"


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.
