Roundcube Plus Help Desk

Knowledgebase
Search help:

How do I setup CalDAV with the calendar plugin?

The Roundcube Plus calendar plugin comes with a CalDAV server that makes it possible for the users to connect to their Roundcube calendars with programs like iOS Calendar, Thunderbird, Outlook, Evolution, or any other CalDAV-enabled client.

HOW DOES IT WORK?

When the CalDAV server is properly set up and enabled, the users can create CalDAV connections for any of their local Roundcube calendars. This is done by editing the calendar and clicking on the "Sync calendar" tab.

The connections can be set up as writable or read-only. The user can create an unlimited number of connections per calendar.

When creating a new connection, the username will be generated automatically and the password will be provided by the user. Connection usernames must be unique system-wide and creating them automatically provides the simplest user experience.

SERVER COMPATIBILITY

The CalDAV functionality should work properly with:

  • Apache 2 with mod_php,
  • Nginx 1.3.9 or higher,

It might not work properly with:

  • Lighttpd
  • IIS

The CalDAV login process requires the server to include the authentication information in the headers. If the server doesn't do this, you won't be able to log in to the CalDAV server. This might happen if you run the CalDAV subdomain without a proper SSL certificate or run PHP over CGI or FastCGI. For more information see this FAQ: http://sabre.io/dav/faq.

CLIENT COMPATIBILITY

Theoretically the CalDAV server should work properly with any CalDAV-enabled app or program. However, some programs might implement the CalDAV functionality better than others. For example, it has been reported that some versions of the Synchronizer addon for Outlook have problems with refreshing calendar events. Since this is an app-specific issue, we're not able to fix it.

Here's the list of apps we have tested the server with:

  • iOS Calendar
  • Mac OS X Calendar
  • Thunderbird (using the Lightning extension; Windows / Linux)
  • emClient (Windows)
  • Outlook (using CalDAV Synchronizer; Windows)
  • Evolution (Linux)

REQUIREMENTS

Subdomain pointing to the CalDAV root

In other to use the CalDAV server, you must create a new subdomain and point it to this directory:

[your_roundcube_installation]/plugins/xcalendar/caldav

The goal is to have the above-mentioned directory available at the root of your url, for example:

https://caldav.example.com

The users will use this URL (along with a calendar-specific path) as the CalDAV address when setting up their calendars in third-party apps.

There's one problem with this approach. Because some apps, for example Thunderbird, store the username and password for the domain and don't take into consideration url paths, having a hard-coded subdomain will only allow the users to add one calendar. If a user creates another calendar and tries to add it to Thunderbird, it won't work.

Before we present the solution, let's explain the problem. Say, you have two calendars and you create a CalDAV connection for each one. You'll have a different URL, username, and password for each calendar, but they will both be based on the same subdomain. You'll be able to add the first calendar to Thunderbird without any problems. It will ask you for the URL, username and password. But it'll then turn around and store that username and password and assign it to the subdomain.

If you try to add the second calendar, Thunderbird will never ask you for the username and password because it will think it already knows it: it will try to use the username/password from your first calendar for your second calendar because the subdomain is the same. The connection will fail and you will not be able to use the second calendar. This is a limitation of Thunderbird that we're not able to fix.

The solution is to create a wildcard subdomain for the CalDAV server:

https://*.caldav.example.com

The calendar plugin will replace the asterisk in the URL with the username of the caldav connection, thus making each subdomain unique:

https://3eul54w1do.caldav.example.com
https://k5iti5sd1y.caldav.example.com
https://56uqf4nz61.caldav.example.com
etc.

Now Thunderbird will store the username and password for each unique URL and the users will be able to use any number of calendars in Thunderbird.

2. Apache Server

The CalDAV server depends on the Apache rewrite rules specified in this file:

[your_roundcube_installation]/plugins/xcalendar/caldav/.htaccess

If you use a different web server, make sure to add the equivalent server-specific rules for that directory.

SETUP

To enable the CalDAV server follow these steps:

1. Create a subdomain as explained in REQUIREMENTS above.

2. Edit the file [roundcube]/plugins/xcalendar/config.inc.php and specify your subdomain in the option "xcalendar_caldav_server_domain", for example:

$config['xcalendar_caldav_server_domain'] = 'https://*.caldav.example.com';

3. Enable the CalDAV server by setting the "xcalendar_caldav_server_enabled" option in the same config file to true, like this:

$config['xcalendar_caldav_server_enabled'] = true;

If your config file doesn't have the options xcalendar_caldav_server_domain and xcalendar_caldav_server_enabled, simply add them at the end of the file.

TROUBLESHOOTING

CPANEL PROBLEMS

If you're using the calendar on a cPanel Roundcube installation, your server security settings might not allow you to point a subdomain to the directory where Roundcube is installed, since it's outside of your server's document root. You may need to create an exception or relax your security settings to make this work, or install a new version of Roundcube.

LOGIN PROBLEMS

The first step to troubleshooting the CalDAV server problems is to create a new CalDAV connection in Roundcube and then navigate to the CalDAV URL in your browser. The browser should pop up a login dialog.

If your server's authentication is working properly, you will see this message after you type your connection's username and password:

"There was no plugin in the system that was willing to handle this GET method. Enable the Browser plugin to get a better result here."

You have successfully logged in to the server, but the browser doesn't know how to handle the CalDAV request, which is normal.

If you type your connection's username and password but you can't log in (you get the login popup over and over again) it might mean that your server strips the authentication header from the request and doesn't pass it on to PHP. In other words the username/password information you type in the browser never gets passed on to the program.

This might happen on some servers if the CalDAV URL doesn't use SSL. It's also been known to happen on Windows servers with or without SSL.

To fix this, edit the file plugins/xcalendar/caldav/.htaccess and uncomment the following line:

# SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

To uncomment the line remove the #.

OTHER PROBLEMS

If you're able to log in to the CalDAV server, but you're still experiencing problems, you should enable the server's browser navigation functionality. This functionality will help you navigate your CalDAV principals (connection usernames,) calendars, and events right from your browser and see them just like a CalDAV client application would. As you try to navigate your CalDAV server, any errors should become quickly apparent.

To enable the browser navigation of your CalDAV server, uncomment this line at the end of the file plugins/xcalendar/caldav/index.php:

// $server->addPlugin(new Sabre\DAV\Browser\Plugin());

To uncomment the line remove the //.

If you get 'File not found' errors while browsing your server, you may need to modify the CalDAV .htaccess redirect rule. Edit the file plugins/xcalendar/caldav/.htaccess and change this line according to your server's requirements:

RewriteRule ^(.*)$ /index.php/$1 [L]

For example, this works on some Windows servers:

RewriteRule . index.php [L]

Was this article helpful? yes / no