CalDAV Calendaring

This provides surgemail standalone CalDAV calendaring support (including calendar sharing) for mobile devices and desktop clients.

CalDAV Quick Start for administrators

  1. Install from the admin interface and test the environment is working correctly:
    • Install using admin web interface - value added features - calendar sync - install
    • (Unix only) verify system php-cgi is installed (version 5.3+) and install if needed
    • (Unix only) point g_web_php_exe at system php-cgi (version 5.3+)
    • Verify environment is running
  2. Login with your calendaring client of choice:
    • Surgeweb : make sure this is enabled in admin interface if needed
    • iOS : Should autodetect caldav url:
      Just specify server, username (eg user@domain.com), password.
    • Other clients: You may need to manually enter the calendar url:
      caldav url: yourserver.com/cal/principals/user@domain.com
      username: user@domain.com password: {your password}
    • Tested to work with iOS, OSX iCal, Mozilla Lightning, Android CalDAV Sync
  3. Customise sharing of calendars using surgeweb:
    • Surgeweb - calendars - left column - configure caldav calendars

Installation Notes

Background

CalDAV calendaring support is based on the SabreDAV php library and is hosted by the surgemail webserver. This is integrated with surgemail for authentication. So any user with a valid surgemail email account should also be able to use CalDAV calendaring as soon as this has been enabled and installed

SabreDAV is php based. As surgemail does not use php technology elsewhere a suitable php environment needs to be installed. On windows the installer will setup a fully self contained and functional php-cgi installed in the surgemail {g_home}/php directory. On unix systems you will need to make sure you have a suitable php-cgi already installed (version 5.3+).

SabreDAV itself is a set of php scripts. Additions have been made to integrate with the surgemail for authentication and to share calendars with other users on the same server. This sharing is configured in surgeweb, and individual calendars may be shared as read/write, read only, or free/busy only.

Installation

Installation of the calendaring php scripts can be done from admin interface (value added features - calendar sync) or using "tellmail caldav_install".

  • On windows this installer also installs a standalone php-cgi config in surgemail/php.
  • On unix systems you will also have to make sure there is a system installed fully functional php-cgi (version 5.3+) and check g_web_php_exe is correctly set to use this.

Running the installer, should result in the following output and a running calendars implementation.

C:\surgemail>tellmail caldav_install

CALDAV INSTALLER - this will enable surgemail hosted CalDAV calendaring

This installer will update :
 - Standalone php-cgi distribution (surgemail/php/*) [windows only]
 - SabreDAV and NetWin SabreDAV extensions (surgemail/phplib/*)
 - Calendar script, test scripts, calendar data (surgemail/scripts/*)
 - Any necessary surgemail.ini settings
        (any existing surgemail CalDAV calendar database will remain intact)

Note: CalDAV provides standalone calendaring for mobile and desktop clients and
is currently NOT YET integrated with the surgeplus calendar or surgeweb.

-----------------

Downloading php distribution [php_windows.zip]
Downloading [php_windows.zip] (52.09% of 7,368 KB)
Downloading [php_windows.zip] (100.00% of 7,368 KB)
Distribution ready for installation [php_windows.zip] size=7545115
PHP distribution [php_windows.zip] extracted and installed

Downloading php libraries (SabreDAV and NetWin extensions) [phplib.zip]
Downloading [phplib.zip] (36.49% of 467 KB)
Downloading [phplib.zip] (100.00% of 467 KB)
Distribution ready for installation [phplib.zip] size=478729
PHP libraries (SabreDAV and NetWin extensions) extracted and installed

Installing surgemail integration files
Directory created [c:\surgemail\scripts\data]
Installed [c:\surgemail\scripts\phpinfo.php]
Installed [c:\surgemail\scripts\netwin.php]
Installed [c:\surgemail\scripts\cal.php]
Installed empty database [c:\surgemail\scripts\data\caldb.sqlite]

Verifying surgemail.ini settings
 added: g_url_redirect from="/.well-known/caldav" to="/cal"
 added: g_url_alias from="/cal" to="/scripts/cal.php"

-----------------

Installation complete, and should hopefully be "ready to use" for your surgemail users :-)

Now now test this yourself to confirm all is well:
 - Verify base PHP installation: http://yourserver/scripts/phpinfo.php
 - Verify configuration for SabreDAV: http://yourserver/scripts/netwin.php
 - Verify authentication integration: http://yourserver/cal
 - Connected using calDAV client eg iOS device

For further info see http://netwinsite.com/surgemail/help/caldav.htm


C:\surgemail>

Verify system php-cgi (Unix / OSX only)

Many unix distributions differ a little when it comes to installing and configuring php (both in terms of package names and in terms of installer utilities). But the following instructions possibly with minor modification as a result of googling install instructions on your distribution of choice should get you a long way. The following works under recent Ubuntu linux:

root@svr:/usr/local/surgemail# which php-cgi

root@svr:/usr/local/surgemail#
Run above, shows: "bother no php-cgi installed", so run :
	apt-get install php5-cgi
	...
After successful installation:
root@svr:/usr/local/surgemail# which php-cgi
/usr/bin/php-cgi

root@svr:/usr/local/surgemail# php-cgi -v
PHP 5.3.5-1ubuntu7.10 with Suhosin-Patch (cgi-fcgi) (built: Jun 19 2012 00:54:37)
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2010 Zend Technologies

root@svr:/usr/local/surgemail#
Great have php set to run, use surgemail.ini setting of and restart surgemail or issue "tellmail reload".
	g_web_php_exe "/usr/bin/php-cgi"
Now run the web based verification as documented in the next step and install additional packages as needed shown below. eg:
	apt-get install php5-imap
	apt-get install php5-sqlite

Verify the environment

There is quite a lot that "may not be working" after the above so there is a simple three step verification proces to go though.

1. Verify php is running

The script surgemail/scripts/phpinfo.php script is a minimal php script to see whether surgemail is able to correctly run php scripts using php-cgi. Connect to this by browsing to the url:

   http://yourserver.com/scripts/phpinfo.php


Correctly working php-cgi

If this request fails php-cgi is not setup correctly. Make sure g_web_php_exe is correctly set and check your php configuration and log files for possible sources of the fault. On windows these can be found surgemail/php/php.ini and surgemail/php_errors.log. On unix it will be system specific.

2. Verify php config for sabredav

In order to run CalDAV calendaring php needs to be be at least version 5.3+ and have the modules PDO, PDO_SQLITE and IMAP installed. This can be verified using the url:

   http://yourserver.com/scripts/netwin.php


CalDAV php-cgi prerequisites met

Any missing modules should get noted on this page. If modules are missing or php version is older than 5.3 you will need to upgrade your php installation.

This should be unnecessary and all setup on windows, but on unix you may need to upgrade your installed php version or install additional modules.

3. Verify authentication integration

Lastly verify the authentication. By default calDAV will connect to surgemail imap on 127.0.0.1:143 to verify the authentication information. To test this is working use a browser to connect to the SabreDAV debugging interface, and login with your full email address "user@domain.com" and password:

   http://yourserver.com/cal


Authentication worked

On some servers, particularly older servers it may be a little tricky meeting these prerequisites. Notably php-cgi 5.3, PDO and PDO_SQLITE are essential. The imap module is recommended but optional. It is recommended you use imap based authentication, but if for some reason that is not possible you can edit the surgemail/phplib/netwin/Nwauth_sabre.php to authenticate by connecting to nwauth directly in which case you will not need the imap module installed in php-cgi.

If there are any issues first check the surgemail/scripts/cal.log file and then the php log file to try and identify the source of the issue.

Now on to the client configuration.