CalDAV plugin install

  1. Home
  2. Knowledge Base
  3. Installation
  4. CalDAV plugin install

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 modern 7.0+ 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

  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 7.0+) and install if needed
    • (Unix only) point g_web_php_exe at system php-cgi (version 7.0+)
    • 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 7.0+).

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/writeread 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+) 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:

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

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.

Was this article helpful?

Related Articles