From 326859e53ec4cb59a8a524ac296e1c6e92cdae1f Mon Sep 17 00:00:00 2001 From: Unrud Date: Wed, 7 Jun 2017 21:39:54 +0200 Subject: [PATCH] Document features of the development version --- configuration.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++ plugins.md | 8 +++++++ proxy.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++ use.md | 14 +++++++---- wsgi.md | 8 +++++++ 5 files changed, 143 insertions(+), 5 deletions(-) diff --git a/configuration.md b/configuration.md index c4ce63a1..3866eeed 100644 --- a/configuration.md +++ b/configuration.md @@ -86,6 +86,17 @@ Path to the private key for SSL. Only effective if `ssl` is enabled. Default: `/etc/ssl/radicale.key.pem` +### certificate_authority + +(This feature is only available in the development version!) + +Path to the CA certificate for validating client certificates. This can be used +to secure TCP traffic between Radicale and a reverse proxy. If you want to +authenticate users with client-side certificates, you also have to write an +authentication plugin that extracts the user name from the certifcate. + +Default: + ### protocol SSL protocol used. See python's ssl module for available values. @@ -130,6 +141,20 @@ Available backends: : Use an [Apache htpasswd file](https://httpd.apache.org/docs/current/programs/htpasswd.html) to store usernames and passwords. +`remote_user` +: (This feature is only available in the development version!) + + Takes the user name from the `REMOTE_USER` environment variable and disables + HTTP authentication. This can be used to provide the user name from a WSGI + server. + +`http_x_remote_user` +: (This feature is only available in the development version!) + + Takes the user name from the `X-Remote-User` HTTP header and disables HTTP + authentication. This can be used to provide the user name from a reverse + proxy. + Default: `None` ### htpasswd_filename @@ -226,6 +251,24 @@ Folder for storing local collections, created if not present. Default: `/var/lib/radicale/collections` +### filesystem_locking + +(This setting is only available in the development version!) + +Lock the storage. This must be disabled if locking is not supported by the +underlying file system. Never start multiple instances of Radicale or edit the +storage externally while Radicale is running if disabled. + +Default: `True` + +### max_sync_token_age + +(This feature is only available in the development version!) + +Delete sync-token that are older than the specified time. (seconds) + +Default: `2592000` + ### filesystem_fsync Sync all changes to disk during requests. (This can impair performance.) Disabling it increases the risk of data loss, when the system crashes or @@ -239,6 +282,21 @@ Command that is run after changes to storage. Take a look at the Default: +## web +### type + +(This feature is only available in the development version!) + +The backend that provides the web interface of Radicale. + +`none` +: Just shows the message "Radicale works!". + +`internal` +: Allows creation and management of address books and calendars. + +Default: `internal` + ## logging ## debug Set the default logging level to debug. diff --git a/plugins.md b/plugins.md index fa880e08..e0d00de1 100644 --- a/plugins.md +++ b/plugins.md @@ -62,6 +62,14 @@ The module must contain a class `Rights` that extends `radicale.rights.BaseRights`. Take a look at the file `radicale/rights.py` in Radicale's source code for more information. +## Web plugins +(This feature is only available in the development version!) + +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.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 `Collection` that extends diff --git a/proxy.md b/proxy.md index 97d4f4b8..203f71b4 100644 --- a/proxy.md +++ b/proxy.md @@ -21,3 +21,63 @@ location /radicale/ { # The trailing / is important! Be reminded that Radicale's default configuration enforces limits on the maximum number of parallel connections, the maximum file size and the rate of incorrect authentication attempts. Connections are terminated after a timeout. + +## Manage user accounts with the reverse proxy + +(This feature is only available in the development version!) + +Set the configuration option `type` in the `auth` section to +`http_x_remote_user`. +Radicale uses the user name provided in the `X-Remote-User` HTTP header and +disables HTTP authentication. + +Example **nginx** configuration: + +```nginx +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; + auth_basic "Radicale - Password Required"; + auth_basic_user_file /etc/nginx/htpasswd; +} +``` + +## Secure connection between Radicale and the reverse proxy + +(This feature is only available in the development version!) + +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. + +```shell +$ 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: + +```ini +[server] +ssl = True +certificate = /path/to/server_cert.pem +key = /path/to/server_key.pem +certificate_authority = /path/to/client_cert.pem +``` + +Example **nginx** configuration: + +```nginx +location /radicale/ { + ... + # 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; + proxy_ssl_trusted_certificate /path/to/server_cert.pem; +} +``` diff --git a/use.md b/use.md index 06e8c355..4533090d 100644 --- a/use.md +++ b/use.md @@ -20,10 +20,10 @@ Radicale has been tested with: Many clients do not support the creation of new calendars and address books. You have to use another client for this or create them manually -(unfortunately this is quite complicated). A future release of Radicale 2.x.x -will come with a built-in web interface that lets you create and manage -collections conveniently. Manual creation of -calendars and address books is described in the last chapter. +(unfortunately this is quite complicated). The development version of Radicale +has a web interface that lets you create and manage collections conveniently. +Manual creation of calendars and address books is described in +the last chapter. In some clients you can just enter the URL of the Radicale server (e.g. `http://localhost:5232`) and your user name. In others, you have to @@ -70,11 +70,15 @@ the Radicale server, because of the You have to add additional HTTP header in the `headers` section of Radicale's configuration. The documentation of **InfCloud** has more details on this. +In the development version of Radicale you can integrate InfCloud directly with +[RadicaleInfCloud](https://github.com/Unrud/RadicaleInfCloud). + ## Manual creation of calendars and address books This is not the recommended way of creating and managing your calendars and address books. Use a client with support for it if possible -(e.g. **DAVdroid**). +(e.g. **DAVdroid**). The development version of Radicale has a web interface +that lets you create and manage collections conveniently. ### Direct editing of the storage diff --git a/wsgi.md b/wsgi.md index 540c042b..ec010bfe 100644 --- a/wsgi.md +++ b/wsgi.md @@ -16,3 +16,11 @@ the `remote_user` module for this use-case. Be reminded that Radicale's default configuration enforces limits on the maximum upload file size. + +## Manage user accounts with the WSGI server + +(This feature is only available in the development version!) + +Set the configuration option `type` in the `auth` section to `remote_user`. +Radicale uses the user name provided by the WSGI server and disables +authentication over HTTP.