Back to website

Roundcube Plus Roundcube Plus Help Desk Knowledgebase Plugins
How do I setup CalDAV with the calendar plugin?

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
  • cPanel/WHM

cPanel does not provide a static url to access Roundcube and it does not allow creating subdomains that point to the Roundcube directory, so it's not possible to set up an access point for the xcalendar CalDAV server.

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)

SETUP

1. Subdomain setup

The first thing to do in order to set up the CalDAV server is to create a new subdomain and point it to this directory:

[your_roundcube_installation]/plugins/xcalendar/caldav

Make sure that when you navigate to your caldav URL, for example:

https://caldav.example.com

the server will serve the content from the the above mentioned directory, not from the root directory where your Roundcube is installed.

But wait... it's better to use a wildcard subdomain. Here's why: 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.

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 / Nginx Setup

In order for the CalDAV server to work properly, all the request URLs need to be routed through xcalendar/caldav/index.php. What this means is that when you (or a CalDAV client program) navigate to this CalDAV URL:

https://caldav.com/calendars/3iydlr7a2f/

the server will not try to serve the contents of the directory xcalendar/caldav/calendars/3iydlr7a2f (which doesn't exist) but will serve the file xcalendar/caldav/index.php with the calendar parameters appended as a string, like this:

https://caldav.com/index.php/calendars/3iydlr7a2f/

The CalDAV PHP script will then extract that extra texts, parse it as parameters and use it to serve the correct content.

If you're using Apache, this rewriting should work out-of-the box because of the xcalendar/caldav/.htaccess file that includes all the necessary rewrite rules. If it doesn't work, make sure the Apache rewrite module is installed. If you're still having problems, edit the .htaccess file and modify the rewrite rule. For example, this works on some Windows servers: RewriteRule . index.php [L]

Unlike Apache, Nginx doesn't read .htaccess files, so you'll need to add the correct rewrite rules to the nginx configuration file. Here's an example of the nginx server section with the rewrite rules included:

server {
    listen 443 ssl;
    server_name <your-caldav-domain>;
    root <your-roundcube-directory>/plugins/xcalendar/caldav;
    index index.php;

    location / {
        rewrite ^/\.well-known/caldav.*$ /index.php/ redirect;

        if (!-e $request_filename){
            rewrite ^(.*)$ /index.php/$1 break;
        }

        fastcgi_pass unix:/var/run/php/php-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param REQUEST_URI $request_uri;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    location ~ /\.ht {
        deny all;
    }
}

3. The xcalendar plugin setup

Now that the domain and the server are set up, we need to let the xcalendar plugin know which domain will be used for the CalDAV server.

1. 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';

2. 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

The first step to troubleshooting the CalDAV server problems is to enable the CalDAV browser plugin which will enable you to browse the CalDAV server using your browser. Edit the file plugins/xcalendar/config.inc.php and set the 'xcalendar_caldav_enable_browser_plugin' option to true:

$config['xcalendar_caldav_enable_browser_plugin'] = true;

If this option doesn't exist in your config file, just add it at the end.

Now create a new CalDAV connection in Roundcube (if you haven't done it already) and navigate to the CalDAV URL in your browser. The browser should pop up a login dialog. Remember that the username it's asking for is not your Roundcube username but the CalDAV connection username.

If you're not able to log in...

...in other words, you get the login popup over and over again, it probably means 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.

If you're using Apache, edit the file xcalendar/caldav/.htaccess and uncomment the following line:

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

(To uncomment the line remove the #.)

If you're able to login but can't navigate...

...in other words, the home page displays fine, but as soon as you click anywhere you get 404 or 403 errors, it means that the URL rewriting is not working properly. Go back to the section "Apache / Nginx Setup" above to make sure the server is set up properly.

If you're getting PHP require_once errors...

...saying that a file under the directory [roundcube_directory]/program/lib/Roundcube cannot be loaded, it probably means that the Roundcube library files on your server are not located under your Roundcube installation directory. In that case, you'll need to find the Roundcube library and create a soft link to make sure it appears under [roundcube_directory]/program/lib.

For example, if the Roundcube library is located under /usr/share/php7/Roundcube and your Roundcube installation is installed under /srv/www/roundcubemail, you'll need to make a soft link like this:

ln -s /usr/share/php7/Roundcube /srv/www/roundcubemail/program/lib/

If it works...

...congratulations! Now don't forget to disable the browser plugin in the xcalendar config file.

If it still doesn't work...

...create a helpdesk ticket describing the problem and we'll try to help. Describe your setup and attach some screenshots if you can, they're usually helpful.

 

Article Details

Article ID:
30
Category:
Plugins

Related articles