Radicale can be configured with a configuration file or with command
line arguments.
Configuration files have INI-style syntax comprising key-value pairs
grouped into sections with section headers enclosed in brackets.
You can also use command-line options in startup scripts as shown in
the following examples:
The following describes all configuration sections and options.
[server]
The configuration options in this section are only relevant in
standalone mode; they are ignored, when Radicale runs on WSGI.
hosts
A comma separated list of addresses that the server will bind to.
Default: localhost:5232
max_connections
The maximum number of parallel connections. Set to 0 to
disable the limit.
Default: 8
max_content_length
The maximum size of the request body. (bytes)
Default: 100000000
In case of using a reverse proxy in front of check also there related
option
timeout
Socket timeout. (seconds)
Default: 30
ssl
Enable transport layer encryption.
Default: False
certificate
Path of the SSL certifcate.
Default: /etc/ssl/radicale.cert.pem
key
Path to the private key for SSL. Only effective if ssl
is enabled.
Default: /etc/ssl/radicale.key.pem
certificate_authority
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 username
from the certificate.
Default: (unset)
protocol
(>= 3.3.1)
Accepted SSL protocol (maybe not all supported by underlying OpenSSL
version) Example for secure configuration: ALL -SSLv3 -TLSv1 -TLSv1.1
Format: Apache SSLProtocol list (from "mod_ssl")
Default: (system default)
ciphersuite
(>= 3.3.1)
Accepted SSL ciphersuite (maybe not all supported by underlying
OpenSSL version) Example for secure configuration: DHE:ECDHE:-NULL:-SHA
Format: OpenSSL cipher list (see also "man openssl-ciphers")
Default: (system-default)
script_name
(>= 3.5.0)
Strip script name from URI if called by reverse proxy
Default: (taken from HTTP_X_SCRIPT_NAME or SCRIPT_NAME)
[auth]
type
The method to verify usernames and passwords.
Available types are:
none
Just allows all usernames and passwords.
denyall (>= 3.2.2)
Just denies all usernames and passwords.
htpasswd
Use an Apache
htpasswd file to store usernames and passwords.
remote_user
Takes the username from the REMOTE_USER environment
variable and disables Radicale's internal HTTP authentication. This can
be used to provide the username from a WSGI server which authenticated
the client upfront. Requires validation, otherwise clients can supply
the header themselves, which then is unconditionally trusted.
http_x_remote_user
Takes the username from the X-Remote-User HTTP header and
disables Radicale's internal HTTP authentication. This can be used to
provide the username from a reverse proxy which authenticated the client
upfront. Requires validation, otherwise clients can supply the header
themselves, which then is unconditionally trusted.
ldap (>= 3.3.0)
Use a LDAP or AD server to authenticate users by relaying credentials
from clients and handle results.
dovecot (>= 3.3.1)
Use a Dovecot server to authenticate users by relaying credentials from
clients and handle results.
imap (>= 3.4.1)
Use an IMAP server to authenticate users by relaying credentials from
clients and handle results.
oauth2 (>= 3.5.0)
Use an OAuth2 server to authenticate users by relaying credentials from
clients and handle results. OAuth2 authentication (SSO) directly on
client is not supported. Use herefore http_x_remote_user in
combination with SSO support in reverse proxy (e.g.
Apache+mod_auth_openidc).
pam (>= 3.5.0)
Use local PAM to authenticate users by relaying credentials from client
and handle result..
Default: none (< 3.5.0) /
denyall (>= 3.5.0)
cache_logins
(>= 3.4.0)
Cache successful/failed logins until expiration time. Enable this to
avoid overload of authentication backends.
Default: False
cache_successful_logins_expiry
(>= 3.4.0)
Expiration time of caching successful logins in seconds
Default: 15
cache_failed_logins_expiry
(>= 3.4.0)
Expiration time of caching failed logins in seconds
Default: 90
htpasswd_filename
Path to the htpasswd file.
Default: /etc/radicale/users
htpasswd_encryption
The encryption method that is used in the htpasswd file. Use htpasswd
or similar to generate this files.
Available methods:
plain
Passwords are stored in plaintext. This is not recommended. as it is
obviously insecure! The htpasswd file for this can be
created by hand and looks like:
user1:password1
user2:password2
bcrypt
This uses a modified version of the Blowfish stream cipher, which is
considered very secure. The installation of Python's
bcrypt module is required for this to work.
md5
Use an iterated MD5 digest of the password with salt (nowadays
insecure).
sha256 (>= 3.1.9)
Use an iterated SHA-256 digest of the password with salt.
sha512 (>= 3.1.9)
Use an iterated SHA-512 digest of the password with salt.
argon2 (>= 3.5.3)
Use an iterated ARGON2 digest of the password with salt. The
installation of Python's argon2-cffi module is required
for this to work.
autodetect (>= 3.1.9)
Automatically detect the encryption method used per user entry.
Default: md5 (< 3.3.0) /
autodetect (>= 3.3.0)
htpasswd_cache
(>= 3.4.0)
Enable caching of htpasswd file based on size and mtime_ns
Default: False
delay
Average delay (in seconds) after failed login attempts.
Default: 1
realm
Message displayed in the client when a password is needed.
Default: Radicale - Password Required
ldap_uri
(>= 3.3.0)
URI to the LDAP server. Mandatory for auth type
ldap.
Default: ldap://localhost
ldap_base
(>= 3.3.0)
Base DN of the LDAP server. Mandatory for auth type
ldap.
Default: (unset)
ldap_reader_dn
(>= 3.3.0)
DN of a LDAP user with read access users and - if defined - groups.
Mandatory for auth type ldap.
Default: (unset)
ldap_secret
(>= 3.3.0)
Password of ldap_reader_dn. Mandatory for auth type
ldap unless ldap_secret_file is given.
Default: (unset)
ldap_secret_file
(>= 3.3.0)
Path to the file containing the password of
ldap_reader_dn. Mandatory for auth type ldap
unless ldap_secret is given.
Default: (unset)
ldap_filter
(>= 3.3.0)
Filter to search for the LDAP entry of the user to authenticate. It
must contain '{0}' as placeholder for the login name.
Default: (cn={0})
ldap_user_attribute
(>= 3.4.0)
LDAP attribute whose value shall be used as the username after
successful authentication.
If set, you can use flexible logins in ldap_filter and
still have consolidated usernames, e.g. to allow users to login using
mail addresses as an alternative to cn, simply set
ldap_filter = (&(objectclass=inetOrgPerson)(|(cn={0})(mail={0})))
ldap_user_attribute = cn
Even for simple filter setups, it is recommended to set it in order
to get usernames exactly as they are stored in LDAP and to avoid
inconsistencies in the upper-/lower-case spelling of the login
names.
Default: (unset, in which case the login name is directly used as the
username)
ldap_use_ssl
(>= 3.3.0)
Use ssl on the LDAP connection. Deprecated! Use
ldap_security instead.
ldap_security
(>= 3.5.2)
Use encryption on the LDAP connection.
One of
Default: none
ldap_ssl_verify_mode
(>= 3.3.0)
Certificate verification mode for tls and starttls.
One of
Default: REQUIRED
ldap_ssl_ca_file
(>= 3.3.0)
Path to the CA file in PEM format which is used to certify the server
certificate
Default: (unset)
ldap_groups_attribute
(>= 3.4.0)
LDAP attribute in the authenticated user's LDAP entry to read the
group memberships from.
E.g. memberOf to get groups on Active Directory and
alikes, groupMembership on Novell eDirectory, ...
If set, get the user's LDAP groups from the attribute given.
For DN-valued attributes, the value of the RDN is used to determine
the group names. The implementation also supports non-DN-valued
attributes: their values are taken directly.
The user's group names can be used later on to define rights. They
also give you access to the group calendars, if those exist.
- Group calendars are placed directly under
collection_root_folder
/GROUPS/ with the
base64-encoded group name as the calendar folder name.
- Group calendar folders are not created automatically. This must be
done manually. In the LDAP-authentication
section of Radicale's wiki you can find a script to create a group
calendar.
Default: (unset)
ldap_group_members_attribute
(>= 3.5.6)
Attribute in the group entries to read the group's members from.
E.g. member for groups with objectclass
groupOfNames.
Using ldap_group_members_attribute,
ldap_group_base and ldap_group_filter is an
alternative approach to getting the user's groups. Instead of reading
them from ldap_groups_attribute in the user's entry, an
additional query is performed to seach for those groups beneath
ldap_group_base, that have the user's DN in their
ldap_group_members_attribute and additionally fulfil
ldap_group_filter.
As with DN-valued ldap_groups_attribute, the value of
the RDN is used to determine the group names.
Default: (unset)
ldap_group_base
(>= 3.5.6)
Base DN to search for groups. Only necessary if
ldap_group_members_attribute is set, and if the base DN for
groups differs from ldap_base.
Default: (unset, in which case ldap_base is used as
fallback)
ldap_group_filter
(>= 3.5.6)
Search filter to search for groups having the user DN found as
member. Only necessary ldap_group_members_attribute is set,
and you want the groups returned to be restricted instead of all groups
the user's DN is in.
Default: (unset)
ldap_ignore_attribute_create_modify_timestamp
(>= 3.5.1)
Quirks for Authentik LDAP server, which violates the LDAP RFCs: add
modifyTimestamp and createTimestamp to the exclusion list of internal
ldap3 client so that these schema attributes are not checked.
Default: False
dovecot_connection_type
(>= 3.4.1)
Connection type for dovecot authentication.
One of:
Note: credentials are transmitted in cleartext
Default: AF_UNIX
dovecot_socket
(>= 3.3.1)
Path to the Dovecot client authentication socket (eg.
/run/dovecot/auth-client on Fedora). Radicale must have read & write
access to the socket.
Default: /var/run/dovecot/auth-client
dovecot_host
(>= 3.4.1)
Host of dovecot socket exposed via network
Default: localhost
dovecot_port
(>= 3.4.1)
Port of dovecot socket exposed via network
Default: 12345
remote_ip_source
(>= 3.5.6)
For authentication mechanisms that are made aware of the remote IP
(such as dovecot via the rip= auth protocol parameter),
determine the source to use. Currently, valid values are
REMOTE_ADDR (default) : Use the REMOTE_ADDR environment
variable that captures the remote address of the socket connection.
X-Remote-Addr : Use the X-Remote-Addr HTTP
header value.
In the case of X-Remote-Addr, Radicale must be running
be running behind a proxy that you control and that sets/overwrites the
X-Remote-Addr header (doesn't pass it) so that the value
passed to dovecot is reliable. For example, for nginx, add
proxy_set_header X-Remote-Addr $remote_addr;
to the configuration sample.
Default: REMOTE_ADDR
imap_host
(>= 3.4.1)
IMAP server hostname.
One of:
- address
- address:port
- imap.server.tld
Default: localhost
imap_security
(>= 3.4.1)
Secure the IMAP connection:
One of:
Default: tls
oauth2_token_endpoint
(>= 3.5.0)
Endpoint URL for the OAuth2 token
Default: (unset)
pam_service
(>= 3.5.0)
PAM service name
Default: radicale
pam_group_membership
(>= 3.5.0)
PAM group user should be member of
Default: (unset)
lc_username
Сonvert username to lowercase. Recommended to be True
for case-insensitive auth providers like ldap, kerberos, ...
Default: False
Notes:
lc_username and uc_username are mutually
exclusive- for auth type
ldap the use of
ldap_user_attribute is preferred over
lc_username
uc_username
(>= 3.3.2)
Сonvert username to uppercase. Recommended to be True
for case-insensitive auth providers like ldap, kerberos, ...
Default: False
Notes:
uc_username and lc_username are mutually
exclusive- for auth type
ldap the use of
ldap_user_attribute is preferred over
uc_username
strip_domain
(>= 3.2.3)
Strip domain from username
Default: False
urldecode_username
(>= 3.5.3)
URL-decode the username. If the username is an email address, some
clients send the username URL-encoded (notably iOS devices) breaking the
authentication process (user@example.com becomes
user%40example.com). This setting forces decoding the username.
Default: False
[storage]
type
Backend used to store data.
Available backends are:
Default: multifilesystem
filesystem_folder
Folder for storing local collections; will be auto-created if not
present.
Default: /var/lib/radicale/collections
filesystem_cache_folder
(>= 3.3.2)
Folder for storing cache of local collections; will be auto-created
if not present
Default: (filesystem_folder)
Note: only used if use_cache_subfolder_* options are active
Note: can be used on multi-instance setup to cache files on local
node (see below)
use_cache_subfolder_for_item
(>= 3.3.2)
Use subfolder collection-cache for cache file structure
of 'item' instead of inside collection folders, created if not
present
Default: False
Note: can be used on multi-instance setup to cache 'item' on local
node
use_cache_subfolder_for_history
(>= 3.3.2)
Use subfolder collection-cache for cache file structure
of 'history' instead of inside collection folders, created if not
present
Default: False
Note: only use on single-instance setup: it will break consistency
with clients in multi-instance setup
use_cache_subfolder_for_synctoken
(>= 3.3.2)
Use subfolder collection-cache for cache file structure
of 'sync-token' instead of inside collection folders, created if not
present
Default: False
Note: only use on single-instance setup: it will break consistency
with clients in multi-instance setup
use_mtime_and_size_for_item_cache
(>= 3.3.2)
Use last modification time (in nanoseconds) and size (in bytes) for
'item' cache instead of SHA256 (improves speed)
Default: False
Notes:
- check used filesystem mtime precision before enabling
- conversion is done on access
- bulk conversion can be done offline using the storage verification
option
radicale --verify-storage
folder_umask
(>= 3.3.2)
umask to use for folder creation (not applicable for OS Windows)
Default: (system-default, usually 0022)
Useful values:
0077 (user:rw group:- other:-)0027 (user:rw group:r other:-)0007 (user:rw group:rw other:-)0022 (user:rw group:r other:r)
max_sync_token_age
Delete sync-tokens that are older than the specified time (in
seconds).
Default: 2592000
skip_broken_item
(>= 3.2.2)
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 collections with
Git tutorial for an example.
Default: (unset)
Supported placeholders:
%(user)s: logged-in user%(cwd)s: current working directory (>=
3.5.1)%(path)s: full path of item (>= 3.5.1)%(to_path)s: full path of destination item (only set on
MOVE request) (>= 3.5.5)%(request)s: request method (>= 3.5.5)
The command will be executed with base directory defined in
filesystem_folder (see above)
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: (unset)
[hook]
type
Hook binding for event changes and deletion notifications.
Available types are:
none
Disabled. Nothing will be notified.
rabbitmq (>= 3.2.0)
Push the message to the rabbitmq server.
email (>= 3.5.5)
Send an email notification to event attendees.
Default: none
dryrun
(> 3.5.4)
Dry-Run / simulate (i.e. do not really trigger) the hook action.
Default: False
rabbitmq_endpoint
(>= 3.2.0)
End-point address for rabbitmq server. E.g.:
amqp://user:password@localhost:5672/
Default: (unset)
rabbitmq_topic
(>= 3.2.0)
RabbitMQ topic to publish message in.
Default: (unset)
rabbitmq_queue_type
(>= 3.2.0)
RabbitMQ queue type for the topic.
Default: classic
smtp_server
(>= 3.5.5)
Address of SMTP server to connect to.
Default: (unset)
smtp_port
(>= 3.5.5)
Port on SMTP server to connect to.
Default:
smtp_security
(>= 3.5.5)
Use encryption on the SMTP connection.
One of:
Default: none
smtp_ssl_verify_mode
(>= 3.5.5)
The certificate verification mode for tls and starttls.
One of:
Default: REQUIRED
smtp_username
(>= 3.5.5)
Username to authenticate with SMTP server. Leave empty to disable
authentication (e.g. using local mail server).
Default: (unset)
smtp_password
(>= 3.5.5)
Password to authenticate with SMTP server. Leave empty to disable
authentication (e.g. using local mail server).
Default: (unset)
from_email
(>= 3.5.5)
Email address to use as sender in email notifications.
Default: (unset)
mass_email
(>= 3.5.5)
When enabled, send one email to all attendee email addresses. When
disabled, send one email per attendee email address.
Default: False
new_or_added_to_event_template
(>= 3.5.5)
Template to use for added/updated event email body sent to an
attendee when the event is created or they are added to a pre-existing
event.
The following placeholders will be replaced:
$organizer_name: Name of the organizer, or "Unknown
Organizer" if not set in event$from_email: Email address the email is sent from$attendee_name: Name of the attendee (email recipient),
or "everyone" if mass email enabled.$event_name: Name/summary of the event, or "No Title"
if not set in event$event_start_time: Start time of the event in ISO 8601
format$event_end_time: End time of the event in ISO 8601
format, or "No End Time" if the event has no end time$event_location: Location of the event, or "No Location
Specified" if not set in event
Providing any words prefixed with $ not included in the list above
will result in an error.
Default:
Hello $attendee_name,
You have been added as an attendee to the following calendar event.
$event_title
$event_start_time - $event_end_time
$event_location
This is an automated message. Please do not reply.
deleted_or_removed_from_event_template
(>= 3.5.5)
Template to use for deleted/removed event email body sent to an
attendee when the event is deleted or they are removed from the
event.
The following placeholders will be replaced:
$organizer_name: Name of the organizer, or "Unknown
Organizer" if not set in event$from_email: Email address the email is sent from$attendee_name: Name of the attendee (email recipient),
or "everyone" if mass email enabled.$event_name: Name/summary of the event, or "No Title"
if not set in event$event_start_time: Start time of the event in ISO 8601
format$event_end_time: End time of the event in ISO 8601
format, or "No End Time" if the event has no end time$event_location: Location of the event, or "No Location
Specified" if not set in event
Providing any words prefixed with $ not included in the list above
will result in an error.
Default:
Hello $attendee_name,
The following event has been deleted.
$event_title
$event_start_time - $event_end_time
$event_location
This is an automated message. Please do not reply.
updated_event_template
(>= 3.5.5)
Template to use for updated event email body sent to an attendee when
non-attendee-related details of the event are updated.
Existing attendees will NOT be notified of a modified event if the
only changes are adding/removing other attendees.
The following placeholders will be replaced:
$organizer_name: Name of the organizer, or "Unknown
Organizer" if not set in event$from_email: Email address the email is sent from$attendee_name: Name of the attendee (email recipient),
or "everyone" if mass email enabled.$event_name: Name/summary of the event, or "No Title"
if not set in event$event_start_time: Start time of the event in ISO 8601
format$event_end_time: End time of the event in ISO 8601
format, or "No End Time" if the event has no end time$event_location: Location of the event, or "No Location
Specified" if not set in event
Providing any words prefixed with $ not included in the list above
will result in an error.
Default:
Hello $attendee_name,
The following event has been updated.
$event_title
$event_start_time - $event_end_time
$event_location
This is an automated message. Please do not reply.