This provides surgemail standalone CalDAV calendaring support (including calendar sharing) for mobile devices and desktop clients.
For surgemail 7.4q+ see updated install notes.
CalDAV Quick Start for administrators
- Install from the admin interface and test the environment is working correctly:
- 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
- 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-5.6).
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-5.6) 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 https://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-5.6 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.