This provides surgemail standalone CalDAV calendaring support (including calendar sharing) for mobile devices and desktop clients.
Surgemail 7.4q+ uses SabreDAV version 3.2.2 and is compatible with 7.0-7.9 versions of PHP. Older versions of surgemail used SabreDAV 1.6.2 and needed php version 5.3-5.6, see the older 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 7.0-7.9).
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 7.0-7.9) 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 SurgeMail Version 7.4q-1, Built Aug 26 2020 08:24:11, Platform Windows 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, desktop clients and surgeweb. ----------------- Downloading php distribution [php_windows_v2.zip] Downloading [php_windows_v2.zip] (49.15% of 24 MB) Downloading [php_windows_v2.zip] (86.34% of 24 MB) Distribution ready for installation [php_windows_v2.zip] size=24129166 PHP distribution [php_windows_v2.zip] extracted and installed Downloading php libraries (SabreDAV and NetWin extensions) [phplib_v2.zip] Downloading [phplib_v2.zip] (92.06% of 1,259 KB) Downloading [phplib_v2.zip] (100.00% of 1,259 KB) Distribution ready for installation [phplib_v2.zip] size=1259477 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_v2.php] Installed empty database [c:\surgemail\scripts\data\caldb_v2.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 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 php-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 7.4.3 (cgi-fcgi) (built: May 26 2020 12:24:22) Copyright (c) The PHP Group Zend Engine v3.4.0, Copyright (c) Zend Technologies with Zend OPcache v7.4.3, Copyright (c), by 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 php-imap apt-get install php-sqlite3 apt-get install php-mbstring apt-get install php-dom
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:
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:
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:
Authentication worked
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.