Security: Untrusted clients should not be able to
access the Radicale server directly. Otherwise, they can authenticate as
@@ -633,16 +681,22 @@ 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
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
[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/;
@@ -661,15 +715,15 @@ values don't matter and you can keep the defaults.
environment variable, otherwise no configuration file is loaded and the
default configuration is used.
Example uWSGI configuration:
-[uwsgi]
-http-socket = 127.0.0.1:5232
-processes = 8
-plugin = python3
-module = radicale
-env = RADICALE_CONFIG=/etc/radicale/config
[uwsgi]
+http-socket = 127.0.0.1:5232
+processes = 8
+plugin = python3
+module = radicale
+env = RADICALE_CONFIG=/etc/radicale/config
Example Gunicorn configuration:
-gunicorn --bind '127.0.0.1:5232' --env 'RADICALE_CONFIG=/etc/radicale/config' \
- --workers 8 radicale
gunicorn --bind '127.0.0.1:5232' --env 'RADICALE_CONFIG=/etc/radicale/config' \
+ --workers 8 radicale
Manage user accounts with the WSGI server
Set the configuration option type in the
@@ -692,9 +746,18 @@ content:
.Radicale.tmp-*
The configuration option hook in the
storage section must be set to the following command:
-git add -A && (git diff --cached --quiet || git commit -m "Changes by "%(user)s)
git add -A && (git diff --cached --quiet || git commit -m "Changes by \"%(user)s\"")
The command gets executed after every change to the storage and
commits the changes into the git repository.
+For the hook to not cause errors either git user
+details need to be set and match the owner of the collections directory
+or the repository needs to be marked as safe.
+When using the systemd unit file from the Running as a service section this
+cannot be done via a .gitconfig file in
+the users home directory, as Radicale won't have read permissions!
+In /var/lib/radicale/collections/.git run:
+git config user.name "radicale"
+git config user.email "radicale@example.com"
Radicale can be configured with a configuration file or with command
line arguments.
An example configuration file looks like:
-[server]
-# Bind all addresses
-hosts = 0.0.0.0:5232, [::]:5232
-
-[auth]
-type = htpasswd
-htpasswd_filename = ~/.config/radicale/users
-htpasswd_encryption = md5
-
-[storage]
-filesystem_folder = ~/.var/lib/radicale/collections
[server]
+# Bind all addresses
+hosts = 0.0.0.0:5232, [::]:5232
+
+[auth]
+type = htpasswd
+htpasswd_filename = ~/.config/radicale/users
+htpasswd_encryption = autodetect
+
+[storage]
+filesystem_folder = ~/.var/lib/radicale/collections
Radicale tries to load configuration files from
/etc/radicale/config and
~/.config/radicale/config. Custom paths can be specified
@@ -725,9 +788,9 @@ configuration files can be separated by : (resp.
optional.
The same example configuration via command line arguments looks
like:
-python3 -m radicale --server-hosts 0.0.0.0:5232,[::]:5232 \
- --auth-type htpasswd --auth-htpasswd-filename ~/.config/radicale/users \
- --auth-htpasswd-encryption md5
python3 -m radicale --server-hosts 0.0.0.0:5232,[::]:5232 \
+ --auth-type htpasswd --auth-htpasswd-filename ~/.config/radicale/users \
+ --auth-htpasswd-encryption autodetect
Add the argument --config "" to stop Radicale from
loading the default configuration files. Run
python3 -m radicale --help for more information.
@@ -814,6 +877,8 @@ server.
http_x_remote_user : Takes the username from the
X-Remote-User HTTP header and disables HTTP authentication.
This can be used to provide the username from a reverse proxy.
+ldap : Use a LDAP or AD server to authenticate
+users.
Default: none
@@ -833,10 +898,16 @@ and looks like:
user2:password2
bcrypt : This uses a modified version of the Blowfish
stream cipher. It's very secure. The installation of
-radicale[bcrypt] is required for this.
-md5 : This uses an iterated md5 digest of the password
-with a salt.
-Default: md5
+bcrypt is required for this.
+md5 : This uses an iterated MD5 digest of the password
+with a salt (nowadays insecure).
+sha256 : This uses an iterated SHA-256 digest of the
+password with a salt.
+sha512 : This uses an iterated SHA-512 digest of the
+password with a salt.
+autodetect : This selects autodetection of method per
+entry.
+Default: autodetect
delay
@@ -848,6 +919,78 @@ with a salt.
Message displayed in the client when a password is needed.
Default: Radicale - Password Required
+
+ldap_uri
+The URI to the ldap server
+Default: ldap://localhost
+
+
+ldap_base
+LDAP base DN of the ldap server. This parameter must be provided if
+auth type is ldap.
+Default:
+
+
+ldap_reader_dn
+The DN of a ldap user with read access to get the user accounts. This
+parameter must be provided if auth type is ldap.
+Default:
+
+
+ldap_secret
+The password of the ldap_reader_dn. This parameter must be provided
+if auth type is ldap.
+Default:
+
+
+ldap_filter
+The search filter to find the user DN to authenticate by the
+username. User '{0}' as placeholder for the user name.
+Default: (cn={0})
+
+
+ldap_load_groups
+Load the ldap groups of the authenticated user. These groups can be
+used later on to define rights. This also gives you access to the group
+calendars, if they exist.
+
+- The group calendar will be placed under
+collection_root_folder/GROUPS
+- The name of the calendar directory is the base64 encoded group
+name.
+- The group calneder folders will not be created automaticaly. This
+must be created manualy. Here
+you can find a script to create group calneder folders https://github.com/Kozea/Radicale/wiki/LDAP-authentication
+
+Default: False
+
+
+ldap_use_ssl
+Use ssl on the ldap connection
+Default: False
+
+
+ldap_ssl_verify_mode
+The certifikat verification mode. NONE, OPTIONAL or REQUIRED
+Default: REQUIRED
+
+
+ldap_ssl_ca_file
+The path to the CA file in pem format which is used to certificate
+the server certificate
+Default:
+
+
+lc_username
+Сonvert username to lowercase, must be true for case-insensitive auth
+providers like ldap, kerberos
+Default: False
+
+
+strip_domain
+Strip domain from username
+Default: False
+
rights
@@ -875,6 +1018,22 @@ and write their own collections under the path /USERNAME/.
file
File for the rights backend from_file. See the Rights section.
+
+permit_delete_collection
+(New since 3.1.9)
+Global control of permission to delete complete collection (default:
+True)
+If False it can be permitted by permissions per section with: D If
+True it can be forbidden by permissions per section with: d
+
+
+permit_overwrite_collection
+(New since 3.3.0)
+Global control of permission to overwrite complete collection
+(default: True)
+If False it can be permitted by permissions per section with: O If
+True it can be forbidden by permissions per section with: o
+
storage
@@ -899,12 +1058,34 @@ only be used with a single process.
(seconds)
Default: 2592000
+
+skip_broken_item
+Skip broken item instead of triggering an exception
+Default: True
+
hook
Command that is run after changes to storage. Take a look at the Versioning with Git tutorial for an
example.
Default:
+
+predefined_collections
+Create predefined user collections
+Example:
+ {
+ "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"
+ }
+ }
+Default:
+
web
@@ -933,17 +1114,88 @@ books and calendars.
Don't include passwords in logs.
Default: True
+
+bad_put_request_content
+Log bad PUT request content (for further diagnostics)
+Default: False
+
+
+backtrace_on_debug
+Log backtrace on level=debug
+Default: False
+
+
+
+request_content_on_debug
+Log request on level=debug
+Default: False
+
+
+response_content_on_debug = True
+Log response on level=debug
+Default: False
+
+
+rights_rule_doesnt_match_on_debug = True
+Log rights rule which doesn't match on level=debug
+Default: False
+
+
+hook
+
+type
+Hook binding for event changes and deletion notifications.
+Available types:
+none : Disabled. Nothing will be notified.
+rabbitmq : Push the message to the rabbitmq server.
+Default: none
-
-Supported Clients
+
+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
+
+max_freebusy_occurrence
+When returning a free-busy report, a list of busy time occurrences
+are generated based on a given time frame. Large time frames could
+generate a lot of occurrences based on the time frame supplied. This
+setting limits the lookup to prevent potential denial of service attacks
+on large time frames. If the limit is reached, an HTTP error is thrown
+instead of returning the results.
+Default: 10000
+
+
+
+
+
+Supported Clients
Radicale has been tested with:
- Android with DAVx⁵ (formerly DAVdroid)
@@ -969,15 +1221,25 @@ you have to enter the URL of the collection directly (e.g.
http://localhost:5232) and your username. DAVx⁵ will show
all existing calendars and address books and you can create new.
-
Authentication and Rights
@@ -1064,24 +1327,24 @@ to calendars and address books outside the home directory of users
collections and will not show them to the user. This is only useful if
you access calendars and address books directly via URL.
An example rights file:
-# Allow reading root collection for authenticated users
-[root]
-user: .+
-collection:
-permissions: R
-
-# Allow reading and writing principal collection (same as username)
-[principal]
-user: .+
-collection: {user}
-permissions: RW
-
-# Allow reading and writing calendars and address books that are direct
-# children of the principal collection
-[calendars]
-user: .+
-collection: {user}/[^/]+
-permissions: rw
# Allow reading root collection for authenticated users
+[root]
+user: .+
+collection:
+permissions: r
+
+# Allow reading and writing principal collection (same as username)
+[principal]
+user: .+
+collection: {user}
+permissions: RW
+
+# Allow reading and writing calendars and address books that are direct
+# children of the principal collection
+[calendars]
+user: .+
+collection: {user}/[^/]+
+permissions: rw
The titles of the sections are ignored (but must be unique). The keys
user and collection contain regular
expressions, that are matched against the username and the path of the
@@ -1110,6 +1373,14 @@ expensive search requests)
W: write collections (excluding address books and
calendars)
w: write address book and calendar collections
+D: permit delete of collection in case
+permit_delete_collection=False
+d: forbid delete of collection in case
+permit_delete_collection=True
+O: permit overwrite of collection in case
+permit_overwrite_collection=False
+o: forbid overwrite of collection in case
+permit_overwrite_collection=True
@@ -1160,10 +1431,10 @@ system. The storage is locked with exclusive access while the
Linux shell scripts
Use the flock
utility.
-# Exclusive
-$ flock --exclusive /path/to/storage/.Radicale.lock COMMAND
-# Shared
-$ flock --shared /path/to/storage/.Radicale.lock COMMAND
# Exclusive
+$ flock --exclusive /path/to/storage/.Radicale.lock COMMAND
+# Shared
+$ flock --shared /path/to/storage/.Radicale.lock COMMAND
Linux and MacOS
@@ -1188,11 +1459,11 @@ folder in the file system storage (e.g.
clients that the collection is a calendar, you have to create the file
.Radicale.props with the following content in the
folder:
-
+
The calendar is now available at the URL path
/user/calendar. For address books the file must
contain:
-
+
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
@@ -1323,49 +1594,49 @@ password.
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"])
#!/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 ""
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:
-
+
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
[auth]
+type = radicale_static_password_auth
+password = secret
You can uninstall the module with:
-python3 -m pip uninstall radicale_static_password_auth
python3 -m pip uninstall radicale_static_password_auth
Authentication plugins
@@ -1403,11 +1674,6 @@ more information.
Contribute
-
-Chat with Us on IRC
-Want to say something? Join our IRC room: ##kozea on
-Freenode.
-
Documentation
-To change or complement the documentation create a pull request to DOCUMENTATION.md.
+To change or complement the documentation create a pull request to DOCUMENTATION.md.
@@ -1429,14 +1695,14 @@ you want to add new features, fix bugs or update the documentation.
PyPI
Radicale is available on PyPI. To
install, just type as superuser:
-python3 -m pip install --upgrade radicale
python3 -m pip install --upgrade radicale
Git Repository
If you want the development version of Radicale, take a look at the
git repository on
GitHub, or install it directly with:
-python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
You can also download the content of the repository as an archive.