From e8c974a72aab3fcbf64fad2addebcf5ebdbafa6b Mon Sep 17 00:00:00 2001 From: Peter Bieringer Date: Sat, 15 Mar 2025 14:35:30 +0100 Subject: [PATCH] add versions when option was introduced --- DOCUMENTATION.md | 130 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 111 insertions(+), 19 deletions(-) diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 542d55b7..5f18488d 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -765,10 +765,12 @@ 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: +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") @@ -777,6 +779,8 @@ 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") @@ -785,6 +789,8 @@ 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) @@ -832,26 +838,27 @@ Available backends: authentication. This can be used to provide the username from a reverse proxy. -`ldap` +`ldap` _(>= 3.3.0)_ : Use a LDAP or AD server to authenticate users. -`dovecot` +`dovecot` _(>= 3.3.1)_ : Use a Dovecot server to authenticate users. -`imap` +`imap` _(>= 3.4.1)_ : Use an IMAP server to authenticate users. -`oauth2` +`oauth2` _(>= 3.5.0)_ : Use an OAuth2 server to authenticate users. -`pam` +`pam` _(>= 3.5.0)_ : Use local PAM to authenticate users. - -Default: `none` +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. @@ -859,12 +866,16 @@ 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` @@ -899,19 +910,21 @@ Available methods: `md5` : This uses an iterated MD5 digest of the password with a salt (nowadays insecure). -`sha256` +`sha256` _(>= 3.1.9)_ : This uses an iterated SHA-256 digest of the password with a salt. -`sha512` +`sha512` _(>= 3.1.9)_ : This uses an iterated SHA-512 digest of the password with a salt. -`autodetect` +`autodetect` _(>= 3.1.9)_ : This selects autodetection of method per entry. -Default: `autodetect` +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` @@ -930,48 +943,64 @@ Default: `Radicale - Password Required` ##### ldap_uri +_(>= 3.3.0)_ + The URI to the ldap server Default: `ldap://localhost` ##### ldap_base +_(>= 3.3.0)_ + LDAP base DN of the ldap server. This parameter must be provided if auth type is ldap. Default: ##### ldap_reader_dn +_(>= 3.3.0)_ + 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 +_(>= 3.3.0)_ + The password of the ldap_reader_dn. Either this parameter or `ldap_secret_file` must be provided if auth type is ldap. Default: ##### ldap_secret_file +_(>= 3.3.0)_ + Path of the file containing the password of the ldap_reader_dn. Either this parameter or `ldap_secret` must be provided if auth type is ldap. Default: ##### ldap_filter +_(>= 3.3.0)_ + 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_user_attribute +_(>= 3.4.0)_ + The LDAP attribute whose value shall be used as the user name after successful authentication Default: not set, i.e. the login name given is used directly. ##### ldap_groups_attribute +_(>= 3.4.0)_ + The LDAP attribute to read the group memberships from in the authenticated user's LDAP entry. If set, load the LDAP group memberships from the attribute given @@ -983,28 +1012,36 @@ This also gives you access to the group calendars, if they exist. Use 'memberOf' if you want to load groups on Active Directory and alikes, 'groupMembership' on Novell eDirectory, ... -Default: unset +Default: (unset) ##### ldap_use_ssl +_(>= 3.3.0)_ + Use ssl on the ldap connection Default: False ##### ldap_ssl_verify_mode +_(>= 3.3.0)_ + The certificate verification mode. NONE, OPTIONAL or REQUIRED Default: REQUIRED ##### ldap_ssl_ca_file +_(>= 3.3.0)_ + The path to the CA file in pem format which is used to certificate the server certificate Default: ##### dovecot_connection_type = AF_UNIX +_(>= 3.4.1)_ + Connection type for dovecot authentication (AF_UNIX|AF_INET|AF_INET6) Note: credentials are transmitted in cleartext @@ -1013,48 +1050,64 @@ Default: `AF_UNIX` ##### dovecot_socket +_(>= 3.3.1)_ + The 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 via network exposed dovecot socket Default: `localhost` ##### dovecot_port +_(>= 3.4.1)_ + Port of via network exposed dovecot socket Default: `12345` ##### imap_host +_(>= 3.4.1)_ + IMAP server hostname: address | address:port | [address]:port | imap.server.tld Default: `localhost` ##### imap_security +_(>= 3.4.1)_ + Secure the IMAP connection: tls | starttls | none Default: `tls` ##### oauth2_token_endpoint +_(>= 3.5.0)_ + OAuth2 token endpoint URL Default: ##### pam_service +_(>= 3.5.0)_ + PAM service Default: radicale ##### pam_group_membership +_(>= 3.5.0)_ + PAM group user should be member of Default: @@ -1070,6 +1123,8 @@ Note: cannot be enabled together with `uc_username` ##### uc_username +_(>= 3.3.2)_ + Сonvert username to uppercase, must be true for case-insensitive auth providers like ldap, kerberos @@ -1079,6 +1134,8 @@ Note: cannot be enabled together with `lc_username` ##### strip_domain +_(>= 3.2.3)_ + Strip domain from username Default: `False` @@ -1120,7 +1177,7 @@ File for the rights backend `from_file`. See the ##### permit_delete_collection -(New since 3.1.9) +_(>= 3.1.9)_ Global control of permission to delete complete collection (default: True) @@ -1129,7 +1186,7 @@ If True it can be forbidden by permissions per section with: d ##### permit_overwrite_collection -(New since 3.3.0) +_(>= 3.3.0)_ Global control of permission to overwrite complete collection (default: True) @@ -1161,6 +1218,8 @@ Default: `/var/lib/radicale/collections` ##### filesystem_cache_folder +_(>= 3.3.2)_ + Folder for storing cache of local collections, created if not present Default: (filesystem_folder) @@ -1171,6 +1230,8 @@ Note: can be used on multi-instance setup to cache files on local node (see belo ##### 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` @@ -1179,6 +1240,8 @@ 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` @@ -1187,6 +1250,8 @@ Note: use only on single-instance setup, will break consistency with client in m ##### 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` @@ -1195,6 +1260,8 @@ Note: use only on single-instance setup, will break consistency with client in m ##### use_mtime_and_size_for_item_cache +_(>= 3.3.2)_ + Use last modifiction time (nanoseconds) and size (bytes) for 'item' cache instead of SHA256 (improves speed) Default: `False` @@ -1205,6 +1272,8 @@ Note: conversion is done on access, bulk conversion can be done offline using st ##### folder_umask +_(>= 3.3.2)_ + Use configured umask for folder creation (not applicable for OS Windows) Default: (system-default, usual `0022`) @@ -1219,6 +1288,8 @@ Default: `2592000` ##### skip_broken_item +_(>= 3.2.2)_ + Skip broken item instead of triggering an exception Default: `True` @@ -1279,7 +1350,7 @@ Set the logging level. Available levels: **debug**, **info**, **warning**, **error**, **critical** -Default: `warning` +Default: `warning` _(< 3.2.0)_ `info` _(>= 3.2.0)_ ##### mask_passwords @@ -1289,30 +1360,40 @@ Default: `True` ##### bad_put_request_content +_(>= 3.2.1)_ + Log bad PUT request content (for further diagnostics) Default: `False` ##### backtrace_on_debug +_(>= 3.2.2)_ + Log backtrace on level=debug Default: `False` ##### request_header_on_debug +_(>= 3.2.2)_ + Log request on level=debug Default: `False` ##### request_content_on_debug +_(>= 3.2.2)_ + Log request on level=debug Default: `False` ##### response_content_on_debug +_(>= 3.2.2)_ + Log response on level=debug Default: `False` @@ -1325,6 +1406,8 @@ Default: `False` ##### storage_cache_actions_on_debug +_(>= 3.3.2)_ + Log storage cache actions on level=debug Default: `False` @@ -1350,13 +1433,15 @@ Available types: `none` : Disabled. Nothing will be notified. -`rabbitmq` +`rabbitmq` _(>= 3.2.0)_ : Push the message to the rabbitmq server. Default: `none` ##### rabbitmq_endpoint +_(>= 3.2.0)_ + End-point address for rabbitmq server. Ex: amqp://user:password@localhost:5672/ @@ -1364,19 +1449,26 @@ Default: ##### rabbitmq_topic +_(>= 3.2.0)_ + RabbitMQ topic to publish message. Default: ##### rabbitmq_queue_type +_(>= 3.2.0)_ + RabbitMQ queue type for the topic. Default: classic #### reporting + ##### max_freebusy_occurrence +_(>= 3.2.3)_ + 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 @@ -1591,8 +1683,8 @@ The following `permissions` are recognized: (CalDAV/CardDAV is susceptible to 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 +* **D:** permit delete of collection in case permit_delete_collection=False _(>= 3.3.0)_ +* **d:** forbid delete of collection in case permit_delete_collection=True _(>= 3.3.0)_ * **O:** permit overwrite of collection in case permit_overwrite_collection=False * **o:** forbid overwrite of collection in case permit_overwrite_collection=True