Calendar and Contacts Server for Debian
=======================================

Database Setup
==============

Calendar and Contacts Server can currently use either files or postgresql for 
storing users' calendars and addressbooks.

Files
-----

Since calendarserver uses extended attributes you must mount the filesystem
that contains the calendars and addressbooks (/var/spool/caldavd by default) 
with extended attributes enabled. On ext2/ext3 filesystems use the user_xattr 
mount option, XFS has extended attributes enabled by default.

To use files for storage, you have to ensure that UseDatabase is set to false
in /etc/caldavd/caldavd.plist as below (this is also the default setting with
which caldavd.plist is installed):

    <key>UseDatabase</key>
    <false/>

    <!--
    <key>DBType</key>
    <string>postgres</string>
    <key>DSN</key>
    <string>127.0.0.1:caldav:caldav:password::</string>
     -->

While backing up the calendars and addressbooks when using files for stroage, 
it should be kept in mind that calendarserver uses extended attributes for the
document root. Therefore the user should use a program that supports backing up
extened attributes as well. "bsdtar" supports archiving extended attributes 
(default behaviour if bsdtar is run as root). If you are using rsync to copy 
the calendars, you will have to explicity pass the "-X" option to rsync (even 
if you are transferring in archive mode using --archive/-a).

PostgreSQL
----------

You will have to first create a caldav user and database before configuring
calendarserver.

 # su - postgres
 # createuser caldav --pwprompt --no-createdb --no-createrole --no-superuser
 Enter password for new role: <Enter password>
 Enter it again: <Reenter password>
 # createdb --owner=caldav caldav

Now, import the calendarserver schema.

 # psql -f /usr/share/pyshared/txdav/common/datastore/sql_schema/current.sql caldav

Configure postgres details in caldavd.plist as below (ensure that you comment
out UseDatabase option):

    <!--
    <key>UseDatabase</key>
    <false/>
     -->

    <key>DBType</key>
    <string>postgres</string>
    <key>DSN</key>
    <string>127.0.0.1:caldav:caldav:password::</string>

where password is the password that you have set for postgres caldav user
above.


Basic Setup
===========

You have to add a /etc/caldavd/accounts.xml to tell caldavd about your accounts
and users. See /usr/share/doc/calendarserver/examples/accounts.xml for an
example. Likewise you have to add a /etc/caldavd/sudoers.plist. Both files have
to be present, otherwise the calendarserver will not work.

The URI to your CalDAV calendar will typically look like:

 http://<server>:8008/calendars/users/<user>/calendar/

where <server> is the hostname or the IP of the server on which calendarserver
is installed and <user> is the username of a calendarserver user as specified 
in accounts.xml. Similarly, the URI to your CardDAV addressbook will look like:

 http://<server>:8008/addressbooks/users/<user>/addressbook/


Loadbalancing
=============

In order to enable laod balancing onto different processors/cores you need to
set the ProcessCount in /etc/caldavd/caldavd.plist accordingly.


Enabling SPNEGO/Kerberos
========================

To make SPNEGO/Kerberos authentication work you have to add service principals
for HTTP/caldavd.example.com@EXAMPLE.COM and
http/caldavd.example.com@EXAMPLE.COM to your servers keytab /etc/krb5.keytab
(replace caldavd.example.com by the fqdn of your caldav server and EXAMPLE.COM
by your Kerberos realm).

The uppercase http variant is used by most clients like iceowl and icedove with
iceowl-extension while the lowercase version is used by iCal. The keytab must
be readable for user caldavd which can be achieved by:

chgrp caldavd /etc/krb5.keytab
chmod 0640 /etc/krb5.keytab

Now you have to specify the name of a ServicePrincipal in
/etc/caldavd/caldavd.plist:

    <!-- Kerberos/SPNEGO -->
    <key>Kerberos</key>
    <dict>
      <key>Enabled</key>
      <true/>
      <key>ServicePrincipal</key>
      <string>http/caldavd.example.com@EXAMPLE.COM</string>
    </dict>

Note: if you use iceowl/iceowl-extension the
network.negotiate-auth.trusted-uris in iceowl/icedove must match on your
calendarservers uri otherwise SPNEGO will not work. A good choice is
"https://".


Nameservice Switch Backend
==========================

If you don't want to manage accounts in a separate XML file you can use the
names service switch backend. Details on how to set this up can be found at:

http://honk.sigxcpu.org/con/Apple_Calendarser_with_Name_Service_Switch_directory_backend.html

Note that in order to function properly "getent passwd" must list all users
that should be able to access the calendarserver. This might not be the case if
you hit the search limit of your LDAP server.

Also note that the username and groupname (without the prefix) shouldn't be the
same else calendarserver might get confused.

PAM authentication is supported (python-pam needs to be installed). The pam 
service name is "caldav". Basic Authentication should be enabled and Digest 
Authentication should be disabled for PAM authentication to work. It is 
suggested to use PAM authentication in conjunction with SSL (https) so that the
password is not sent in plain text. For PAM authentication against local unix 
passwords, the user "caldavd" should be added to the "shadow" group.

 -- Guido Guenther <agx@sigxcpu.org>  Thu, 30 Apr 2008 16:17:56 +0100


LDAP Directory Backend
======================

LDAP Directory service has been merged upstream in calendarserver 3.0
(python-ldap package has to be installed for using this directory service).
Information on configurating LDAP can be found at: 

    http://trac.calendarserver.org/wiki/ConfiguringLDAP

Possible authentication methods are "LDAP" (default) and "PAM" (python-pam 
needs to be installed). The pam service name is "caldav". For PAM/LDAP 
authentication, Basic Authentication should be enabled and Digest 
Authentication should be disabled (as shown below). It is suggested to use 
PAM/LDAP authentication in conjunction with SSL (https) so that the password 
is not sent in plain text. For PAM authentication against local unix passwords,
the user "caldavd" should be added to the "shadow" group.

    <!-- Clear text; best avoided -->
    <key>Basic</key>
    <dict>
      <key>Enabled</key>
      <true/>
    </dict>

    <!-- Digest challenge/response -->
    <key>Digest</key>
    <dict>
      <key>Enabled</key>
      <false/>
      <key>Algorithm</key>
      <string>md5</string>
      <key>Qop</key>
      <string></string>
    </dict>

For LDAP anonymous binding, the dn and password entries should be present in 
the configuration file but their values should be empty.

 -- Rahul Amaram <amaramrahul@users.sourceforge.net>  Tue, 24 Aug 2010 22:05:00 +0530


FAQ
===

Calendar and Contacts Server FAQ is maintained at:

    http://trac.calendarserver.org/wiki/FAQ