Radicale/configuration.md

---
layout: page
title: Configuration
permalink: /configuration/
---

Radicale can be configured with a configuration file or with
command line arguments.

An example configuration file looks like:
```ini
[server]
hosts = 0.0.0.0:5232  # Bind all addresses
[auth]
type = htpasswd
htpasswd_filename = /path/to/users
htpasswd_encryption = bcrypt
[storage]
filesystem_folder = ~/.var/lib/radicale/collections
```

Radicale tries to load configuration files from */etc/radicale/config*,
*~/.config/radicale/config* and the ``RADICALE_CONFIG`` environment variable.
This behaviour can be overwritten by specifying a path with the
``--config /path/to/config`` command line argument.

The same example configuration via command line arguments looks like:
```sh
python3 -m radicale --config "" --server-hosts 0.0.0.0:5232 --auth-type htpasswd --htpasswd-filename /path/to/htpasswd --htpasswd-encryption bcrypt
```

The ``--config ""`` argument is required to stop Radicale from trying
to load configuration files. Run ``python3 -m radicale --help`` for more information.

In the following, all configuration categories and options are described.

## server
Most configuration options in this category are only relevant in standalone
mode. All options beside ``max_content_length`` and ``realm`` are ignored,
when Radicale runs via WSGI.

### hosts
A comma separated list of addresses that the server will bind to.

Default: ``127.0.0.1:5555``

### daemon
Daemonize the Radicale process. It does not reset the umask or double fork.

Default: ``False``

### pid
If daemon mode is enabled, Radicale will write its PID to this file.

Default:

### max_connections
The maximum number of parallel connections. Set to ``0`` to disable the limit.

Default: ``20``

### max_content_length
The maximum size of the request body. (bytes)

Default ``10000000``

### ssl
Enable transport layer encryption.

Default: ``False``

### key
Path to the private key for SSL. Only effective if ``ssl`` is enabled.

Default: ``/etc/ssl/radicale.key.pem``

### protocol
SSL protocol used. See python's ssl module for available values.

Default: ``PROTOCOL_TLSv1_2``

### ciphers
Available ciphers for SSL. See python's ssl module for available ciphers.

Default:

### dns_lookup
Reverse DNS to resolve client address in logs.

Default: ``True``

### realm
Message displayed in the client when a password is needed.

Default: ``Radicale - Password Required``

## encoding
### request
Encoding for responding requests.

Default: ``utf-8``

### stock
Encoding for storing local collections

Default: ``utf-8``

## auth
### type
The method to verify usernames and passwords.

Available backends:

`None`
: Just allows all usernames and passwords.

`htpasswd`
: Use an [Apache htpasswd file](https://httpd.apache.org/docs/current/programs/htpasswd.html) to store
  usernames and passwords.

Default: ``None``

### htpasswd_filename
Path to the htpasswd file.

Default:

### htpasswd_encryption
The encryption method that is used in the htpasswd file. Use the
[htpasswd](https://httpd.apache.org/docs/current/programs/htpasswd.html)
or similar to generate this files.

Available methods:

`plain`
: Passwords are stored in plaintext. This is obviously not secure!
  The htpasswd file for this can be created by hand and looks like:
  ```htpasswd
  user1:password1
  user2:password2
  ```

`bcrypt`
: This uses a modified version of the Blowfish stream cipher. It's very secure.
  The **passlib** python module is required for this. Additionally you may need
  one of the following python modules: **bcrypt**, **py-bcrypt** or **bcryptor**.

`md5`
: This uses an iterated md5 digest of the password with a salt.
  The **passlib** python module is required for this.

`sha1`
: Passwords are stored as SHA1 hashes. It's insecure!

`ssha`
: Passwords are stored as salted SHA1 hashes. It's insecure!

`crypt`
: This uses UNIX [crypt(3)](http://man7.org/linux/man-pages/man3/crypt.3.html).
  It's insecure!

Default: ``bcrypt``

## rights
### type
The backend that is used to check the access rights of collections.

Available backends:

`None`
: Everyone can read and write everything.

`authenticated`
: Authenticated users can read and write everything.

`owner_only`
: Authenticated users can read and write their own collections under the path
  */USERNAME/*.

`owner_write`
: Authenticated users can read everything and write their own collections under
  the path */USERNAME/*.

`from_file`
: Load the rules from a file.

Default: ``owner_only``

### file
File for the rights backend ``from_file``.  See the
[Rights]({{ site.baseurl }}/logging/) page.

## storage
### type
The backend that is used to store data.

Available backends:

`multifilesystem`
: Stores the data in the filesystem.

Default: ``multifilesystem``

### 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
power fails!

Default: ``True``

### hook
Command that is run after changes to storage. Take a look at the
[Versioning]({{ site.baseurl }}/versioning/) page for an example.

Default:

## logging
## debug
Set the default logging level to debug.

Default: ``False``

### full_environment
Log all environment variables (including those set in the shell).

Default: ``False``

### mask_passwords
Don't include passwords in logs.

Default: ``True``

### config
Logging configuration file. See the [Logging]({{ site.baseurl }}/logging/) page.

Default:

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

An example to relax the same-origin policy:
```ini
Access-Control-Allow-Origin = *
```