From d64d8a1924587aca28df661f6318d43f07f5a093 Mon Sep 17 00:00:00 2001 From: Github Actions <> Date: Sun, 16 Mar 2025 17:57:05 +0000 Subject: [PATCH] Generate documentation --- v3.html | 157 +++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 121 insertions(+), 36 deletions(-) diff --git a/v3.html b/v3.html index 918615d3..6ef6fe96 100644 --- a/v3.html +++ b/v3.html @@ -303,10 +303,12 @@ on GitHub.

You want to try Radicale but only have 5 minutes free in your calendar? Let's go right now and play a bit with Radicale!

When everything works, you can get a client and start creating calendars and -address books. The server only binds to localhost (is -not reachable over the network) and you can log in with -any username and password. If Radicale fits your needs, it may be time -for some basic configuration.

+address books. By default, the server only binds to localhost (is not +reachable over the network) and you can log in with any user name and +password. When everything works, you may get a local client and start +creating calendars and address books. If Radicale fits your needs, it +may be time for some basic +configuration to support remote clients.

Follow one of the chapters below depending on your operating system.

@@ -367,6 +369,11 @@ file.

The secure way

The users file can be created and managed with htpasswd:

+

Note: some OS contain unpatched htpasswd (< 2.4.59) +without supporting SHA-256 or SHA-512 (e.g. Ubuntu LTS 22), in this case +use '-B' for "bcrypt" hash method or stay with insecure MD5 (default) or +SHA-1 ('-s').

+

Note that support of SHA-256 or SHA-512 was introduced with 3.1.9

# Create a new htpasswd file with the user "user1" using SHA-512 as hash method
 $ htpasswd -5 -c /path/to/users user1
 New password:
@@ -682,7 +689,9 @@ and disables HTTP authentication.

 

 
Security: Untrusted clients should not be able to
 access the Radicale server directly. Otherwise, they can authenticate as
-any user.

+any user by simply setting related HTTP header. This can be prevented by
+restrict listen to loopback interface only or at least a local firewall
+rule.
@@ -892,10 +901,11 @@ 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:

+

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")

@@ -903,11 +913,18 @@ Format: Apache SSLProtocol list (from "mod_ssl")

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)

+

encoding

@@ -929,6 +946,8 @@ Format: OpenSSL cipher list (see also "man openssl-ciphers")

The method to verify usernames and passwords.

Available backends:

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 @@ -938,26 +957,35 @@ 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.

-

dovecot : Use a Dovecot server to authenticate -users.

-

imap : Use a IMAP server to authenticate users.

-

Default: none

+

ldap (>= 3.3.0) : Use a LDAP or AD server to +authenticate users.

+

dovecot (>= 3.3.1) : Use a Dovecot server to +authenticate users.

+

imap (>= 3.4.1) : Use an IMAP server to +authenticate users.

+

oauth2 (>= 3.5.0) : Use an OAuth2 server to +authenticate users.

+

pam (>= 3.5.0) : Use local PAM to +authenticate users.

+

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

@@ -981,16 +1009,18 @@ stream cipher. It's very secure. The installation of 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

+

sha256 (>= 3.1.9) : This uses an iterated +SHA-256 digest of the password with a salt.

+

sha512 (>= 3.1.9) : This uses an iterated +SHA-512 digest of the password with a salt.

+

autodetect (>= 3.1.9) : This selects +autodetection of method per 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

@@ -1006,29 +1036,34 @@ entry.

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.

@@ -1036,18 +1071,21 @@ auth type is ldap.

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 @@ -1065,26 +1103,30 @@ calendar.

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

@@ -1092,6 +1134,7 @@ the server certificate

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.

@@ -1099,25 +1142,47 @@ access to the socket.

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:

+
lc_username

Сonvert username to lowercase, must be true for case-insensitive auth @@ -1127,6 +1192,7 @@ providers like ldap, kerberos

uc_username
+

(>= 3.3.2)

Сonvert username to uppercase, must be true for case-insensitive auth providers like ldap, kerberos

Default: False

@@ -1134,6 +1200,7 @@ providers like ldap, kerberos

strip_domain
+

(>= 3.2.3)

Strip domain from username

Default: False

@@ -1166,7 +1233,7 @@ and write their own collections under the path /USERNAME/.

permit_delete_collection
-

(New since 3.1.9)

+

(>= 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 @@ -1174,7 +1241,7 @@ 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)

If False it can be permitted by permissions per section with: O If @@ -1200,6 +1267,7 @@ only be used with a single process.

filesystem_cache_folder
+

(>= 3.3.2)

Folder for storing cache of local collections, created if not present

Default: (filesystem_folder)

@@ -1210,6 +1278,7 @@ 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

@@ -1219,6 +1288,7 @@ 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

@@ -1228,6 +1298,7 @@ client 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

@@ -1237,6 +1308,7 @@ client in multi-instance setup

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

@@ -1247,6 +1319,7 @@ offline using storage verification option
folder_umask
+

(>= 3.3.2)

Use configured umask for folder creation (not applicable for OS Windows)

Default: (system-default, usual 0022)

@@ -1263,6 +1336,7 @@ other:r)

skip_broken_item
+

(>= 3.2.2)

Skip broken item instead of triggering an exception

Default: True

@@ -1316,7 +1390,8 @@ books and calendars.

Available levels: debug, info, warning, error, critical

-

Default: warning

+

Default: warning (< 3.2.0) info +(>= 3.2.0)

mask_passwords
@@ -1325,26 +1400,31 @@ books and calendars.

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

@@ -1355,6 +1435,7 @@ books and calendars.

storage_cache_actions_on_debug
+

(>= 3.3.2)

Log storage cache actions on level=debug

Default: False

@@ -1373,22 +1454,26 @@ be specified.

Hook binding for event changes and deletion notifications.

Available types:

none : Disabled. Nothing will be notified.

-

rabbitmq : Push the message to the rabbitmq server.

+

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/

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

@@ -1397,6 +1482,7 @@ amqp://user:password@localhost:5672/

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 @@ -1483,15 +1569,14 @@ username and password. It will list your existing address books.

InfCloud, CalDavZAP and CardDavMATE

-

You can integrate InfCloud into Radicale's web interface with RadicaleInfCloud. -No additional configuration is required.

-

Set the URL of the Radicale server in config.js. If -InfCloud is not hosted on the same server and port as -Radicale, the browser will deny access to the Radicale server, because -of the same-origin -policy. You have to add additional HTTP header in the -headers section of Radicale's configuration. The -documentation of InfCloud has more details on this.

+

You can integrate InfCloud into Radicale's web interface with by +simply download latest package from InfCloud +and extract content to new folder infcloud in +radicale/web/internal_data/.

+

No further adjustments are required as content is adjusted on the fly +(tested with 0.13.1).

+

See also Wiki/Client +InfCloud.

Command line

@@ -1602,9 +1687,9 @@ expensive search requests) calendars)
  • w: write address book and calendar collections
  • D: permit delete of collection in case -permit_delete_collection=False
    • +permit_delete_collection=False (>= 3.3.0)
  • d: forbid delete of collection in case -permit_delete_collection=True
    • +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 @@ -1844,7 +1929,7 @@ content:

    def __init__(self, configuration): super().__init__(configuration.copy(PLUGIN_CONFIG_SCHEMA)) - def login(self, login, password): + def _login(self, login, password): # Get password from configuration option static_password = self.configuration.get("auth", "password") # Check authentication