Radicale v3 master v3 v2 v1

Linux / *BSD ¶

First, make sure that python 3.8 or later and pip are installed. On most distributions it should be enough to install the package python3-pip.

Then open a console and type:

# Run the following command as root or
# add the --user argument to only install for the current user
$ python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
$ python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections

Victory! Open http://localhost:5232 in your browser! You can log in with any username and password.

Windows ¶

The first step is to install Python. Go to python.org and download the latest version of Python 3. Then run the installer. On the first window of the installer, check the "Add Python to PATH" box and click on "Install now". Wait a couple of minutes, it's done!

Launch a command prompt and type:

python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
python -m radicale --storage-filesystem-folder=~/radicale/collections

Victory! Open http://localhost:5232 in your browser! You can log in with any username and password.

Authentication ¶

In its default configuration Radicale doesn't check usernames or passwords. If the server is reachable over a network, you should change this.

First a users file with all usernames and passwords must be created. It can be stored in the same directory as the configuration file.

# Create a new htpasswd file with the user "user1" using SHA-512 as hash method
$ htpasswd -5 -c /path/to/users user1
New password:
Re-type new password:
# Add another user
$ htpasswd -5 /path/to/users user2
New password:
Re-type new password:

[auth]
type = htpasswd
htpasswd_filename = /path/to/users
htpasswd_encryption = autodetect

user1:password1
user2:password2

[auth]
type = htpasswd
htpasswd_filename = /path/to/users
# encryption method used in the htpasswd file
htpasswd_encryption = plain

Addresses ¶

The default configuration binds the server to localhost. It can't be reached from other computers. This can be changed with the following configuration options (IPv4 and IPv6):

[server]
hosts = 0.0.0.0:5232, [::]:5232

Storage ¶

Data is stored in the folder /var/lib/radicale/collections. The path can be changed with the following configuration:

[storage]
filesystem_folder = /path/to/storage

Security: The storage folder should not be readable by unauthorized users. Otherwise, they can read the calendar data and lock the storage. You can find OS dependent instructions in the Running as a service section.

Limits ¶

Radicale enforces limits on the maximum number of parallel connections, the maximum file size (important for contacts with big photos) and the rate of incorrect authentication attempts. Connections are terminated after a timeout. The default values should be fine for most scenarios.

[server]
max_connections = 20
# 100 Megabyte
max_content_length = 100000000
# 30 seconds
timeout = 30

[auth]
# Average delay after failed login attempts in seconds
delay = 1

Linux with systemd system-wide ¶

Recommendation: check support by Linux Distribution Packages instead of manual setup / initial configuration.

Create the radicale user and group for the Radicale service. (Run useradd --system --user-group --home-dir / --shell /sbin/nologin radicale as root.) The storage folder must be writable by radicale. (Run mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections as root.)

Security: The storage should not be readable by others. (Run chmod -R o= /var/lib/radicale/collections as root.)

Create the file /etc/systemd/system/radicale.service:

[Unit]
Description=A simple CalDAV (calendar) and CardDAV (contact) server
After=network.target
Requires=network.target

[Service]
ExecStart=/usr/bin/env python3 -m radicale
Restart=on-failure
User=radicale
# Deny other users access to the calendar data
UMask=0027
# Optional security settings
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
PrivateDevices=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
NoNewPrivileges=true
ReadWritePaths=/var/lib/radicale/collections

[Install]
WantedBy=multi-user.target

Radicale will load the configuration file from /etc/radicale/config.

To enable and manage the service run:

# Enable the service
$ systemctl enable radicale
# Start the service
$ systemctl start radicale
# Check the status of the service
$ systemctl status radicale
# View all log messages
$ journalctl --unit radicale.service

Linux with systemd as a user ¶

Create the file ~/.config/systemd/user/radicale.service:

[Unit]
Description=A simple CalDAV (calendar) and CardDAV (contact) server

[Service]
ExecStart=/usr/bin/env python3 -m radicale
Restart=on-failure

[Install]
WantedBy=default.target

Radicale will load the configuration file from ~/.config/radicale/config. You should set the configuration option filesystem_folder in the storage section to something like ~/.var/lib/radicale/collections.

To enable and manage the service run:

# Enable the service
$ systemctl --user enable radicale
# Start the service
$ systemctl --user start radicale
# Check the status of the service
$ systemctl --user status radicale
# View all log messages
$ journalctl --user --unit radicale.service

Windows with "NSSM - the Non-Sucking Service Manager" ¶

First install NSSM and start nssm install in a command prompt. Apply the following configuration:

• Service name: Radicale
• Application
  • Path: C:\Path\To\Python\python.exe
  • Arguments: -m radicale --config C:\Path\To\Config
• I/O redirection
  • Error: C:\Path\To\Radicale.log

Security: Be aware that the service runs in the local system account, you might want to change this. Managing user accounts is beyond the scope of this manual. Also, make sure that the storage folder and log file is not readable by unauthorized users.

The log file might grow very big over time, you can configure file rotation in NSSM to prevent this.

The service is configured to start automatically when the computer starts. To start the service manually open Services in Computer Management and start the Radicale service.

Manage user accounts with the reverse proxy ¶

Set the configuration option type in the auth section to http_x_remote_user. Radicale uses the username provided in the X-Remote-User HTTP header and disables HTTP authentication.

Example nginx configuration:

location /radicale/ {
    proxy_pass           http://localhost:5232/;
    proxy_set_header     X-Script-Name /radicale;
    proxy_set_header     X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header     X-Remote-User $remote_user;
    proxy_set_header     Host $http_host;
    auth_basic           "Radicale - Password Required";
    auth_basic_user_file /etc/nginx/htpasswd;
}

Example Caddy configuration:

handle_path /radicale/* {
    uri strip_prefix /radicale
    basicauth {
        USER HASH
    }
    reverse_proxy localhost:5232 {
        header_up X-Script-Name /radicale
        header_up X-remote-user {http.auth.user.id}
    }
}

Example Apache configuration:

RewriteEngine On
RewriteRule ^/radicale$ /radicale/ [R,L]

<Location "/radicale/">
    AuthType     Basic
    AuthName     "Radicale - Password Required"
    AuthUserFile "/etc/radicale/htpasswd"
    Require      valid-user

    ProxyPass        http://localhost:5232/ retry=0
    ProxyPassReverse http://localhost:5232/
    RequestHeader    set X-Script-Name /radicale
    RequestHeader    set X-Remote-User expr=%{REMOTE_USER}
</Location>

Example Apache .htaccess configuration:

DirectoryIndex disabled
RewriteEngine On
RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]

AuthType     Basic
AuthName     "Radicale - Password Required"
AuthUserFile "/etc/radicale/htpasswd"
Require      valid-user

# Set to directory of .htaccess file:
RequestHeader set X-Script-Name /radicale
RequestHeader set X-Remote-User expr=%{REMOTE_USER}

Security: Untrusted clients should not be able to access the Radicale server directly. Otherwise, they can authenticate as any user.

Secure connection between Radicale and the reverse proxy ¶

SSL certificates can be used to encrypt and authenticate the connection between Radicale and the reverse proxy. First you have to generate a certificate for Radicale and a certificate for the reverse proxy. The following commands generate self-signed certificates. You will be asked to enter additional information about the certificate, the values don't matter and you can keep the defaults.

openssl req -x509 -newkey rsa:4096 -keyout server_key.pem -out server_cert.pem \
        -nodes -days 9999
openssl req -x509 -newkey rsa:4096 -keyout client_key.pem -out client_cert.pem \
        -nodes -days 9999

Use the following configuration for Radicale:

[server]
ssl = True
certificate = /path/to/server_cert.pem
key = /path/to/server_key.pem
certificate_authority = /path/to/client_cert.pem

If you're using the Let's Encrypt's Certbot, the configuration should look similar to this:

[server]
ssl = True
certificate = /etc/letsencrypt/live/{Your Domain}/fullchain.pem
key = /etc/letsencrypt/live/{Your Domain}/privkey.pem

Example nginx configuration:

location /radicale/ {
    proxy_pass https://localhost:5232/;
    ...
    # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...).
    proxy_ssl_certificate         /path/to/client_cert.pem;
    proxy_ssl_certificate_key     /path/to/client_key.pem;
}

Manage user accounts with the WSGI server ¶

Set the configuration option type in the auth section to remote_user. Radicale uses the username provided by the WSGI server and disables authentication over HTTP.

server ¶

The configuration options in this category are only relevant in standalone mode. All options are ignored, when Radicale runs via WSGI.

encoding ¶

auth ¶

user1:password1
user2:password2

rights ¶

storage ¶

 {
   "def-addressbook": {
      "D:displayname": "Personal Address Book",
      "tag": "VADDRESSBOOK"
   },
   "def-calendar": {
      "C:supported-calendar-component-set": "VEVENT,VJOURNAL,VTODO",
      "D:displayname": "Personal Calendar",
      "tag": "VCALENDAR"
   }
 }

web ¶

logging ¶

headers ¶

In this section additional HTTP headers that are sent to clients can be specified.

An example to relax the same-origin policy:

Access-Control-Allow-Origin = *

hook ¶

rabbitmq_endpoint ¶

End-point address for rabbitmq server. Ex: amqp://user:password@localhost:5672/

Default:

rabbitmq_topic ¶

RabbitMQ topic to publish message.

Default:

rabbitmq_queue_type ¶

RabbitMQ queue type for the topic.

Default: classic

reporting ¶

Adress books with CardBook add-on ¶

Add a new address book on the network with CardDAV. Enter the URL of the Radicale server (e.g. http://localhost:5232) and your username and password. It will list your existing address books.

Layout ¶

The file system contains the following files and folders:

• .Radicale.lock: The lock file for locking the storage.
• collection-root: This folder contains all collections and items.

A collection is represented by a folder. This folder may contain the file .Radicale.props with all WebDAV properties of the collection encoded as JSON.

An item is represented by a file containing the iCalendar data.

All files and folders, whose names start with a dot but not .Radicale. (internal files) are ignored.

If you introduce syntax errors in any of the files, all requests that access the faulty data will fail. The logging output should contain the names of the culprits.

Caches and sync-tokens are stored in the .Radicale.cache folder inside of collections. This folder may be created or modified, while the storage is locked for shared access. In theory, it should be safe to delete the folder. Caches will be recreated automatically and clients will be told that their sync-token isn't valid anymore.

You may encounter files or folders that start with .Radicale.tmp-. Radicale uses them for atomic creation and deletion of files and folders. They should be deleted after requests are finished but it's possible that they are left behind when Radicale or the computer crashes. It's safe to delete them.

Locking ¶

When the data is accessed by hand or by an externally invoked script, the storage must be locked. The storage can be locked for exclusive or shared access. It prevents Radicale from reading or writing the file system. The storage is locked with exclusive access while the hook runs.

# Exclusive
$ flock --exclusive /path/to/storage/.Radicale.lock COMMAND
# Shared
$ flock --shared /path/to/storage/.Radicale.lock COMMAND

Manually creating collections ¶

To create a new collection, you have to create the corresponding folder in the file system storage (e.g. collection-root/user/calendar). To tell Radicale and clients that the collection is a calendar, you have to create the file .Radicale.props with the following content in the folder:

{"tag": "VCALENDAR"}

The calendar is now available at the URL path /user/calendar. For address books the file must contain:

{"tag": "VADDRESSBOOK"}

Calendar and address book collections must not have any child collections. Clients with automatic discovery of collections will only show calendars and address books that are direct children of the path /USERNAME/.

Delete collections by deleting the corresponding folders.

Protocol overview ¶

Here is a simple overview of the global architecture for reaching a calendar or an address book through network:

Radicale is only the server part of this architecture.

Please note that:

• CalDAV and CardDAV are superset protocols of WebDAV,
• WebDAV is a superset protocol of HTTP.

Radicale being a CalDAV/CardDAV server, it also can be seen as a special WebDAV and HTTP server.

Radicale is not the client part of this architecture. It means that Radicale never draws calendars, address books, events and contacts on the screen. It only stores them and give the possibility to share them online with other people.

If you want to see or edit your events and your contacts, you have to use another software called a client, that can be a "normal" applications with icons and buttons, a terminal or another web application.

Code Architecture ¶

The radicale package offers the following modules.

__init__ : Contains the entry point for WSGI.

__main__ : Provides the entry point for the radicale executable and includes the command line parser. It loads configuration files from the default (or specified) paths and starts the internal server.

app : This is the core part of Radicale, with the code for the CalDAV/CardDAV server. The code managing the different HTTP requests according to the CalDAV/CardDAV specification can be found here.

auth : Used for authenticating users based on username and password, mapping usernames to internal users and optionally retrieving credentials from the environment.

config : Contains the code for managing configuration and loading settings from files.

ìtem : Internal representation of address book and calendar entries. Based on VObject.

log : The logger for Radicale based on the default Python logging module.

rights : This module is used by Radicale to manage access rights to collections, address books and calendars.

server : The integrated HTTP server for standalone use.

storage : This module contains the classes representing collections in Radicale and the code for storing and loading them in the filesystem.

web : This module contains the web interface.

utils : Contains general helper functions.

httputils : Contains helper functions for working with HTTP.

pathutils : Helper functions for working with paths and the filesystem.

xmlutils : Helper functions for working with the XML part of CalDAV/CardDAV requests and responses. It's based on the ElementTree XML API.

Getting started ¶

To get started we walk through the creation of a simple authentication plugin, that accepts login attempts with a static password.

The easiest way to develop and install python modules is Distutils. For a minimal setup create the file setup.py with the following content in an empty folder:

#!/usr/bin/env python3

from distutils.core import setup

setup(name="radicale_static_password_auth",
      packages=["radicale_static_password_auth"])

In the same folder create the sub-folder radicale_static_password_auth. The folder must have the same name as specified in packages above.

Create the file __init__.py in the radicale_static_password_auth folder with the following content:

from radicale.auth import BaseAuth
from radicale.log import logger

PLUGIN_CONFIG_SCHEMA = {"auth": {
    "password": {"value": "", "type": str}}}


class Auth(BaseAuth):
    def __init__(self, configuration):
        super().__init__(configuration.copy(PLUGIN_CONFIG_SCHEMA))

    def login(self, login, password):
        # Get password from configuration option
        static_password = self.configuration.get("auth", "password")
        # Check authentication
        logger.info("Login attempt by %r with password %r",
                    login, password)
        if password == static_password:
            return login
        return ""

Install the python module by running the following command in the same folder as setup.py:

python3 -m pip install .

To make use this great creation in Radicale, set the configuration option type in the auth section to radicale_static_password_auth:

[auth]
type = radicale_static_password_auth
password = secret

You can uninstall the module with:

python3 -m pip uninstall radicale_static_password_auth

Authentication plugins ¶

This plugin type is used to check login credentials. The module must contain a class Auth that extends radicale.auth.BaseAuth. Take a look at the file radicale/auth/__init__.py in Radicale's source code for more information.

Rights management plugins ¶

This plugin type is used to check if a user has access to a path. The module must contain a class Rights that extends radicale.rights.BaseRights. Take a look at the file radicale/rights/__init__.py in Radicale's source code for more information.

Web plugins ¶

This plugin type is used to provide the web interface for Radicale. The module must contain a class Web that extends radicale.web.BaseWeb. Take a look at the file radicale/web/__init__.py in Radicale's source code for more information.

Storage plugins ¶

This plugin is used to store collections and items. The module must contain a class Storage that extends radicale.storage.BaseStorage. Take a look at the file radicale/storage/__init__.py in Radicale's source code for more information.

Oriented to Calendar and Contact User Agents ¶

Calendar and contact servers work with calendar and contact clients, using a defined protocol. CalDAV and CardDAV are good protocols, covering lots of features and use cases, but it is quite hard to implement fully.

Some calendar servers have been created to follow the CalDAV and CardDAV RFCs as much as possible: Davical, Baïkal and Darwin Calendar Server, for example, are much more respectful of CalDAV and CardDAV and can be used with many clients. They are very good choices if you want to develop and test new CalDAV clients, or if you have a possibly heterogeneous list of user agents.

Even if it tries it best to follow the RFCs, Radicale does not and will not blindly implement the CalDAV and CardDAV standards. It is mainly designed to support the CalDAV and CardDAV implementations of different clients.

Simple ¶

Radicale is designed to be simple to install, simple to configure, simple to use.

The installation is very easy, particularly with Linux: one dependency, no superuser rights needed, no configuration required, no database. Installing and launching the main script out-of-the-box, as a normal user, are often the only steps to have a simple remote calendar and contact access.

Contrary to other servers that are often complicated, require high privileges or need a strong configuration, the Radicale Server can (sometimes, if not often) be launched in a couple of minutes, if you follow the tutorial.

Lazy ¶

The CalDAV RFC defines what must be done, what can be done and what cannot be done. Many violations of the protocol are totally defined and behaviors are given in such cases.

Radicale often assumes that the clients are perfect and that protocol violations do not exist. That is why most of the errors in client requests have undetermined consequences for the lazy server that can reply good answers, bad answers, or even no answer.