diff --git a/1.1.html b/1.1.html index c64e8d03d..7e873570d 100644 --- a/1.1.html +++ b/1.1.html @@ -1,11 +1,11 @@ - + Redirect -

Please follow this link.

+

Please follow this link.

diff --git a/documentation-generator/template.html b/documentation-generator/template.html index 45016dc49..5f4c316b8 100644 --- a/documentation-generator/template.html +++ b/documentation-generator/template.html @@ -9,19 +9,19 @@ $if(math)$ $math$ $endif$ - - - - - + + + + + - + Radicale $branch$ Documentation - - - - + + + +
@@ -31,7 +31,7 @@

$branch$ diff --git a/html/master/about.html b/html/master/about.html new file mode 100644 index 000000000..f61a47a48 --- /dev/null +++ b/html/master/about.html @@ -0,0 +1,382 @@ + + + + + + + + + + + + + + +Radicale master Documentation + + + + + +
+
+

+Radicale + +master + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + + + + + +
+

About

+
+

Main Goals

+

Radicale is a complete calendar and contact storing and manipulating +solution. It can store multiple calendars and multiple address +books.

+

Calendar and contact manipulation is available from both local and +distant accesses, possibly limited through authentication policies.

+

It aims to be a lightweight solution, easy to use, easy to install, +easy to configure. As a consequence, it requires few software +dependencies and is preconfigured to work out-of-the-box.

+

Radicale is written in Python. It runs on most of the UNIX-like +platforms (Linux, *BSD, macOS) and Windows. It is free and open-source +software.

+
+
+

What Radicale Will Never Be

+

Radicale is a server, not a client. No interfaces will be created to +work with the server.

+

CalDAV and CardDAV are not perfect protocols. We think that their +main problem is their complexity, that is why we decided not to +implement the whole standard but just enough to understand some of its +client-side implementations.

+

CalDAV and CardDAV are the best open standards available, and they +are quite widely used by both clients and servers. We decided to use it, +and we will not use another one.

+
+
+

Technical Choices

+

Important global development choices have been decided before writing +code. They are very useful to understand why the Radicale Project is +different from other CalDAV and CardDAV servers, and why features are +included or not in the code.

+
+
Oriented to Calendar and Contact User Agents
+

Calendar and contact servers work with calendar and contact clients, +using a defined protocol. CalDAV and CardDAV are good protocols, +covering lots of features and use cases, but it is quite hard to +implement fully.

+

Some calendar servers have been created to follow the CalDAV and +CardDAV RFCs as much as possible: Davical, Baïkal and Darwin Calendar Server, for +example, are much more respectful of CalDAV and CardDAV and can be used +with many clients. They are very good choices if you want to develop and +test new CalDAV clients, or if you have a possibly heterogeneous list of +user agents.

+

Even if it tries it best to follow the RFCs, Radicale does not and +will not blindly implement the CalDAV and CardDAV +standards. It is mainly designed to support the CalDAV and CardDAV +implementations of different clients.

+
+
+
Simple
+

Radicale is designed to be simple to install, simple to configure, +simple to use.

+

The installation is very easy, particularly with Linux: one +dependency, no superuser rights needed, no configuration required, no +database. Installing and launching the main script out-of-the-box, as a +normal user, are often the only steps to have a simple remote calendar +and contact access.

+

Contrary to other servers that are often complicated, require high +privileges or need a strong configuration, the Radicale Server can +(sometimes, if not often) be launched in a couple of minutes, if you +follow the tutorial.

+
+
+
Lazy
+

The CalDAV RFC defines what must be done, what can be done and what +cannot be done. Many violations of the protocol are totally defined and +behaviors are given in such cases.

+

Radicale often assumes that the clients are perfect and that protocol +violations do not exist. That is why most of the errors in client +requests have undetermined consequences for the lazy server that can +reply good answers, bad answers, or even no answer.

+
+
+
+

History

+

Radicale has been started as a (free topic) stupid school project +replacing another (assigned topic) even more stupid school project.

+

At the beginning, it was just a proof-of-concept. The main goal was +to write a small, dirty and simple CalDAV server working with Lightning, +using no external libraries. That's how we created a piece of code +that's (quite) easy to understand, to use and to hack.

+

The first +lines have been added to the SVN (!) repository as I was drinking +(many) beers at the very end of 2008 (Python 2.6 and 3.0 were just +released). It's now packaged for a growing number of Linux +distributions.

+

And that was fun going from here to there thanks to you!

+
+
+
+
+ diff --git a/html/master/contribute.html b/html/master/contribute.html new file mode 100644 index 000000000..401376107 --- /dev/null +++ b/html/master/contribute.html @@ -0,0 +1,307 @@ + + + + + + + + + + + + + + +Radicale master Documentation + + + + + +
+
+

+Radicale + +master + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + + + +
+

Contribute

+
+

Report Bugs

+

Found a bug? Want a new feature? Report a new issue on the Radicale +bug-tracker.

+
+
+

Hack

+

Interested in hacking? Feel free to clone the git repository on GitHub if +you want to add new features, fix bugs or update the documentation.

+
+
+

Documentation

+

To change or complement the documentation create a pull request to DOCUMENTATION.md.

+
+
+ + +
+
+ diff --git a/html/master/documentation.html b/html/master/documentation.html new file mode 100644 index 000000000..bdc5ebcad --- /dev/null +++ b/html/master/documentation.html @@ -0,0 +1,1646 @@ + + + + + + + + + + + + + + +Radicale master Documentation + + + + + +
+
+

+Radicale + +master + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + +
+

Documentation

+
+

Options

+
+

General Options

+
+
--version
+

Print version

+
+
+
--verify-storage
+

Verification of local collections storage

+
+
+
--verify-item
+

(>= 3.6.0)

+

Verification of a particular item file

+
+
+
--verify-sharing
+

(>= 3.7.0)

+

Verification of local sharing database

+
+
+
-C|--config
+

Load one or more specified config file(s)

+
+
+
-D|--debug
+

Turns log level to debug

+
+
+
+

Configuration Options

+

Each supported option from config file can be provided/overridden by +command line replacing _ with - and prepending +the section followed by a -, e.g.

+
[logging]
+backtrace_on_debug = False
+

can be enabled using --logging-backtrace-on-debug=true +on command line.

+
+
+
+

Configuration

+

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.

+

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 = 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 +with the --config /path/to/config command line argument or +the RADICALE_CONFIG environment variable. Multiple +configuration files can be separated by : (resp. +; on Windows). Paths that start with ? are +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 autodetect
+

Add the argument --config "" to stop Radicale from +loading the default configuration files. Run +python3 -m radicale --help for more information.

+

You can also use command-line options in startup scripts as shown in +the following examples:

+
## simple variable containing multiple options
+RADICALE_OPTIONS="--logging-level=debug --config=/etc/radicale/config --logging-request-header-on-debug --logging-rights-rule-doesnt-match-on-debug"
+/usr/bin/radicale $RADICALE_OPTIONS
+
+## variable as array method #1
+RADICALE_OPTIONS=("--logging-level=debug" "--config=/etc/radicale/config" "--logging-request-header-on-debug" "--logging-rights-rule-doesnt-match-on-debug")
+/usr/bin/radicale ${RADICALE_OPTIONS[@]}
+
+## variable as array method #2
+RADICALE_OPTIONS=()
+RADICALE_OPTIONS+=("--logging-level=debug")
+RADICALE_OPTIONS+=("--config=/etc/radicale/config")
+/usr/bin/radicale ${RADICALE_OPTIONS[@]}
+

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

+
+
+
delay_on_error
+

(>= 3.7.0)

+

Base delay in case of error 5xx response (seconds)

+

Default: 1

+
+
+
max_content_length
+

The maximum size of the request body. (bytes)

+

Default: 100000000 (100 Mbyte)

+

In case of using a reverse proxy in front of check also there related +option.

+
+
+
max_resource_size
+

(>= 3.5.10)

+

The maximum size of a resource. (bytes)

+

Default: 10000000 (10 Mbyte)

+

Limited to 80% of max_content_length to cover plain base64 encoded +payload.

+

Announced to clients requesting "max-resource-size" via PROPFIND.

+
+
+
timeout
+

Socket timeout. (seconds)

+

Default: 30

+
+
+
ssl
+

Enable transport layer encryption.

+

Default: False

+
+
+
certificate
+

Path of the SSL certificate.

+

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)

+
+
+
+

[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 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_remote_user (>= 3.5.9) Takes the +username from the Remote-User HTTP header HTTP_REMOTE_USER +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.

    • +

  • http_x_remote_user
    +Takes the username from the X-Remote-User HTTP header +HTTP_X_REMOTE_USER 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 file.

+

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 or missing login attempts or +denied access.

+

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_security
+

(>= 3.5.2)

+

Use encryption on the LDAP connection.

+

One of

+
    +
  • none
    • +
  • tls
    • +
  • starttls
    • +
+

Default: none

+
+
+
ldap_ssl_verify_mode
+

(>= 3.3.0)

+

Certificate verification mode for tls and starttls.

+

One of

+
    +
  • NONE
    • +
  • OPTIONAL
    • +
  • REQUIRED.
    • +
+

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 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 search 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:

+
    +
  • AF_UNIX
    • +
  • AF_INET
    • +
  • AF_INET6
    • +
+

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:

+
    +
  • tls
    • +
  • starttls
    • +
  • none
    • +
+

Default: tls

+
+
+
oauth2_token_endpoint
+

(>= 3.5.0)

+

Endpoint URL for the OAuth2 token

+

Default: (unset)

+
+
+
oauth2_client_id
+

(>= 3.7.0)

+

Client ID used to request the Auth2 token

+

Default: radicale

+
+
+
oauth2_client_secret
+

(>= 3.7.0)

+

Client secret used to request the Auth2 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

+
+
+
+

[rights]

+
+
type
+

Authorization backend that is used to check the access rights to +collections.

+

The default and recommended backend is owner_only. If +access to calendars and address books outside the user's collection +directory (that's /username/) is granted, clients will not +detect these collections automatically and will not show them to the +users. Choosing any other authorization backend is only useful if you +access calendars and address books directly via URL.

+

Available backends are:

+
    +

  • 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
+

Name of the file containing the authorization rules for the +from_file backend. See the Rights section for details.

+

Default: /etc/radicale/rights

+
+
+
permit_delete_collection
+

(>= 3.1.9)

+

Global permission to delete complete collections.

+
    +
  • If False it can be explicitly granted per collection by +rights permissions: D
    • +
  • If True it can be explicitly forbidden per collection +by rights permissions: d
    • +
+

Default: True

+
+
+
permit_overwrite_collection
+

(>= 3.3.0)

+

Global permission to overwrite complete collections.

+
    +
  • If False it can be explicitly granted per collection by +rights permissions: O
    • +
  • If True it can be explicitly forbidden per collection +by rights permissions: o
    • +
+

Default: True

+
+
+
+

[storage]

+
+
type
+

Backend used to store data.

+

Available backends are:

+
    +

  • multifilesystem
    +Stores the data in the filesystem.

    • +

  • multifilesystem_nolock
    +The multifilesystem backend without file-based locking. +Must only be used with a single process.

    • +
+

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

+
+
+
strict_preconditions
+

(>= 3.5.8)

+

Strict preconditions check on PUT in case item already exists RFC6352#9.2

+

Default: False

+
+
+
validate_user_value
+

(>= 3.7.2)

+

Validate user value content

+

Available types are:

+
    +
  • none
    • +
  • minimal (control and some special chars)
    • +
  • unicode-letter (unicode letters)
    • +
  • no-unicode (no unicode)
    • +
  • strict (reduced ASCII set)
    • +
+

Default: minimum

+
+
+
validate_path_type
+

(>= 3.7.2)

+

Validate path value content

+
    +
  • none
    • +
  • minimal (control and some special chars)
    • +
  • unicode-letter (unicode letters)
    • +
  • no-unicode (no unicode)
    • +
  • strict (reduced ASCII set)
    • +
+

Default: minimum

+
+
+
hook
+

Command that is run after changes to storage. See 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)

+
+
+
+

[web]

+
+
type
+

The backend that provides the web interface of Radicale.

+

Available backends are:

+
    +

  • none
    +Simply shows the message "Radicale works!".

    • +

  • internal
    +Allows creation and management of address books and calendars.

    • +
+

Default: internal

+
+
+
+

[logging]

+
+
level
+

Set the logging level.

+

Available levels are:

+
    +
  • trace (>= 3.7.1)
    • +
  • debug
    • +
  • info
    • +
  • notice (>= 3.7.1)
    • +
  • warning
    • +
  • error
    • +
  • critical
    • +
  • alert (>= 3.7.1)
    • +
+

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

+
+
+
limit_content
+

(>= 3.7.0)

+

Limit content of wrapped text (chars)

+

Default: 3000

+
+
+
trace_on_debug
+

(> 3.5.4) && (< 3.7.1)

+

Do not filter debug messages starting with 'TRACE'

+

Default: False

+
+
+
trace_filter
+

(> 3.5.4) && (< 3.7.1)

+

Filter debug messages starting with 'TRACE/'

+

Prerequisite: trace_on_debug = True

+

(>= 3.7.1)

+

Filter trace messages starting with ''

+

Prerequisite: level = trace

+

Default: (empty)

+
+
+
mask_passwords
+

Do not include passwords in logs.

+

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 header on level = debug

+

Default: False

+
+
+
request_content_on_debug
+

(>= 3.2.2)

+

Log request content (body) on level = debug

+

Default: False

+
+
+
response_header_on_debug
+

(>= 3.5.10)

+

Log response header on level = debug

+

Default: False

+
+
+
response_content_on_debug
+

(>= 3.2.2)

+

Log response content (body) on level = debug

+

Default: False

+
+
+
rights_rule_doesnt_match_on_debug
+

(>= 3.2.3)

+

Log rights rule which doesn't match on level = debug

+

Default: False

+
+
+
storage_cache_actions_on_debug
+

(>= 3.3.2)

+

Log storage cache actions on level = debug

+

Default: False

+
+
+
profiling_per_request
+

(>= 3.5.10)

+

Log profiling data on level=info

+

Default: none

+

One of

+
    +
  • none (disabled)
    • +
  • per_request (above minimum duration)
    • +
  • per_request_method (regular interval)
    • +
+
+
+
profiling_per_request_min_duration
+

(>= 3.5.10)

+

Log profiling data per request minimum duration (seconds) before +logging, otherwise skip

+

Default: 3

+
+
+
profiling_per_request_header
+

(>= 3.5.10)

+

Log profiling request header (if passing minimum duration)

+

Default: False

+
+
+
profiling_per_request_xml
+

(>= 3.5.10)

+

Log profiling request XML (if passing minimum duration)

+

Default: False

+
+
+
profiling_per_request_method_interval
+

(>= 3.5.10)

+

Log profiling data per method interval (seconds) Triggered by +request, not active on idle systems

+

Default: 600

+
+
+
profiling_top_x_functions
+

(>= 3.5.10)

+

Log profiling top X functions (limit)

+

Default: 10

+
+
+
+

[headers]

+

This section can be used to specify additional HTTP headers that will +be sent to clients.

+

An example to relax the same-origin policy:

+
Access-Control-Allow-Origin = *
+

An example to set CSP to disallow execution of unknown +javascript:

+
Content-Security-Policy = default-src 'self'; object-src 'none'
+
+
+

[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:

+
    +
  • none
    • +
  • tls
    • +
  • starttls
    • +
+

Default: none

+
+
+
smtp_ssl_verify_mode
+

(>= 3.5.5)

+

The certificate verification mode for tls and starttls.

+

One of:

+
    +
  • NONE
    • +
  • OPTIONAL
    • +
  • REQUIRED
    • +
+

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.
+
+
+
+

[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 +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

+
+
+
+

[sharing]

+

(>= 3.7.0)

+

See also Collection +Sharing.

+
+
type
+

(>= 3.7.0)

+

Sharing database type

+

One of:

+
    +
  • none
    • +
  • csv
    • +
  • files
    • +
+

Default: none (implicit disabling the feature)

+
+
+
database_path
+

(>= 3.7.0)

+

Sharing database path

+

Default:

+
    +
  • type csv: +(filesystem_folder)/collection-db/sharing.csv
    • +
  • type files: +(filesystem_folder)/collection-db/files
    • +
+
+
+
collection_by_token
+

(>= 3.7.0)

+

Share collection by token

+

Default: false

+
+
+
collection_by_map
+

(>= 3.7.0)

+

Share collection by map

+

Default: false

+
+
+
permit_create_token
+

(>= 3.7.0)

+

Permit create of token-based sharing

+

Default: false

+
    +
  • If False it can be explicitly granted by +rights permissions: T
    • +
  • If True it can be explicitly forbidden by +rights permissions: t
    • +
+
+
+
permit_create_map
+

(>= 3.7.0)

+

Permit create of map-based sharing

+

Default: false

+
    +
  • If False it can be explicitly granted by +rights permissions: M
    • +
  • If True it can be explicitly forbidden by +rights permissions: m
    • +
+
+
+
permit_properties_overlay
+

(>= 3.7.0)

+

Permit (limited) properties overlay by user of shared collection

+

Default: false

+
    +
  • If False it can be explicitly granted by share +permissions: P
    • +
  • If True it can be explicitly forbidden by +share permissions: p
    • +
+
+
+
enforce_properties_overlay
+

(>= 3.7.0)

+

Enforce properties overlay even on write access

+

Default: true

+
    +
  • If False it can be explicitly enforced by +share permissions: E
    • +
  • If True it can be explicitly forbidden by +share permissions: e
    • +
+
+
+
default_permissions_create_token
+

Default permissions for create token-based sharing

+

Default: r

+

Supported: rwEePp

+
+
+
default_permissions_create_map
+

Default permissions for map-based sharing

+

Default: r

+

Supported: rwEePp

+
+
+
+
+ + + + + +
+
+ diff --git a/html/master/download.html b/html/master/download.html new file mode 100644 index 000000000..e21a79216 --- /dev/null +++ b/html/master/download.html @@ -0,0 +1,403 @@ + + + + + + + + + + + + + + +Radicale master Documentation + + + + + +
+
+

+Radicale + +master + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + + + + +
+

Download

+
+

PyPI

+

Radicale is available on PyPI. To +install, just type as superuser:

+
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
+

You can also download the content of the repository as an archive.

+
+
+

Source Packages

+

You can find the source packages of all releases on GitHub.

+
+
+

Docker

+

Radicale is available as a Docker image for platforms +linux/amd64 and linux/arm64 on:

+ +

Here are the steps to install Radicale via Docker Compose:

+
    +

  1. Create required directories

    +

    Create a directory to store the data, configuration and compose +file.

    +

    For example, assuming ./radicale:

    +
    $ mkdir radicale
+$ cd radicale
    +

    Create directories to store data and configuration.

    +

    For example, assuming data directory as ./data and +configuration directory as ./config:

    +
    $ mkdir config data
    2. +

  2. Download the compose file

    +
    $ wget https://raw.githubusercontent.com/Kozea/Radicale/refs/heads/master/compose.yaml
    +

    The compose file assumes ./config and +./data directories. Review the file and modify as +needed.

    3. +

  3. Create Radicale configuration file as necessary

    +

    Create a new configuration file or place an existing one in the +./config directory.

    +

    Note: This section demonstrates only basic steps to +setup Radicale using docker compose. For details on +configuring Radicale, including authentication, please refer to the +documentation for Basic Configuration +or detailed Configuration

    4. +

  4. Start Radicale

    +
    $ docker compose up -d
    +

    This will start the Radicale container in detached mode.

    +

    To view the logs of the running container, run:

    +
    $ docker compose logs -f
    +

    To stop the container, run this from the current directory:

    +
    $ docker compose down
    5. +
+
+
Available tags
+
    +
  • stable: Points to the latest stable release. This is +recommended for most users.
    • +
  • Major.Minor.Patch (e.g. 3.6.1): Points to a specific +release version.
    • +
  • Major.Minor (e.g. 3.6): Tracks the latest release for a +minor version.
    • +
  • Major (e.g. 3): Tracks the latest release for a major +version.
    • +
  • nightly tags (e.g. nightly-20260206): Nightly +builds.
    • +
  • latest: Points to the most recent build. In most cases, +this is nightly.
    • +
+
+
+
+

Linux Distribution Packages

+

Radicale has been packaged for:

+ +

Radicale is also available +on Cloudron.

+

If you are interested in creating packages for other Linux +distributions, read the "Contribute" +section.

+
+
+ +
+
+ diff --git a/html/master/index.html b/html/master/index.html new file mode 100644 index 000000000..d4a7220cf --- /dev/null +++ b/html/master/index.html @@ -0,0 +1,338 @@ + + + + + + + + + + + + + + +Radicale master Documentation + + + + + +
+
+

+Radicale + +master + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+
+

Translations of this page

+ +
+
+

Getting started

+
+

About Radicale

+

Radicale is a small but powerful CalDAV (calendars, to-do lists) and +CardDAV (contacts) server, that:

+
    +
  • Shares calendars and contact lists through CalDAV, CardDAV and +HTTP.
    • +
  • Supports events, todos, journal entries and business cards.
    • +
  • Works out-of-the-box, no complicated setup or configuration +required.
    • +
  • Offers flexible authentication options.
    • +
  • Can limit access by authorization.
    • +
  • Can secure connections with TLS.
    • +
  • Works with many CalDAV and CardDAV +clients.
    • +
  • Stores all data on the file system in a simple folder +structure.
    • +
  • Can be extended with plugins.
    • +
  • Is GPLv3-licensed free software.
    • +
+
+
+

Installation

+

Check

+ +
+
+

What's New?

+

Read the Changelog +on GitHub.

+
+
+ + + + + + + +
+
+ diff --git a/html/master/internals.html b/html/master/internals.html new file mode 100644 index 000000000..7bb21e1ff --- /dev/null +++ b/html/master/internals.html @@ -0,0 +1,671 @@ + + + + + + + + + + + + + + +Radicale master Documentation + + + + + +
+
+

+Radicale + +master + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + + +
+

Internals

+
+

Authorization and Rights

+

This section describes the format of the rights file for the +from_file authentication backend. The configuration option +file in the rights section must point to the +rights file.

+

The recommended rights method is owner_only. If access +is granted to calendars and address books outside the home directory of +users (that's /USERNAME/), clients will not detect these +collections automatically, and will not show them to the users. 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
+

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 +collection. Permissions from the first matching section are used. If no +section matches, access gets denied.

+

The username is empty for anonymous users. Therefore, the regex +.+ only matches authenticated users and .* +matches everyone (including anonymous users).

+

The path of the collection is separated by / and has no +leading or trailing /. Therefore, the path of the root +collection is empty.

+

In the collection regex you can use {user} +and get groups from the user regex with {0}, +{1}, etc.

+

In consequence of the parameter substitution you have to write +{{ and }} if you want to use regular curly +braces in the user and collection regexes.

+

The following permissions are recognized:

+
    +
  • R: read collections (excluding address books and +calendars)
    • +
  • r: read address book and calendar collections
    • +
  • i: subset of r that only allows +direct access via HTTP method GET (CalDAV/CardDAV is susceptible to +expensive search requests)
    • +
  • W: write collections (excluding address books and +calendars)
    • +
  • w: write address book and calendar collections
    • +
  • D: allow deleting a collection in case +permit_delete_collection=False (>= 3.3.0)
    • +
  • d: deny deleting a collection in case +permit_delete_collection=True (>= 3.3.0)
    • +
  • O: allow overwriting a collection in case +permit_overwrite_collection=False (>= +3.3.0)
    • +
  • o: deny overwriting a collection in case +permit_overwrite_collection=True (>= +3.3.0)
    • +
  • T: permit create of token-based sharing of +collection in case permit_create_token=False (>= +3.7.0)
    • +
  • t: deny create of token-based sharing of collection +in case permit_create_token=True (>= +3.7.0)
    • +
  • M: permit create of map-based sharing of collection +in case permit_create_map= False (>= +3.7.0)
    • +
  • m: deny create of map-based sharing of collection +in case permit_create_map=True (>= 3.7.0)
    • +
+
+
+

Storage

+

This document describes the layout and format of the file system +storage, the multifilesystem backend.

+

It is safe to access and manipulate the data by hand or with scripts. +Scripts can be invoked manually, periodically (e.g. using cron) +or after each change to the storage with the configuration option +hook in the storage section (e.g. Versioning collections with +Git).

+
+

Layout

+

The file system comprises the following files and folders:

+
    +
  • .Radicale.lock: The lock file for locking the +storage.
    • +
  • collection-root: This folder contains all collections +and items.
    • +
+

Each collection is represented by a folder. This folder may contain +the file .Radicale.props with all WebDAV properties of the +collection encoded as JSON.

+

Each item in a calendar or address book collection is represented by +a file containing the item's iCalendar resp. vCard data.

+

All files and folders, whose names start with a dot but not with +.Radicale. (internal files) are ignored.

+

Syntax errors in any of the files will cause all requests accessing +the faulty data to fail. The logging output should contain the names of +the culprits.

+

Caches and sync-tokens are stored in the .Radicale.cache +folder inside of collections. This folder may be created or modified, +while the storage is locked for shared access. In theory, it should be +safe to delete the folder. Caches will be recreated automatically and +clients will be told that their sync-token is not valid anymore.

+

You may encounter files or folders that start with +.Radicale.tmp-. Radicale uses them for atomic creation and +deletion of files and folders. They should be deleted after requests are +finished but it is possible that they are left behind when Radicale or +the computer crashes. You can safely delete them.

+
+
+

Locking

+

When the data is accessed by hand or by an externally invoked script, +the storage must be locked. The storage can be locked for exclusive or +shared access. It prevents Radicale from reading or writing the file +system. The storage is locked with exclusive access while the +hook runs.

+
+
Linux shell scripts
+

Use the flock +utility to acquire exclusive or shared locks for the commands you want +to run on Radicale's data.

+
# Exclusive lock for COMMAND
+$ flock --exclusive /path/to/storage/.Radicale.lock COMMAND
+# Shared lock for COMMAND
+$ flock --shared /path/to/storage/.Radicale.lock COMMAND
+
+
+
Linux and MacOS
+

Use the flock +syscall. Python provides it in the fcntl +module.

+
+
+
Windows
+

Use LockFile +for exclusive access or LockFileEx +which also supports shared access. Setting +nNumberOfBytesToLockLow to 1 and +nNumberOfBytesToLockHigh to 0 works.

+
+
+
+

Manually creating collections

+

To create a new collection, you need to create the corresponding +folder in the file system storage (e.g. +collection-root/user/calendar). To indicate to Radicale and +clients that the collection is a calendar, you have to create the file +.Radicale.props with the following content in the +folder:

+
{"tag": "VCALENDAR"}
+

The calendar is now available at the URL path (e.g. +/user/calendar). For address books +.Radicale.props must contain:

+
{"tag": "VADDRESSBOOK"}
+

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 +/USERNAME/.

+

Delete collections by deleting the corresponding folders.

+
+
+
+

Logging overview

+

Radicale logs to stderr. The verbosity of the log output +can be controlled with --debug command line argument or the +level configuration option in the logging section.

+
+
+

Architecture

+

Radicale is a small piece of software, but understanding it is not as +easy as it seems. But don't worry, reading this short section is enough +to understand what a CalDAV/CardDAV server is, and how Radicale's code +is organized.

+
+

Protocol overview

+

Here is a simple overview of the global architecture for reaching a +calendar or an address book through network:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PartLayerProtocol or Format
ServerCalendar/Contact StorageiCal/vCard
''Calendar/Contact ServerCalDAV/CardDAV Server
TransferNetworkCalDAV/CardDAV (HTTP + TLS)
ClientCalendar/Contact ClientCalDAV/CardDAV Client
''GUITerminal, GTK, Web interface, etc.
+

Radicale is only the server part of this +architecture.

+

Please note:

+
    +
  • CalDAV and CardDAV are extension protocols of WebDAV,
    • +
  • WebDAV is an extension of the HTTP protocol.
    • +
+

Radicale being a CalDAV/CardDAV server, can also be seen as a special +WebDAV and HTTP server.

+

Radicale is not the client part of this +architecture. It means that Radicale never draws calendars, address +books, events and contacts on the screen. It only stores them and give +the possibility to share them online with other people.

+

If you want to see or edit your events and your contacts, you have to +use another software called a client, that can be a "normal" +applications with icons and buttons, a terminal or another web +application.

+
+
+

Code Architecture

+

The radicale package offers the following modules.

+
    +

  • __init__ : Contains the entry point for +WSGI.

    • +

  • __main__ : Provides the entry point for the +radicale executable and includes the command line parser. +It loads configuration files from the default (or specified) paths and +starts the internal server.

    • +

  • app : This is the core part of Radicale, with the +code for the CalDAV/CardDAV server. The code managing the different HTTP +requests according to the CalDAV/CardDAV specification can be found +here.

    • +

  • auth : Used for authenticating users based on +username and password, mapping usernames to internal users and +optionally retrieving credentials from the environment.

    • +

  • config : Contains the code for managing +configuration and loading settings from files.

    • +

  • ìtem : Internal representation of address book and +calendar entries. Based on VObject.

    • +

  • log : The logger for Radicale based on the default +Python logging module.

    • +

  • rights : This module is used by Radicale to manage +access rights to collections, address books and calendars.

    • +

  • server : The integrated HTTP server for standalone +use.

    • +

  • storage : This module contains the classes +representing collections in Radicale and the code for storing and +loading them in the filesystem.

    • +

  • sharing : This module contains the classes +representing collection sharing. (>= 3.7.0)

    • +

  • web : This module contains the web +interface.

    • +

  • utils : Contains general helper functions.

    • +

  • httputils : Contains helper functions for working +with HTTP.

    • +

  • pathutils : Helper functions for working with paths +and the filesystem.

    • +

  • xmlutils : Helper functions for working with the XML +part of CalDAV/CardDAV requests and responses. It's based on the +ElementTree XML API.

    • +
+
+
+
+

Plugins

+

Radicale can be extended by plugins for authentication, rights +management and storage. Plugins are python modules.

+
+

Getting started with plugin development

+

To get started we walk through the creation of a simple +authentication plugin, that accepts login attempts with a static +password.

+

The easiest way to develop and install python +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"])
+

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

Install the python module by running the following command in the +same folder as setup.py:

+
python3 -m pip install .
+

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
+

You can uninstall the module with:

+
python3 -m pip uninstall radicale_static_password_auth
+
+
+

Authentication plugins

+

This plugin type is used to check login credentials. The module must +contain a class Auth that extends +radicale.auth.BaseAuth. Take a look at the file +radicale/auth/__init__.py in Radicale's source code for +more information.

+
+
+

Rights management plugins

+

This plugin type is used to check if a user has access to a path. The +module must contain a class Rights that extends +radicale.rights.BaseRights. Take a look at the file +radicale/rights/__init__.py in Radicale's source code for +more information.

+
+
+

Web plugins

+

This plugin type is used to provide the web interface for Radicale. +The module must contain a class Web that extends +radicale.web.BaseWeb. Take a look at the file +radicale/web/__init__.py in Radicale's source code for more +information.

+
+
+

Storage plugins

+

This plugin is used to store collections and items. The module must +contain a class Storage that extends +radicale.storage.BaseStorage. Take a look at the file +radicale/storage/__init__.py in Radicale's source code for +more information.

+
+
+
+ + + +
+
+ diff --git a/html/master/supported-clients.html b/html/master/supported-clients.html new file mode 100644 index 000000000..cf6ce83d5 --- /dev/null +++ b/html/master/supported-clients.html @@ -0,0 +1,441 @@ + + + + + + + + + + + + + + +Radicale master Documentation + + + + + +
+
+

+Radicale + +master + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + +
+

Supported Clients

+

Radicale has been tested with:

+ +

Many clients do not support the creation of new calendars and address +books. You can use Radicale's web interface (e.g. http://localhost:5232) to create and +manage address books and calendars.

+

In some clients, it is sufficient to simply enter the URL of the +Radicale server (e.g. http://localhost:5232) and your +username. In others, you have to enter the URL of the collection +directly (e.g. http://localhost:5232/user/calendar).

+

Some clients (notably macOS's Calendar.app) may silently refuse to +include account credentials over unsecured HTTP, leading to unexpected +authentication failures. In these cases, you want to make sure the +Radicale server is accessible over HTTPS.

+
+

DAVx⁵

+

Enter the URL of the Radicale server (e.g. +http://localhost:5232) and your username. DAVx⁵ will show +all existing calendars and address books and you can create new +ones.

+
+
+

OneCalendar

+

When adding account, select CalDAV account type, then enter username, +password and the Radicale server (e.g. +https://yourdomain:5232). OneCalendar will show all +existing calendars and (FIXME: address books), you need to select which +ones you want to see. OneCalendar supports many other server types +too.

+
+
+

GNOME Calendar, Contacts

+

GNOME 46 added CalDAV and CardDAV support to GNOME Online +Accounts.

+

Open GNOME Settings, navigate to Online Accounts > +Connect an Account > Calendar, Contacts and Files. +Enter the URL (e.g. https://example.com/radicale) and your +credentials then click Sign In. In the pop-up dialog, turn off +Files. After adding Radicale in GNOME Online Accounts, +it should be available in GNOME Contacts and GNOME Calendar.

+
+
+

Evolution

+

In Evolution add a new calendar and address book +respectively with WebDAV. Enter the URL of the Radicale server (e.g. +http://localhost:5232) and your username. Clicking on the +search button will list the existing calendars and address books.

+

Adding CalDAV and CardDAV accounts in Evolution will automatically +make them available in GNOME Contacts and GNOME Calendar.

+
+
+

KDE PIM Applications

+

In Kontact add a DAV Groupware resource to +Akonadi under Settings > Configure Kontact > Calendar > +General > Calendars, select the protocol (CalDAV or CardDAV), +add the URL to the Radicale collections and enter the credentials. After +synchronization of the calendar resp. addressbook items, you can manage +them in Kontact.

+
+
+

Thunderbird

+

Add a new calendar on the network. Enter your username and the URL of +the Radicale server (e.g. http://localhost:5232). After +asking for your password, it will list the existing calendars.

+
+
Address books with CardBook add-on
+

Add a new address book on the network with CardDAV. Enter the URL of +the Radicale server (e.g. http://localhost:5232) and your +username and password. It will list your existing address books.

+
+
+
+

InfCloud, CalDavZAP and CardDavMATE

+

You can integrate InfCloud into Radicale's web interface with by +simply downloading the latest package from InfCloud +and extract the content into a folder named 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

+

This is not the recommended way of creating and managing your +calendars and address books. Use Radicale's web interface or a client +with support for it (e.g. DAVx⁵).

+

To create a new calendar run something like:

+
$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \
+'<?xml version="1.0" encoding="UTF-8" ?>
+<create xmlns="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:I="http://apple.com/ns/ical/">
+  <set>
+    <prop>
+      <resourcetype>
+        <collection />
+        <C:calendar />
+      </resourcetype>
+      <C:supported-calendar-component-set>
+        <C:comp name="VEVENT" />
+        <C:comp name="VJOURNAL" />
+        <C:comp name="VTODO" />
+      </C:supported-calendar-component-set>
+      <displayname>Calendar</displayname>
+      <C:calendar-description>Example calendar</C:calendar-description>
+      <I:calendar-color>#ff0000ff</I:calendar-color>
+    </prop>
+  </set>
+</create>'
+

To create a new address book run something like:

+
$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \
+'<?xml version="1.0" encoding="UTF-8" ?>
+<create xmlns="DAV:" xmlns:CR="urn:ietf:params:xml:ns:carddav">
+  <set>
+    <prop>
+      <resourcetype>
+        <collection />
+        <CR:addressbook />
+      </resourcetype>
+      <displayname>Address book</displayname>
+      <CR:addressbook-description>Example address book</CR:addressbook-description>
+    </prop>
+  </set>
+</create>'
+

The collection /USERNAME will be created automatically, +when the user authenticates to Radicale for the first time. Clients with +automatic discovery of collections will only show calendars and address +books that are direct children of the path /USERNAME/.

+

Delete the collections by running something like:

+
curl -u user -X DELETE 'http://localhost:5232/user/calendar'
+

Note: requires config/option +permit_delete_collection = True

+
+
+ + + + +
+
+ diff --git a/html/master/tutorials.html b/html/master/tutorials.html new file mode 100644 index 000000000..a5d7dca92 --- /dev/null +++ b/html/master/tutorials.html @@ -0,0 +1,841 @@ + + + + + + + + + + + + + + +Radicale master Documentation + + + + + +
+
+

+Radicale + +master + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + +
+

Tutorials

+
+

Simple 5-minute setup

+

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!

+

The server, configured with settings from this section, only binds to +localhost (i.e. it is not reachable over the network), and you can log +in with any username 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 and desired authentication type.

+

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

+
+

Linux / *BSD

+

Hint: instead of downloading from PyPI, look for packages provided by +your distribution. They +contain also startup scripts integrated into your distributions, that +allow Radicale to run daemonized.

+

First, make sure that python 3.9 or later and +pip are installed. On most distributions it should be +enough to install the package python3-pip.

+
+
as normal user
+

Recommended only for testing - open a console and type:

+
# Run the following command to only install for the current user
+python3 -m pip install --user --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
+

If install is not working and instead +error: externally-managed-environment is displayed, create +and activate a virtual environment in advance.

+
python3 -m venv ~/venv
+source ~/venv/bin/activate
+

and try to install with

+
python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
+

Start the service manually, data is stored only for the current +user

+
# Start, data is stored for the current user only
+python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections --auth-type none
+
+
+
as system user (or as root)
+

Alternatively, you can install and run as system user or as root (not +recommended):

+
# Run the following command as root (not recommended) or non-root system user
+# (the later may require --user in case dependencies are not available system-wide and/or virtual environment)
+python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
+

Start the service manually, with data stored in a system folder under +/var/lib/radicale/collections:

+
# Start, data is stored in a system folder (requires write permissions to /var/lib/radicale/collections)
+python3 -m radicale --storage-filesystem-folder=/var/lib/radicale/collections --auth-type none
+
+
+
+

Windows

+

The first step is to install Python. Go to python.org and download the latest version +of Python 3. Then run the installer. On the first window of the +installer, check the "Add Python to PATH" box and click on "Install +now". Wait a couple of minutes, it's done!

+

Launch a command prompt and type:

+
python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
+python -m radicale --storage-filesystem-folder=~/radicale/collections --auth-type none
+
+
Common
+

Success!!! Open http://localhost:5232 in your browser! +You can log in with any username and password as no authentication is +required by example option --auth-type none. This is +INSECURE, see Configuration/Authentication for more details.

+

Just note that default configuration for security reason binds the +server to localhost (IPv4: 127.0.0.1, IPv6: +::1). See Addresses and Configuration/Server for more details.

+
+
+
+
+

Basic Configuration

+

Installation instructions can be found in the simple 5-minute setup tutorial.

+

Radicale tries to load configuration files from +/etc/radicale/config and +~/.config/radicale/config. Custom paths can be specified +with the --config /path/to/config command line argument or +the RADICALE_CONFIG environment variable. Multiple +configuration files can be separated by : (resp. +; on Windows). Paths that start with ? are +optional.

+

You should create a new configuration file at the desired location. +(If the use of a configuration file is inconvenient, all options can be +passed via command line arguments.)

+

All configuration options are described in detail in the Configuration section.

+
+

Authentication

+

In its default configuration since version 3.5.0, Radicale rejects +all authentication attempts by using config option +type = denyall (introduced with 3.2.2) as default until +explicitly configured.

+

Versions before 3.5.0 did not check usernames or passwords at all, +unless explicitly configured. If such a server is reachable over a +network, you should change this as soon as possible.

+

First a users file with all usernames and passwords must +be created. It can be stored in the same directory as the configuration +file.

+
+
The secure way
+

The users file can be created and managed with htpasswd:

+

Note: some OSes or distributions contain outdated versions of +htpasswd (< 2.4.59) without support for SHA-256 or +SHA-512 (e.g. Ubuntu LTS 22). In these cases, use +htpasswd's command line option -B for the +bcrypt hash method (recommended), or stay with the insecure +(not recommended) MD5 (default) or SHA-1 (command line option +-s).

+

Note: support of SHA-256 and 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:
+Re-type new password:
+# Add another user
+$ htpasswd -5 /path/to/users user2
+New password:
+Re-type new password:
+

Authentication can be enabled with the following configuration:

+
[auth]
+type = htpasswd
+htpasswd_filename = /path/to/users
+htpasswd_encryption = autodetect
+
+
+
The simple but insecure way
+

Create the users file by hand with lines containing the +username and password separated by :. Example:

+
user1:password1
+user2:password2
+

Authentication can be enabled with the following configuration:

+
[auth]
+type = htpasswd
+htpasswd_filename = /path/to/users
+# encryption method used in the htpasswd file
+htpasswd_encryption = plain
+
+
+
+

Addresses

+

The default configuration binds the server to localhost. It cannot be +reached from other computers. This can be changed with the following +configuration options (IPv4 and IPv6):

+
[server]
+hosts = 0.0.0.0:5232, [::]:5232
+
+
+

Storage

+

Data is stored in the folder +/var/lib/radicale/collections. The path can be changed with +the following configuration:

+
[storage]
+filesystem_folder = /path/to/storage
+
+

Security: The storage folder shall not be readable +by unauthorized users. Otherwise, they can read the calendar data and +lock the storage. You can find OS dependent instructions in the Running as a service section.

+
+
+
+

Limits

+

Radicale enforces limits on the maximum number of parallel +connections, the maximum file size (important for contacts with big +photos) and the rate of incorrect authentication attempts. Connections +are terminated after a timeout. The default values should be fine for +most scenarios.

+
[server]
+max_connections = 20
+# 100 Megabyte
+max_content_length = 100000000
+# 10 Megabyte (>= 3.5.10)
+max_resource_size = 10000000
+# 30 seconds
+timeout = 30
+
+[auth]
+# Average delay after failed login attempts in seconds
+# Also used for invalid/not-existing/not-enabled share-by-token (>= 3.7.0)
+delay = 1
+
+
+
+

Running as a service

+

The method to run Radicale as a service depends on your host +operating system. Follow one of the chapters below depending on your +operating system and requirements.

+
+

Linux with systemd system-wide

+

Recommendation: check support by Linux Distribution Packages +instead of manual setup / initial configuration.

+

Create the radicale user and group for the Radicale +service by running (as root):

+
useradd --system --user-group --home-dir / --shell /sbin/nologin radicale
+

The storage folder must be made writable by the +radicale user by running (as root):

+
mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections
+

If a dedicated cache folder is configured (see option filesystem_cache_folder), it also +must be made writable by radicale. To achieve that, run +(as root):

+
mkdir -p /var/cache/radicale && chown -R radicale:radicale /var/cache/radicale
+
+

Security: The storage shall not be readable by +others. To make sure this is the case, run (as root):

+
chmod -R o= /var/lib/radicale/collections
+
+

Create the file +/etc/systemd/system/radicale.service:

+
[Unit]
+Description=A simple CalDAV (calendar) and CardDAV (contact) server
+After=network.target
+Requires=network.target
+
+[Service]
+ExecStart=/usr/bin/env python3 -m radicale
+Restart=on-failure
+User=radicale
+# Deny other users access to the calendar data
+UMask=0027
+# Optional security settings
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateDevices=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+NoNewPrivileges=true
+ReadWritePaths=/var/lib/radicale/
+# Replace with following in case dedicated cache folder should be used
+#ReadWritePaths=/var/lib/radicale/ /var/cache/radicale/
+
+[Install]
+WantedBy=multi-user.target
+

In this system-wide implementation, Radicale will load the +configuration from the file /etc/radicale/config.

+

To enable and manage the service run:

+
# Enable the service
+$ systemctl enable radicale
+# Start the service
+$ systemctl start radicale
+# Check the status of the service
+$ systemctl status radicale
+# View all log messages
+$ journalctl --unit radicale.service
+
+
+

Linux with systemd as a user

+

Create the file +~/.config/systemd/user/radicale.service:

+
[Unit]
+Description=A simple CalDAV (calendar) and CardDAV (contact) server
+
+[Service]
+ExecStart=/usr/bin/env python3 -m radicale
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+

In this user-specific configuration, Radicale will load the +configuration from the file ~/.config/radicale/config. You +should set the configuration option filesystem_folder in +the storage section to something like +~/.var/lib/radicale/collections.

+

To enable and manage the service run:

+
# Enable the service
+$ systemctl --user enable radicale
+# Start the service
+$ systemctl --user start radicale
+# Check the status of the service
+$ systemctl --user status radicale
+# View all log messages
+$ journalctl --user --unit radicale.service
+
+
+

Windows with "NSSM - the Non-Sucking Service Manager"

+

First install NSSM and start +nssm install in a command prompt. Apply the following +configuration:

+
    +
  • Service name: Radicale
    • +
  • Application +
      +
    • Path: C:\Path\To\Python\python.exe
      • +
    • Arguments: --config C:\Path\To\Config
      • +
    • +
  • I/O redirection +
      +
    • Error: C:\Path\To\Radicale.log
      • +
    • +
+
+

Security: Be aware that the service runs in the +local system account, you might want to change this. Managing user +accounts is beyond the scope of this manual. Also, make sure that the +storage folder and log file is not readable by unauthorized users.

+
+

The log file might grow very big over time, you can configure file +rotation in NSSM to prevent this.

+

The service is configured to start automatically when the computer +starts. To start the service manually open Services in +Computer Management and start the +Radicale service.

+
+
+
+

Reverse Proxy

+

When a reverse proxy is used, and Radicale should be made available +at a path below the root (such as /radicale/), then this +path must be provided via the X-Script-Name header (without +a trailing /). The proxy must remove the location from the +URL path that is forwarded to Radicale. If Radicale should be made +available at the root of the web server (in the nginx case using +location /), then the setting of the +X-Script-Name header should be removed from the example +below.

+

Example nginx configuration extension:

+

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/nginx/

+
location /radicale/ { # The trailing / is important!
+    proxy_pass        http://localhost:5232;
+    proxy_set_header  X-Script-Name /radicale;
+    proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header  X-Forwarded-Host $host;
+    proxy_set_header  X-Forwarded-Port $server_port;
+    proxy_set_header  X-Forwarded-Proto $scheme;
+    proxy_set_header  Host $http_host;
+    proxy_pass_header Authorization;
+}
+

Example Caddy configuration extension:

+

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/caddy/

+
handle_path /radicale/* {
+    uri strip_prefix /radicale
+    reverse_proxy localhost:5232 {
+        # replace "HOST" with configured hostname of URL (FQDN) in client
+        header_up Host HOST
+        # replace "PORT" with configured port of URL in client
+        header_up X-Forwarded-Port PORT
+    }
+}
+

Example Apache configuration extension:

+

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/apache/

+
RewriteEngine On
+RewriteRule ^/radicale$ /radicale/ [R,L]
+
+<Location "/radicale/">
+    ProxyPass        http://localhost:5232/ retry=0
+    ProxyPassReverse http://localhost:5232/
+    RequestHeader    set X-Script-Name /radicale
+    RequestHeader    set X-Forwarded-Port "%{SERVER_PORT}s"
+    RequestHeader    set X-Forwarded-Proto expr=%{REQUEST_SCHEME}
+    <IfVersion >= 2.4.40>
+    Proxy100Continue Off
+    </IfVersion>
+</Location>
+

Example Apache .htaccess configuration:

+
DirectoryIndex disabled
+RewriteEngine On
+RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]
+
+# Set to directory of .htaccess file:
+RequestHeader set X-Script-Name /radicale
+RequestHeader set X-Forwarded-Port "%{SERVER_PORT}s"
+RequestHeader unset X-Forwarded-Proto
+<If "%{HTTPS} =~ /on/">
+RequestHeader set X-Forwarded-Proto "https"
+</If>
+

Example lighttpd configuration:

+
server.modules += ( "mod_proxy" , "mod_setenv" )
+
+$HTTP["url"] =~ "^/radicale/" {
+  proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => "5232" )) )
+  setenv.add-request-header = ( "X-Script-Name" => "/radicale" )
+}
+

Be reminded that Radicale's default configuration enforces limits on +the maximum number of parallel connections, the maximum file size and +the rate of incorrect authentication attempts. Connections are +terminated after a timeout.

+
+

Manage user accounts with the reverse proxy

+

Set the configuration option type in the +auth section to http_x_remote_user. Radicale +uses the username provided in the X-Remote-User HTTP header +and disables its internal HTTP authentication.

+

Example nginx configuration:

+
location /radicale/ {
+    proxy_pass           http://localhost:5232/;
+    proxy_set_header     X-Script-Name /radicale;
+    proxy_set_header     X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header     X-Remote-User $remote_user;
+    proxy_set_header     Host $http_host;
+    auth_basic           "Radicale - Password Required";
+    auth_basic_user_file /etc/nginx/htpasswd;
+}
+

Example Caddy configuration:

+
handle_path /radicale/* {
+    uri strip_prefix /radicale
+    basicauth {
+        USER HASH
+    }
+    reverse_proxy localhost:5232 {
+        header_up X-Script-Name /radicale
+        header_up X-remote-user {http.auth.user.id}
+    }
+}
+

Example Apache configuration:

+
RewriteEngine On
+RewriteRule ^/radicale$ /radicale/ [R,L]
+
+<Location "/radicale/">
+    AuthType     Basic
+    AuthName     "Radicale - Password Required"
+    AuthUserFile "/etc/radicale/htpasswd"
+    Require      valid-user
+
+    ProxyPass        http://localhost:5232/ retry=0
+    ProxyPassReverse http://localhost:5232/
+    <IfVersion >= 2.4.40>
+    Proxy100Continue Off
+    </IfVersion>
+    RequestHeader    set X-Script-Name /radicale
+    RequestHeader    set X-Remote-User expr=%{REMOTE_USER}
+</Location>
+

Example Apache .htaccess configuration:

+
DirectoryIndex disabled
+RewriteEngine On
+RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]
+
+AuthType     Basic
+AuthName     "Radicale - Password Required"
+AuthUserFile "/etc/radicale/htpasswd"
+Require      valid-user
+
+# Set to directory of .htaccess file:
+RequestHeader set X-Script-Name /radicale
+RequestHeader set X-Remote-User expr=%{REMOTE_USER}
+
+

Security: Untrusted clients should not be able to +access the Radicale server directly. Otherwise, they can authenticate as +any user by simply setting related HTTP header. This can be prevented by +listening to the loopback interface only or local firewall rules.

+
+
+
+

Secure connection between Radicale and the reverse proxy

+

SSL certificates can be used to encrypt and authenticate the +connection between Radicale and the reverse proxy. First you need to +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, +these values do not really 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
+

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
+

If you are using the Let's Encrypt 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/;
+    ...
+    # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...).
+    proxy_ssl_certificate         /path/to/client_cert.pem;
+    proxy_ssl_certificate_key     /path/to/client_key.pem;
+}
+
+
+
+

WSGI Server

+

Radicale is compatible with the WSGI specification.

+

A configuration file can be set with the RADICALE_CONFIG +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
+

Example Gunicorn configuration:

+
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 +auth section to remote_user. This way Radicale +uses the username provided by the WSGI server and disables its internal +authentication over HTTP.

+
+
+
+

Versioning collections with Git

+

This tutorial describes how to keep track of all changes to calendars +and address books with git (or any other version +control system).

+

The repository must be initialized in the collection base directory +of the user running radicale daemon.

+
## assuming "radicale" user is starting "radicale" service
+# change to user "radicale"
+su -l -s /bin/bash radicale
+
+# change to collection base directory defined in [storage] -> filesystem_folder
+#  assumed here /var/lib/radicale/collections
+cd /var/lib/radicale/collections
+
+# initialize git repository
+git init
+
+# set user and e-mail, here minimum example
+git config user.name "$USER"
+git config user.email "$USER@$HOSTNAME"
+
+# define ignore of cache/lock/tmp files
+cat <<'END' >.gitignore
+.Radicale.cache
+.Radicale.lock
+.Radicale.tmp-*
+END
+

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

The command gets executed after every change to the storage and +commits the changes into the git repository.

+

Log of git can be investigated using

+
su -l -s /bin/bash radicale
+cd /var/lib/radicale/collections
+git log
+

In case of problems, make sure you run radicale with +--debug switch and inspect the log output. For more +information, please visit section on +logging.

+

Reason for problems can be

+
    +
  • SELinux status -> check related audit log
    • +
  • problematic file/directory permissions
    • +
  • command is not fond or cannot be executed or argument problem
    • +
+
+
+ + + + + + +
+
+ diff --git a/html/v1/contribute.html b/html/v1/contribute.html new file mode 100644 index 000000000..31c2a04b1 --- /dev/null +++ b/html/v1/contribute.html @@ -0,0 +1,407 @@ + + + + + + + + + + + + + + +Radicale v1 Documentation + + + + + +
+
+

+Radicale + +v1 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + +
+

Contribute

+
+

Chat with Us on IRC

+

Want to say something? Join our IRC room: ##kozea on Freenode.

+
+
+

Report Bugs

+

Found a bug? Want a new feature? Report a new issue on the +Radicale bug-tracker.

+
+
+

Hack

+

Interested in hacking? Feel free to clone the +git repository on Github if you want to add new features, +fix bugs or update documentation.

+
+
+ + + +
+
+ diff --git a/html/v1/documentation.html b/html/v1/documentation.html new file mode 100644 index 000000000..556d8412a --- /dev/null +++ b/html/v1/documentation.html @@ -0,0 +1,1802 @@ + + + + + + + + + + + + + + +Radicale v1 Documentation + + + + + +
+
+

+Radicale + +v1 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ +
+

Documentation

+
+

User documentation

+

This document describes how to install and configure the server.

+ +
+
+

Project description

+

This document defines the main goals of the Radicale Project, what it +covers and what it does not.

+ +
+
+

Technical choices

+

This document describes the global technical choices of the Radicale +Project and the global architectures of its different parts.

+ +
+
+

User Documentation

+
+

Installation

+
+
Dependencies
+

Radicale is written in pure Python and does not depend on any +library. It is known to work on Python 2.6, 2.7, 3.1, 3.2, 3.3, 3.4 and +PyPy > 1.9. The dependencies are optional, as they are only needed +for various authentication methods[1].

+

Linux and MacOS users certainly have Python already installed. For +Windows users, please install Python[2] thanks to the +adequate installer.

+
+
+
Radicale
+

Radicale can be freely downloaded on the project +website, download section. Just get the file and unzip it in a +folder of your choice.

+
+
+
CalDAV and CardDAV Clients
+

At this time Radicale has been tested and works fine with the latest +version of:

+ +

More clients will be supported in the future. However, it may work +with any calendar or contact client which implements CalDAV or CardDAV +specifications too (luck is highly recommended).

+
+
+
+

Simple Usage

+
+
Starting the Server
+

To start Radicale CalDAV server, you have to launch the file called +radicale.py located in the root folder of the software +package.

+
+
+
Starting the Client
+
+
Lightning
+

After starting Lightning, click on File and +New Calendar. Upcoming window asks you about your calendar +storage. Chose a calendar On the Network, otherwise +Lightning will use its own file system storage instead of Radicale's one +and your calendar won't be remotely accessible.

+

Next window asks you to provide information about remote calendar +access. Protocol used by Radicale is CalDAV. A standard +location for a basic use of a Radicale calendar is +http://localhost:5232/user/calendar.ics/, where you can +replace user and calendar.ics by some strings +of your choice. Calendars are automatically created if needed. Please +note that the trailing slash is important.

+

You can now customize your calendar by giving it a nickname and a +color. This is only used by Lightning to identify calendars among +others.

+

If no warning sign appears next to the calendar name, you can now add +events and tasks to your calendar. All events and tasks are stored in +the server, they can be accessed and modified from multiple clients by +multiple users at the same time.

+

Lightning and Thunderbird cannot access CardDAV servers yet. Also, as +of version 17.0.5 the SOGo Connector addon is not fully functionally and +will create extra address book entries with every sync.

+
+
+
Evolution
+

Calendars

+

First of all, show the calendar page in Evolution by clicking on the +calendar icon at the bottom of the side pane. Then add a new calendar by +choosing in the menu File → New → Calendar.

+

A new window opens. The calendar type is +CalDAV, and the location is something like +http://localhost:5232/user/calendar.ics/, where you can +replace user and calendar by some strings of +your choice. Calendars are automatically created if needed. Please note +that the trailing slash is important.

+

You can fill other attributes like the color and the name, these are +only used for Evolution and are not uploaded.

+

Click on OK, and your calendar should be ready for +use.

+

Contacts

+

Switch to the contacts page and click +File → New → Adress book. In the new window choose +WebDAV as type and something like +http://localhost:5232/user/addressbook.vcf/ as location. +Remember to enter the correct username.

+
+
+
KOrganizer
+

Calendars

+

Tested with 4.8.3, you need one running on Akonadi for Cal/CarDav +support.

+

The procedure below can also be done trough the sidebar "Calendar +Manager". But to ensure it works for everyone this examples uses the +menu-bar.

+
    +
  1. Click Settings → Configure KOrganizer.
    2. +
  2. Click on General → Calendars.
    3. +
  3. Click on Add.
    4. +
  4. Choose DAV groupware resource (and click +OK).
    5. +
  5. Enter your username/passord (and click on Next).
    6. +
  6. Select Configure the resource manually (and click on +Finish).
    7. +
  7. Fill in a Display name.
    8. +
  8. Fill in your Username and Password.
    9. +
  9. Click Add.
    10. +
  10. Choose CalDav.
    11. +
  11. For remote URL enter +http://myserver:5232/Username/Calendar.ics/
    12. +
  12. Click Fetch.
    13. +
  13. Select desired calendar.
    14. +
  14. Hit OK.
    15. +
  15. Hit OK again.
    16. +
  16. Close the Configuration Window (Click OK).
    17. +
  17. Restart Korganizer for the calendar to appear in the "Calendar +Manager" sidebar (at least with version 4.8.3.)
    18. +
+
+

Note

+

After you created a calender in a collection you can also use +http://myserver:5232/Username/ as an URL This will then +list all available calendars.

+
+

Contacts

+

You can add a address book analogously to the above instructions, +just choose CardDav and +http://myserver:5232/Username/AddressBook.vcf/ in step 10 +and 11. Also, if you already have a calendar set up you can add an +address book to its "DAV groupware resource" under Configure-Kontact → +Calendar → General → Calendars → Modify. This way you don't have to +enter username and password twice.

+
+
+
CalendarSync
+

CalendarSync can be combined with any Android calendar app and can +even store the calendars in existing Android calendars which are synced +by other sync adapters. Of course it can also create its own +calendars.

+

So, to sync using CalendarSync you will have to:

+
    +
  • start the app,
    • +
  • press the Menu button,
    • +
  • select Create WebiCal,
    • +
  • choose to start with a guided configuration.
    • +
+

Then enter your URL, Username and Password. As URL please use +http(s)://server:port/username/.

+

If you can use HTTPS depends on your setup. Please replace +username with the name of your user account.

+

Press test connection button. If everything signaled as OK then press +search calendars button, select the calendars which you want to sync, +and press the configure calendar button at the top of the display. Your +calendars are now configured.

+

You can then start the first sync by going back to the main screen of +the app an pressing the Process Webicals button. Of course +you can also configure the app at its preferences to sync +automatically.

+
+
+
ContactSync
+

ContactSync is designed to sync contacts from and to various sources. +It can also overtake contacts and push them to the server, also if they +are only available on the device (local only contacts).

+

So to sync your contacts from the Radical server to your Android +device:

+
    +
  • start the app
    • +
  • press the Menu button,
    • +
  • select Create WebContact,
    • +
  • select guided configuration mode.
    • +
+

As URL please use http(s)://server:port/username/.

+

At the URL you will have to replace server:port and +username so that it matches your specific setup. It also +depends on your configuration if you can use HTTPS or if you have to use +HTTP.

+

Press test connection button, if everything signaled as OK then press +search address book button. Select the address books which you want to +sync and press the configure address book button at the top of the +display.

+

You can then start the first sync by going back to the main screen of +the app and pressing the Handle WebContacts button. Of +course you can also configure the app at its preferences to sync +automatically.

+
+
+
CalDAV-Sync
+

CalDAV-Sync is implemented as sync adapter to integrate seamlessly +with any calendar app and widget. Therefore you have to access it via +Accounts & Sync settings after installing it from the +Market.

+

So, to add new calendars to your phone open +Accounts & Sync settings and tap on +Add account, selecting CalDAV as type. In the next view, +you have to switch to Manual Mode. Enter the full CalDAV URL of your +Radicale account (e.g. http://example.com:5232/Username/) +and corresponding login data. If you want to create a new calendar you +have to specify its full URL e.g. +http://example.com:5232/Username/Calendar.ics/. Please note +that the trailing slash is important.

+

Tap on Next and the app checks for all available +calendars on your account, listing them in the next view. (Note: +CalDAV-Sync will not only check under the url you entered but also under +http://example.com:5232/UsernameYouEnteredForLogin/. This +might cause strange errors.) You can now select calendars you want to +sync and set a local nickname and color for each. Hitting +Next again brings up the last page. Enter your email +address and uncheck Sync from server to phone only if you +want to use two-way-sync.

+
+

Note

+

CalDAV-Sync officially is in alpha state and two-way-sync is marked +as an experimental feature. Though it works fine for me, using +two-way-sync is on your own risk!

+
+

Tap on Finish and you're done. You're now able to use +the new calendars in the same way you were using Google calendars +before.

+
+
+
CardDAV-Sync
+

Set up works like CalDAV-Sync, just use .vcf instead of .ics if you +enter the URL, e.g. +http://example.com:5232/Username/AddressBook.vcf/.

+
+
+
DAVdroid
+

DAVdroid is a free and +open-source CalDAV/CardDAV client that is available in Play Store for a +small fee or in FDroid for free.

+

To make it working with Radicale, just add a new DAVdroid account and +enter https://example.com/radicale/user/ as base URL +(assuming that your Radicale runs at +https://example.com/radicale/; don't forget to set +base_prefix correctly).

+
+
+
aCal
+

aCal is a CalDAV client for Android. It comes with its own calendar +application and does not integrate in the Android calendar. It is a +"CalDAV only" calendar, i.e. it only works in combination with a CalDAV +server. It can connect to several calendars on the server and will +display them all in one calendar. It works nice with Radicale.

+

To configure aCal, start aCal, go to the Settings +screen, select Server, then Add server. Choose +Manual Configuration and select Advanced +(bottom of the screen). Then enter the host name of your server, check +Active, enter your user name and password. The +Simple Domain of your server is the domain part of your +fully qualified host name (e.g. if your server is +myserver.mydomain.org, choose +mydomain.org).

+

As Simple Path you need to specify +/<user> where user is the user you use to connect to +Radicale. Server Name is the fully qualified name of your +server machine (myserver.mydomain.org). The +Server Path is /<user>/.

+

For Authentication Type you need to specify the method +you chose for Radicale. Check Use SSL if your Radicale is +configured to use SSL.

+

As the last thing you need to specify the port Radicale listens to. +When your server is configured you can go back to the first +Settings screen, and select +Calendars and Addressbooks. You should find all the +calendars that are available to your user on the Radicale server. You +can then configure each of them (display colour, notifications, +etc.).

+
+
+
InfCloud, CalDavZAP & CardDavMATE
+

Because settings are the same for InfCloud, +CalDavZAP and CardDavMATE
+only InfCloud is used in description below.

+

Radicale configuration

+

Add/Modify the following section in Radicale main configuration +file:

+
# Additional HTTP headers
+[headers]
+Access-Control-Allow-Origin = *
+Access-Control-Allow-Methods = GET, POST, OPTIONS, PROPFIND, PROPPATCH, REPORT, PUT, MOVE, DELETE, LOCK, UNLOCK
+Access-Control-Allow-Headers = Authorization, Content-type, Depth, Destination, If-match, If-None-Match, Lock-Token, Overwrite, Prefer, Timeout, User-Agent, X-Client, X-Requested-With
+Access-Control-Expose-Headers = Etag
+

InfCloud needs read access for everybody +(including anonymous users) on Radicale's root directory. If using +Radicales rights management add the following section to rights +file:

+
# Allow caldavzap, carddavmate and infcloud to work
+[infcloud]
+user: .*
+collection: /
+permission: r
+

Additional you need to change [owner-write] section to +use the same syntax for collection as shown in [public] +section.

+
# Give write access to owners
+[owner-write]
+user: .+
+# collection: ^%(login)s/.+$    # DOES NOT WORK
+collection: ^%(login)s(/.+)?$
+permission: rw
+

InfCloud configuration

+

Inside InfCloud configuration file +config.js you need to set +globalNetworkCheckSettings like following example:

+
// href: 
+// put in here your protocol, host and port where Radicale is listening
+// additionalResources:
+// put in here a comma separated list of collections you want additionally look at.
+// Don't forget '' around each collections name
+var globalNetworkCheckSettings={
+    href: 'https://host.example.com:5232/',
+    hrefLabel: null,
+    crossDomain: null,
+    additionalResources: ['public'],
+    forceReadOnly: null,
+    withCredentials: false,
+    showHeader: true,
+    settingsAccount: true,
+    syncInterval: 60000,
+    timeOut: 30000,
+    lockTimeOut: 10000,
+    delegation: false,
+    ignoreAlarms: false,
+    backgroundCalendars: []
+}
+
+

Note

+

InfCloud, CardDavMATE and +CalDavZAP cannot create calendars and/or address books. +They need to be created before first login. Each user +needs to have minimum of one calendar and/or one adressbook even if only +using shared addresses and/or calendars. Client will not login, if the +user collections don't exists.

+
+

You can easily create them by directly calling the URL's from your +browser:
+  http(s)://host.example.com:5232/user/calendar.ics/
+  http(s)://host.example.com:5232/user/addresses.vcf/

+

Replace "http(s)" with the correct protocol, "host.example.com:5232" +with you host:port where Radicale is running,
+"user" with the correct login name or the shared resource name i.e. +'public',
+"calendar.ics" and "addresses.vcf" with the collection names you want to +use
+and do NOT forget the '/' at line end.

+
+

Note

+

If using self-signed certificates you need to do the following steps +before using InfCloud, CardDavMATE or +CalDavZAP.
+With your browser call one of the above URLs.
+Your browser warn you that you are trying to access an +Insecure site.
+Download and accept the certificate offered by the Radicale +server.
+After installing and accepting it you should restart your browser.

+
+
+
+
iPhone & iPad
+

Calendars

+

For iOS devices, the setup is fairly straightforward but there are a +few settings that are critical for proper operation.

+
    +
  1. From the Home screen, open Settings
    2. +
  2. Select Mail, Contacts, Calendars
    3. +
  3. Select Add Account… → Other → +Add CalDAV Account
    4. +
  4. Enter the server URL here, including https, the port, +and the user/calendar path, ex: +https://myserver.domain.com:3000/bob/birthdays.ics/ (please +note that the trailing slash is important)
    5. +
  5. Enter your username and password as defined in your server +config
    6. +
  6. Enter a good description of the calendar in the +Description field. Otherwise it will put the whole +servername in the field.
    7. +
  7. Now go back to the Mail, Contacts, Calendars screen and +scroll down to the Calendars section. You must change the +Sync option to sync All events otherwise new +events won't show up on your iOS devices!
    8. +
+
+

Note

+

Everything should be working now so test creating events and make +sure they stay created. If you create events on your iOS device and they +disappear after the fetch period, you probably forgot to change the sync +setting in step 7. Likewise, if you create events on another device and +they don't appear on your iPad of iPhone, then make sure your sync +settings are correct

+
+
+

Warning

+

In iOS 5.x, please check twice that the Sync all entries +option is activated, otherwise some events may not be shown in your +calendar.

+
+

Contacts

+

In Contacts on iOS 6:

+
    +
  1. From the Home screen, open Settings
    2. +
  2. Select Mail, Contacts, Calendars
    3. +
  3. Select Add Account… → Other → +Add CardDAV Account
    4. +
  4. As Server use the Radicale server URL with port, for +example localhost:5232
    5. +
  5. Add any User name you like (if you didn't configure +authentication)
    6. +
  6. Add any Password you like (again, if you didn't +configure authentication)
    7. +
  7. Change the Description to something more readable +(optional)
    8. +
  8. Tap Next
    9. +
  9. An alert showing Cannot Connect Using SSL will pop up +as we haven't configured SSL yet, Continue for now
    10. +
  10. Back on the Mail, Contacts, Calendars screen you scroll +to the Contacts section, select the Radicale server as +Default Account when you want to save new contacts to the +Radicale server
    11. +
  11. Exit to the Home screen and open Contacts, tap +Groups, you should see the Radicale server
    12. +
+
+

Note

+

You'll need version 0.8.1 or up for this to work. Earlier versions +will forget your new settings after a reboot.

+
+
+
+
OS X
+
+

Note

+

This description assumes you do not have any authentication or +encryption configured. If you want to use iCal with authentication or +encryption, you just have to fill in the corresponding fields in your +calendar's configuration.

+
+

Calendars

+

In iCal 4.0 or iCal 5.0:

+
    +
  1. Open the Preferences dialog and select the +Accounts tab
    2. +
  2. Click the + button at the lower left to open the +account creation wizard
    3. +
  3. As Account type select CalDAV
    4. +
  4. Select any User name you like
    5. +
  5. The Password field can be left empty (we did not +configure authentication)
    6. +
  6. As Server address use domain:port, for +example localhost:5232 (this would be the case if you start +an unconfigured Radicale on your local machine)
    7. +
+

Click Create. The wizard will now tell you, that no +encryption is in place (Unsecured Connection). This is +expected and will change if you configure Radicale to use SSL. Click +Continue.

+
+

Warning

+

In iCal 5.x, please check twice that the +Sync all entries option is activated, otherwise some events +may not be shown in your calendar.

+
+

The wizard will close, leaving you in the Account tab +again. The account is now set-up. You can close the +Preferences window.

+
+

Important

+

To add a calendar to your shiny new account you have to go to the +menu and select +File → New Calendar → <your shiny new account>. A new +calendar appears in the left panel waiting for you to enter a name.

+

This is needed because the behaviour of the big + button +in the main window is confusing as you can't focus an empty account and +iCal will just add a calendar to another account.

+
+

Contacts

+

In Contacts 7 (previously known as AddressBook):

+
    +
  1. Open the Preferences dialog and select the +Accounts tab.
    2. +
  2. Click the + button at the lower left to open the +account creation wizard.
    3. +
  3. As Account type select CardDAV.
    4. +
  4. Add any User name you like.
    5. +
  5. The Password field can be left empty (if we didn't +configure authentication).
    6. +
  6. As Server address use domain:port, for +example localhost:5232 (this would be the case if you start +an unconfigured Radicale server on your local machine).
    7. +
  7. Click Create. Contacts will complain about an +Unsecured Connection if you don't have SSL enabled. Click +Create again.
    8. +
  8. You might want to change the Description of the newly +added account to something more readable. (optional)
    9. +
  9. Switch to the General tab in the preferences and select +the Radicale server as Default Account at the bottom of the +screen. It probably shows up as `domain:port or the name +you choose if you changed the description. Newly added contacts are +added to the default account and by default this will be the local +On My Mac account.
    10. +
+
+

Note

+

You'll need version 0.8.1 or up for this to work. Earlier versions +can read CardDAV contacts but can't add new contacts.

+
+
+
+
syncEvolution
+

You can find more information about syncEvolution and Radicale on the +syncEvolution +wiki page.

+
+
+
Nokia / Microsoft Windows Phones
+
    +
  1. Go to "Settings" > "email+accounts"
    2. +
  2. Click "add an account" > "iCloud"
    3. +
  3. Enter random email address (e.g. "foo@bar" and "qwerty") > "sign in"
    4. +
  4. A new account "iCloud" with the given email address appears on the +list. The status is "Not up to date". Click the account.
    5. +
  5. An error message is given. Click "close".
    6. +
  6. Enter new and "real" values to the account setting fields: +
      +
    • "Account name": This name appears on the calendar etc. Examples: +"Home", "Word", "Sauna reservation"
      • +
    • "Email address": Not used
      • +
    • "Sync contacts and calendar": Select the sync interval
      • +
    • "Content to sync": Uncheck "Contacts", check "Calendar"
      • +
    • "Your name": Not used
      • +
    • "Username": Username to your Radicale server
      • +
    • "Password": Password to your Radicale server
      • +
    • Click "advanced settings"
      • +
    • "Calendar server (CalDAV)": Enter the full path to the calendar .ics +file. Don't forget the trailing slash. Example: +https://my.server.fi:5232/myusername/calendarname.ics/
      • +
    7. +
+

Don't forget to add your CA to the phone if you're using a +self-signed certificate on your Radicale. Make the CA downloadable to +Internet Explorer. The correct certificate format is X509 (with .cer +file extension).

+
+
+
+
+

Complex Configuration

+
+

Note

+

This section is written for Linux users, but can be easily adapted +for Windows and MacOS users.

+
+
+
Installing the Server
+

You can install Radicale thanks to the following command, with +superuser rights:

+
python setup.py install
+

Then, launching the server can be easily done by typing as a normal +user:

+
radicale
+
+
+
Configuring the Server
+
+
Main Configuration File
+
+

Note

+

This section is following the latest stable version changes. Please +look at the default configuration file included in your package if you +have an older version of Radicale.

+
+

The server configuration can be modified in +/etc/radicale/config or in +~/.config/radicale/config. You can use the +--config parameter in the command line to choose a specific +path. You can also set the RADICALE_CONFIG environment +variable to a path of your choice. Here is the default configuration +file, with the main parameters:

+
[server]
+
+# CalDAV server hostnames separated by a comma
+# IPv4 syntax: address:port
+# IPv6 syntax: [address]:port
+# For example: 0.0.0.0:9999, [::]:9999
+# IPv6 adresses are configured to only allow IPv6 connections
+#hosts = 0.0.0.0:5232
+
+# Daemon flag
+#daemon = False
+
+# File storing the PID in daemon mode
+#pid =
+
+# SSL flag, enable HTTPS protocol
+#ssl = False
+
+# SSL certificate path
+#certificate = /etc/apache2/ssl/server.crt
+
+# SSL private key
+#key = /etc/apache2/ssl/server.key
+
+# SSL Protocol used. See python's ssl module for available values
+#protocol = PROTOCOL_SSLv23
+
+# Ciphers available. See python's ssl module for available ciphers
+#ciphers =
+
+# Reverse DNS to resolve client address in logs
+#dns_lookup = True
+
+# Root URL of Radicale (starting and ending with a slash)
+#base_prefix = /
+
+# Possibility to allow URLs cleaned by a HTTP server, without the base_prefix
+#can_skip_base_prefix = False
+
+# Message displayed in the client when a password is needed
+#realm = Radicale - Password Required
+
+
+[encoding]
+
+# Encoding for responding requests
+#request = utf-8
+
+# Encoding for storing local collections
+#stock = utf-8
+
+
+[well-known]
+
+# Path where /.well-known/caldav/ is redirected
+#caldav = '/%(user)s/caldav/'
+
+# Path where /.well-known/carddav/ is redirected
+#carddav = '/%(user)s/carddav/'
+
+
+[auth]
+
+# Authentication method
+# Value: None | htpasswd | IMAP | LDAP | PAM | courier | http | remote_user | custom
+#type = None
+
+# Custom authentication handler
+#custom_handler =
+
+# Htpasswd filename
+#htpasswd_filename = /etc/radicale/users
+
+# Htpasswd encryption method
+# Value: plain | sha1 | ssha | crypt | bcrypt | md5
+#htpasswd_encryption = crypt
+
+# LDAP server URL, with protocol and port
+#ldap_url = ldap://localhost:389/
+
+# LDAP base path
+#ldap_base = ou=users,dc=example,dc=com
+
+# LDAP login attribute
+#ldap_attribute = uid
+
+# LDAP filter string
+# placed as X in a query of the form (&(...)X)
+# example: (objectCategory=Person)(objectClass=User)(memberOf=cn=calenderusers,ou=users,dc=example,dc=org)
+# leave empty if no additional filter is needed
+#ldap_filter =
+
+# LDAP dn for initial login, used if LDAP server does not allow anonymous searches
+# Leave empty if searches are anonymous
+#ldap_binddn =
+
+# LDAP password for initial login, used with ldap_binddn
+#ldap_password =
+
+# LDAP scope of the search
+#ldap_scope = OneLevel
+
+# IMAP Configuration
+#imap_hostname = localhost
+#imap_port = 143
+#imap_ssl = False
+
+# PAM group user should be member of
+#pam_group_membership =
+
+# Path to the Courier Authdaemon socket
+#courier_socket =
+
+# HTTP authentication request URL endpoint
+#http_url =
+# POST parameter to use for username
+#http_user_parameter =
+# POST parameter to use for password
+#http_password_parameter =
+
+
+[git]
+
+# Git default options
+#committer = Radicale <radicale@example.com>
+
+
+[rights]
+
+# Rights backend
+# Value: None | authenticated | owner_only | owner_write | from_file | custom
+#type = None
+
+# Custom rights handler
+#custom_handler =
+
+# File for rights management from_file
+#file = ~/.config/radicale/rights
+
+
+[storage]
+
+# Storage backend
+# -------
+# WARNING: ONLY "filesystem" IS DOCUMENTED AND TESTED,
+#          OTHER BACKENDS ARE NOT READY FOR PRODUCTION.
+# -------
+# Value: filesystem | multifilesystem | database | custom
+#type = filesystem
+
+# Custom storage handler
+#custom_handler =
+
+# Folder for storing local collections, created if not present
+#filesystem_folder = ~/.config/radicale/collections
+
+# Database URL for SQLAlchemy
+# dialect+driver://user:password@host/dbname[?key=value..]
+# For example: sqlite:///var/db/radicale.db, postgresql://user:password@localhost/radicale
+# See http://docs.sqlalchemy.org/en/rel_0_8/core/engines.html#sqlalchemy.create_engine
+#database_url =
+
+
+[logging]
+
+# Logging configuration file
+# If no config is given, simple information is printed on the standard output
+# For more information about the syntax of the configuration file, see:
+# http://docs.python.org/library/logging.config.html
+#config = /etc/radicale/logging
+# Set the default logging level to debug
+#debug = False
+# Store all environment variables (including those set in the shell)
+#full_environment = False
+
+
+[headers]
+
+# Additional HTTP headers
+#Access-Control-Allow-Origin = *
+

This configuration file is read each time the server is launched. If +some values are not given, the default ones are used. If no +configuration file is available, all the default values are used.

+
+
+
Logging Configuration File
+

Radicale uses the default logging facility for Python. The default +configuration prints the information messages to the standard output. It +is possible to print debug messages thanks to:

+
radicale --debug
+

Radicale can also be configured to send the messages to the console, +logging files, syslog, etc. For more information about the syntax of the +configuration file, see: http://docs.python.org/library/logging.config.html. +Here is an example of logging configuration file:

+
# Loggers, handlers and formatters keys
+
+[loggers]
+# Loggers names, main configuration slots
+keys = root
+
+[handlers]
+# Logging handlers, defining logging output methods
+keys = console,file
+
+[formatters]
+# Logging formatters
+keys = simple,full
+
+
+# Loggers
+
+[logger_root]
+# Root logger
+level = DEBUG
+handlers = console,file
+
+
+# Handlers
+
+[handler_console]
+# Console handler
+class = StreamHandler
+level = INFO
+args = (sys.stdout,)
+formatter = simple
+
+[handler_file]
+# File handler
+class = FileHandler
+args = ('/var/log/radicale',)
+formatter = full
+
+
+# Formatters
+
+[formatter_simple]
+# Simple output format
+format = %(message)s
+
+[formatter_full]
+# Full output format
+format = %(asctime)s - %(levelname)s: %(message)s
+
+
+
Command Line Options
+

All the options of the server part can be changed with +command line options. These options are available by typing:

+
radicale --help
+
+
+
+
WSGI, CGI and FastCGI
+

Radicale comes with a WSGI support, +allowing the software to be used behind any HTTP server supporting WSGI +such as Apache.

+

Moreover, it is possible to use flup to wrap Radicale into +a CGI, FastCGI, SCGI or AJP application, and therefore use it with +Lighttpd, Nginx or even Tomcat.

+
+
Apache and mod_wsgi
+

To use Radicale with Apache's mod_wsgi, you first have +to install the Radicale module in your Python path and write your +.wsgi file (in /var/www for example):

+
import radicale
+radicale.log.start()
+application = radicale.Application()
+
+

Note

+

The hosts, daemon, pid, +ssl, certificate, key, +protocol and ciphers keys of the +[server] part of the configuration are ignored.

+
+

Next you have to create the Apache virtual host (adapt the +configuration to your environment):

+
<VirtualHost *:80>
+    ServerName cal.yourdomain.org
+
+    WSGIDaemonProcess radicale user=www-data group=www-data threads=1
+    WSGIScriptAlias / /var/www/radicale.wsgi
+
+    <Directory /var/www>
+        WSGIProcessGroup radicale
+        WSGIApplicationGroup %{GLOBAL}
+        AllowOverride None
+        Order allow,deny
+        allow from all
+    </Directory>
+</VirtualHost>
+
+

Warning

+

You should use the root of the (sub)domain +(WSGIScriptAlias /), else some CalDAV features may not +work.

+
+

If you want to use authentication with Apache, you really +should use one of the Apache authentication modules, instead of the ones +from Radicale: they're just better.

+

Deactivate any rights and module in Radicale and use your favourite +Apache authentication backend. You can then restrict the access: allow +the alice user to access /alice/* URLs, and +everything should work as expected.

+

Here is one example of Apache configuration file:

+
<VirtualHost *:80>
+    ServerName radicale.local
+
+    WSGIDaemonProcess radicale user=radicale group=radicale threads=1
+    WSGIScriptAlias / /usr/share/radicale/radicale.wsgi
+
+    <Directory /usr/share/radicale/>
+        WSGIProcessGroup radicale
+        WSGIApplicationGroup %{GLOBAL}
+
+        AuthType Basic
+        AuthName "Radicale Authentication"
+        AuthBasicProvider file
+        AuthUserFile /usr/share/radicale/radicale.passwd
+
+        AllowOverride None
+        Require valid-user
+
+        RewriteEngine On
+        RewriteCond %{REMOTE_USER}%{PATH_INFO} !^([^/]+/)\1
+        RewriteRule .* - [Forbidden]
+    </Directory>
+</VirtualHost>
+

If you're still convinced that access control is better with +Radicale, you have to add WSGIPassAuthorization On in your +Apache configuration files, as explained in the +mod_wsgi documentation.

+
+

Note

+

Read-only calendars or address books can also be served by a simple +Apache HTTP server, as Radicale stores full-text icalendar and vcard +files with the default configuration.

+
+
+
+
+
Authentication
+

Authentication is possible through:

+
    +
  • Courier-Authdaemon socket
    • +
  • htpasswd file, including list of plain user/password couples
    • +
  • HTTP, checking status code of a POST request
    • +
  • IMAP
    • +
  • LDAP
    • +
  • PAM
    • +
  • Remote user given by HTTP server
    • +
+

Check the [auth] section of your configuration file to +know the different options offered by these authentication modules.

+

Some authentication methods need additional modules, see Python Versions and OS +Support for further information.

+

You can also write and use a custom module handle authentication if +you use a different technology.

+

Please note that these modules have not been verified by security +experts. If you need a really secure way to handle authentication, you +should put Radicale behind a real HTTP server and use its authentication +and rights management methods.

+
+
+
Rights Management
+

You can set read and write rights for collections according to the +authenticated user and the owner of the collection.

+

The owner of a collection is determined by the URL of the +collection. For example, +http://my.server.com:5232/anna/calendar.ics/ is owned by +the user called anna.

+

The authenticated user is the login used for +authentication.

+

5 different configurations are available, you can choose the one you +want in your configuration file. You can also write and use a custom +module handle rights management if you need a specific pattern.

+
+
None
+

Everybody (including anonymous users) has read and write access to +all collections.

+
+
+
Authenticated
+

An authenticated users has read and write access to all collections, +anonymous users have no access to these collections.

+
+
+
Owner Only
+

Only owners have read and write access to their own collections. The +other users, authenticated or anonymous, have no access to these +collections.

+
+
+
Owner Write
+

Authenticated users have read access to all collections, but only +owners have write access to their own collections. Anonymous users have +no access to collections.

+
+
+
From File
+

Rights are based on a regex-based file whose name is specified in the +config (section "right", key "file").

+

Authentication login is matched against the "user" key, and +collection's path is matched against the "collection" key. You can use +Python's ConfigParser interpolation values %(login)s and %(path)s. You +can also get groups from the user regex in the collection with {0}, {1}, +etc.

+

For example, for the "user" key, ".+" means "authenticated user" and +".*" means "anybody" (including anonymous users).

+

Section names are only used for naming the rule.

+

Leading or ending slashes are trimmed from collection's path.

+

Example:

+
# The default path for this kind of files is ~/.config/radicale/rights
+# This can be changed in the configuration file
+#
+# This file gives independant examples to help users write their own
+# configuration files. Using these examples together in the same configuration
+# file is meaningless.
+#
+# The first rule matching both user and collection patterns will be returned.
+
+# This means all users starting with "admin" may read any collection
+[admin]
+user: ^admin.*$
+collection: .*
+permission: r
+
+# This means all users may read and write any collection starting with public.
+# We do so by just not testing against the user string.
+[public]
+user: .*
+collection: ^public(/.+)?$
+permission: rw
+
+# A little more complex: give read access to users from a domain for all
+# collections of all the users (ie. user@domain.tld can read domain/*).
+[domain-wide-access]
+user: ^.+@(.+)\..+$
+collection: ^{0}/.+$
+permission: r
+
+# Allow authenticated user to read all collections
+[allow-everyone-read]
+user: .+
+collection: .*
+permission: r
+
+# Give write access to owners
+[owner-write]
+user: .+
+collection: ^%(login)s/.*$
+permission: w
+
+
+
+
Git Support
+
+

Note

+

If the project doesn't comply with the requirements to use Git, +Radicale will still work. Your collections will run fine but without the +versionning system.

+
+

Git is now automatically supported on Radicale. It depends on dulwich.

+
+
Configure Radicale
+

Radicale automatically detects the .git folder in the path +you configured for the filesystem_folder variable in the +[storage] section of your configuration file. Make sure a +repository is created at this location or create one (using git init +. for instance) else it won't work.

+

To summarize :

+
    +
  • Configure your Git installation
    • +
  • Get Radicale and dulwich
    • +
  • Create the repository where your collections are stored
    • +
  • Run Radicale and it should work
    • +
+
+
+
How it works
+

Radicale will automatically commit any changes on your collections. +It will use your git config to find parameters such as the committer and +that's all.

+
+
+
Issues
+

A dulwich project ported on Python 3 exists but it seems that it +doesn't follow the current api (committer is mandatory and not retrieved +from the git config by default). Until this problem isn't fixed, the Git +support for Radicale on Python 3 will not be ensured.

+
+
+
+
+

Python Versions and OS Support

+
+
TLS Support
+

Python 2.6 suffered a +bug causing huge timeout problems with TLS. The bug is fixed since +Python 2.6.6.

+

IMAP authentication over TLS requires Python 3.2.

+

Python 2.7 and Python 3.x do not suffer this bug.

+
+
+
Crypt Support
+

With the htpasswd access, many encryption methods are available, and +crypt is the default one in Radicale. Unfortunately, the +crypt module is unavailable on Windows, you have to pick +another method on this OS.

+

Additional md5 and bcrypt methods are +available when the passlib module is installed.

+
+
+
IMAP Authentication
+

The IMAP authentication module relies on the imaplib module, +available with 2.x versions of Python. However, TLS is only available in +Python 3.2. Older versions of Python or a non-modern server who does not +support STARTTLS can only authenticate against localhost as +passwords are transmitted in PLAIN. Legacy SSL mode on port 993 is not +supported.

+
+
+
LDAP Authentication
+

The LDAP authentication module relies on the python-ldap module, and thus +only works with 2.x versions of Python.

+
+
+
PAM Authentication
+

The PAM authentication module relies on the python-pam +module.

+

Bear in mind that on Linux systems, if you're authenticating against +PAM files (i.e. /etc/shadow), the user running Radicale +must have the right permissions. For instance, you might want to add the +radicale user to the shadow group.

+
+
+
HTTP Authentication
+

The HTTP authentication module relies on the requests +module.

+
+
+
Daemon Mode
+

The daemon mode relies on forks, and thus only works on Unix-like +OSes (incuding Linux, OS X, BSD).

+
+
+
+
+

Project Description

+
+

Main Goals

+

The Radicale Project is a complete calendar and contact storing and +manipulating solution. It can store multiple calendars and multiple +address books.

+

Calendar and contact manipulation is available from both local and +distant accesses, possibly limited through authentication policies.

+
+
+

What Radicale Is

+
+
Calendar and Contact Server
+

The Radicale Project is mainly a calendar and contact server, giving +local and distant access for reading, creating, modifying and deleting +multiple calendars through simplified CalDAV and CardDAV protocols.

+

Data can be encrypted by SSL, and their access can be restricted +using different authentication methods.

+
+
+
+

What Radicale Is not and will not Be

+
+
Calendar or Contact User Agent
+

Radicale is a server, not a client. No interfaces will be created to +work with the server, as it is a really (really really) much more +difficult task[3].

+
+
+
Original Calendar or Contact Access Protocol
+

CalDAV and CardDAV are not perfect protocols. We think that their +main problem is their complexity[4], that is why we +decided not to implement the whole standard but just enough to +understand some of its client-side implementations [5].

+

CalDAV and CardDAV are the best open standards available and they are +quite widely used by both clients and servers[6]. We +decided to use it, and we will not use another one.

+
+
+
+
+

Technical Choices

+
+

Global Technical Choices

+
+
General Description
+

The Radicale Project aims to be a light solution, easy to use, easy +to install, easy to configure. As a consequence, it requires few +software dependencies and is pre-configured to work out-of-the-box.

+

The Radicale Project runs on most of the UNIX-like platforms (Linux, +*BSD, MacOS X) and Windows. It is free and open-source software.

+
+
+
Language
+

The different parts of the Radicale Project are written in Python. +This is a high-level language, fully object-oriented, available for the +main operating systems and released with a lot of useful libraries.

+
+
+
Protocols and Formats
+

The main protocols and formats fully or partially implemented in the +Radicale Project are described by RFCs:

+
    +
  • HyperText Transfer Protocol (HTTP) RFC +2616
    • +
  • WebDAV Access Control Protocol (ACL) RFC +3744
    • +
  • Calendaring Extensions to WebDAV (CalDAV) RFC +4791
    • +
  • HTTP Extensions for Web Distributed Authoring and Versioning +(WebDAV) RFC 4918
    • +
  • Transport Layer Security (TLS) RFC +5246
    • +
  • iCalendar format (iCal) RFC +5545
    • +
  • vCard Format Specification RFC +6350
    • +
  • vCard Extensions to Web Distributed Authoring and Versioning +(CardDAV) RFC 6352
    • +
+
+

Note

+

CalDAV and CardDAV implementations require iCal, +vCard, ACL, WebDAV, HTTP and TLS. The Radicale Server does not +and will not implement correctly these standards, as explained +in the Development Choices part.

+
+
+
+
Development Choices
+

Important global development choices have been decided before writing +code. They are very useful to understand why the Radicale Project is +different from other CalDAV and CardDAV servers, and why features are +included or not in the code.

+
+
Oriented to Calendar and Contact User Agents
+

Calendar and contact servers work with calendar and contact clients, +using a defined protocol. CalDAV and CardDAV are good protocols, +covering lots of features and use cases, but it is quite hard to +implement fully.

+

Some calendar servers have been created to follow the CalDAV and +CardDAV RFCs as much as possible: Davical[7], Cosmo[8] and Darwin Calendar Server[9], for +example, are much more respectful of CalDAV and CardDAV and can be used +with a large number of clients. They are very good choices if you want +to develop and test new CalDAV clients, or if you have a possibly +heterogeneous list of user agents.

+

The Radicale Server does not and will not support +the CalDAV and CardDAV standards. It supports the CalDAV and CardDAV +implementations of different clients (Lightning, Evolution, Android, +iPhone, iCal, and more).

+
+
+
Simple
+

The Radicale Server is designed to be simple to install, simple to +configure, simple to use.

+

The installation is very easy, particularly with Linux: no +dependencies, no superuser rights needed, no configuration required. +Launching the main script out-of-the-box, as a normal user, is often the +only step to have a simple remote calendar and contact access.

+

Contrary to other servers that are often complicated, require high +privileges or need a strong configuration, the Radicale Server can +(sometimes, if not often) be launched in a couple of minutes, if you +follow the User Documentation.

+
+
+
Lazy
+

We, Radicale Project developers, are lazy. That is why we have chosen +Python: no more ; or {}[10]. +This is also why our server is lazy.

+

The CalDAV RFC defines what must be done, what can be done and what +cannot be done. Many violations of the protocol are totally defined and +behaviours are given in such cases.

+

The Radicale Server assumes that the clients are perfect and that +protocol violations do not exist. That is why most of the errors in +client requests have undetermined consequences for the lazy server that +can reply good answers, bad answers, or even no answer.

+

As already mentioned, the Radicale server doesn't fully support the +CalDAV and CardDAV RFCs. For example, nested filters in queries +currently don't work in all cases. Examples of not working queries can +be found in issues #120 and #121.

+
+
+
+
+

Architectures

+
+
General Architecture
+

Here is a simple overview of the global architecture for reaching a +calendar through network:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PartLayerProtocol or Format
ServerCalendar/Contact StorageiCal/vCard
Calendar/Contact ServerCalDAV/CardDAV Server
TransferNetworkCalDAV/CardDAV (HTTP + TLS)
ClientCalendar/Contact ClientCalDAV/CardDAV Client
GUITerminal, GTK, etc.
+

The Radicale Project is only the server part of this +architecture.

+
+
+
Code Architecture
+

The package offers 8 modules.

+
    +

  • __main__
    +The main module provides a simple function called run. Its +main work is to read the configuration from the configuration file and +from the options given in the command line; then it creates a server, +according to the configuration.

    • +

  • __init__
    +This is the core part of the module, with the code for the CalDAV +server. The server inherits from a HTTP or HTTPS server class, which +relies on the default HTTP server class given by Python. The code +managing the different HTTP requests according to the CalDAV +normalization is written here.

    • +

  • config
    +This part gives a dict-like access to the server configuration, read +from the configuration file. The configuration can be altered when +launching the executable with some command line options.

    • +

  • ical
    +In this module are written the classes to represent collections and +items in Radicale. The simple iCalendar and vCard readers and writers +are included in this file. The readers and writers are small and stupid: +they do not fully understand the iCalendar format and do not know at all +what a date is.

    • +

  • xmlutils
    +The functions defined in this module are mainly called by the CalDAV +server class to read the XML part of the request, read or alter the +calendars, and create the XML part of the response. The main part of +this code relies on ElementTree.

    • +

  • log
    +The start function provided by this module starts a logging +mechanism based on the default Python logging module. Logging options +can be stored in a logging configuration file.

    • +

  • acl
    +This module is a set of Access Control Lists, a set of methods used by +Radicale to manage rights to access the calendars. When the CalDAV +server is launched, an Access Control List is chosen in the set, +according to the configuration. The HTTP requests are then filtered to +restrict the access using a list of login/password-based access +controls.

    • +

  • storage
    +This folder is a set of storage modules able to read and write +collections. Currently there are three storage modules: +filesystem, storing each collection into one flat +plain-text file, multifilesystem, storing each entries into +separates plain-text files, and database, storing entries +in a database. filesystem is stable and battle-tested, +others are experimentals.

    • +
+ +
+
+
+
+ + + + +
+
+ diff --git a/html/v1/download.html b/html/v1/download.html new file mode 100644 index 000000000..945fd923a --- /dev/null +++ b/html/v1/download.html @@ -0,0 +1,484 @@ + + + + + + + + + + + + + + +Radicale v1 Documentation + + + + + +
+
+

+Radicale + +v1 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + +
+

Download

+
+

PyPI

+

Radicale is available +on PyPI. To install, just type as superuser:

+
pip install radicale==1.1.*
+
+
+

Git Repository

+

If you want the development version of Radicale, take a look at the +git repository on GitHub, or clone it thanks to:

+
git clone git://github.com/Kozea/Radicale.git
+

You can also download the Radicale +package of the git repository.

+
+
+

Source Packages

+

You can download the Radicale package for each release:

+ +
+
+

Linux Distribution Packages

+

Radicale has been packaged for:

+ +

Radicale is also available +on Cloudron and has a Dockerfile.

+

If you are interested in creating packages for other Linux +distributions, read the "Contribute" page.

+
+
+ + +
+
+ diff --git a/html/v1/footnotes.html b/html/v1/footnotes.html new file mode 100644 index 000000000..3f4e1ad00 --- /dev/null +++ b/html/v1/footnotes.html @@ -0,0 +1,441 @@ + + + + + + + + + + + + + + +Radicale v1 Documentation + + + + + +
+
+

+Radicale + +v1 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + + +
+

Footnotes

+
+

1

+

See Python Versions and OS +Support for further information.

+
+
+

2

+

Python download page.

+
+
+

3

+

I repeat: we are lazy.

+
+
+

4

+

Try to read RFC 4791. Then try to understand it. Then try to +implement it. Then try to read it again.

+
+
+

5

+

Radicale is oriented to +calendar user agents.

+
+
+

6

+

CalDAV +implementations, by Wikipedia.

+
+
+

7

+

Davical, a standards-compliant +calendar server.

+
+
+

8

+

Cosmo, +the web contents and calendars sharing server build to support the +Chandler Project.

+
+
+

9

+

Darwin Calendar Server, +a standards-compliant calendar server mainly developed by Apple.

+
+
+

10

+

Who says "Ruby is even less verbose!" should read the PEP +20.

+
+
+
+
+ diff --git a/html/v1/index.html b/html/v1/index.html new file mode 100644 index 000000000..240101c92 --- /dev/null +++ b/html/v1/index.html @@ -0,0 +1,428 @@ + + + + + + + + + + + + + + +Radicale v1 Documentation + + + + + +
+
+

+Radicale + +v1 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+
+

A Simple Calendar and Contact Server

+
+

Presentation

+

The Radicale Project is a complete CalDAV (calendar) and CardDAV +(contact) server solution.

+

Calendars and address books are available for both local and remote +access, possibly limited through authentication policies. They can be +viewed and edited by calendar and contact clients on mobile phones or +computers.

+
+
+

Technical Description

+

Radicale aims to be a light solution, easy to use, easy to install, +easy to configure. As a consequence, it requires few software +dependencies and is pre-configured to work out-of-the-box.

+

Radicale runs on most of the UNIX-like platforms (Linux, *BSD, +MacOS X) and Windows. It is free and open-source software, written in +Python, released under GPL version 3.

+
+
+

Main Features

+
    +
  • Shares calendars through CalDAV, WebDAV and HTTP
    • +
  • Shares contacts through CardDAV, WebDAV and HTTP
    • +
  • Supports events, todos, journal entries and business cards
    • +
  • Works out-of-the-box, no installation nor configuration +required
    • +
  • Warns users on concurrent editing
    • +
  • Limits access by authentication
    • +
  • Secures connections
    • +
+
+
+

Supported Clients

+

Radicale supports the latest versions of many CalDAV and CardDAV +clients.

+
+
+ + + + + +
+
+ diff --git a/html/v1/news.html b/html/v1/news.html new file mode 100644 index 000000000..00a10c881 --- /dev/null +++ b/html/v1/news.html @@ -0,0 +1,1271 @@ + + + + + + + + + + + + + + +Radicale v1 Documentation + + + + + +
+
+

+Radicale + +v1 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + +
+

News

+
+

May 19, 2020 - Radicale 1.1.7

+

Radicale 1.1.7 is out!

+
+

1.1.7 - Third Law of Nature

+
    +
  • Fix error in --export-storage
    • +
  • Include documentation in source archive
    • +
+
+
+
+

Jul 24, 2017 - Radicale 1.1.6

+

Radicale 1.1.6 is out!

+
+

1.1.6 - Third Law of Nature

+
    +
  • Improve logging for --export-storage
    • +
+
+
+
+

Jul 24, 2017 - Radicale 1.1.5

+

Radicale 1.1.5 is out!

+
+

1.1.5 - Third Law of Nature

+
    +
  • Improve logging for --export-storage
    • +
+
+
+
+

Jun 25, 2017 - Radicale 1.1.4

+

Radicale 1.1.4 is out!

+
+

1.1.4 - Third Law of Nature

+
    +
  • Use shutil.move for --export-storage
    • +
+
+
+
+

May 27, 2017 - Radicale 1.1.3

+

Radicale 1.1.3 is out!

+
+

1.1.3 - Third Law of Nature

+
    +
  • Add a --export-storage=FOLDER command-line argument (by +Unrud, see #606)
    • +
+
+
+
+

April 19, 2017 - Radicale 1.1.2

+

Radicale 1.1.2 is out!

+
+

1.1.2 - Third Law of Nature

+
    +
  • Security fix: Add a random timer to avoid timing oracles and simple +bruteforce attacks when using the htpasswd authentication method.
    • +
  • Various minor fixes.
    • +
+
+
+
+

December 31, 2015 - Radicale 1.1

+

Radicale 1.1 is out!

+
+

1.1 - Law of Nature

+

One feature in this release is not backward +compatible:

+
    +
  • Use the first matching section for rights (inspired from daald)
    • +
+

Now, the first section matching the path and current user in your +custom rights file is used. In the previous versions, the most +permissive rights of all the matching sections were applied. This new +behaviour gives a simple way to make specific rules at the top of the +file independant from the generic ones.

+

Many improvements in this release are related to +security, you should upgrade Radicale as soon as possible:

+
    +
  • Improve the regex used for well-known URIs (by Unrud)
    • +
  • Prevent regex injection in rights management (by Unrud)
    • +
  • Prevent crafted HTTP request from calling arbitrary functions (by +Unrud)
    • +
  • Improve URI sanitation and conversion to filesystem path (by +Unrud)
    • +
  • Decouple the daemon from its parent environment (by Unrud)
    • +
+

Some bugs have been fixed and little enhancements have been +added:

+
    +
  • Assign new items to corret key (by Unrud)
    • +
  • Avoid race condition in PID file creation (by Unrud)
    • +
  • Improve the docker version (by cdpb)
    • +
  • Encode message and commiter for git commits
    • +
  • Test with Python 3.5
    • +
+
+
+
+

September 14, 2015 - Radicale 1.0, what's next?

+

Radicale 1.0 is out!

+
+

1.0 - Sunflower

+
    +
  • Enhanced performances (by Mathieu Dupuy)
    • +
  • Add MD5-APR1 and BCRYPT for htpasswd-based authentication (by +Jan-Philip Gehrcke)
    • +
  • Use PAM service (by Stephen Paul Weber)
    • +
  • Don't discard PROPPATCH on empty collections (Markus +Unterwaditzer)
    • +
  • Write the path of the collection in the git message (Matthew +Monaco)
    • +
  • Tests launched on Travis
    • +
+

As explained in a previous mail, +this version is called 1.0 because:

+
    +
  • there are no big changes since 0.10 but some small changes are +really useful,
    • +
  • simple tests are now automatically launched on Travis, and more can +be added in the future (https://travis-ci.org/Kozea/Radicale).
    • +
+

This version will be maintained with only simple bug fixes on a +separate git branch called 1.0.x.

+

Now that this milestone is reached, it's time to think about the +future. When Radicale has been created, it was just a proof-of-concept. +The main goal was to write a small, stupid and simple CalDAV server +working with Lightning, using no external libraries. That's how we +created a piece of code that's (quite) easy to understand, to use and to +hack.

+

The first lines have been added to the SVN (!) repository as I was +drinking beers at the very end of 2008. It's now packaged for a growing +number of Linux distributions.

+

And that was fun going from here to there thanks to you. So… +Thank you, you're amazing. I'm so glad I've spent +endless hours fixing stupid bugs, arguing about databases and meeting +invitations, reading incredibly interesting RFCs and debugging with the +fabulous clients from Apple. I mean: that really, really was really, +really cool :).

+

During these years, a lot of things have changed and many users now +rely on Radicale in production. For example, I use it to manage medical +calendars, with thousands requests per day. Many people are happy to +install Radicale on their small home servers, but are also frustrated by +performance and unsupported specifications when they're trying to use it +seriously.

+

So, now is THE FUTURE! I think that Radicale 2.0 should:

+
    +
  • rely on a few external libraries for simple critical points (dealing +with HTTP and iCal for example),
    • +
  • be thread-safe,
    • +
  • be small,
    • +
  • be documented in a different way (for example by splitting the +client part from the server part, and by adding use cases),
    • +
  • let most of the "auth" modules outside in external modules,
    • +
  • have more and more tests,
    • +
  • have reliable and faster filesystem and database storage +mechanisms,
    • +
  • get a new design :).
    • +
+

I'd also secretly love to drop the Python 2.x support.

+

These ideas are not all mine (except from the really, really, really +important "design" point :p), they have been proposed by many developers +and users. I've just tried to gather them and keep points that seem +important to me.

+

Other points have been discussed with many users and contibutors, +including:

+
    +
  • support of other clients, including Windows and BlackBerry +phones,
    • +
  • server-side meeting invitations,
    • +
  • different storage system as default (or even unique?).
    • +
+

I'm not a huge fan of these features, either because I can't do +anything about them, or because I think that they're Really Bad Ideas®™. +But I'm ready to talk about them, because, well, I may not be always +right!

+

Need to talk about this? You know how to contact us!

+
+
+
+

January 12, 2015 - Radicale 0.10

+

Radicale 0.10 is out!

+
+

0.10 - Lovely Endless Grass

+
    +
  • Support well-known URLs (by Mathieu Dupuy)
    • +
  • Fix collection discovery (by Markus Unterwaditzer)
    • +
  • Reload logger config on SIGHUP (by Élie Bouttier)
    • +
  • Remove props files when deleting a collection (by Vincent Untz)
    • +
  • Support salted SHA1 passwords (by Marc Kleine-Budde)
    • +
  • Don't spam the logs about non-SSL IMAP connections to localhost (by +Giel van Schijndel)
    • +
+

This version should bring some interesting discovery and +auto-configuration features, mostly with Apple clients.

+

Lots of love and kudos for the people who have spent hours to test +features and report issues, that was long but really useful (and some of +you have been really patient :p).

+

Issues are welcome, I'm sure that you'll find horrible, terrible, +crazy bugs faster than me. I'll release a version 0.10.1 if needed.

+

What's next? It's time to fix and improve the storage methods. A real +API for the storage modules is a good beginning, many pull requests are +already ready to be discussed and merged, and we will probably get some +good news about performance this time. Who said "databases, please"?

+
+
+
+

July 12, 2013 - Radicale 0.8

+

Radicale 0.8 is out!

+
+

0.8 - Rainbow

+
    +
  • New authentication and rights management modules (by Matthias +Jordan)
    • +
  • Experimental database storage
    • +
  • Command-line option for custom configuration file (by Mark +Adams)
    • +
  • Root URL not at the root of a domain (by Clint Adams, Fabrice +Bellet, Vincent Untz)
    • +
  • Improved support for iCal, CalDAVSync, CardDAVSync, CalDavZAP and +CardDavMATE
    • +
  • Empty PROPFIND requests handled (by Christoph Polcin)
    • +
  • Colon allowed in passwords
    • +
  • Configurable realm message
    • +
+

This version brings some of the biggest changes since Radicale's +creation, including an experimental support of database storage, clean +authentication modules, and rights management finally designed for real +users.

+

So, dear user, be careful: this version changes important +things in the configuration file, so check twice that everything is OK +when you update to 0.8, or you can have big problems.

+

More and more clients are supported, as a lot of bug fixes and +features have been added for this purpose. And before you ask: yes, 2 +web-based clients, CalDavZAP and +CardDavMATE, are now supported!

+

Even if there has been a lot of time to test these new features, I am +pretty sure that some really annoying bugs have been left in this +version. We will probably release minor versions with bugfixes during +the next weeks, and it will not take one more year to reach 0.8.1.

+

The documentation has been updated, but some parts are missing and +some may be out of date. You can report bugs or even +write +documentation directly on GitHub if you find something strange (and +you probably will).

+

If anything is not clear, or if the way rights work is a bit +complicated to understand, or if you are so happy because everything +works so well, you can share your +thoughts!

+

It has been a real pleasure to work on this version, with brilliant +ideas and interesting bug reports from the community. I'd really like to +thank all the people reporting bugs, chatting on IRC, sending mails and +proposing pull requests: you are awesome.

+
+
+
+

August 3, 2012 - Radicale 0.7.1

+

Radicale 0.7.1 is out!

+
+

0.7.1 - Waterfalls

+
    +
  • Many address books fixes
    • +
  • New IMAP ACL (by Daniel Aleksandersen)
    • +
  • PAM ACL fixed (by Daniel Aleksandersen)
    • +
  • Courier ACL fixed (by Benjamin Frank)
    • +
  • Always set display name to collections (by Oskari Timperi)
    • +
  • Various DELETE responses fixed
    • +
+

It's been a long time since the last version… As usual, many people +have contributed to this new version, that's a pleasure to get these +pull requests.

+

Most of the commits are bugfixes, especially about ACL backends and +address books. Many clients (including aCal and SyncEvolution) will be +much happier with this new version than with the previous one.

+

By the way, one main new feature has been added: a new IMAP ACL +backend, by Daniel. And about authentication, exciting features are +coming soon, stay tuned!

+

Next time, as many mails have come from angry and desperate coders, +tests will be finally added to help them to add features and +fix bugs. And after that, who knows, it may be time to release Radicale +1.0…

+
+
+
+

March 22, 2012 - Radicale 0.7

+

Radicale 0.7 is out, at least!

+
+

0.7 - Eternal Sunshine

+
    +
  • Repeating events
    • +
  • Collection deletion
    • +
  • Courier and PAM authentication methods
    • +
  • CardDAV support
    • +
  • Custom LDAP filters supported
    • +
+

A lot of people have reported bugs, proposed new +features, added useful code and tested many clients. Thank you Lynn, +Ron, Bill, Patrick, Hidde, Gerhard, Martin, Brendan, Vladimir, and +everybody I've forgotten.

+
+
+
+

January 5, 2012 - Radicale 0.6.4, News from Calypso

+

New year, new release. Radicale 0.6.4 has a really short +changelog:

+
+

0.6.4 - Tulips

+
    +
  • Fix the installation with Python 3.1
    • +
+

The bug was in fact caused by a bug in Python 3.1, +everything should be OK now.

+
+
+

Calypso

+

After a lot of changes in Radicale, Keith Packard has decided to +launch a fork called Calypso, with nice features +such as a Git storage mechanism and a CardDAV support.

+

There are lots of differences between the two projects, but the final +goal for Radicale is to provide these new features as soon as possible. +Thanks to the work of Keith and other people on GitHub, a basic CardDAV +support has been added in the carddav branch +and already works with Evolution. Korganizer also works with existing +address books, and CardDAV-Sync will be tested soon. If you want to test +other clients, please let us know!

+
+
+
+

November 3, 2011 - Radicale 0.6.3

+

Radicale version 0.6.3 has been released, with bugfixes that could be +interesting for you!

+
+

0.6.3 - Red Roses

+
    +
  • MOVE requests fixed
    • +
  • Faster REPORT answers
    • +
  • Executable script moved into the package
    • +
+
+
+

What's New Since 0.6.2?

+

The MOVE requests were suffering a little bug that is fixed now. +These requests are only sent by Apple clients, Mac users will be +happy.

+

The REPORT request were really, really slow (several minutes for +large calendars). This was caused by an awful algorithm parsing the +entire calendar for each event in the calendar. The calendar is now only +parsed three times, and the events are found in a Python list, turning +minutes into seconds! Much better, but far from perfection…

+

Finally, the executable script parsing the command line options and +starting the HTTP servers has been moved from the +radicale.py file into the radicale package. +Two executable are now present in the archive: the good old +radicale.py, and bin/radicale. The second one +is only used by setup.py, where the hack used to rename +radicale.py into radicale has therefore been +removed. As a consequence, you can now launch Radicale with the simple +python -m radicale command, without relying on an +executable.

+
+
+

Time for a Stable Release!

+

The next release may be a stable release, symbolically called 1.0. +Guess what's missing? Tests, of course!

+

A non-regression testing suite, based on the clients' requests, will +soon be added to Radicale. We're now thinking about a smart solution to +store the tests, to represent the expected answers and to launch the +requests. We've got crazy ideas, so be prepared: you'll definitely +want to write tests during the next weeks!

+

Repeating events, PAM and Courier authentication methods have already +been added in master. You'll find them in the 1.0 release!

+
+
+

What's Next?

+

Being stable is one thing, being cool is another one. If you want +some cool new features, you may be interested in:

+
    +
  • WebDAV and CardDAV support
    • +
  • Filters and rights management
    • +
  • Multiple storage backends, such as databases and git
    • +
  • Freebusy periods
    • +
  • Email alarms
    • +
+

Issues have been reported in the bug tracker, you can follow there +the latest news about these features. Your beloved text editor is +waiting for you!

+
+
+
+

September 27, 2011 - Radicale 0.6.2

+

0.6.2 is out with minor bugfixes.

+
+

0.6.2 - Seeds

+
    +
  • iPhone and iPad support fixed
    • +
  • Backslashes replaced by slashes in PROPFIND answers on Windows
    • +
  • PyPI archive set as default download URL
    • +
+
+
+
+

August 28, 2011 - Radicale 0.6.1, Changes, Future

+

As previously imagined, a new 0.6.1 version has been released, mainly +fixing obvious bugs.

+
+

0.6.1 - Growing Up

+
    +
  • Example files included in the tarball
    • +
  • htpasswd support fixed
    • +
  • Redirection loop bug fixed
    • +
  • Testing message on GET requests
    • +
+

The changelog is really small, so there should be no real new +problems since 0.6. The example files for logging, FastCGI and WSGI are +now included in the tarball, for the pleasure of our dear packagers!

+

A new branch has been created for various future bug fixes. You can +expect to get more 0.6.x versions, making this branch a kind of "stable" +branch with no big changes.

+
+
+

GitHub, Mailing List, New Website

+

A lot of small changes occurred during the last weeks.

+

If you're interested in code and new features, please note that we +moved the project from Gitorious to GitHub. Being hosted by +Gitorious was a nice experience, but the service was not that good and +we were missing some useful features such as git hooks. Moreover, GitHub +is really popular, we're sure that we'll meet a lot of kind users and +coders there.

+

We've also created a mailing-list on Librelist to keep a +public trace of the mails we're receiving. It a bit empty now, but we're +sure that you'll soon write us some kind words. For example, you can +tell us what you think of our new website!

+
+
+

Future Features

+

In the next weeks, new exciting features are coming in the master +branch! Some of them are almost ready:

+
    +
  • Henry-Nicolas has added the support for the PAM and +Courier-Authdaemon authentication mechanisms.
    • +
  • An anonymous called Keith Packard has prepared some small changes, +such as one file per event, cache and git versioning. Yes. Really.
    • +
+

As you can find in the Radicale Roadmap, tests, +rights and filters are expected for 0.7.

+
+
+
+

August 1, 2011 - Radicale 0.6 Released

+

Time for a new release with a lot of new exciting +features!

+
+

0.6 - Sapling

+
    +
  • WSGI support
    • +
  • IPv6 support
    • +
  • Smart, verbose and configurable logs
    • +
  • Apple iCal 4 and iPhone support (by Łukasz Langa)
    • +
  • CalDAV-Sync support (by Marten Gajda)
    • +
  • aCal support
    • +
  • KDE KOrganizer support
    • +
  • LDAP auth backend (by Corentin Le Bail)
    • +
  • Public and private calendars (by René Neumann)
    • +
  • PID file
    • +
  • MOVE requests management
    • +
  • Journal entries support
    • +
  • Drop Python 2.5 support
    • +
+

Well, it's been a little longer than expected, but for good reasons: +a lot of features have been added, and a lot of clients are known to +work with Radicale, thanks to kind contributors. That's definitely good +news! But…

+

Testing all the clients is really painful, moreover for the ones from +Apple (I have no Mac nor iPhone of my own). We should seriously think of +automated tests, even if it's really hard to maintain, and maybe not +that useful. If you're interested in tests, you can look at the +wonderful regression suite of DAViCal.

+

The new features, for example the WSGI support, are also poorly +documented. If you have some Apache or lighttpd configuration working +with Radicale, you can make the world a little bit better by writing a +paragraph or two in the Radicale +documentation. It's simple plain text, don't be afraid!

+

Because of all these changes, Radicale 0.6 may be a little bit buggy; +a 0.6.1 will probably be released soon, fixing small problems with +clients and features. Get ready to report bugs, I'm sure that you can +find one (and fix it)!

+
+
+
+

July 2, 2011 - Feature Freeze for 0.6

+

According to the roadmap, a +lot of features have been added since Radicale 0.5, much more than +expected. It's now time to test Radicale with your favourite client and +to report bugs before we release the next stable version!

+

Last week, the iCal and iPhone support written by Łukasz has been +fixed in order to restore the broken Lightning support. After two +afternoons of tests with Rémi, we managed to access the same calendar +with Lightning, iCal, iPhone and Evolution, and finally discovered that +CalDAV could also be a perfect instant messaging protocol between a Mac, +a PC and a phone.

+

After that, we've had the nice surprise to see events displayed +without a problem (but after some strange steps of configuration) by +aCal on Salem's Android phone.

+

It was Friday, fun fun fun fun.

+

So, that's it: Radicale supports Lightning, Evolution, Kontact, aCal +for Android, iPhone and iCal. Of course, before releasing a new +tarball:

+
    +
  • documentation is needed for the +new clients that are not documented yet (Kontact, aCal and iPhone);
    • +
  • tests are welcome, particularly for the Apple clients that I can't +test anymore;
    • +
  • no more features will be added, they'll wait in separate branches +for the 0.7 development.
    • +
+

Please report bugs +if anything goes wrong during your tests, or just let us know by Jabber or by mail if everything is OK.

+
+
+

May 1, 2011 - Ready for WSGI

+

Here it is! Radicale is now ready to be launched behind your +favourite HTTP server (Apache, Lighttpd, Nginx or Tomcat for example). +That's really good news, because:

+
    +
  • Real HTTP servers are much more efficient and reliable than the +default Python server used in Radicale;
    • +
  • All the authentication backends available for your server will be +available for Radicale;
    • +
  • Thanks to flup, Radicale +can be interfaced with all the servers supporting CGI, AJP, FastCGI or +SCGI;
    • +
  • Radicale works very well without any additional server, without any +dependencies, without configuration, just as it was working before;
    • +
  • This one more feature removes useless code, less is definitely +more.
    • +
+

The WSGI support has only be tested as a stand-alone executable and +behind Lighttpd, you should definitely try if it works with you +favourite server too!

+

No more features will be added before (quite) a long time, because a +lot of documentation and test is waiting for us. If you want to write +tutorials for some CalDAV clients support (iCal, Android, iPhone), HTTP +servers support or logging management, feel free to fork the documentation git +repository and ask for a merge. It's plain text, I'm sure you can do +it!

+
+
+

April 30, 2011 - Apple iCal Support

+

After a long, long work, the iCal support has finally been added to +Radicale! Well, this support is only for iCal 4 and is highly +experimental, but you can test it right now with the git master branch. +Bug reports are welcome!

+

Dear MacOS users, you can thank all the gentlemen who sended a lot of +debugging iformation. Special thanks to Andrew from DAViCal, who helped +us a lot with his tips and his tests, and Rémi Hainaud who lent his +laptop for the final tests.

+

The default server address is localhost:5232/user/, +where calendars can be added. Multiple calendars and owner-less +calendars are not tested yet, but they should work quite well. More +documentation will be added during the next days. It will then be time +to release the Radicale 0.6 version, and work on the WSGI support.

+
+
+

April 25, 2011 - Two Features and One New Roadmap

+

Two features have just reached the master branch, and the roadmap has +been refreshed.

+
+

LDAP Authentication

+

Thanks to Corentin, the LDAP authentication is now included in +Radicale. The support is experimental and may suffer unstable connexions +and security problems. If you are interested in this feature (a lot of +people seem to be), you can try it and give some feedback.

+

No SSL support is included yet, but this may be quite easy to add. By +the way, serious authentication methods will rely on a "real" HTTP +server, as soon as Radicale supports WSGI.

+
+
+

Journal Entries

+

Mehmet asked for the journal entries (aka. notes or memos) support, +that's done! This also was an occasion to clean some code in the iCal +parser, and to add a much better management of multi-lines entries. +People experiencing crazy X-RADICALE-NAME entries can now +clean their files, Radicale won't pollute them again.

+
+
+

New Roadmap

+

Except from htpasswd and LDAP, most of the authentication backends +(database, SASL, PAM, user groups) are not really easy to include in +Radicale. The easiest solution to solve this problem is to give Radicale +a CGI support, to put it behind a solid server such as Apache. Of +course, CGI is not enough: a WSGI support is quite better, with the +FastCGI, AJP and SCGI backends offered by flup. Quite exciting, isn't +it?

+

That's why it was important to add new versions on the roadmap. The +0.6 version is now waiting for the Apple iCal support, and of course for +some tests to kill the last remaining bugs. The only 0.7 feature will be +WSGI, allowing many new authentication methods and a real multithread +support.

+

After that, 0.8 may add CalDAV rights and filters, while 1.0 will +draw thousands of rainbows and pink unicorns (WebDAV sync, CardDAV, +Freebusy). A lot of funky work is waiting for you, hackers!

+
+
+

Bugs

+

Many bugs have also been fixed, most of them due to the owner-less +calendars support. Radicale 0.6 may be out in a few weeks, you should +spend some time testing the master branch and filling the bug +tracker.

+
+
+
+

April 10, 2011 - New Features

+

Radicale 0.5 was released only 8 days ago, but 3 new features have +already been added to the master branch:

+
    +
  • IPv6 support, with multiple addresses/ports support
    • +
  • Logs and debug mode
    • +
  • Owner-less calendars
    • +
+

Most of the code has been written by Necoro and Corentin, and that +was not easy at all: Radicale is now multithreaded! For sure, you can +find many bugs and report them on the bug tracker. +And if you're fond of logging, you can even add a default configuration +file and more debug messages in the source.

+
+
+

April 2, 2011 - Radicale 0.5 Released

+

Radicale 0.5 is out! Here is what's new:

+
+

0.5 - Historical Artifacts

+
    +
  • Calendar depth
    • +
  • iPhone support
    • +
  • MacOS and Windows support
    • +
  • HEAD requests management
    • +
  • htpasswd user from calendar path
    • +
+

iPhone support, but no iCal support for 0.5, despite our hard work, +sorry! After 1 month with no more activity on the dedicated bug, it was +time to forget it and hack on new awesome features. Thanks for your +help, dear Apple users, I keep the hope that one day, Radicale will work +with you!

+

So, what's next? As promised, some cool git branches will soon be +merged, with LDAP support, logging, IPv6 and anonymous calendars. Sounds +pretty cool, heh? Talking about new features, more and more people are +asking for a CardDAV support in Radicale. A +git branch and a +feature request are open, feel free to hack and discuss.

+
+
+
+

February 3, 2011 - Jabber Room and iPhone Support

+

After a lot of help and testing work from Andrew, Björn, Anders, +Dorian and Pete (and other ones we could have forgotten), a simple +iPhone support has been added in the git repository. If you are +interested, you can test this feature right now by downloading the latest git version (a tarball +is even available too if you don't want or know how to use git).

+

No documentation has been written yet, but using the right URL in the +configuration should be enough to synchronize your calendars. If you +have any problems, you can ask by joining our new Jabber room: radicale@room.jabber.kozea.fr.

+

Radicale 0.5 will be released as soon as the iCal support is ready. +If you have an Apple computer, Python skills and some time to spend, +we'd be glad to help you debugging Radicale.

+
+
+

October 21, 2010 - News from Radicale

+

During the last weeks, Radicale has not been idle, even if no news +have been posted since August. Thanks to Pete, Pierre-Philipp and +Andrew, we're trying to add a better support on MacOS, Windows and +mobile devices like iPhone and Android-based phones.

+

All the tests on Windows have been successful: launching Radicale and +using Lightning as client works without any problems. On Android too, +some testers have reported clients working with Radicale. These were the +good news.

+

The bad news come from Apple: both iPhone and MacOS default clients +are not working yet, despite the latest enhancements given to the +PROPFIND requests. The problems are quite hard to debug due to our lack +of Apple hardware, but Pete is helping us in this difficult quest! +Radicale 0.5 will be out as soon as these two clients are working.

+

Some cool stuff is coming next, with calendar collections and groups, +and a simple web-based CalDAV client in early development. Stay +tuned!

+
+
+

August 8, 2010 - Radicale 0.4 Released

+

Radicale 0.4 is out! Here is what's new:

+
+

0.4 - Hot Days Back

+
    +
  • Personal calendars
    • +
  • HEAD requests
    • +
  • Last-Modified HTTP header
    • +
  • no-ssl and foreground options
    • +
  • Default configuration file
    • +
+

This release has mainly been released to help our dear packagers to +include a default configuration file and to write init scripts. Big +thanks to Necoro for his work on the new Gentoo ebuild!

+
+
+
+

July 4, 2010 - Three Features Added Last Week

+

Some features have been added in the git repository during the last +weeks, thanks to Jerome and Mariusz!

+
    +

  • Personal Calendars
    +Calendars accessed through the htpasswd ACL module can now be personal. +Thanks to the personal option, a user called +bob can access calendars at /bob/* but not to +the /alice/* ones.

    • +

  • HEAD Requests
    +Radicale can now answer HEAD requests. HTTP headers can be retrieved +thanks to this request, without getting contents given by the GET +requests.

    • +

  • Last-Modified HTTP header
    +The Last-Modified header gives the last time when the calendar has been +modified. This is used by some clients to cache the calendars and not +retrieving them if they have not been modified.

    • +
+
+
+

June 14, 2010 - Radicale 0.3 Released

+

Radicale 0.3 is out! Here is what’s new:

+
+

0.3 - Dancing Flowers

+
    +
  • Evolution support
    • +
  • Version management
    • +
+

The website changed a little bit too, with some small HTML5 and CSS3 +features such as articles, sections, transitions, opacity, box shadows +and rounded corners. If you’re reading this website with Internet +Explorer, you should consider using a standard-compliant browser!

+

Radicale is now included in Squeeze, the testing branch of Debian. A +Radicale ebuild +for Gentoo has been proposed too. If you want to package Radicale +for another distribution, you’re welcome!

+

Next step is 0.5, with calendar collections, and Windows and MacOS +support.

+
+
+
+

May 31, 2010 - May News

+
+

News from contributors

+

Jonas Smedegaard packaged Radicale for Debian last week. Two +packages, called radicale for the daemon and +python-radicale for the module, have been added to Sid, the +unstable branch of Debian. Thank you, Jonas!

+

Sven Guckes corrected some of the strange-English-sentences present +on this website. Thank you, Sven!

+
+
+

News from software

+

A simple VERSION has been added in the library: you can +now play with radicale.VERSION and +$radicale --version.

+

After playing with the version (should not be too long), you may +notice that the next version is called 0.3, and not 0.5 as previously +decided. The 0.3 main goal is to offer the support for Evolution as soon +as possible, without waiting for the 0.5. After more than a month of +test, we corrected all the bugs we found and everything seems to be +fine; we can imagine that a brand new tarball will be released during +the first days of June.

+
+
+
+

April 19, 2010 - Evolution Supported

+

Radicale now supports another CalDAV client: Evolution, the default mail, +addressbook and calendaring client for Gnome. This feature was quite +easy to add, as it required less than 20 new lines of code in the +requests handler.

+

If you are interested, just clone the git +repository.

+
+
+

April 13, 2010 - Radicale 0.2 Released

+

Radicale 0.2 is out! Here is what’s new:

+
+

0.2 - Snowflakes

+
    +
  • Sunbird pre-1.0 support
    • +
  • SSL connection
    • +
  • Htpasswd authentication
    • +
  • Daemon mode
    • +
  • User configuration
    • +
  • Twisted dependency removed
    • +
  • Python 3 support
    • +
  • Real URLs for PUT and DELETE
    • +
  • Concurrent modification reported to users
    • +
  • Many bugs fixed by Roger Wenham
    • +
+

First of all, we would like to thank Roger Wenham for his bugfixes +and his supercool words.

+

You may have noticed that Sunbird 1.0 has not been released, but +according to the Mozilla developers, 1.0pre is something like a final +version.

+

You may have noticed too that Radicale can be downloaded from +PyPI. Of course, it is also available on the download page.

+
+
+
+

January 21, 2010 - HTTPS and Authentication

+

HTTPS connections and authentication have been added to Radicale this +week. Command-line options and personal configuration files are also +ready for test. According to the TODO file included in the package, the +next version will finally be 0.2, when sunbird 1.0 is out. Go, Mozilla +hackers, go!

+
    +

  • HTTPS connection
    +HTTPS connections are now available using the standard TLS mechanisms. +Give Radicale a private key and a certificate, and your data are now +safe.

    • +

  • Authentication
    +A simple authentication architecture is now available, allowing +different methods thanks to different modules. The first two modules are +fake (no authentication) and htpasswd +(authentication with an htpasswd file created by the Apache +tool). More methods such as LDAP are coming soon!

    • +
+
+
+

January 15, 2010 - Ready for Python 3

+

Dropping Twisted dependency was the first step leading to another big +feature: Radicale now works with Python 3! The code was given a small +cleanup, with some simplifications mainly about encoding. Before the +0.1.1 release, feel free to test the git repository, all Python versions +from 2.5 should be OK.

+
+
+

January 11, 2010 - Twisted no Longer Required

+

Good news! Radicale 0.1.1 will support Sunbird 1.0, but it has +another great feature: it has no external dependency! Twisted is no +longer required for the git version, removing about 50 lines of +code.

+
+
+

December 31, 2009 - Lightning and Sunbird 1.0b2pre Support

+

Lightning/Sunbird 1.0b2pre is out, adding minor changes in CalDAV +support. A new +commit makes Radicale work with versions 0.9, 1.0b1 et 1.0b2. +Moreover, etags are now quoted according to the RFC +2616.

+
+
+

December 9, 2009 - Thunderbird 3 released

+

Thunderbird +3 is out, and Lightning/Sunbird 1.0 should be released in a few +days. The last commit +in git should make Radicale work with versions 0.9 and 1.0b1pre. +Radicale 0.1.1 will soon be released adding support for version 1.0.

+
+
+

September 1, 2009 - Radicale 0.1 Released

+

First Radicale release! Here is the changelog:

+
+

0.1 - Crazy Vegetables

+
    +
  • First release
    • +
  • Lightning/Sunbird 0.9 compatibility
    • +
  • Easy installer
    • +
+

You can download this version on the download +page.

+
+
+
+

July 28, 2009 - Radicale on Gitorious

+

Radicale code has been released on Gitorious! Take a look at the Radicale main page on +Gitorious to view and download source code.

+
+
+

July 27, 2009 - Radicale Ready to Launch

+

The Radicale Project is launched. The code has been cleaned up and +will be available soon…

+
+
+ +
+
+ diff --git a/html/v2/about.html b/html/v2/about.html new file mode 100644 index 000000000..b3084aae5 --- /dev/null +++ b/html/v2/about.html @@ -0,0 +1,604 @@ + + + + + + + + + + + + + + +Radicale v2 Documentation + + + + + +
+
+

+Radicale + +v2 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + +
+

About

+
+

Main Goals

+

Radicale is a complete calendar and contact storing and manipulating +solution. It can store multiple calendars and multiple address +books.

+

Calendar and contact manipulation is available from both local and +distant accesses, possibly limited through authentication policies.

+

It aims to be a lightweight solution, easy to use, easy to install, +easy to configure. As a consequence, it requires few software +dependencies and is pre-configured to work out-of-the-box.

+

Radicale is written in Python. It runs on most of the UNIX-like +platforms (Linux, *BSD, macOS) and Windows. It is free and open-source +software.

+
+
+

What Radicale Will Never Be

+

Radicale is a server, not a client. No interfaces will be created to +work with the server, as it is a really (really really) much more +difficult task.

+

CalDAV and CardDAV are not perfect protocols. We think that their +main problem is their complexity, that is why we decided not to +implement the whole standard but just enough to understand some of its +client-side implementations.

+

CalDAV and CardDAV are the best open standards available and they are +quite widely used by both clients and servers. We decided to use it, and +we will not use another one.

+
+
+

Technical Choices

+

Important global development choices have been decided before writing +code. They are very useful to understand why the Radicale Project is +different from other CalDAV and CardDAV servers, and why features are +included or not in the code.

+
+
Oriented to Calendar and Contact User Agents
+

Calendar and contact servers work with calendar and contact clients, +using a defined protocol. CalDAV and CardDAV are good protocols, +covering lots of features and use cases, but it is quite hard to +implement fully.

+

Some calendar servers have been created to follow the CalDAV and +CardDAV RFCs as much as possible: Davical, Baïkal and Darwin Calendar Server, for +example, are much more respectful of CalDAV and CardDAV and can be used +with a large number of clients. They are very good choices if you want +to develop and test new CalDAV clients, or if you have a possibly +heterogeneous list of user agents.

+

Even if it tries it best to follow the RFCs, Radicale does not and +will not blindly implements the CalDAV and CardDAV +standards. It is mainly designed to support the CalDAV and CardDAV +implementations of different clients.

+
+
+
Simple
+

Radicale is designed to be simple to install, simple to configure, +simple to use.

+

The installation is very easy, particularly with Linux: one +dependency, no superuser rights needed, no configuration required, no +database. Installing and launching the main script out-of-the-box, as a +normal user, are often the only steps to have a simple remote calendar +and contact access.

+

Contrary to other servers that are often complicated, require high +privileges or need a strong configuration, the Radicale Server can +(sometimes, if not often) be launched in a couple of minutes, if you +follow the tutorial.

+
+
+
Lazy
+

The CalDAV RFC defines what must be done, what can be done and what +cannot be done. Many violations of the protocol are totally defined and +behaviours are given in such cases.

+

Radicale often assumes that the clients are perfect and that protocol +violations do not exist. That is why most of the errors in client +requests have undetermined consequences for the lazy server that can +reply good answers, bad answers, or even no answer.

+
+
+
+

History

+

Radicale has been started as a (free topic) stupid school project +replacing another (assigned topic) even more stupid school project.

+

At the beginning, it was just a proof-of-concept. The main goal was +to write a small, dirty and simple CalDAV server working with Lightning, +using no external libraries. That's how we created a piece of code +that's (quite) easy to understand, to use and to hack.

+

The first +lines have been added to the SVN (!) repository as I was drinking +(many) beers at the very end of 2008 (Python 2.6 and 3.0 were just +released). It's now packaged for a growing number of Linux +distributions.

+

And that was fun going from here to there thanks to you!

+
+
+ +
+
+ diff --git a/html/v2/contribute.html b/html/v2/contribute.html new file mode 100644 index 000000000..3bcec0a67 --- /dev/null +++ b/html/v2/contribute.html @@ -0,0 +1,533 @@ + + + + + + + + + + + + + + +Radicale v2 Documentation + + + + + +
+
+

+Radicale + +v2 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + +
+

Contribute

+
+

Chat with Us on IRC

+

Want to say something? Join our IRC room: ##kozea on +Freenode.

+
+
+

Report Bugs

+

Found a bug? Want a new feature? Report a new issue on the Radicale +bug-tracker.

+
+
+

Hack

+

Interested in hacking? Feel free to clone the git repository on Github if +you want to add new features, fix bugs or update the documentation.

+
+
+

Documentation

+

To change or complement the documentation create a pull request to DOCUMENTATION.md.

+
+
+ + + +
+
+ diff --git a/html/v2/documentation.html b/html/v2/documentation.html new file mode 100644 index 000000000..c845fde71 --- /dev/null +++ b/html/v2/documentation.html @@ -0,0 +1,1864 @@ + + + + + + + + + + + + + + +Radicale v2 Documentation + + + + + +
+
+

+Radicale + +v2 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ +
+

Documentation

+

This documentation page is written for version 2.x.x. If you want to +update Radicale from 1.x.x to 2.x.x, please follow our migration guide. You can find on +GitHub the documentation page for the 1.1.x +versions.

+
+

Install and Set Up

+

You're new to Radicale and you want to know how to use it? Welcome +aboard!

+ +
+
+

Use

+ +
+
+

Configure

+

Now that you have Radicale running, let's see what we can configure +to make it fit your needs.

+ +
+
+

Hack

+

Using is fun, but hacking is soooooooo coooooool. Radicale is a +really small and simple piece of code, it may be the perfect project to +start hacking!

+ +
+
+

Tutorial

+

You want to try Radicale but only have 5 minutes free in your +calendar? Let's go right now! You won't have the best installation ever, +but it will be enough to play a little 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 user name and +password. If Radicale fits your needs, it may be time for some basic configuration.

+

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

+
+

Linux / *BSD

+

First of all, make sure that python 3.3 or later +(python ≥ 3.6 is recommended) and pip +are installed. On most distributions it should be enough to install the +package python3-pip.

+

Then open a console and type:

+
# Run the following command as root or
+# add the --user argument to only install for the current user
+$ python3 -m pip install --upgrade radicale==2.1.*
+$ python3 -m radicale --config "" --storage-filesystem-folder=~/.var/lib/radicale/collections
+

Victory! Open http://localhost:5232/ in your +browser! You can login with any username and password.

+
+
+

Windows

+

The first step is to install Python. Go to python.org and download the latest version +of Python 3. Then run the installer. On the first window of the +installer, check the "Add Python to PATH" box and click on "Install +now". Wait a couple of minutes, it's done!

+

Launch a command prompt and type:

+
C:\Users\User> python -m pip install --upgrade radicale==2.1.*
+C:\Users\User> python -m radicale --config "" --storage-filesystem-folder=~/radicale/collections
+

If you are using PowerShell replace --config "" with +--config '""'.

+

Victory! Open http://localhost:5232/ in your +browser! You can login with any username and password.

+
+
+

MacOS

+

To be written.

+
+
+
+

Basic Setup

+

Installation instructions can be found on the Tutorial page.

+
+

Configuration

+

Radicale tries to load configuration files from +/etc/radicale/config, +~/.config/radicale/config and the +RADICALE_CONFIG environment variable. A custom path can be +specified with the --config /path/to/config command line +argument.

+

You should create a new configuration file at the desired location. +(If the use of a configuration file is inconvenient, all options can be +passed via command line arguments.)

+

All configuration options are described in detail on the Configuration page.

+
+
+

Authentication

+

In its default configuration Radicale doesn't check user names or +passwords. If the server is reachable over a network, you should change +this.

+

First a users file with all user names and passwords +must be created. It can be stored in the same directory as the +configuration file.

+
+
The secure way
+

The users file can be created and managed with htpasswd:

+
# Create a new htpasswd file with the user "user1"
+$ htpasswd -B -c /path/to/users user1
+New password:
+Re-type new password:
+# Add another user
+$ htpasswd -B /path/to/users user2
+New password:
+Re-type new password:
+

bcrypt is used to secure the passwords. Radicale +requires additional dependencies for this encryption method:

+
$ python3 -m pip install --upgrade radicale[bcrypt]==2.1.*
+

Authentication can be enabled with the following configuration:

+
[auth]
+type = htpasswd
+htpasswd_filename = /path/to/users
+# encryption method used in the htpasswd file
+htpasswd_encryption = bcrypt
+
+
+
The simple but insecure way
+

Create the users file by hand with lines containing the +user name and password separated by :. Example:

+
user1:password1
+user2:password2
+

Authentication can be enabled with the following configuration:

+
[auth]
+type = htpasswd
+htpasswd_filename = /path/to/users
+# encryption method used in the htpasswd file
+htpasswd_encryption = plain
+
+
+
+

Addresses

+

The default configuration binds the server to localhost. It can't be +reached from other computers. This can be changed with the following +configuration options:

+
[server]
+hosts = 0.0.0.0:5232
+

More addresses can be added (separated by commas).

+
+
+

Storage

+

Data is stored in the folder +/var/lib/radicale/collections. The path can be changed with +the following configuration:

+
[storage]
+filesystem_folder = /path/to/storage
+

Security: The storage folder should not be readable +by unauthorized users. Otherwise, they can read the calendar data and +lock the storage. You can find OS dependent instructions in the +Running as a service section.

+
+
+

Limits

+

Radicale enforces limits on the maximum number of parallel +connections, the maximum file size (important for contacts with big +photos) and the rate of incorrect authentication attempts. Connections +are terminated after a timeout. The default values should be fine for +most scenarios.

+
[server]
+max_connections = 20
+# 100 Megabyte
+max_content_length = 100000000
+# 30 seconds
+timeout = 30
+
+[auth]
+# Average delay after failed login attempts in seconds
+delay = 1
+
+
+

Running as a service

+

The method to run Radicale as a service depends on your host +operating system. Follow one of the chapters below depending on your +operating system and requirements.

+
+
Linux with systemd as a user
+

Create the file +~/.config/systemd/user/radicale.service:

+
[Unit]
+Description=A simple CalDAV (calendar) and CardDAV (contact) server
+
+[Service]
+ExecStart=/usr/bin/env python3 -m radicale
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+

Radicale will load the configuration file from +~/.config/radicale/config. You should set the configuration +option filesystem_folder in the storage +section to something like +~/.var/lib/radicale/collections.

+

To enable and manage the service run:

+
# Enable the service
+$ systemctl --user enable radicale
+# Start the service
+$ systemctl --user start radicale
+# Check the status of the service
+$ systemctl --user status radicale
+# View all log messages
+$ journalctl --user --unit radicale.service
+
+
+
Linux with systemd system-wide
+

Create the radicale user and group for the Radicale +service. (Run +useradd --system --home-dir / --shell /sbin/nologin radicale +as root.) The storage folder must be writable by +radicale. (Run +mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections +as root.)

+

Security: The storage should not be readable by +others. (Run chmod -R o= /var/lib/radicale/collections as +root.)

+

Create the file +/etc/systemd/system/radicale.service:

+
[Unit]
+Description=A simple CalDAV (calendar) and CardDAV (contact) server
+After=network.target
+Requires=network.target
+
+[Service]
+ExecStart=/usr/bin/env python3 -m radicale
+Restart=on-failure
+User=radicale
+# Deny other users access to the calendar data
+UMask=0027
+# Optional security settings
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateDevices=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+NoNewPrivileges=true
+ReadWritePaths=/var/lib/radicale/collections
+
+[Install]
+WantedBy=multi-user.target
+

Radicale will load the configuration file from +/etc/radicale/config.

+

To enable and manage the service run:

+
# Enable the service
+$ systemctl enable radicale
+# Start the service
+$ systemctl start radicale
+# Check the status of the service
+$ systemctl status radicale
+# View all log messages
+$ journalctl --unit radicale.service
+
+
+
+

MacOS with launchd

+

To be written.

+
+
+

Classic daemonization

+

Set the configuration option daemon in the section +server to True. You may want to set the option +pid to the path of a PID file.

+

After daemonization the server will not log anything. You have to +configure Logging.

+

If you start Radicale now, it will initialize and fork into the +background. The main process exits, after the PID file is written.

+

Security: You can set the umask +with umask 0027 before you start the daemon, to protect +your calendar data and log files from other users. Don't forget to set +permissions of files that are already created!

+
+
+

Windows with "NSSM - the Non-Sucking Service Manager"

+

First install NSSM and start +nssm install in a command prompt. Apply the following +configuration:

+
    +
  • Service name: Radicale
    • +
  • Application +
      +
    • Path: C:\Path\To\Python\python.exe
      • +
    • Arguments: -m radicale --config C:\Path\To\Config
      • +
    • +
  • I/O redirection +
      +
    • Error: C:\Path\To\Radicale.log
      • +
    • +
+

Security: Be aware that the service runs in the +local system account, you might want to change this. Managing user +accounts is beyond the scope of this manual. Also make sure that the +storage folder and log file is not readable by unauthorized users.

+

The log file might grow very big over time, you can configure file +rotation in NSSM to prevent this.

+

The service is configured to start automatically when the computer +starts. To start the service manually open Services in +Computer Management and start the +Radicale service.

+
+
+
+

Reverse Proxy

+

When a reverse proxy is used, the path at which Radicale is available +must be provided via the X-Script-Name header. The proxy +must remove the location from the URL path that is forwarded to +Radicale.

+

Example nginx configuration:

+
location /radicale/ { # The trailing / is important!
+    proxy_pass        http://localhost:5232/; # The / is important!
+    proxy_set_header  X-Script-Name /radicale;
+    proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_pass_header Authorization;
+}
+

Example Apache configuration:

+
RewriteEngine On
+RewriteRule ^/radicale$ /radicale/ [R,L]
+
+<Location "/radicale/">
+    ProxyPass        http://localhost:5232/ retry=0
+    ProxyPassReverse http://localhost:5232/
+    RequestHeader    set X-Script-Name /radicale/
+</Location>
+

Be reminded that Radicale's default configuration enforces limits on +the maximum number of parallel connections, the maximum file size and +the rate of incorrect authentication attempts. Connections are +terminated after a timeout.

+
+

Manage user accounts with the reverse proxy

+

Set the configuration option type in the +auth section to http_x_remote_user. Radicale +uses the user name provided in the X-Remote-User HTTP +header and disables HTTP authentication.

+

Example nginx configuration:

+
location /radicale/ {
+    proxy_pass           http://localhost:5232/;
+    proxy_set_header     X-Script-Name /radicale;
+    proxy_set_header     X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header     X-Remote-User $remote_user;
+    auth_basic           "Radicale - Password Required";
+    auth_basic_user_file /etc/nginx/htpasswd;
+}
+

Example Apache configuration:

+
RewriteEngine On
+RewriteRule ^/radicale$ /radicale/ [R,L]
+
+<Location "/radicale/">
+    AuthType      Basic
+    AuthName      "Radicale - Password Required"
+    AuthUserFile  "/etc/radicale/htpasswd"
+    Require       valid-user
+
+    ProxyPass        http://localhost:5232/ retry=0
+    ProxyPassReverse http://localhost:5232/
+    RequestHeader    set X-Script-Name /radicale/
+    RequestHeader    set X-Remote-User expr=%{REMOTE_USER}
+</Location>
+

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

+
+
+

Secure connection between Radicale and the reverse proxy

+

SSL certificates can be used to encrypt and authenticate the +connection between Radicale and the reverse proxy. First you have to +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
+

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
+

Example nginx configuration:

+
location /radicale/ {
+    proxy_pass https://localhost:5232/;
+    ...
+    # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...).
+    proxy_ssl_certificate         /path/to/client_cert.pem;
+    proxy_ssl_certificate_key     /path/to/client_key.pem;
+    proxy_ssl_trusted_certificate /path/to/server_cert.pem;
+}
+
+
+
+

WSGI

+

Radicale is compatible with the WSGI specification.

+

A configuration file can be set with the RADICALE_CONFIG +environment variable, otherwise no configuration file is loaded and the +default configuration is used.

+

Be reminded that Radicale's default configuration enforces limits on +the maximum upload file size.

+

Security: The None authentication type +disables all rights checking. Don't use it with +REMOTE_USER. Use remote_user instead.

+

Example uWSGI configuration:

+
[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' --workers 8 --env 'RADICALE_CONFIG=/etc/radicale/config' radicale
+
+

Manage user accounts with the WSGI server

+

Set the configuration option type in the +auth section to remote_user. Radicale uses the +user name provided by the WSGI server and disables authentication over +HTTP.

+
+
+
+

Versioning

+

This page describes how to keep track of all changes to calendars and +address books with git (or any other version control +system).

+

The repository must be initialized by running git init +in the file system folder. Internal files of Radicale can be excluded by +creating the file .gitignore with the following +content:

+
.Radicale.cache
+.Radicale.lock
+.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)
+

The command gets executed after every change to the storage and +commits the changes into the git repository.

+
+
+

Clients

+

Radicale has been tested with:

+ +

Many clients do not support the creation of new calendars and address +books. You can use Radicale's web interface (e.g. http://localhost:5232) to create and +manage collections.

+

In some clients you can just enter the URL of the Radicale server +(e.g. http://localhost:5232) and your user name. In others, +you have to enter the URL of the collection directly (e.g. +http://localhost:5232/user/calendar).

+
+

DAVx⁵

+

Enter the URL of the Radicale server (e.g. +http://localhost:5232) and your user name. DAVx⁵ will show +all existing calendars and address books and you can create new.

+
+
+

GNOME Calendar, Contacts and Evolution

+

GNOME Calendar and Contacts do not +support adding WebDAV calendars and address books directly, but you can +add them in Evolution.

+

In Evolution add a new calendar and address book +respectively with WebDAV. Enter the URL of the Radicale server (e.g. +http://localhost:5232) and your user name. Clicking on the +search button will list the existing calendars and address books.

+
+
+

Thunderbird

+
+
CardBook
+

Add a new address book on the network with CardDAV. You have to enter +the full URL of the collection (e.g. +http://localhost:5232/user/addressbook) and your user +name.

+
+
+
Lightning
+

Add a new calendar on the network with CalDAV. (Don't +use iCalendar (ICS)!) You have to enter the full URL of the +collection (e.g. http://localhost:5232/user/calendar). If +you want to add calendars from different users on the same server, you +can specify the user name in the URL (e.g. +http://user@localhost...)

+
+
+
+

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.

+
+
+

Manual creation of calendars and address books

+

This is not the recommended way of creating and managing your +calendars and address books. Use Radicale's web interface or a client +with support for it (e.g. DAVx⁵).

+
+
Direct editing of the storage
+

To create a new collection, you have to create the corresponding +folder in the file system storage (e.g. +collection-root/user/calendar). To tell Radicale and +clients that the collection is a calendar, you have to create the file +.Radicale.props with the following content in the +folder:

+
{"tag": "VCALENDAR"}
+

The calendar is now available at the URL path +/user/calendar. For address books the file must +contain:

+
{"tag": "VADDRESSBOOK"}
+

Calendar and address book collections must not have any child +collections. Clients with automatic discovery of collections will only +show calendars and addressbooks that are direct children of the path +/USERNAME/.

+

Delete collections by deleting the corresponding folders.

+
+
+
HTTP requests with curl
+

To create a new calendar run something like:

+
$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \
+'<?xml version="1.0" encoding="UTF-8" ?>
+<create xmlns="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:I="http://apple.com/ns/ical/">
+  <set>
+    <prop>
+      <resourcetype>
+        <collection />
+        <C:calendar />
+      </resourcetype>
+      <C:supported-calendar-component-set>
+        <C:comp name="VEVENT" />
+        <C:comp name="VJOURNAL" />
+        <C:comp name="VTODO" />
+      </C:supported-calendar-component-set>
+      <displayname>Calendar</displayname>
+      <C:calendar-description>Example calendar</C:calendar-description>
+      <I:calendar-color>#ff0000ff</I:calendar-color>
+    </prop>
+  </set>
+</create>'
+

To create a new address book run something like:

+
$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \
+'<?xml version="1.0" encoding="UTF-8" ?>
+<create xmlns="DAV:" xmlns:CR="urn:ietf:params:xml:ns:carddav">
+  <set>
+    <prop>
+      <resourcetype>
+        <collection />
+        <CR:addressbook />
+      </resourcetype>
+      <displayname>Address book</displayname>
+      <CR:addressbook-description>Example address book</CR:addressbook-description>
+    </prop>
+  </set>
+</create>'
+

The collection /USERNAME will be created automatically, +when the user authenticates to Radicale for the first time. Clients with +automatic discovery of collections will only show calendars and address +books that are direct children of the path /USERNAME/.

+

Delete the collections by running something like:

+
$ curl -u user -X DELETE 'http://localhost:5232/user/calendar'
+
+
+
+
+

Configuration

+

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
+
+[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:

+
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:5232

+
+
+
daemon
+

Daemonize the Radicale process. It does not reset the umask.

+

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: 100000000

+
+
+
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 user name +from the certifcate.

+

Default:

+
+
+
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. It also +disables rights checking.

+

htpasswd : Use an Apache +htpasswd file to store usernames and passwords.

+

remote_user : Takes the user name from the +REMOTE_USER environment variable and disables HTTP +authentication. This can be used to provide the user name from a WSGI +server.

+

http_x_remote_user : Takes the user name from the +X-Remote-User HTTP header and disables HTTP authentication. +This can be used to provide the user name from a reverse proxy.

+

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 +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:

+
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). +It's insecure!

+

Default: bcrypt

+
+
+
delay
+

Average delay after failed login attempts in seconds.

+

Default: 1

+
+
+
+

rights

+
+
type
+

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

+

The recommended backend is owner_only. If access to +calendars and address books outside of the home directory of users +(that's /USERNAME/) is granted, clients won't detect these +collections and will not show them to the user. Choosing any other +method is only useful if you access calendars and address books directly +via URL.

+

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 page.

+
+
+
+

storage

+
+
type
+

The backend that is used to store data.

+

Available backends:

+

multifilesystem : Stores the data in the filesystem.

+

Default: multifilesystem

+
+
+
filesystem_folder
+

Folder for storing local collections, created if not present.

+

Default: /var/lib/radicale/collections

+
+
+
filesystem_locking
+

Lock the storage. This must be disabled if locking is not supported +by the underlying file system. Never start multiple instances of +Radicale or edit the storage externally while Radicale is running if +disabled.

+

Default: True

+
+
+
max_sync_token_age
+

Delete sync-token that are older than the specified time. +(seconds)

+

Default: 2592000

+
+
+
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 page for an example.

+

Default:

+
+
+
+

web

+
+
type
+

The backend that provides the web interface of Radicale.

+

Available backends:

+

none : Just shows the message "Radicale works!".

+

internal : Allows creation and management of address +books and calendars.

+

Default: internal

+
+
+
+

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 +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:

+
Access-Control-Allow-Origin = *
+
+
+
+

Authentication and Rights

+

This page describes the format of the rights file for the +from_file authentication backend. The configuration option +file in the rights section must point to the +rights file.

+

The recommended rights method is owner_only. If access +to calendars and address books outside of the home directory of users +(that's /USERNAME/) is granted, clients won't detect these +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:

+
# The user "admin" can read and write any collection.
+[admin]
+user = admin
+collection = .*
+permission = rw
+
+# Block access for the user "user" to everything.
+[block]
+user = user
+collection = .*
+permission =
+
+# Authenticated users can read and write their own collections.
+[owner-write]
+user = .+
+collection = %(login)s(/.*)?
+permission = rw
+
+# Everyone can read the root collection
+[read]
+user = .*
+collection =
+permission = r
+

The titles of the sections are ignored (but must be unique). The keys +user and collection contain regular +expressions, that are matched against the user name and the path of the +collection. Permissions from the first matching section are used. If no +section matches, access gets denied.

+

The user name is empty for anonymous users. Therefore, the regex +.+ only matches authenticated users and .* +matches everyone (including anonymous users).

+

The path of the collection is separated by / and has no +leading or trailing /. Therefore, the path of the root +collection is empty.

+

%(login)s gets replaced by the user name and +%(path)s by the path of the collection. You can also get +groups from the user regex in the collection +regex with {0}, {1}, etc.

+
+
+

Storage

+

This document describes the layout and format of the file system +storage (multifilesystem backend).

+

It's safe to access and manipulate the data by hand or with scripts. +Scripts can be invoked manually, periodically (e.g. with cron) +or after each change to the storage with the configuration option +hook in the storage section (e.g. Git Versioning).

+
+

Layout

+

The file system contains the following files and folders:

+
    +
  • .Radicale.lock: The lock file for locking the +storage.
    • +
  • collection-root: This folder contains all collections +and items.
    • +
+

A collection is represented by a folder. This folder may contain the +file .Radicale.props with all WebDAV properties of the +collection encoded as JSON.

+

An item is represented by a file containing the iCalendar data.

+

All files and folders, whose names start with a dot but not +.Radicale. (internal files) are ignored.

+

If you introduce syntax errors in any of the files, all requests that +access the faulty data will fail. The logging output should contain the +names of the culprits.

+

Future releases of Radicale 2.x.x will store caches and sync-tokens +in the .Radicale.cache folder inside of collections. This +folder may be created or modified, while the storage is locked for +shared access. In theory, it should be safe to delete the folder. Caches +will be recreated automatically and clients will be told that their +sync-token isn't valid anymore.

+

You may encounter files or folders that start with +.Radicale.tmp-. Radicale uses them for atomic creation and +deletion of files and folders. They should be deleted after requests are +finished but it's possible that they are left behind when Radicale or +the computer crashes. It's safe to delete them.

+
+
+

Locking

+

When the data is accessed by hand or by an externally invoked script, +the storage must be locked. The storage can be locked for exclusive or +shared access. It prevents Radicale from reading or writing the file +system. The storage is locked with exclusive access while the +hook runs.

+
+
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
+
+
+
Linux and MacOS
+

Use the flock +syscall. Python provides it in the fcntl +module.

+
+
+
Windows
+

Use LockFile +for exclusive access or LockFileEx +which also supports shared access. Setting +nNumberOfBytesToLockLow to 1 and +nNumberOfBytesToLockHigh to 0 works.

+
+
+
+
+

Logging

+

Radicale logs to stderr. The verbosity of the log output +can be controlled with --debug command line argument or the +debug configuration option in the logging +section.

+

This is the recommended configuration for use with modern init +systems (like systemd) or if you just test Radicale in +a terminal.

+

You can configure Radicale to write its logging output to files (and +even rotate them). This is useful if the process daemonizes or if your +chosen method of running Radicale doesn't handle logging output.

+

A logging configuration file can be specified in the +config configuration option in the logging +section. The file format is explained in the Python +Logging Module.

+
+

Logging to a file

+

An example configuration to write the log output to the file +/var/log/radicale/log:

+
[loggers]
+keys = root
+
+[handlers]
+keys = file
+
+[formatters]
+keys = full
+
+[logger_root]
+# Change this to DEBUG or INFO for higher verbosity.
+level = WARNING
+handlers = file
+
+[handler_file]
+class = FileHandler
+# Specify the output file here.
+args = ('/var/log/radicale/log',)
+formatter = full
+
+[formatter_full]
+format = %(asctime)s - [%(thread)x] %(levelname)s: %(message)s
+

You can specify multiple logger, +handler and formatter if you want to +have multiple simultaneous log outputs.

+

The parent folder of the log files must exist and must be writable by +Radicale.

+

Security: The log files should not be readable by +unauthorized users. Set permissions accordingly.

+
+
Timed rotation of disk log files
+

An example handler configuration to write the log +output to the file /var/log/radicale/log and rotate it. +Replace the section handler_file from the file logging +example:

+
[handler_file]
+class = handlers.TimedRotatingFileHandler
+# Specify the output file and parameter for rotation here.
+# See https://docs.python.org/3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler
+# Example: rollover at midnight and keep 7 files (means one week)
+args = ('/var/log/radicale/log', 'midnight', 1, 7)
+formatter = full
+
+
+
Rotation of disk log files based on size
+

An example handler configuration to write the log +output to the file /var/log/radicale/log and rotate it . +Replace the section handle_file from the file logging +example:

+
[handler_file]
+class = handlers.RotatingFileHandler
+# Specify the output file and parameter for rotation here.
+# See https://docs.python.org/3/library/logging.handlers.html#logging.handlers.RotatingFileHandler
+# Example: rollover at 100000 kB and keep 10 files (means 1 MB)
+args = ('/var/log/radicale/log', 'a', 100000, 10)
+formatter = full
+
+
+
+
+

Architecture

+

Radicale is a really small piece of software, but understanding it is +not as easy as it seems. But don't worry, reading this short page is +enough to understand what a CalDAV/CardDAV server is, and how Radicale's +code is organized.

+
+

General Architecture

+

Here is a simple overview of the global architecture for reaching a +calendar or an address book through network:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PartLayerProtocol or Format
ServerCalendar/Contact StorageiCal/vCard
Calendar/Contact ServerCalDAV/CardDAV Server
TransferNetworkCalDAV/CardDAV (HTTP + TLS)
ClientCalendar/Contact ClientCalDAV/CardDAV Client
GUITerminal, GTK, Web interface, etc.
+

Radicale is only the server part of this +architecture.

+

Please note that:

+
    +
  • CalDAV and CardDAV are superset protocols of WebDAV,
    • +
  • WebDAV is a superset protocol of HTTP.
    • +
+

Radicale being a CalDAV/CardDAV server, it also can be seen as a +special WebDAV and HTTP server.

+

Radicale is not the client part of this +architecture. It means that Radicale never draws calendars, address +books, events and contacts on the screen. It only stores them and give +the possibility to share them online with other people.

+

If you want to see or edit your events and your contacts, you have to +use another software called a client, that can be a "normal" +applications with icons and buttons, a terminal or another web +application.

+
+
+

Code Architecture

+

The radicale package offers 9 modules.

+

__main__ : The main module provides a simple function +called run. Its main work is to read the configuration from the +configuration file and from the options given in the command line; then +it creates a server, according to the configuration.

+

__init__ : This is the core part of the module, with the +code for the CalDAV/CardDAV server. The server inherits from a +WSGIServer server class, which relies on the default HTTP server class +given by Python. The code managing the different HTTP requests according +to the CalDAV/CardDAV normalization is written here.

+

config : This part gives a dict-like access to the +server configuration, read from the configuration file. The +configuration can be altered when launching the executable with some +command line options.

+

xmlutils : The functions defined in this module are +mainly called by the CalDAV/CardDAV server class to read the XML part of +the request, read or alter the calendars, and create the XML part of the +response. The main part of this code relies on ElementTree.

+

log : The start function provided by this module starts +a logging mechanism based on the default Python logging module. Logging +options can be stored in a logging configuration file.

+

auth : This module provides a default authentication +manager equivalent to Apache's htpasswd. Login + password couples are +stored in a file and used to authenticate users. Passwords can be +encrypted using various methods. Other authentication methods can +inherit from the base class in this file and be provided as plugins.

+

rights : This module is a set of Access Control Lists, a +set of methods used by Radicale to manage rights to access the +calendars. When the CalDAV/CardDAV server is launched, an Access Control +List is chosen in the set, according to the configuration. The HTTP +requests are then filtered to restrict the access depending on who is +authenticated. Other configurations can be written using regex-based +rules. Other rights managers can also inherit from the base class in +this file and be provided as plugins.

+

storage : In this module are written the classes +representing collections and items in Radicale, and the class storing +these collections and items in your filesystem. Other storage classes +can inherit from the base class in this file and be provided as +plugins.

+

web : This module contains the web interface.

+
+
+
+

Plugins

+

Radicale can be extended by plugins for authentication, rights +management and storage. Plugins are python modules.

+
+

Getting started

+

To get started we walk through the creation of a simple +authentication plugin, that accepts login attempts if the username and +password are equal.

+

The easiest way to develop and install python +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_silly_auth", packages=["radicale_silly_auth"])
+

In the same folder create the sub-folder +radicale_silly_auth. The folder must have the same name as +specified in packages above.

+

Create the file __init__.py in the +radicale_silly_auth folder with the following content:

+
from radicale.auth import BaseAuth
+
+
+class Auth(BaseAuth):
+    def is_authenticated(self, user, password):
+        # Example custom configuration option
+        foo = ""
+        if self.configuration.has_option("auth", "foo"):
+            foo = self.configuration.get("auth", "foo")
+        self.logger.info("Configuration option %r is %r", "foo", foo)
+
+        # Check authentication
+        self.logger.info("Login attempt by %r with password %r",
+                         user, password)
+        return user == password
+

Install the python module by running the following command in the +same folder as setup.py:

+
python3 -m pip install --upgrade .
+

To make use this great creation in Radicale, set the configuration +option type in the auth section to +radicale_silly_auth:

+
[auth]
+type = radicale_silly_auth
+foo = bar
+

You can uninstall the module with:

+
python3 -m pip uninstall radicale_silly_auth
+
+
+

Authentication plugins

+

This plugin type is used to check login credentials. The module must +contain a class Auth that extends +radicale.auth.BaseAuth. Take a look at the file +radicale/auth.py in Radicale's source code for more +information.

+
+
+

Rights management plugins

+

This plugin type is used to check if a user has access to a path. The +module must contain a class Rights that extends +radicale.rights.BaseRights. Take a look at the file +radicale/rights.py in Radicale's source code for more +information.

+
+
+

Web plugins

+

This plugin type is used to provide the web interface for Radicale. +The module must contain a class Web that extends +radicale.web.BaseWeb. Take a look at the file +radicale/web.py in Radicale's source code for more +information.

+
+
+

Storage plugins

+

This plugin is used to store collections and items. The module must +contain a class Collection that extends +radicale.storage.BaseCollection. Take a look at the file +radicale/storage.py in Radicale's source code for more +information.

+
+
+
+

Migration from 1.x.x to 2.x.x

+
+

Why a Migration?

+

Radicale 2.x.x is different from 1.x.x, here's everything you need to +know about this! Please read this page carefully if you want to +update Radicale.

+

You'll also find extra information in issue #372.

+
+
+

Python 3 Only

+

Radicale 2.x.x works with Python >= 3.3, and doesn't work +anymore with Python 2.

+

(No, Python 3.3 is not new, it's been released more than 4 years ago. +Debian stable provides Python 3.4.)

+
+
+

Dependencies

+

Radicale now depends on VObject, a +"full-featured Python package for parsing and creating iCalendar and +vCard files". That's the price to pay to correctly read crazy iCalendar +files and support date-based filters, even on recurring +events.

+
+
+

Storage

+

Calendars and address books are stored in a different way between +1.x.x and 2.x.x versions. Launching 2.x.x without migrating your +collections first will not work, Radicale won't be able to read your +previous data.

+

There's now only one way to store data in Radicale: collections are +stored as folders and events / contacts are stored in files. This new +storage is close to the multifilesystem, but it's +now thread-safe, with atomic writes and file locks. Other +storage types can be used by creating plugins.

+

To migrate data to Radicale 2.x.x the command line argument +--export-storage was added to Radicale 1.1.x. Start +Radicale 1.x.x as you would normally do, but add the argument +--export-storage path/to/empty/folder. Radicale will export +the storage into the specified folder. This folder can be directly used +with the default storage backend of Radicale 2.x.x.

+

If you import big calendars or address books into Radicale 2.x.x the +first request might take a long time, because it has to initialize its +internal caches. Clients can time out, subsequent requests will be much +faster.

+

You can check the imported storage for errors by starting Radicale +>= 2.1.5 with the --verify-storage argument.

+

You can install version 1.1.x with:

+
$ python3 -m pip install --upgrade radicale==1.1.*
+
+
+

Authentication

+

Radicale 2.x.x only provides htpasswd authentication +out-of-the-box. Other authentication methods can be added by +creating or using plugins.

+
+
+

Rights

+

In Radicale 2.x.x, rights are managed using regex-based rules based +on the login of the authenticated user and the URL of the resource. +Default configurations are built in for common cases, you'll find more +about this on the Authentication +& Rights page.

+

Other rights managers can be added by creating plugins.

+
+
+

Versioning

+

Support for versioning with git was removed from +Radicale 2.x.x. Instead, the configuration option hook in +the storage section was added, the Collection Versioning page explains its usage for +version control.

+
+
+
+ + + + +
+
+ diff --git a/html/v2/download.html b/html/v2/download.html new file mode 100644 index 000000000..5b7ecc591 --- /dev/null +++ b/html/v2/download.html @@ -0,0 +1,613 @@ + + + + + + + + + + + + + + +Radicale v2 Documentation + + + + + +
+
+

+Radicale + +v2 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + +
+

Download

+
+

PyPI

+

Radicale is available on PyPI. To +install, just type as superuser:

+
$ python3 -m pip install --upgrade radicale==2.1.*
+
+
+

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 git+https://github.com/Kozea/Radicale
+

You can also download the content of the repository as an archive.

+
+
+

Source Packages

+

You can download the Radicale package for each release:

+ +
+
+

Linux Distribution Packages

+

Radicale has been packaged for:

+ +

Radicale is also available +on Cloudron and has a Dockerfile.

+

If you are interested in creating packages for other Linux +distributions, read the "Contribute" page.

+
+
+ + +
+
+ diff --git a/html/v2/index.html b/html/v2/index.html new file mode 100644 index 000000000..665de9918 --- /dev/null +++ b/html/v2/index.html @@ -0,0 +1,546 @@ + + + + + + + + + + + + + + +Radicale v2 Documentation + + + + + +
+
+

+Radicale + +v2 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+
+

Getting started

+
+

About Radicale

+

Radicale is a small but powerful CalDAV (calendars, todo-lists) and +CardDAV (contacts) server, that:

+
    +
  • Shares calendars through CalDAV, WebDAV and HTTP.
    • +
  • Shares contacts through CardDAV, WebDAV and HTTP.
    • +
  • Supports events, todos, journal entries and business cards.
    • +
  • Works out-of-the-box, no installation nor configuration +required.
    • +
  • Can warn users on concurrent editing.
    • +
  • Can limit access by authentication.
    • +
  • Can secure connections.
    • +
  • Works with many CalDAV and CardDAV clients.
    • +
  • Is GPLv3-licensed free software.
    • +
+
+
+

Installation

+

Radicale is really easy to install and works out-of-the-box.

+
$ python3 -m pip install --upgrade radicale==2.1.*
+$ python3 -m radicale --config "" --storage-filesystem-folder=~/.var/lib/radicale/collections
+

When your server is launched, you can check that everything's OK by +going to http://localhost:5232/ with your browser! You can login with +any username and password.

+

Want more? Why don't you check our wonderful documentation?

+
+
+

What's New?

+

Latest version of Radicale is 2.1.12, released on May 19, 2020 (changelog).

+

Read latest news…

+
+
+ + + + + +
+
+ diff --git a/html/v2/news.html b/html/v2/news.html new file mode 100644 index 000000000..a29e51ec9 --- /dev/null +++ b/html/v2/news.html @@ -0,0 +1,1628 @@ + + + + + + + + + + + + + + +Radicale v2 Documentation + + + + + +
+
+

+Radicale + +v2 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + + +
+

News

+

Latest version of Radicale is 2.1.12, released on May 19, 2020 (changelog).

+
+

May 19, 2020 - Radicale 2.1.12

+

Radicale 2.1.12 is out!

+
+

2.1.12 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Include documentation in source archive
    • +
+
+
+
+

November 5, 2018 - Radicale 2.1.11

+

Radicale 2.1.11 is out!

+
+

2.1.11 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Fix moving items between collections
    • +
+
+
+
+

August 16, 2018 - Radicale 2.1.10

+

Radicale 2.1.10 is out!

+
+

2.1.10 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Update required versions for dependencies
    • +
  • Get RADICALE_CONFIG from WSGI environ
    • +
  • Improve HTTP status codes
    • +
  • Fix race condition in storage lock creation
    • +
  • Raise default limits for content length and timeout
    • +
  • Log output from hook
    • +
+
+
+
+

April 21, 2018 - Radicale 2.1.9

+

Radicale 2.1.9 is out!

+
+

2.1.9 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Specify versions for dependencies
    • +
  • Move WSGI initialization into module
    • +
  • Check if REPORT method is actually supported
    • +
  • Include rights file in source distribution
    • +
  • Specify md5 and bcrypt as extras
    • +
  • Improve logging messages
    • +
  • Windows: Fix crash when item path is a directory
    • +
+
+
+
+

September 24, 2017 - Radicale 2.1.8

+

Radicale 2.1.8 is out!

+
+

2.1.8 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Flush files before fsync'ing
    • +
+
+
+
+

September 17, 2017 - Radicale 2.1.7

+

Radicale 2.1.7 is out!

+
+

2.1.7 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Don't print warning when cache format changes
    • +
  • Add documentation for BaseAuth
    • +
  • Add is_authenticated2(login, user, password) to +BaseAuth
    • +
  • Fix names of custom properties in PROPFIND requests with +D:propname or D:allprop
    • +
  • Return all properties in PROPFIND requests with +D:propname or D:allprop
    • +
  • Allow D:displayname property on all collections
    • +
  • Answer with D:unauthenticated for +D:current-user-principal property when not logged in
    • +
  • Remove non-existing ICAL:calendar-color and +C:calendar-timezone properties from PROPFIND requests with +D:propname or D:allprop
    • +
  • Add D:owner property to calendar and address book +objects
    • +
  • Remove D:getetag and D:getlastmodified +properties from regular collections
    • +
+
+
+
+

September 11, 2017 - Radicale 2.1.6

+

Radicale 2.1.6 is out!

+
+

2.1.6 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Fix content-type of VLIST
    • +
  • Specify correct COMPONENT in content-type of VCALENDAR
    • +
  • Cache COMPONENT of calendar objects (improves speed with some +clients)
    • +
  • Stricter parsing of filters
    • +
  • Improve support for CardDAV filter
    • +
  • Fix some smaller bugs in CalDAV filter
    • +
  • Add X-WR-CALNAME and X-WR-CALDESC to calendars downloaded via +HTTP/WebDAV
    • +
  • Use X-WR-CALNAME and X-WR-CALDESC from calendars published via +WebDAV
    • +
+
+
+
+

August 25, 2017 - Radicale 2.1.5

+

Radicale 2.1.5 is out!

+
+

2.1.5 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Add --verify-storage command-line argument
    • +
  • Allow comments in the htpasswd file
    • +
  • Don't strip whitespaces from user names and passwords in the +htpasswd file
    • +
  • Remove cookies from logging output
    • +
  • Allow uploads of whole collections with many components
    • +
  • Show warning message if server.timeout is used with Python < +3.5.2
    • +
+
+
+
+

August 4, 2017 - Radicale 2.1.4

+

Radicale 2.1.4 is out!

+
+

2.1.4 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Fix incorrect time range matching and calculation for some +edge-cases with rescheduled recurrences
    • +
  • Fix owner property
    • +
+
+
+
+

August 2, 2017 - Radicale 2.1.3

+

Radicale 2.1.3 is out!

+
+

2.1.3 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Enable timeout for SSL handshakes and move them out of the main +thread
    • +
  • Create cache entries during upload of items
    • +
  • Stop built-in server on Windows when Ctrl+C is pressed
    • +
  • Prevent slow down when multiple requests hit a collection during +cache warm-up
    • +
+
+
+
+

July 24, 2017 - Radicale 2.1.2

+

Radicale 2.1.2 is out!

+
+

2.1.2 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Remove workarounds for bugs in VObject < 0.9.5
    • +
  • Error checking of collection tags and associated components
    • +
  • Improve error checking of uploaded collections and components
    • +
  • Don't delete empty collection properties implicitly
    • +
  • Improve logging of VObject serialization
    • +
+
+
+
+

July 1, 2017 - Radicale 2.1.1

+

Radicale 2.1.1 is out!

+
+

2.1.1 - Wild Radish Again

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.x.x.

+
    +
  • Add missing UIDs instead of failing
    • +
  • Improve error checking of calendar and address book objects
    • +
  • Fix upload of whole address books
    • +
+
+
+
+

June 25, 2017 - Radicale 2.1.0

+

Radicale 2.1.0 is out!

+
+

2.1.0 - Wild Radish

+

This release is compatible with version 2.0.0. Follow our migration guide if you want to +switch from 1.x.x to 2.1.0.

+
    +
  • Built-in web interface for creating and managing address books and +calendars +
      +
    • can be extended with web plugins
      • +
    • +
  • Much faster storage backend
    • +
  • Significant reduction in memory usage
    • +
  • Improved logging +
      +
    • Include paths (of invalid items / requests) in log messages
      • +
    • Include configuration values causing problems in log messages
      • +
    • Log warning message for invalid requests by clients
      • +
    • Log error message for invalid files in the storage backend
      • +
    • No stack traces unless debugging is enabled
      • +
    • +
  • Time range filter also regards overwritten recurrences
    • +
  • Items that couldn't be filtered because of bugs in VObject are +always returned (and a warning message is logged)
    • +
  • Basic error checking of configuration files
    • +
  • File system locking isn't disabled implicitly anymore, instead a new +configuration option gets introduced
    • +
  • The permissions of the lock file are not changed anymore
    • +
  • Support for sync-token
    • +
  • Support for client-side SSL certificates
    • +
  • Rights plugins can decide if access to an item is granted explicitly +
      +
    • Respond with 403 instead of 404 for principal collections of +non-existing users when owner_only plugin is used +(information leakage)
      • +
    • +
  • Authentication plugins can provide the login and password from the +environment +
      +
    • new remote_user plugin, that gets the login from the +REMOTE_USER environment variable (for WSGI server)
      • +
    • new http_x_remote_user plugin, that gets the login from +the X-Remote-User HTTP header (for reverse proxies)
      • +
    • +
+
+
+
+

May 27, 2017 - Radicale 2.0.0

+

Radicale 2.0.0 is out!

+
+

2.0.0 - Little Big Radish

+

This feature is not compatible with the 1.x.x versions. Follow our migration guide if you want to +switch from 1.x.x to 2.0.0.

+
    +
  • Support Python 3.3+ only, Python 2 is not supported anymore
    • +
  • Keep only one simple filesystem-based storage system
    • +
  • Remove built-in Git support
    • +
  • Remove built-in authentication modules
    • +
  • Keep the WSGI interface, use Python HTTP server by default
    • +
  • Use a real iCal parser, rely on the "vobject" external module
    • +
  • Add a solid calendar discovery
    • +
  • Respect the difference between "files" and "folders", don't rely on +slashes
    • +
  • Remove the calendar creation with GET requests
    • +
  • Be stateless
    • +
  • Use a file locker
    • +
  • Add threading
    • +
  • Get atomic writes
    • +
  • Support new filters
    • +
  • Support read-only permissions
    • +
  • Allow External plugins for authentication, rights management, +storage and version control
    • +
+

This release concludes endless months of hard work from the +community. You, all users and contributors, deserve a big thank +you.

+

This project has been an increadible experience for me, your dear +Guillaume, creator and maintainer of Radicale. After more than 8 years +of fun, I think that it's time to open this software to its +contributors. Radicale can grow and become more than the toy it used to +be. I've always seen Radicale as a small and simple piece of code, and I +don't want to prevent people from adding features just because I can't +or don't want to maintain them. The community is now large enough to +handle this.

+

If you're interested in Radicale, you can read #372 and build +its future.

+
+
+
+

May 3, 2017 - Radicale 1.1.2

+

Radicale 1.1.2 is out!

+
+

1.1.2 - Third Law of Nature

+
    +
  • Security fix: Add a random timer to avoid timing +oracles and simple bruteforce attacks when using the htpasswd +authentication method.
    • +
  • Various minor fixes.
    • +
+
+
+
+

December 31, 2015 - Radicale 1.1

+

Radicale 1.1 is out!

+
+

1.1 - Law of Nature

+

One feature in this release is not backward +compatible:

+
    +
  • Use the first matching section for rights (inspired from daald)
    • +
+

Now, the first section matching the path and current user in your +custom rights file is used. In the previous versions, the most +permissive rights of all the matching sections were applied. This new +behaviour gives a simple way to make specific rules at the top of the +file independant from the generic ones.

+

Many improvements in this release are related to +security, you should upgrade Radicale as soon as possible:

+
    +
  • Improve the regex used for well-known URIs (by Unrud)
    • +
  • Prevent regex injection in rights management (by Unrud)
    • +
  • Prevent crafted HTTP request from calling arbitrary functions (by +Unrud)
    • +
  • Improve URI sanitation and conversion to filesystem path (by +Unrud)
    • +
  • Decouple the daemon from its parent environment (by Unrud)
    • +
+

Some bugs have been fixed and little enhancements have been +added:

+
    +
  • Assign new items to corret key (by Unrud)
    • +
  • Avoid race condition in PID file creation (by Unrud)
    • +
  • Improve the docker version (by cdpb)
    • +
  • Encode message and commiter for git commits
    • +
  • Test with Python 3.5
    • +
+
+
+
+

September 14, 2015 - Radicale 1.0, what's next?

+

Radicale 1.0 is out!

+
+

1.0 - Sunflower

+
    +
  • Enhanced performances (by Mathieu Dupuy)
    • +
  • Add MD5-APR1 and BCRYPT for htpasswd-based authentication (by +Jan-Philip Gehrcke)
    • +
  • Use PAM service (by Stephen Paul Weber)
    • +
  • Don't discard PROPPATCH on empty collections (Markus +Unterwaditzer)
    • +
  • Write the path of the collection in the git message (Matthew +Monaco)
    • +
  • Tests launched on Travis
    • +
+

As explained in a previous mail, +this version is called 1.0 because:

+
    +
  • there are no big changes since 0.10 but some small changes are +really useful,
    • +
  • simple tests are now automatically launched on Travis, and more can +be added in the future (https://travis-ci.org/Kozea/Radicale).
    • +
+

This version will be maintained with only simple bug fixes on a +separate git branch called 1.0.x.

+

Now that this milestone is reached, it's time to think about the +future. When Radicale has been created, it was just a proof-of-concept. +The main goal was to write a small, stupid and simple CalDAV server +working with Lightning, using no external libraries. That's how we +created a piece of code that's (quite) easy to understand, to use and to +hack.

+

The first lines have been added to the SVN (!) repository as I was +drinking beers at the very end of 2008. It's now packaged for a growing +number of Linux distributions.

+

And that was fun going from here to there thanks to you. So… +Thank you, you're amazing. I'm so glad I've spent +endless hours fixing stupid bugs, arguing about databases and meeting +invitations, reading incredibly interesting RFCs and debugging with the +fabulous clients from Apple. I mean: that really, really was really, +really cool :).

+

During these years, a lot of things have changed and many users now +rely on Radicale in production. For example, I use it to manage medical +calendars, with thousands requests per day. Many people are happy to +install Radicale on their small home servers, but are also frustrated by +performance and unsupported specifications when they're trying to use it +seriously.

+

So, now is THE FUTURE! I think that Radicale 2.0 should:

+
    +
  • rely on a few external libraries for simple critical points (dealing +with HTTP and iCal for example),
    • +
  • be thread-safe,
    • +
  • be small,
    • +
  • be documented in a different way (for example by splitting the +client part from the server part, and by adding use cases),
    • +
  • let most of the "auth" modules outside in external modules,
    • +
  • have more and more tests,
    • +
  • have reliable and faster filesystem and database storage +mechanisms,
    • +
  • get a new design :).
    • +
+

I'd also secretly love to drop the Python 2.x support.

+

These ideas are not all mine (except from the really, really, really +important "design" point :p), they have been proposed by many developers +and users. I've just tried to gather them and keep points that seem +important to me.

+

Other points have been discussed with many users and contibutors, +including:

+
    +
  • support of other clients, including Windows and BlackBerry +phones,
    • +
  • server-side meeting invitations,
    • +
  • different storage system as default (or even unique?).
    • +
+

I'm not a huge fan of these features, either because I can't do +anything about them, or because I think that they're Really Bad Ideas®™. +But I'm ready to talk about them, because, well, I may not be always +right!

+

Need to talk about this? You know how to contact us!

+
+
+
+

January 12, 2015 - Radicale 0.10

+

Radicale 0.10 is out!

+
+

0.10 - Lovely Endless Grass

+
    +
  • Support well-known URLs (by Mathieu Dupuy)
    • +
  • Fix collection discovery (by Markus Unterwaditzer)
    • +
  • Reload logger config on SIGHUP (by Élie Bouttier)
    • +
  • Remove props files when deleting a collection (by Vincent Untz)
    • +
  • Support salted SHA1 passwords (by Marc Kleine-Budde)
    • +
  • Don't spam the logs about non-SSL IMAP connections to localhost (by +Giel van Schijndel)
    • +
+

This version should bring some interesting discovery and +auto-configuration features, mostly with Apple clients.

+

Lots of love and kudos for the people who have spent hours to test +features and report issues, that was long but really useful (and some of +you have been really patient :p).

+

Issues are welcome, I'm sure that you'll find horrible, terrible, +crazy bugs faster than me. I'll release a version 0.10.1 if needed.

+

What's next? It's time to fix and improve the storage methods. A real +API for the storage modules is a good beginning, many pull requests are +already ready to be discussed and merged, and we will probably get some +good news about performance this time. Who said "databases, please"?

+
+
+
+

July 12, 2013 - Radicale 0.8

+

Radicale 0.8 is out!

+
+

0.8 - Rainbow

+
    +
  • New authentication and rights management modules (by Matthias +Jordan)
    • +
  • Experimental database storage
    • +
  • Command-line option for custom configuration file (by Mark +Adams)
    • +
  • Root URL not at the root of a domain (by Clint Adams, Fabrice +Bellet, Vincent Untz)
    • +
  • Improved support for iCal, CalDAVSync, CardDAVSync, CalDavZAP and +CardDavMATE
    • +
  • Empty PROPFIND requests handled (by Christoph Polcin)
    • +
  • Colon allowed in passwords
    • +
  • Configurable realm message
    • +
+

This version brings some of the biggest changes since Radicale's +creation, including an experimental support of database storage, clean +authentication modules, and rights management finally designed for real +users.

+

So, dear user, be careful: this version changes important +things in the configuration file, so check twice that everything is OK +when you update to 0.8, or you can have big problems.

+

More and more clients are supported, as a lot of bug fixes and +features have been added for this purpose. And before you ask: yes, 2 +web-based clients, CalDavZAP and +CardDavMATE, are now supported!

+

Even if there has been a lot of time to test these new features, I am +pretty sure that some really annoying bugs have been left in this +version. We will probably release minor versions with bugfixes during +the next weeks, and it will not take one more year to reach 0.8.1.

+

The documentation has been updated, but some parts are missing and +some may be out of date. You can report bugs or even +write +documentation directly on GitHub if you find something strange (and +you probably will).

+

If anything is not clear, or if the way rights work is a bit +complicated to understand, or if you are so happy because everything +works so well, you can share your +thoughts!

+

It has been a real pleasure to work on this version, with brilliant +ideas and interesting bug reports from the community. I'd really like to +thank all the people reporting bugs, chatting on IRC, sending mails and +proposing pull requests: you are awesome.

+
+
+
+

August 3, 2012 - Radicale 0.7.1

+

Radicale 0.7.1 is out!

+
+

0.7.1 - Waterfalls

+
    +
  • Many address books fixes
    • +
  • New IMAP ACL (by Daniel Aleksandersen)
    • +
  • PAM ACL fixed (by Daniel Aleksandersen)
    • +
  • Courier ACL fixed (by Benjamin Frank)
    • +
  • Always set display name to collections (by Oskari Timperi)
    • +
  • Various DELETE responses fixed
    • +
+

It's been a long time since the last version… As usual, many people +have contributed to this new version, that's a pleasure to get these +pull requests.

+

Most of the commits are bugfixes, especially about ACL backends and +address books. Many clients (including aCal and SyncEvolution) will be +much happier with this new version than with the previous one.

+

By the way, one main new feature has been added: a new IMAP ACL +backend, by Daniel. And about authentication, exciting features are +coming soon, stay tuned!

+

Next time, as many mails have come from angry and desperate coders, +tests will be finally added to help them to add features and +fix bugs. And after that, who knows, it may be time to release Radicale +1.0…

+
+
+
+

March 22, 2012 - Radicale 0.7

+

Radicale 0.7 is out, at least!

+
+

0.7 - Eternal Sunshine

+
    +
  • Repeating events
    • +
  • Collection deletion
    • +
  • Courier and PAM authentication methods
    • +
  • CardDAV support
    • +
  • Custom LDAP filters supported
    • +
+

A lot of people have reported bugs, proposed new +features, added useful code and tested many clients. Thank you Lynn, +Ron, Bill, Patrick, Hidde, Gerhard, Martin, Brendan, Vladimir, and +everybody I've forgotten.

+
+
+
+

January 5, 2012 - Radicale 0.6.4, News from Calypso

+

New year, new release. Radicale 0.6.4 has a really short +changelog:

+
+

0.6.4 - Tulips

+
    +
  • Fix the installation with Python 3.1
    • +
+

The bug was in fact caused by a bug in Python 3.1, +everything should be OK now.

+
+
+

Calypso

+

After a lot of changes in Radicale, Keith Packard has decided to +launch a fork called Calypso, with nice features +such as a Git storage mechanism and a CardDAV support.

+

There are lots of differences between the two projects, but the final +goal for Radicale is to provide these new features as soon as possible. +Thanks to the work of Keith and other people on GitHub, a basic CardDAV +support has been added in the carddav branch +and already works with Evolution. Korganizer also works with existing +address books, and CardDAV-Sync will be tested soon. If you want to test +other clients, please let us know!

+
+
+
+

November 3, 2011 - Radicale 0.6.3

+

Radicale version 0.6.3 has been released, with bugfixes that could be +interesting for you!

+
+

0.6.3 - Red Roses

+
    +
  • MOVE requests fixed
    • +
  • Faster REPORT answers
    • +
  • Executable script moved into the package
    • +
+
+
+

What's New Since 0.6.2?

+

The MOVE requests were suffering a little bug that is fixed now. +These requests are only sent by Apple clients, Mac users will be +happy.

+

The REPORT request were really, really slow (several minutes for +large calendars). This was caused by an awful algorithm parsing the +entire calendar for each event in the calendar. The calendar is now only +parsed three times, and the events are found in a Python list, turning +minutes into seconds! Much better, but far from perfection…

+

Finally, the executable script parsing the command line options and +starting the HTTP servers has been moved from the +radicale.py file into the radicale package. +Two executable are now present in the archive: the good old +radicale.py, and bin/radicale. The second one +is only used by setup.py, where the hack used to rename +radicale.py into radicale has therefore been +removed. As a consequence, you can now launch Radicale with the simple +python -m radicale command, without relying on an +executable.

+
+
+

Time for a Stable Release!

+

The next release may be a stable release, symbolically called 1.0. +Guess what's missing? Tests, of course!

+

A non-regression testing suite, based on the clients' requests, will +soon be added to Radicale. We're now thinking about a smart solution to +store the tests, to represent the expected answers and to launch the +requests. We've got crazy ideas, so be prepared: you'll definitely +want to write tests during the next weeks!

+

Repeating events, PAM and Courier authentication methods have already +been added in master. You'll find them in the 1.0 release!

+
+
+

What's Next?

+

Being stable is one thing, being cool is another one. If you want +some cool new features, you may be interested in:

+
    +
  • WebDAV and CardDAV support
    • +
  • Filters and rights management
    • +
  • Multiple storage backends, such as databases and git
    • +
  • Freebusy periods
    • +
  • Email alarms
    • +
+

Issues have been reported in the bug tracker, you can follow there +the latest news about these features. Your beloved text editor is +waiting for you!

+
+
+
+

September 27, 2011 - Radicale 0.6.2

+

0.6.2 is out with minor bugfixes.

+
+

0.6.2 - Seeds

+
    +
  • iPhone and iPad support fixed
    • +
  • Backslashes replaced by slashes in PROPFIND answers on Windows
    • +
  • PyPI archive set as default download URL
    • +
+
+
+
+

August 28, 2011 - Radicale 0.6.1, Changes, Future

+

As previously imagined, a new 0.6.1 version has been released, mainly +fixing obvious bugs.

+
+

0.6.1 - Growing Up

+
    +
  • Example files included in the tarball
    • +
  • htpasswd support fixed
    • +
  • Redirection loop bug fixed
    • +
  • Testing message on GET requests
    • +
+

The changelog is really small, so there should be no real new +problems since 0.6. The example files for logging, FastCGI and WSGI are +now included in the tarball, for the pleasure of our dear packagers!

+

A new branch has been created for various future bug fixes. You can +expect to get more 0.6.x versions, making this branch a kind of "stable" +branch with no big changes.

+
+
+

GitHub, Mailing List, New Website

+

A lot of small changes occurred during the last weeks.

+

If you're interested in code and new features, please note that we +moved the project from Gitorious to GitHub. Being hosted by Gitorious +was a nice experience, but the service was not that good and we were +missing some useful features such as git hooks. Moreover, GitHub is +really popular, we're sure that we'll meet a lot of kind users and +coders there.

+

We've also created a mailing-list on Librelist to keep a public trace +of the mails we're receiving. It a bit empty now, but we're sure that +you'll soon write us some kind words. For example, you can tell us what +you think of our new website!

+
+
+

Future Features

+

In the next weeks, new exciting features are coming in the master +branch! Some of them are almost ready:

+
    +
  • Henry-Nicolas has added the support for the PAM and +Courier-Authdaemon authentication mechanisms.
    • +
  • An anonymous called Keith Packard has prepared some small changes, +such as one file per event, cache and git versioning. Yes. Really.
    • +
+

As you can find in the Radicale Roadmap, tests, +rights and filters are expected for 0.7.

+
+
+
+

August 1, 2011 - Radicale 0.6 Released

+

Time for a new release with a lot of new exciting +features!

+
+

0.6 - Sapling

+
    +
  • WSGI support
    • +
  • IPv6 support
    • +
  • Smart, verbose and configurable logs
    • +
  • Apple iCal 4 and iPhone support (by Łukasz Langa)
    • +
  • CalDAV-Sync support (by Marten Gajda)
    • +
  • aCal support
    • +
  • KDE KOrganizer support
    • +
  • LDAP auth backend (by Corentin Le Bail)
    • +
  • Public and private calendars (by René Neumann)
    • +
  • PID file
    • +
  • MOVE requests management
    • +
  • Journal entries support
    • +
  • Drop Python 2.5 support
    • +
+

Well, it's been a little longer than expected, but for good reasons: +a lot of features have been added, and a lot of clients are known to +work with Radicale, thanks to kind contributors. That's definitely good +news! But…

+

Testing all the clients is really painful, moreover for the ones from +Apple (I have no Mac nor iPhone of my own). We should seriously think of +automated tests, even if it's really hard to maintain, and maybe not +that useful. If you're interested in tests, you can look at the +wonderful regression suite of DAViCal.

+

The new features, for example the WSGI support, are also poorly +documented. If you have some Apache or lighttpd configuration working +with Radicale, you can make the world a little bit better by writing a +paragraph or two in the Radicale +documentation. It's simple plain text, don't be afraid!

+

Because of all these changes, Radicale 0.6 may be a little bit buggy; +a 0.6.1 will probably be released soon, fixing small problems with +clients and features. Get ready to report bugs, I'm sure that you can +find one (and fix it)!

+
+
+
+

July 2, 2011 - Feature Freeze for 0.6

+

According to the roadmap, a +lot of features have been added since Radicale 0.5, much more than +expected. It's now time to test Radicale with your favourite client and +to report bugs before we release the next stable version!

+

Last week, the iCal and iPhone support written by Łukasz has been +fixed in order to restore the broken Lightning support. After two +afternoons of tests with Rémi, we managed to access the same calendar +with Lightning, iCal, iPhone and Evolution, and finally discovered that +CalDAV could also be a perfect instant messaging protocol between a Mac, +a PC and a phone.

+

After that, we've had the nice surprise to see events displayed +without a problem (but after some strange steps of configuration) by +aCal on Salem's Android phone.

+

It was Friday, fun fun fun fun.

+

So, that's it: Radicale supports Lightning, Evolution, Kontact, aCal +for Android, iPhone and iCal. Of course, before releasing a new +tarball:

+
    +
  • documentation +is needed for the new clients that are not documented yet (Kontact, aCal +and iPhone);
    • +
  • tests are welcome, particularly for the Apple clients that I can't +test anymore;
    • +
  • no more features will be added, they'll wait in separate branches +for the 0.7 development.
    • +
+

Please report bugs +if anything goes wrong during your tests, or just let us know by Jabber or by mail if everything is OK.

+
+
+

May 1, 2011 - Ready for WSGI

+

Here it is! Radicale is now ready to be launched behind your +favourite HTTP server (Apache, Lighttpd, Nginx or Tomcat for example). +That's really good news, because:

+
    +
  • Real HTTP servers are much more efficient and reliable than the +default Python server used in Radicale;
    • +
  • All the authentication backends available for your server will be +available for Radicale;
    • +
  • Thanks to flup, Radicale +can be interfaced with all the servers supporting CGI, AJP, FastCGI or +SCGI;
    • +
  • Radicale works very well without any additional server, without any +dependencies, without configuration, just as it was working before;
    • +
  • This one more feature removes useless code, less is definitely +more.
    • +
+

The WSGI support has only be tested as a stand-alone executable and +behind Lighttpd, you should definitely try if it works with you +favourite server too!

+

No more features will be added before (quite) a long time, because a +lot of documentation and test is waiting for us. If you want to write +tutorials for some CalDAV clients support (iCal, Android, iPhone), HTTP +servers support or logging management, feel free to fork the +documentation git repository and ask for a merge. It's plain text, I'm +sure you can do it!

+
+
+

April 30, 2011 - Apple iCal Support

+

After a long, long work, the iCal support has finally been added to +Radicale! Well, this support is only for iCal 4 and is highly +experimental, but you can test it right now with the git master branch. +Bug reports are welcome!

+

Dear MacOS users, you can thank all the gentlemen who sended a lot of +debugging iformation. Special thanks to Andrew from DAViCal, who helped +us a lot with his tips and his tests, and Rémi Hainaud who lent his +laptop for the final tests.

+

The default server address is localhost:5232/user/, +where calendars can be added. Multiple calendars and owner-less +calendars are not tested yet, but they should work quite well. More +documentation will be added during the next days. It will then be time +to release the Radicale 0.6 version, and work on the WSGI support.

+
+
+

April 25, 2011 - Two Features and One New Roadmap

+

Two features have just reached the master branch, and the roadmap has +been refreshed.

+
+

LDAP Authentication

+

Thanks to Corentin, the LDAP authentication is now included in +Radicale. The support is experimental and may suffer unstable connexions +and security problems. If you are interested in this feature (a lot of +people seem to be), you can try it and give some feedback.

+

No SSL support is included yet, but this may be quite easy to add. By +the way, serious authentication methods will rely on a "real" HTTP +server, as soon as Radicale supports WSGI.

+
+
+

Journal Entries

+

Mehmet asked for the journal entries (aka. notes or memos) support, +that's done! This also was an occasion to clean some code in the iCal +parser, and to add a much better management of multi-lines entries. +People experiencing crazy X-RADICALE-NAME entries can now +clean their files, Radicale won't pollute them again.

+
+
+

New Roadmap

+

Except from htpasswd and LDAP, most of the authentication backends +(database, SASL, PAM, user groups) are not really easy to include in +Radicale. The easiest solution to solve this problem is to give Radicale +a CGI support, to put it behind a solid server such as Apache. Of +course, CGI is not enough: a WSGI support is quite better, with the +FastCGI, AJP and SCGI backends offered by flup. Quite exciting, isn't +it?

+

That's why it was important to add new versions on the roadmap. The +0.6 version is now waiting for the Apple iCal support, and of course for +some tests to kill the last remaining bugs. The only 0.7 feature will be +WSGI, allowing many new authentication methods and a real multithread +support.

+

After that, 0.8 may add CalDAV rights and filters, while 1.0 will +draw thousands of rainbows and pink unicorns (WebDAV sync, CardDAV, +Freebusy). A lot of funky work is waiting for you, hackers!

+
+
+

Bugs

+

Many bugs have also been fixed, most of them due to the owner-less +calendars support. Radicale 0.6 may be out in a few weeks, you should +spend some time testing the master branch and filling the bug +tracker.

+
+
+
+

April 10, 2011 - New Features

+

Radicale 0.5 was released only 8 days ago, but 3 new features have +already been added to the master branch:

+
    +
  • IPv6 support, with multiple addresses/ports support
    • +
  • Logs and debug mode
    • +
  • Owner-less calendars
    • +
+

Most of the code has been written by Necoro and Corentin, and that +was not easy at all: Radicale is now multithreaded! For sure, you can +find many bugs and report them on the bug tracker. +And if you're fond of logging, you can even add a default configuration +file and more debug messages in the source.

+
+
+

April 2, 2011 - Radicale 0.5 Released

+

Radicale 0.5 is out! Here is what's new:

+
+

0.5 - Historical Artifacts

+
    +
  • Calendar depth
    • +
  • iPhone support
    • +
  • MacOS and Windows support
    • +
  • HEAD requests management
    • +
  • htpasswd user from calendar path
    • +
+

iPhone support, but no iCal support for 0.5, despite our hard work, +sorry! After 1 month with no more activity on the dedicated bug, it was +time to forget it and hack on new awesome features. Thanks for your +help, dear Apple users, I keep the hope that one day, Radicale will work +with you!

+

So, what's next? As promised, some cool git branches will soon be +merged, with LDAP support, logging, IPv6 and anonymous calendars. Sounds +pretty cool, heh? Talking about new features, more and more people are +asking for a CardDAV support in Radicale. A git branch and a feature +request are open, feel free to hack and discuss.

+
+
+
+

February 3, 2011 - Jabber Room and iPhone Support

+

After a lot of help and testing work from Andrew, Björn, Anders, +Dorian and Pete (and other ones we could have forgotten), a simple +iPhone support has been added in the git repository. If you are +interested, you can test this feature right now by downloading the latest git version (a tarball +is even available too if you don't want or know how to use git).

+

No documentation has been written yet, but using the right URL in the +configuration should be enough to synchronize your calendars. If you +have any problems, you can ask by joining our new Jabber room: radicale@room.jabber.kozea.fr.

+

Radicale 0.5 will be released as soon as the iCal support is ready. +If you have an Apple computer, Python skills and some time to spend, +we'd be glad to help you debugging Radicale.

+
+
+

October 21, 2010 - News from Radicale

+

During the last weeks, Radicale has not been idle, even if no news +have been posted since August. Thanks to Pete, Pierre-Philipp and +Andrew, we're trying to add a better support on MacOS, Windows and +mobile devices like iPhone and Android-based phones.

+

All the tests on Windows have been successful: launching Radicale and +using Lightning as client works without any problems. On Android too, +some testers have reported clients working with Radicale. These were the +good news.

+

The bad news come from Apple: both iPhone and MacOS default clients +are not working yet, despite the latest enhancements given to the +PROPFIND requests. The problems are quite hard to debug due to our lack +of Apple hardware, but Pete is helping us in this difficult quest! +Radicale 0.5 will be out as soon as these two clients are working.

+

Some cool stuff is coming next, with calendar collections and groups, +and a simple web-based CalDAV client in early development. Stay +tuned!

+
+
+

August 8, 2010 - Radicale 0.4 Released

+

Radicale 0.4 is out! Here is what's new:

+
+

0.4 - Hot Days Back

+
    +
  • Personal calendars
    • +
  • HEAD requests
    • +
  • Last-Modified HTTP header
    • +
  • no-ssl and foreground options
    • +
  • Default configuration file
    • +
+

This release has mainly been released to help our dear packagers to +include a default configuration file and to write init scripts. Big +thanks to Necoro for his work on the new Gentoo ebuild!

+
+
+
+

July 4, 2010 - Three Features Added Last Week

+

Some features have been added in the git repository during the last +weeks, thanks to Jerome and Mariusz!

+

Personal Calendars Calendars accessed through the htpasswd ACL module +can now be personal. Thanks to the personal option, a user +called bob can access calendars at /bob/* but +not to the /alice/* ones.

+

HEAD Requests Radicale can now answer HEAD requests. HTTP headers can +be retrieved thanks to this request, without getting contents given by +the GET requests.

+

Last-Modified HTTP header The Last-Modified header gives the last +time when the calendar has been modified. This is used by some clients +to cache the calendars and not retrieving them if they have not been +modified.

+
+
+

June 14, 2010 - Radicale 0.3 Released

+

Radicale 0.3 is out! Here is what’s new:

+
+

0.3 - Dancing Flowers

+
    +
  • Evolution support
    • +
  • Version management
    • +
+

The website changed a little bit too, with some small HTML5 and CSS3 +features such as articles, sections, transitions, opacity, box shadows +and rounded corners. If you’re reading this website with Internet +Explorer, you should consider using a standard-compliant browser!

+

Radicale is now included in Squeeze, the testing branch of Debian. A +Radicale ebuild +for Gentoo has been proposed too. If you want to package Radicale +for another distribution, you’re welcome!

+

Next step is 0.5, with calendar collections, and Windows and MacOS +support.

+
+
+
+

May 31, 2010 - May News

+
+

News from contributors

+

Jonas Smedegaard packaged Radicale for Debian last week. Two +packages, called radicale for the daemon and +python-radicale for the module, have been added to Sid, the +unstable branch of Debian. Thank you, Jonas!

+

Sven Guckes corrected some of the strange-English-sentences present +on this website. Thank you, Sven!

+
+
+

News from software

+

A simple VERSION has been added in the library: you can +now play with radicale.VERSION and +$radicale --version.

+

After playing with the version (should not be too long), you may +notice that the next version is called 0.3, and not 0.5 as previously +decided. The 0.3 main goal is to offer the support for Evolution as soon +as possible, without waiting for the 0.5. After more than a month of +test, we corrected all the bugs we found and everything seems to be +fine; we can imagine that a brand new tarball will be released during +the first days of June.

+
+
+
+

April 19, 2010 - Evolution Supported

+

Radicale now supports another CalDAV client: Evolution, the default mail, +addressbook and calendaring client for Gnome. This feature was quite +easy to add, as it required less than 20 new lines of code in the +requests handler.

+

If you are interested, just clone the git +repository.

+
+
+

April 13, 2010 - Radicale 0.2 Released

+

Radicale 0.2 is out! Here is what’s new:

+
+

0.2 - Snowflakes

+
    +
  • Sunbird pre-1.0 support
    • +
  • SSL connection
    • +
  • Htpasswd authentication
    • +
  • Daemon mode
    • +
  • User configuration
    • +
  • Twisted dependency removed
    • +
  • Python 3 support
    • +
  • Real URLs for PUT and DELETE
    • +
  • Concurrent modification reported to users
    • +
  • Many bugs fixed by Roger Wenham
    • +
+

First of all, we would like to thank Roger Wenham for his bugfixes +and his supercool words.

+

You may have noticed that Sunbird 1.0 has not been released, but +according to the Mozilla developers, 1.0pre is something like a final +version.

+

You may have noticed too that Radicale can be downloaded from +PyPI. Of course, it is also available on the download page.

+
+
+
+

January 21, 2010 - HTTPS and Authentication

+

HTTPS connections and authentication have been added to Radicale this +week. Command-line options and personal configuration files are also +ready for test. According to the TODO file included in the package, the +next version will finally be 0.2, when sunbird 1.0 is out. Go, Mozilla +hackers, go!

+

HTTPS connection HTTPS connections are now available using the +standard TLS mechanisms. Give Radicale a private key and a certificate, +and your data are now safe.

+

Authentication A simple authentication architecture is now available, +allowing different methods thanks to different modules. The first two +modules are fake (no authentication) and +htpasswd (authentication with an htpasswd file +created by the Apache tool). More methods such as LDAP are coming +soon!

+
+
+

January 15, 2010 - Ready for Python 3

+

Dropping Twisted dependency was the first step leading to another big +feature: Radicale now works with Python 3! The code was given a small +cleanup, with some simplifications mainly about encoding. Before the +0.1.1 release, feel free to test the git repository, all Python versions +from 2.5 should be OK.

+
+
+

January 11, 2010 - Twisted no Longer Required

+

Good news! Radicale 0.1.1 will support Sunbird 1.0, but it has +another great feature: it has no external dependency! Twisted is no +longer required for the git version, removing about 50 lines of +code.

+
+
+

December 31, 2009 - Lightning and Sunbird 1.0b2pre Support

+

Lightning/Sunbird 1.0b2pre is out, adding minor changes in CalDAV +support. A new +commit makes Radicale work with versions 0.9, 1.0b1 et 1.0b2. +Moreover, etags are now quoted according to the RFC 2616.

+
+
+

December 9, 2009 - Thunderbird 3 released

+

Thunderbird +3 is out, and Lightning/Sunbird 1.0 should be released in a few +days. The last commit +in git should make Radicale work with versions 0.9 and 1.0b1pre. +Radicale 0.1.1 will soon be released adding support for version 1.0.

+
+
+

September 1, 2009 - Radicale 0.1 Released

+

First Radicale release! Here is the changelog:

+
+

0.1 - Crazy Vegetables

+
    +
  • First release
    • +
  • Lightning/Sunbird 0.9 compatibility
    • +
  • Easy installer
    • +
+

You can download this version on the download +page.

+
+
+
+

July 28, 2009 - Radicale on Gitorious

+

Radicale code has been released on Gitorious! Take a look at the Radicale main page on +Gitorious to view and download source code.

+
+
+

July 27, 2009 - Radicale Ready to Launch

+

The Radicale Project is launched. The code has been cleaned up and +will be available soon…

+
+
+
+
+ diff --git a/html/v3/about.html b/html/v3/about.html new file mode 100644 index 000000000..1f7ac75d2 --- /dev/null +++ b/html/v3/about.html @@ -0,0 +1,378 @@ + + + + + + + + + + + + + + +Radicale v3 Documentation + + + + + +
+
+

+Radicale + +v3 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + + + + +
+

About

+
+

Main Goals

+

Radicale is a complete calendar and contact storing and manipulating +solution. It can store multiple calendars and multiple address +books.

+

Calendar and contact manipulation is available from both local and +distant accesses, possibly limited through authentication policies.

+

It aims to be a lightweight solution, easy to use, easy to install, +easy to configure. As a consequence, it requires few software +dependencies and is preconfigured to work out-of-the-box.

+

Radicale is written in Python. It runs on most of the UNIX-like +platforms (Linux, *BSD, macOS) and Windows. It is free and open-source +software.

+
+
+

What Radicale Will Never Be

+

Radicale is a server, not a client. No interfaces will be created to +work with the server.

+

CalDAV and CardDAV are not perfect protocols. We think that their +main problem is their complexity, that is why we decided not to +implement the whole standard but just enough to understand some of its +client-side implementations.

+

CalDAV and CardDAV are the best open standards available, and they +are quite widely used by both clients and servers. We decided to use it, +and we will not use another one.

+
+
+

Technical Choices

+

Important global development choices have been decided before writing +code. They are very useful to understand why the Radicale Project is +different from other CalDAV and CardDAV servers, and why features are +included or not in the code.

+
+
Oriented to Calendar and Contact User Agents
+

Calendar and contact servers work with calendar and contact clients, +using a defined protocol. CalDAV and CardDAV are good protocols, +covering lots of features and use cases, but it is quite hard to +implement fully.

+

Some calendar servers have been created to follow the CalDAV and +CardDAV RFCs as much as possible: Davical, Baïkal and Darwin Calendar Server, for +example, are much more respectful of CalDAV and CardDAV and can be used +with many clients. They are very good choices if you want to develop and +test new CalDAV clients, or if you have a possibly heterogeneous list of +user agents.

+

Even if it tries it best to follow the RFCs, Radicale does not and +will not blindly implement the CalDAV and CardDAV +standards. It is mainly designed to support the CalDAV and CardDAV +implementations of different clients.

+
+
+
Simple
+

Radicale is designed to be simple to install, simple to configure, +simple to use.

+

The installation is very easy, particularly with Linux: one +dependency, no superuser rights needed, no configuration required, no +database. Installing and launching the main script out-of-the-box, as a +normal user, are often the only steps to have a simple remote calendar +and contact access.

+

Contrary to other servers that are often complicated, require high +privileges or need a strong configuration, the Radicale Server can +(sometimes, if not often) be launched in a couple of minutes, if you +follow the tutorial.

+
+
+
Lazy
+

The CalDAV RFC defines what must be done, what can be done and what +cannot be done. Many violations of the protocol are totally defined and +behaviors are given in such cases.

+

Radicale often assumes that the clients are perfect and that protocol +violations do not exist. That is why most of the errors in client +requests have undetermined consequences for the lazy server that can +reply good answers, bad answers, or even no answer.

+
+
+
+

History

+

Radicale has been started as a (free topic) stupid school project +replacing another (assigned topic) even more stupid school project.

+

At the beginning, it was just a proof-of-concept. The main goal was +to write a small, dirty and simple CalDAV server working with Lightning, +using no external libraries. That's how we created a piece of code +that's (quite) easy to understand, to use and to hack.

+

The first +lines have been added to the SVN (!) repository as I was drinking +(many) beers at the very end of 2008 (Python 2.6 and 3.0 were just +released). It's now packaged for a growing number of Linux +distributions.

+

And that was fun going from here to there thanks to you!

+
+
+
+
+ diff --git a/html/v3/contribute.html b/html/v3/contribute.html new file mode 100644 index 000000000..0697c8025 --- /dev/null +++ b/html/v3/contribute.html @@ -0,0 +1,303 @@ + + + + + + + + + + + + + + +Radicale v3 Documentation + + + + + +
+
+

+Radicale + +v3 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + + +
+

Contribute

+
+

Report Bugs

+

Found a bug? Want a new feature? Report a new issue on the Radicale +bug-tracker.

+
+
+

Hack

+

Interested in hacking? Feel free to clone the git repository on GitHub if +you want to add new features, fix bugs or update the documentation.

+
+
+

Documentation

+

To change or complement the documentation create a pull request to DOCUMENTATION.md.

+
+
+ + +
+
+ diff --git a/html/v3/documentation.html b/html/v3/documentation.html new file mode 100644 index 000000000..a08fade02 --- /dev/null +++ b/html/v3/documentation.html @@ -0,0 +1,1617 @@ + + + + + + + + + + + + + + +Radicale v3 Documentation + + + + + +
+
+

+Radicale + +v3 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + +
+

Documentation

+
+

Options

+
+

General Options

+
+
--version
+

Print version

+
+
+
--verify-storage
+

Verification of local collections storage

+
+
+
--verify-item
+

(>= 3.6.0)

+

Verification of a particular item file

+
+
+
--verify-sharing
+

(>= 3.7.0)

+

Verification of local sharing database

+
+
+
-C|--config
+

Load one or more specified config file(s)

+
+
+
-D|--debug
+

Turns log level to debug

+
+
+
+

Configuration Options

+

Each supported option from config file can be provided/overridden by +command line replacing _ with - and prepending +the section followed by a -, e.g.

+
[logging]
+backtrace_on_debug = False
+

can be enabled using --logging-backtrace-on-debug=true +on command line.

+
+
+
+

Configuration

+

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.

+

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 = 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 +with the --config /path/to/config command line argument or +the RADICALE_CONFIG environment variable. Multiple +configuration files can be separated by : (resp. +; on Windows). Paths that start with ? are +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 autodetect
+

Add the argument --config "" to stop Radicale from +loading the default configuration files. Run +python3 -m radicale --help for more information.

+

You can also use command-line options in startup scripts as shown in +the following examples:

+
## simple variable containing multiple options
+RADICALE_OPTIONS="--logging-level=debug --config=/etc/radicale/config --logging-request-header-on-debug --logging-rights-rule-doesnt-match-on-debug"
+/usr/bin/radicale $RADICALE_OPTIONS
+
+## variable as array method #1
+RADICALE_OPTIONS=("--logging-level=debug" "--config=/etc/radicale/config" "--logging-request-header-on-debug" "--logging-rights-rule-doesnt-match-on-debug")
+/usr/bin/radicale ${RADICALE_OPTIONS[@]}
+
+## variable as array method #2
+RADICALE_OPTIONS=()
+RADICALE_OPTIONS+=("--logging-level=debug")
+RADICALE_OPTIONS+=("--config=/etc/radicale/config")
+/usr/bin/radicale ${RADICALE_OPTIONS[@]}
+

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

+
+
+
delay_on_error
+

(>= 3.7.0)

+

Base delay in case of error 5xx response (seconds)

+

Default: 1

+
+
+
max_content_length
+

The maximum size of the request body. (bytes)

+

Default: 100000000 (100 Mbyte)

+

In case of using a reverse proxy in front of check also there related +option.

+
+
+
max_resource_size
+

(>= 3.5.10)

+

The maximum size of a resource. (bytes)

+

Default: 10000000 (10 Mbyte)

+

Limited to 80% of max_content_length to cover plain base64 encoded +payload.

+

Announced to clients requesting "max-resource-size" via PROPFIND.

+
+
+
timeout
+

Socket timeout. (seconds)

+

Default: 30

+
+
+
ssl
+

Enable transport layer encryption.

+

Default: False

+
+
+
certificate
+

Path of the SSL certificate.

+

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)

+
+
+
+

[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 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_remote_user (>= 3.5.9) Takes the +username from the Remote-User HTTP header HTTP_REMOTE_USER +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.

    • +

  • http_x_remote_user
    +Takes the username from the X-Remote-User HTTP header +HTTP_X_REMOTE_USER 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 file.

+

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. Also +consider version of passlib(libpass): bcrypt >= 5.0.0 requires +passlib(libpass) >= 1.9.3

    • +

  • 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 or missing login attempts or +denied access.

+

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_security
+

(>= 3.5.2)

+

Use encryption on the LDAP connection.

+

One of

+
    +
  • none
    • +
  • tls
    • +
  • starttls
    • +
+

Default: none

+
+
+
ldap_ssl_verify_mode
+

(>= 3.3.0)

+

Certificate verification mode for tls and starttls.

+

One of

+
    +
  • NONE
    • +
  • OPTIONAL
    • +
  • REQUIRED.
    • +
+

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 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 search 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:

+
    +
  • AF_UNIX
    • +
  • AF_INET
    • +
  • AF_INET6
    • +
+

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:

+
    +
  • tls
    • +
  • starttls
    • +
  • none
    • +
+

Default: tls

+
+
+
oauth2_token_endpoint
+

(>= 3.5.0)

+

Endpoint URL for the OAuth2 token

+

Default: (unset)

+
+
+
oauth2_client_id
+

(>= 3.7.0)

+

Client ID used to request the Auth2 token

+

Default: radicale

+
+
+
oauth2_client_secret
+

(>= 3.7.0)

+

Client secret used to request the Auth2 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

+
+
+
+

[rights]

+
+
type
+

Authorization backend that is used to check the access rights to +collections.

+

The default and recommended backend is owner_only. If +access to calendars and address books outside the user's collection +directory (that's /username/) is granted, clients will not +detect these collections automatically and will not show them to the +users. Choosing any other authorization backend is only useful if you +access calendars and address books directly via URL.

+

Available backends are:

+
    +

  • 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
+

Name of the file containing the authorization rules for the +from_file backend. See the Rights section for details.

+

Default: /etc/radicale/rights

+
+
+
permit_delete_collection
+

(>= 3.1.9)

+

Global permission to delete complete collections.

+
    +
  • If False it can be explicitly granted per collection by +rights permissions: D
    • +
  • If True it can be explicitly forbidden per collection +by rights permissions: d
    • +
+

Default: True

+
+
+
permit_overwrite_collection
+

(>= 3.3.0)

+

Global permission to overwrite complete collections.

+
    +
  • If False it can be explicitly granted per collection by +rights permissions: O
    • +
  • If True it can be explicitly forbidden per collection +by rights permissions: o
    • +
+

Default: True

+
+
+
+

[storage]

+
+
type
+

Backend used to store data.

+

Available backends are:

+
    +

  • multifilesystem
    +Stores the data in the filesystem.

    • +

  • multifilesystem_nolock
    +The multifilesystem backend without file-based locking. +Must only be used with a single process.

    • +
+

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

+
+
+
strict_preconditions
+

(>= 3.5.8)

+

Strict preconditions check on PUT in case item already exists RFC6352#9.2

+

Default: False

+
+
+
hook
+

Command that is run after changes to storage. See 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)

+
+
+
+

[web]

+
+
type
+

The backend that provides the web interface of Radicale.

+

Available backends are:

+
    +

  • none
    +Simply shows the message "Radicale works!".

    • +

  • internal
    +Allows creation and management of address books and calendars.

    • +
+

Default: internal

+
+
+
+

[logging]

+
+
level
+

Set the logging level.

+

Available levels are:

+
    +
  • trace (>= 3.7.1)
    • +
  • debug
    • +
  • info
    • +
  • notice (>= 3.7.1)
    • +
  • warning
    • +
  • error
    • +
  • critical
    • +
  • alert (>= 3.7.1)
    • +
+

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

+
+
+
limit_content
+

(>= 3.7.0)

+

Limit content of wrapped text (chars)

+

Default: 3000

+
+
+
trace_on_debug
+

(> 3.5.4) && (< 3.7.1)

+

Do not filter debug messages starting with 'TRACE'

+

Default: False

+
+
+
trace_filter
+

(> 3.5.4) && (< 3.7.1)

+

Filter debug messages starting with 'TRACE/'

+

Prerequisite: trace_on_debug = True

+

(>= 3.7.1)

+

Filter trace messages starting with ''

+

Prerequisite: level = trace

+

Default: (empty)

+
+
+
mask_passwords
+

Do not include passwords in logs.

+

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 header on level = debug

+

Default: False

+
+
+
request_content_on_debug
+

(>= 3.2.2)

+

Log request content (body) on level = debug

+

Default: False

+
+
+
response_header_on_debug
+

(>= 3.5.10)

+

Log response header on level = debug

+

Default: False

+
+
+
response_content_on_debug
+

(>= 3.2.2)

+

Log response content (body) on level = debug

+

Default: False

+
+
+
rights_rule_doesnt_match_on_debug
+

(>= 3.2.3)

+

Log rights rule which doesn't match on level = debug

+

Default: False

+
+
+
storage_cache_actions_on_debug
+

(>= 3.3.2)

+

Log storage cache actions on level = debug

+

Default: False

+
+
+
profiling_per_request
+

(>= 3.5.10)

+

Log profiling data on level=info

+

Default: none

+

One of

+
    +
  • none (disabled)
    • +
  • per_request (above minimum duration)
    • +
  • per_request_method (regular interval)
    • +
+
+
+
profiling_per_request_min_duration
+

(>= 3.5.10)

+

Log profiling data per request minimum duration (seconds) before +logging, otherwise skip

+

Default: 3

+
+
+
profiling_per_request_header
+

(>= 3.5.10)

+

Log profiling request header (if passing minimum duration)

+

Default: False

+
+
+
profiling_per_request_xml
+

(>= 3.5.10)

+

Log profiling request XML (if passing minimum duration)

+

Default: False

+
+
+
profiling_per_request_method_interval
+

(>= 3.5.10)

+

Log profiling data per method interval (seconds) Triggered by +request, not active on idle systems

+

Default: 600

+
+
+
profiling_top_x_functions
+

(>= 3.5.10)

+

Log profiling top X functions (limit)

+

Default: 10

+
+
+
+

[headers]

+

This section can be used to specify additional HTTP headers that will +be sent to clients.

+

An example to relax the same-origin policy:

+
Access-Control-Allow-Origin = *
+

An example to set CSP to disallow execution of unknown +javascript:

+
Content-Security-Policy = default-src 'self'; object-src 'none'
+
+
+

[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:

+
    +
  • none
    • +
  • tls
    • +
  • starttls
    • +
+

Default: none

+
+
+
smtp_ssl_verify_mode
+

(>= 3.5.5)

+

The certificate verification mode for tls and starttls.

+

One of:

+
    +
  • NONE
    • +
  • OPTIONAL
    • +
  • REQUIRED
    • +
+

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.
+
+
+
+

[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 +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

+
+
+
+

[sharing]

+

(>= 3.7.0)

+

See also Collection +Sharing.

+
+
type
+

(>= 3.7.0)

+

Sharing database type

+

One of:

+
    +
  • none
    • +
  • csv
    • +
  • files
    • +
+

Default: none (implicit disabling the feature)

+
+
+
database_path
+

(>= 3.7.0)

+

Sharing database path

+

Default:

+
    +
  • type csv: +(filesystem_folder)/collection-db/sharing.csv
    • +
  • type files: +(filesystem_folder)/collection-db/files
    • +
+
+
+
collection_by_token
+

(>= 3.7.0)

+

Share collection by token

+

Default: false

+
+
+
collection_by_map
+

(>= 3.7.0)

+

Share collection by map

+

Default: false

+
+
+
permit_create_token
+

(>= 3.7.0)

+

Permit create of token-based sharing

+

Default: false

+
    +
  • If False it can be explicitly granted by +rights permissions: T
    • +
  • If True it can be explicitly forbidden by +rights permissions: t
    • +
+
+
+
permit_create_map
+

(>= 3.7.0)

+

Permit create of map-based sharing

+

Default: false

+
    +
  • If False it can be explicitly granted by +rights permissions: M
    • +
  • If True it can be explicitly forbidden by +rights permissions: m
    • +
+
+
+
permit_properties_overlay
+

(>= 3.7.0)

+

Permit (limited) properties overlay by user of shared collection

+

Default: false

+
    +
  • If False it can be explicitly granted by share +permissions: P
    • +
  • If True it can be explicitly forbidden by +share permissions: p
    • +
+
+
+
enforce_properties_overlay
+

(>= 3.7.0)

+

Enforce properties overlay even on write access

+

Default: true

+
    +
  • If False it can be explicitly enforced by +share permissions: E
    • +
  • If True it can be explicitly forbidden by +share permissions: e
    • +
+
+
+
default_permissions_create_token
+

Default permissions for create token-based sharing

+

Default: r

+

Supported: rwEePp

+
+
+
default_permissions_create_map
+

Default permissions for map-based sharing

+

Default: r

+

Supported: rwEePp

+
+
+
+
+ + + + +
+
+ diff --git a/html/v3/download.html b/html/v3/download.html new file mode 100644 index 000000000..4236fd3c9 --- /dev/null +++ b/html/v3/download.html @@ -0,0 +1,399 @@ + + + + + + + + + + + + + + +Radicale v3 Documentation + + + + + +
+
+

+Radicale + +v3 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + + + +
+

Download

+
+

PyPI

+

Radicale is available on PyPI. To +install, just type as superuser:

+
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
+

You can also download the content of the repository as an archive.

+
+
+

Source Packages

+

You can find the source packages of all releases on GitHub.

+
+
+

Docker

+

Radicale is available as a Docker image for platforms +linux/amd64 and linux/arm64 on:

+ +

Here are the steps to install Radicale via Docker Compose:

+
    +

  1. Create required directories

    +

    Create a directory to store the data, configuration and compose +file.

    +

    For example, assuming ./radicale:

    +
    $ mkdir radicale
+$ cd radicale
    +

    Create directories to store data and configuration.

    +

    For example, assuming data directory as ./data and +configuration directory as ./config:

    +
    $ mkdir config data
    2. +

  2. Download the compose file

    +
    $ wget https://raw.githubusercontent.com/Kozea/Radicale/refs/heads/master/compose.yaml
    +

    The compose file assumes ./config and +./data directories. Review the file and modify as +needed.

    3. +

  3. Create Radicale configuration file as necessary

    +

    Create a new configuration file or place an existing one in the +./config directory.

    +

    Note: This section demonstrates only basic steps to +setup Radicale using docker compose. For details on +configuring Radicale, including authentication, please refer to the +documentation for Basic Configuration +or detailed Configuration

    4. +

  4. Start Radicale

    +
    $ docker compose up -d
    +

    This will start the Radicale container in detached mode.

    +

    To view the logs of the running container, run:

    +
    $ docker compose logs -f
    +

    To stop the container, run this from the current directory:

    +
    $ docker compose down
    5. +
+
+
Available tags
+
    +
  • stable: Points to the latest stable release. This is +recommended for most users.
    • +
  • Major.Minor.Patch (e.g. 3.6.1): Points to a specific +release version.
    • +
  • Major.Minor (e.g. 3.6): Tracks the latest release for a +minor version.
    • +
  • Major (e.g. 3): Tracks the latest release for a major +version.
    • +
  • nightly tags (e.g. nightly-20260206): Nightly +builds.
    • +
  • latest: Points to the most recent build. In most cases, +this is nightly.
    • +
+
+
+
+

Linux Distribution Packages

+

Radicale has been packaged for:

+ +

Radicale is also available +on Cloudron.

+

If you are interested in creating packages for other Linux +distributions, read the "Contribute" +section.

+
+
+ +
+
+ diff --git a/html/v3/index.html b/html/v3/index.html new file mode 100644 index 000000000..e741286eb --- /dev/null +++ b/html/v3/index.html @@ -0,0 +1,332 @@ + + + + + + + + + + + + + + +Radicale v3 Documentation + + + + + +
+
+

+Radicale + +v3 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+
+

Translations of this page

+ +
+
+

Getting started

+
+

About Radicale

+

Radicale is a small but powerful CalDAV (calendars, to-do lists) and +CardDAV (contacts) server, that:

+
    +
  • Shares calendars and contact lists through CalDAV, CardDAV and +HTTP.
    • +
  • Supports events, todos, journal entries and business cards.
    • +
  • Works out-of-the-box, no complicated setup or configuration +required.
    • +
  • Offers flexible authentication options.
    • +
  • Can limit access by authorization.
    • +
  • Can secure connections with TLS.
    • +
  • Works with many CalDAV and CardDAV +clients.
    • +
  • Stores all data on the file system in a simple folder +structure.
    • +
  • Can be extended with plugins.
    • +
  • Is GPLv3-licensed free software.
    • +
+
+
+

Installation

+

Check

+ +
+
+

What's New?

+
+
+ + + + + + +
+
+ diff --git a/html/v3/supported-clients.html b/html/v3/supported-clients.html new file mode 100644 index 000000000..6400bc063 --- /dev/null +++ b/html/v3/supported-clients.html @@ -0,0 +1,813 @@ + + + + + + + + + + + + + + +Radicale v3 Documentation + + + + + +
+
+

+Radicale + +v3 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + + + +
+

Supported Clients

+

Radicale has been tested with:

+ +

Many clients do not support the creation of new calendars and address +books. You can use Radicale's web interface (e.g. http://localhost:5232) to create and +manage address books and calendars.

+

In some clients, it is sufficient to simply enter the URL of the +Radicale server (e.g. http://localhost:5232) and your +username. In others, you have to enter the URL of the collection +directly (e.g. http://localhost:5232/user/calendar).

+

Some clients (notably macOS's Calendar.app) may silently refuse to +include account credentials over unsecured HTTP, leading to unexpected +authentication failures. In these cases, you want to make sure the +Radicale server is accessible over HTTPS.

+
+

DAVx⁵

+

Enter the URL of the Radicale server (e.g. +http://localhost:5232) and your username. DAVx⁵ will show +all existing calendars and address books and you can create new +ones.

+
+
+

OneCalendar

+

When adding account, select CalDAV account type, then enter username, +password and the Radicale server (e.g. +https://yourdomain:5232). OneCalendar will show all +existing calendars and (FIXME: address books), you need to select which +ones you want to see. OneCalendar supports many other server types +too.

+
+
+

GNOME Calendar, Contacts

+

GNOME 46 added CalDAV and CardDAV support to GNOME Online +Accounts.

+

Open GNOME Settings, navigate to Online Accounts > +Connect an Account > Calendar, Contacts and Files. +Enter the URL (e.g. https://example.com/radicale) and your +credentials then click Sign In. In the pop-up dialog, turn off +Files. After adding Radicale in GNOME Online Accounts, +it should be available in GNOME Contacts and GNOME Calendar.

+
+
+

Evolution

+

In Evolution add a new calendar and address book +respectively with WebDAV. Enter the URL of the Radicale server (e.g. +http://localhost:5232) and your username. Clicking on the +search button will list the existing calendars and address books.

+

Adding CalDAV and CardDAV accounts in Evolution will automatically +make them available in GNOME Contacts and GNOME Calendar.

+
+
+

KDE PIM Applications

+

In Kontact add a DAV Groupware resource to +Akonadi under Settings > Configure Kontact > Calendar > +General > Calendars, select the protocol (CalDAV or CardDAV), +add the URL to the Radicale collections and enter the credentials. After +synchronization of the calendar resp. addressbook items, you can manage +them in Kontact.

+
+
+

Thunderbird

+

Add a new calendar on the network. Enter your username and the URL of +the Radicale server (e.g. http://localhost:5232). After +asking for your password, it will list the existing calendars.

+
+
Address books with CardBook add-on
+

Add a new address book on the network with CardDAV. Enter the URL of +the Radicale server (e.g. http://localhost:5232) and your +username and password. It will list your existing address books.

+
+
+
+

InfCloud, CalDavZAP and CardDavMATE

+

You can integrate InfCloud into Radicale's web interface with by +simply downloading the latest package from InfCloud +and extract the content into a folder named 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

+

This is not the recommended way of creating and managing your +calendars and address books. Use Radicale's web interface or a client +with support for it (e.g. DAVx⁵).

+

To create a new calendar run something like:

+
$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \
+'<?xml version="1.0" encoding="UTF-8" ?>
+<create xmlns="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:I="http://apple.com/ns/ical/">
+  <set>
+    <prop>
+      <resourcetype>
+        <collection />
+        <C:calendar />
+      </resourcetype>
+      <C:supported-calendar-component-set>
+        <C:comp name="VEVENT" />
+        <C:comp name="VJOURNAL" />
+        <C:comp name="VTODO" />
+      </C:supported-calendar-component-set>
+      <displayname>Calendar</displayname>
+      <C:calendar-description>Example calendar</C:calendar-description>
+      <I:calendar-color>#ff0000ff</I:calendar-color>
+    </prop>
+  </set>
+</create>'
+

To create a new address book run something like:

+
$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \
+'<?xml version="1.0" encoding="UTF-8" ?>
+<create xmlns="DAV:" xmlns:CR="urn:ietf:params:xml:ns:carddav">
+  <set>
+    <prop>
+      <resourcetype>
+        <collection />
+        <CR:addressbook />
+      </resourcetype>
+      <displayname>Address book</displayname>
+      <CR:addressbook-description>Example address book</CR:addressbook-description>
+    </prop>
+  </set>
+</create>'
+

The collection /USERNAME will be created automatically, +when the user authenticates to Radicale for the first time. Clients with +automatic discovery of collections will only show calendars and address +books that are direct children of the path /USERNAME/.

+

Delete the collections by running something like:

+
curl -u user -X DELETE 'http://localhost:5232/user/calendar'
+

Note: requires config/option +permit_delete_collection = True

+
+
+

Authorization and Rights

+

This section describes the format of the rights file for the +from_file authentication backend. The configuration option +file in the rights section must point to the +rights file.

+

The recommended rights method is owner_only. If access +is granted to calendars and address books outside the home directory of +users (that's /USERNAME/), clients will not detect these +collections automatically, and will not show them to the users. 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
+

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 +collection. Permissions from the first matching section are used. If no +section matches, access gets denied.

+

The username is empty for anonymous users. Therefore, the regex +.+ only matches authenticated users and .* +matches everyone (including anonymous users).

+

The path of the collection is separated by / and has no +leading or trailing /. Therefore, the path of the root +collection is empty.

+

In the collection regex you can use {user} +and get groups from the user regex with {0}, +{1}, etc.

+

In consequence of the parameter substitution you have to write +{{ and }} if you want to use regular curly +braces in the user and collection regexes.

+

The following permissions are recognized:

+
    +
  • R: read collections (excluding address books and +calendars)
    • +
  • r: read address book and calendar collections
    • +
  • i: subset of r that only allows +direct access via HTTP method GET (CalDAV/CardDAV is susceptible to +expensive search requests)
    • +
  • W: write collections (excluding address books and +calendars)
    • +
  • w: write address book and calendar collections
    • +
  • D: allow deleting a collection in case +permit_delete_collection=False (>= 3.3.0)
    • +
  • d: deny deleting a collection in case +permit_delete_collection=True (>= 3.3.0)
    • +
  • O: allow overwriting a collection in case +permit_overwrite_collection=False (>= +3.3.0)
    • +
  • o: deny overwriting a collection in case +permit_overwrite_collection=True (>= +3.3.0)
    • +
  • T: permit create of token-based sharing of +collection in case permit_create_token=False (>= +3.7.0)
    • +
  • t: deny create of token-based sharing of collection +in case permit_create_token=True (>= +3.7.0)
    • +
  • M: permit create of map-based sharing of collection +in case permit_create_map= False (>= +3.7.0)
    • +
  • m: deny create of map-based sharing of collection +in case permit_create_map=True (>= 3.7.0)
    • +
+
+
+

Storage

+

This document describes the layout and format of the file system +storage, the multifilesystem backend.

+

It is safe to access and manipulate the data by hand or with scripts. +Scripts can be invoked manually, periodically (e.g. using cron) +or after each change to the storage with the configuration option +hook in the storage section (e.g. Versioning collections with +Git).

+
+

Layout

+

The file system comprises the following files and folders:

+
    +
  • .Radicale.lock: The lock file for locking the +storage.
    • +
  • collection-root: This folder contains all collections +and items.
    • +
+

Each collection is represented by a folder. This folder may contain +the file .Radicale.props with all WebDAV properties of the +collection encoded as JSON.

+

Each item in a calendar or address book collection is represented by +a file containing the item's iCalendar resp. vCard data.

+

All files and folders, whose names start with a dot but not with +.Radicale. (internal files) are ignored.

+

Syntax errors in any of the files will cause all requests accessing +the faulty data to fail. The logging output should contain the names of +the culprits.

+

Caches and sync-tokens are stored in the .Radicale.cache +folder inside of collections. This folder may be created or modified, +while the storage is locked for shared access. In theory, it should be +safe to delete the folder. Caches will be recreated automatically and +clients will be told that their sync-token is not valid anymore.

+

You may encounter files or folders that start with +.Radicale.tmp-. Radicale uses them for atomic creation and +deletion of files and folders. They should be deleted after requests are +finished but it is possible that they are left behind when Radicale or +the computer crashes. You can safely delete them.

+
+
+

Locking

+

When the data is accessed by hand or by an externally invoked script, +the storage must be locked. The storage can be locked for exclusive or +shared access. It prevents Radicale from reading or writing the file +system. The storage is locked with exclusive access while the +hook runs.

+
+
Linux shell scripts
+

Use the flock +utility to acquire exclusive or shared locks for the commands you want +to run on Radicale's data.

+
# Exclusive lock for COMMAND
+$ flock --exclusive /path/to/storage/.Radicale.lock COMMAND
+# Shared lock for COMMAND
+$ flock --shared /path/to/storage/.Radicale.lock COMMAND
+
+
+
Linux and MacOS
+

Use the flock +syscall. Python provides it in the fcntl +module.

+
+
+
Windows
+

Use LockFile +for exclusive access or LockFileEx +which also supports shared access. Setting +nNumberOfBytesToLockLow to 1 and +nNumberOfBytesToLockHigh to 0 works.

+
+
+
+

Manually creating collections

+

To create a new collection, you need to create the corresponding +folder in the file system storage (e.g. +collection-root/user/calendar). To indicate to Radicale and +clients that the collection is a calendar, you have to create the file +.Radicale.props with the following content in the +folder:

+
{"tag": "VCALENDAR"}
+

The calendar is now available at the URL path (e.g. +/user/calendar). For address books +.Radicale.props must contain:

+
{"tag": "VADDRESSBOOK"}
+

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 +/USERNAME/.

+

Delete collections by deleting the corresponding folders.

+
+
+
+

Logging overview

+

Radicale logs to stderr. The verbosity of the log output +can be controlled with --debug command line argument or the +level configuration option in the logging section.

+
+
+

Architecture

+

Radicale is a small piece of software, but understanding it is not as +easy as it seems. But don't worry, reading this short section is enough +to understand what a CalDAV/CardDAV server is, and how Radicale's code +is organized.

+
+

Protocol overview

+

Here is a simple overview of the global architecture for reaching a +calendar or an address book through network:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PartLayerProtocol or Format
ServerCalendar/Contact StorageiCal/vCard
''Calendar/Contact ServerCalDAV/CardDAV Server
TransferNetworkCalDAV/CardDAV (HTTP + TLS)
ClientCalendar/Contact ClientCalDAV/CardDAV Client
''GUITerminal, GTK, Web interface, etc.
+

Radicale is only the server part of this +architecture.

+

Please note:

+
    +
  • CalDAV and CardDAV are extension protocols of WebDAV,
    • +
  • WebDAV is an extension of the HTTP protocol.
    • +
+

Radicale being a CalDAV/CardDAV server, can also be seen as a special +WebDAV and HTTP server.

+

Radicale is not the client part of this +architecture. It means that Radicale never draws calendars, address +books, events and contacts on the screen. It only stores them and give +the possibility to share them online with other people.

+

If you want to see or edit your events and your contacts, you have to +use another software called a client, that can be a "normal" +applications with icons and buttons, a terminal or another web +application.

+
+
+

Code Architecture

+

The radicale package offers the following modules.

+
    +

  • __init__ : Contains the entry point for +WSGI.

    • +

  • __main__ : Provides the entry point for the +radicale executable and includes the command line parser. +It loads configuration files from the default (or specified) paths and +starts the internal server.

    • +

  • app : This is the core part of Radicale, with the +code for the CalDAV/CardDAV server. The code managing the different HTTP +requests according to the CalDAV/CardDAV specification can be found +here.

    • +

  • auth : Used for authenticating users based on +username and password, mapping usernames to internal users and +optionally retrieving credentials from the environment.

    • +

  • config : Contains the code for managing +configuration and loading settings from files.

    • +

  • ìtem : Internal representation of address book and +calendar entries. Based on VObject.

    • +

  • log : The logger for Radicale based on the default +Python logging module.

    • +

  • rights : This module is used by Radicale to manage +access rights to collections, address books and calendars.

    • +

  • server : The integrated HTTP server for standalone +use.

    • +

  • storage : This module contains the classes +representing collections in Radicale and the code for storing and +loading them in the filesystem.

    • +

  • web : This module contains the web +interface.

    • +

  • utils : Contains general helper functions.

    • +

  • httputils : Contains helper functions for working +with HTTP.

    • +

  • pathutils : Helper functions for working with paths +and the filesystem.

    • +

  • xmlutils : Helper functions for working with the XML +part of CalDAV/CardDAV requests and responses. It's based on the +ElementTree XML API.

    • +
+
+
+
+

Plugins

+

Radicale can be extended by plugins for authentication, rights +management and storage. Plugins are python modules.

+
+

Getting started with plugin development

+

To get started we walk through the creation of a simple +authentication plugin, that accepts login attempts with a static +password.

+

The easiest way to develop and install python +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"])
+

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

Install the python module by running the following command in the +same folder as setup.py:

+
python3 -m pip install .
+

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
+

You can uninstall the module with:

+
python3 -m pip uninstall radicale_static_password_auth
+
+
+

Authentication plugins

+

This plugin type is used to check login credentials. The module must +contain a class Auth that extends +radicale.auth.BaseAuth. Take a look at the file +radicale/auth/__init__.py in Radicale's source code for +more information.

+
+
+

Rights management plugins

+

This plugin type is used to check if a user has access to a path. The +module must contain a class Rights that extends +radicale.rights.BaseRights. Take a look at the file +radicale/rights/__init__.py in Radicale's source code for +more information.

+
+
+

Web plugins

+

This plugin type is used to provide the web interface for Radicale. +The module must contain a class Web that extends +radicale.web.BaseWeb. Take a look at the file +radicale/web/__init__.py in Radicale's source code for more +information.

+
+
+

Storage plugins

+

This plugin is used to store collections and items. The module must +contain a class Storage that extends +radicale.storage.BaseStorage. Take a look at the file +radicale/storage/__init__.py in Radicale's source code for +more information.

+
+
+
+ + + +
+
+ diff --git a/html/v3/tutorials.html b/html/v3/tutorials.html new file mode 100644 index 000000000..d973d1ef5 --- /dev/null +++ b/html/v3/tutorials.html @@ -0,0 +1,833 @@ + + + + + + + + + + + + + + +Radicale v3 Documentation + + + + + +
+
+

+Radicale + +v3 + + +

+

Free and Open-Source CalDAV and CardDAV Server

+
+
+ +
+
+
+ + +
+ + +
+

Tutorials

+
+

Simple 5-minute setup

+

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!

+

The server, configured with settings from this section, only binds to +localhost (i.e. it is not reachable over the network), and you can log +in with any username 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 and desired authentication type.

+

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

+
+

Linux / *BSD

+

Hint: instead of downloading from PyPI, look for packages provided by +your distribution. They +contain also startup scripts integrated into your distributions, that +allow Radicale to run daemonized.

+

First, make sure that python 3.9 or later and +pip are installed. On most distributions it should be +enough to install the package python3-pip.

+
+
as normal user
+

Recommended only for testing - open a console and type:

+
# Run the following command to only install for the current user
+python3 -m pip install --user --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
+

If install is not working and instead +error: externally-managed-environment is displayed, create +and activate a virtual environment in advance.

+
python3 -m venv ~/venv
+source ~/venv/bin/activate
+

and try to install with

+
python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
+

Start the service manually, data is stored only for the current +user

+
# Start, data is stored for the current user only
+python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections --auth-type none
+
+
+
as system user (or as root)
+

Alternatively, you can install and run as system user or as root (not +recommended):

+
# Run the following command as root (not recommended) or non-root system user
+# (the later may require --user in case dependencies are not available system-wide and/or virtual environment)
+python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
+

Start the service manually, with data stored in a system folder under +/var/lib/radicale/collections:

+
# Start, data is stored in a system folder (requires write permissions to /var/lib/radicale/collections)
+python3 -m radicale --storage-filesystem-folder=/var/lib/radicale/collections --auth-type none
+
+
+
+

Windows

+

The first step is to install Python. Go to python.org and download the latest version +of Python 3. Then run the installer. On the first window of the +installer, check the "Add Python to PATH" box and click on "Install +now". Wait a couple of minutes, it's done!

+

Launch a command prompt and type:

+
python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
+python -m radicale --storage-filesystem-folder=~/radicale/collections --auth-type none
+
+
Common
+

Success!!! Open http://localhost:5232 in your browser! +You can log in with any username and password as no authentication is +required by example option --auth-type none. This is +INSECURE, see Configuration/Authentication for more details.

+

Just note that default configuration for security reason binds the +server to localhost (IPv4: 127.0.0.1, IPv6: +::1). See Addresses and Configuration/Server for more details.

+
+
+
+
+

Basic Configuration

+

Installation instructions can be found in the simple 5-minute setup tutorial.

+

Radicale tries to load configuration files from +/etc/radicale/config and +~/.config/radicale/config. Custom paths can be specified +with the --config /path/to/config command line argument or +the RADICALE_CONFIG environment variable. Multiple +configuration files can be separated by : (resp. +; on Windows). Paths that start with ? are +optional.

+

You should create a new configuration file at the desired location. +(If the use of a configuration file is inconvenient, all options can be +passed via command line arguments.)

+

All configuration options are described in detail in the Configuration section.

+
+

Authentication

+

In its default configuration since version 3.5.0, Radicale rejects +all authentication attempts by using config option +type = denyall (introduced with 3.2.2) as default until +explicitly configured.

+

Versions before 3.5.0 did not check usernames or passwords at all, +unless explicitly configured. If such a server is reachable over a +network, you should change this as soon as possible.

+

First a users file with all usernames and passwords must +be created. It can be stored in the same directory as the configuration +file.

+
+
The secure way
+

The users file can be created and managed with htpasswd:

+

Note: some OSes or distributions contain outdated versions of +htpasswd (< 2.4.59) without support for SHA-256 or +SHA-512 (e.g. Ubuntu LTS 22). In these cases, use +htpasswd's command line option -B for the +bcrypt hash method (recommended), or stay with the insecure +(not recommended) MD5 (default) or SHA-1 (command line option +-s).

+

Note: support of SHA-256 and 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:
+Re-type new password:
+# Add another user
+$ htpasswd -5 /path/to/users user2
+New password:
+Re-type new password:
+

Authentication can be enabled with the following configuration:

+
[auth]
+type = htpasswd
+htpasswd_filename = /path/to/users
+htpasswd_encryption = autodetect
+
+
+
The simple but insecure way
+

Create the users file by hand with lines containing the +username and password separated by :. Example:

+
user1:password1
+user2:password2
+

Authentication can be enabled with the following configuration:

+
[auth]
+type = htpasswd
+htpasswd_filename = /path/to/users
+# encryption method used in the htpasswd file
+htpasswd_encryption = plain
+
+
+
+

Addresses

+

The default configuration binds the server to localhost. It cannot be +reached from other computers. This can be changed with the following +configuration options (IPv4 and IPv6):

+
[server]
+hosts = 0.0.0.0:5232, [::]:5232
+
+
+

Storage

+

Data is stored in the folder +/var/lib/radicale/collections. The path can be changed with +the following configuration:

+
[storage]
+filesystem_folder = /path/to/storage
+
+

Security: The storage folder shall not be readable +by unauthorized users. Otherwise, they can read the calendar data and +lock the storage. You can find OS dependent instructions in the Running as a service section.

+
+
+
+

Limits

+

Radicale enforces limits on the maximum number of parallel +connections, the maximum file size (important for contacts with big +photos) and the rate of incorrect authentication attempts. Connections +are terminated after a timeout. The default values should be fine for +most scenarios.

+
[server]
+max_connections = 20
+# 100 Megabyte
+max_content_length = 100000000
+# 10 Megabyte (>= 3.5.10)
+max_resource_size = 10000000
+# 30 seconds
+timeout = 30
+
+[auth]
+# Average delay after failed login attempts in seconds
+# Also used for invalid/not-existing/not-enabled share-by-token (>= 3.7.0)
+delay = 1
+
+
+
+

Running as a service

+

The method to run Radicale as a service depends on your host +operating system. Follow one of the chapters below depending on your +operating system and requirements.

+
+

Linux with systemd system-wide

+

Recommendation: check support by Linux Distribution Packages +instead of manual setup / initial configuration.

+

Create the radicale user and group for the Radicale +service by running (as root):

+
useradd --system --user-group --home-dir / --shell /sbin/nologin radicale
+

The storage folder must be made writable by the +radicale user by running (as root):

+
mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections
+

If a dedicated cache folder is configured (see option filesystem_cache_folder), it also +must be made writable by radicale. To achieve that, run +(as root):

+
mkdir -p /var/cache/radicale && chown -R radicale:radicale /var/cache/radicale
+
+

Security: The storage shall not be readable by +others. To make sure this is the case, run (as root):

+
chmod -R o= /var/lib/radicale/collections
+
+

Create the file +/etc/systemd/system/radicale.service:

+
[Unit]
+Description=A simple CalDAV (calendar) and CardDAV (contact) server
+After=network.target
+Requires=network.target
+
+[Service]
+ExecStart=/usr/bin/env python3 -m radicale
+Restart=on-failure
+User=radicale
+# Deny other users access to the calendar data
+UMask=0027
+# Optional security settings
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateDevices=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+NoNewPrivileges=true
+ReadWritePaths=/var/lib/radicale/
+# Replace with following in case dedicated cache folder should be used
+#ReadWritePaths=/var/lib/radicale/ /var/cache/radicale/
+
+[Install]
+WantedBy=multi-user.target
+

In this system-wide implementation, Radicale will load the +configuration from the file /etc/radicale/config.

+

To enable and manage the service run:

+
# Enable the service
+$ systemctl enable radicale
+# Start the service
+$ systemctl start radicale
+# Check the status of the service
+$ systemctl status radicale
+# View all log messages
+$ journalctl --unit radicale.service
+
+
+

Linux with systemd as a user

+

Create the file +~/.config/systemd/user/radicale.service:

+
[Unit]
+Description=A simple CalDAV (calendar) and CardDAV (contact) server
+
+[Service]
+ExecStart=/usr/bin/env python3 -m radicale
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+

In this user-specific configuration, Radicale will load the +configuration from the file ~/.config/radicale/config. You +should set the configuration option filesystem_folder in +the storage section to something like +~/.var/lib/radicale/collections.

+

To enable and manage the service run:

+
# Enable the service
+$ systemctl --user enable radicale
+# Start the service
+$ systemctl --user start radicale
+# Check the status of the service
+$ systemctl --user status radicale
+# View all log messages
+$ journalctl --user --unit radicale.service
+
+
+

Windows with "NSSM - the Non-Sucking Service Manager"

+

First install NSSM and start +nssm install in a command prompt. Apply the following +configuration:

+
    +
  • Service name: Radicale
    • +
  • Application +
      +
    • Path: C:\Path\To\Python\python.exe
      • +
    • Arguments: --config C:\Path\To\Config
      • +
    • +
  • I/O redirection +
      +
    • Error: C:\Path\To\Radicale.log
      • +
    • +
+
+

Security: Be aware that the service runs in the +local system account, you might want to change this. Managing user +accounts is beyond the scope of this manual. Also, make sure that the +storage folder and log file is not readable by unauthorized users.

+
+

The log file might grow very big over time, you can configure file +rotation in NSSM to prevent this.

+

The service is configured to start automatically when the computer +starts. To start the service manually open Services in +Computer Management and start the +Radicale service.

+
+
+
+

Reverse Proxy

+

When a reverse proxy is used, and Radicale should be made available +at a path below the root (such as /radicale/), then this +path must be provided via the X-Script-Name header (without +a trailing /). The proxy must remove the location from the +URL path that is forwarded to Radicale. If Radicale should be made +available at the root of the web server (in the nginx case using +location /), then the setting of the +X-Script-Name header should be removed from the example +below.

+

Example nginx configuration extension:

+

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/nginx/

+
location /radicale/ { # The trailing / is important!
+    proxy_pass        http://localhost:5232;
+    proxy_set_header  X-Script-Name /radicale;
+    proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header  X-Forwarded-Host $host;
+    proxy_set_header  X-Forwarded-Port $server_port;
+    proxy_set_header  X-Forwarded-Proto $scheme;
+    proxy_set_header  Host $http_host;
+    proxy_pass_header Authorization;
+}
+

Example Caddy configuration extension:

+

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/caddy/

+
handle_path /radicale/* {
+    uri strip_prefix /radicale
+    reverse_proxy localhost:5232 {
+    }
+}
+

Example Apache configuration extension:

+

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/apache/

+
RewriteEngine On
+RewriteRule ^/radicale$ /radicale/ [R,L]
+
+<Location "/radicale/">
+    ProxyPass        http://localhost:5232/ retry=0
+    ProxyPassReverse http://localhost:5232/
+    RequestHeader    set X-Script-Name /radicale
+    RequestHeader    set X-Forwarded-Port "%{SERVER_PORT}s"
+    RequestHeader    set X-Forwarded-Proto expr=%{REQUEST_SCHEME}
+    <IfVersion >= 2.4.40>
+    Proxy100Continue Off
+    </IfVersion>
+</Location>
+

Example Apache .htaccess configuration:

+
DirectoryIndex disabled
+RewriteEngine On
+RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]
+
+# Set to directory of .htaccess file:
+RequestHeader set X-Script-Name /radicale
+RequestHeader set X-Forwarded-Port "%{SERVER_PORT}s"
+RequestHeader unset X-Forwarded-Proto
+<If "%{HTTPS} =~ /on/">
+RequestHeader set X-Forwarded-Proto "https"
+</If>
+

Example lighttpd configuration:

+
server.modules += ( "mod_proxy" , "mod_setenv" )
+
+$HTTP["url"] =~ "^/radicale/" {
+  proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => "5232" )) )
+  setenv.add-request-header = ( "X-Script-Name" => "/radicale" )
+}
+

Be reminded that Radicale's default configuration enforces limits on +the maximum number of parallel connections, the maximum file size and +the rate of incorrect authentication attempts. Connections are +terminated after a timeout.

+
+

Manage user accounts with the reverse proxy

+

Set the configuration option type in the +auth section to http_x_remote_user. Radicale +uses the username provided in the X-Remote-User HTTP header +and disables its internal HTTP authentication.

+

Example nginx configuration:

+
location /radicale/ {
+    proxy_pass           http://localhost:5232/;
+    proxy_set_header     X-Script-Name /radicale;
+    proxy_set_header     X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header     X-Remote-User $remote_user;
+    proxy_set_header     Host $http_host;
+    auth_basic           "Radicale - Password Required";
+    auth_basic_user_file /etc/nginx/htpasswd;
+}
+

Example Caddy configuration:

+
handle_path /radicale/* {
+    uri strip_prefix /radicale
+    basicauth {
+        USER HASH
+    }
+    reverse_proxy localhost:5232 {
+        header_up X-Script-Name /radicale
+        header_up X-remote-user {http.auth.user.id}
+    }
+}
+

Example Apache configuration:

+
RewriteEngine On
+RewriteRule ^/radicale$ /radicale/ [R,L]
+
+<Location "/radicale/">
+    AuthType     Basic
+    AuthName     "Radicale - Password Required"
+    AuthUserFile "/etc/radicale/htpasswd"
+    Require      valid-user
+
+    ProxyPass        http://localhost:5232/ retry=0
+    ProxyPassReverse http://localhost:5232/
+    <IfVersion >= 2.4.40>
+    Proxy100Continue Off
+    </IfVersion>
+    RequestHeader    set X-Script-Name /radicale
+    RequestHeader    set X-Remote-User expr=%{REMOTE_USER}
+</Location>
+

Example Apache .htaccess configuration:

+
DirectoryIndex disabled
+RewriteEngine On
+RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]
+
+AuthType     Basic
+AuthName     "Radicale - Password Required"
+AuthUserFile "/etc/radicale/htpasswd"
+Require      valid-user
+
+# Set to directory of .htaccess file:
+RequestHeader set X-Script-Name /radicale
+RequestHeader set X-Remote-User expr=%{REMOTE_USER}
+
+

Security: Untrusted clients should not be able to +access the Radicale server directly. Otherwise, they can authenticate as +any user by simply setting related HTTP header. This can be prevented by +listening to the loopback interface only or local firewall rules.

+
+
+
+

Secure connection between Radicale and the reverse proxy

+

SSL certificates can be used to encrypt and authenticate the +connection between Radicale and the reverse proxy. First you need to +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, +these values do not really 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
+

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
+

If you are using the Let's Encrypt 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/;
+    ...
+    # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...).
+    proxy_ssl_certificate         /path/to/client_cert.pem;
+    proxy_ssl_certificate_key     /path/to/client_key.pem;
+}
+
+
+
+

WSGI Server

+

Radicale is compatible with the WSGI specification.

+

A configuration file can be set with the RADICALE_CONFIG +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
+

Example Gunicorn configuration:

+
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 +auth section to remote_user. This way Radicale +uses the username provided by the WSGI server and disables its internal +authentication over HTTP.

+
+
+
+

Versioning collections with Git

+

This tutorial describes how to keep track of all changes to calendars +and address books with git (or any other version +control system).

+

The repository must be initialized in the collection base directory +of the user running radicale daemon.

+
## assuming "radicale" user is starting "radicale" service
+# change to user "radicale"
+su -l -s /bin/bash radicale
+
+# change to collection base directory defined in [storage] -> filesystem_folder
+#  assumed here /var/lib/radicale/collections
+cd /var/lib/radicale/collections
+
+# initialize git repository
+git init
+
+# set user and e-mail, here minimum example
+git config user.name "$USER"
+git config user.email "$USER@$HOSTNAME"
+
+# define ignore of cache/lock/tmp files
+cat <<'END' >.gitignore
+.Radicale.cache
+.Radicale.lock
+.Radicale.tmp-*
+END
+

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

The command gets executed after every change to the storage and +commits the changes into the git repository.

+

Log of git can be investigated using

+
su -l -s /bin/bash radicale
+cd /var/lib/radicale/collections
+git log
+

In case of problems, make sure you run radicale with +--debug switch and inspect the log output. For more +information, please visit section on +logging.

+

Reason for problems can be

+
    +
  • SELinux status -> check related audit log
    • +
  • problematic file/directory permissions
    • +
  • command is not fond or cannot be executed or argument problem
    • +
+
+
+ + + + + +
+
+ diff --git a/index.html b/index.html index e905688a0..a8046b1ac 100644 --- a/index.html +++ b/index.html @@ -1,11 +1,11 @@ - + Redirect -

Please follow this link.

+

Please follow this link.

- - - -
-
-

-Radicale - -master - - -

-

Free and Open-Source CalDAV and CardDAV Server

-
-
- -
-
-
- - -
-
-

Translations of this page

- -
-
-

Getting started

-
-

About Radicale

-

Radicale is a small but powerful CalDAV (calendars, to-do lists) and -CardDAV (contacts) server, that:

-
    -
  • Shares calendars and contact lists through CalDAV, CardDAV and -HTTP.
    • -
  • Supports events, todos, journal entries and business cards.
    • -
  • Works out-of-the-box, no complicated setup or configuration -required.
    • -
  • Offers flexible authentication options.
    • -
  • Can limit access by authorization.
    • -
  • Can secure connections with TLS.
    • -
  • Works with many CalDAV and CardDAV -clients.
    • -
  • Stores all data on the file system in a simple folder -structure.
    • -
  • Can be extended with plugins.
    • -
  • Is GPLv3-licensed free software.
    • -
-
-
-

Installation

-

Check

- -
-
-

What's New?

-

Read the Changelog -on GitHub.

-
-
-
-

Tutorials

-
-

Simple 5-minute setup

-

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!

-

The server, configured with settings from this section, only binds to -localhost (i.e. it is not reachable over the network), and you can log -in with any username 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 and desired authentication type.

-

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

-
-

Linux / *BSD

-

Hint: instead of downloading from PyPI, look for packages provided by -your distribution. They -contain also startup scripts integrated into your distributions, that -allow Radicale to run daemonized.

-

First, make sure that python 3.9 or later and -pip are installed. On most distributions it should be -enough to install the package python3-pip.

-
-
as normal user
-

Recommended only for testing - open a console and type:

-
# Run the following command to only install for the current user
-python3 -m pip install --user --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
-

If install is not working and instead -error: externally-managed-environment is displayed, create -and activate a virtual environment in advance.

-
python3 -m venv ~/venv
-source ~/venv/bin/activate
-

and try to install with

-
python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
-

Start the service manually, data is stored only for the current -user

-
# Start, data is stored for the current user only
-python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections --auth-type none
-
-
-
as system user (or as root)
-

Alternatively, you can install and run as system user or as root (not -recommended):

-
# Run the following command as root (not recommended) or non-root system user
-# (the later may require --user in case dependencies are not available system-wide and/or virtual environment)
-python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
-

Start the service manually, with data stored in a system folder under -/var/lib/radicale/collections:

-
# Start, data is stored in a system folder (requires write permissions to /var/lib/radicale/collections)
-python3 -m radicale --storage-filesystem-folder=/var/lib/radicale/collections --auth-type none
-
-
-
-

Windows

-

The first step is to install Python. Go to python.org and download the latest version -of Python 3. Then run the installer. On the first window of the -installer, check the "Add Python to PATH" box and click on "Install -now". Wait a couple of minutes, it's done!

-

Launch a command prompt and type:

-
python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
-python -m radicale --storage-filesystem-folder=~/radicale/collections --auth-type none
-
-
Common
-

Success!!! Open http://localhost:5232 in your browser! -You can log in with any username and password as no authentication is -required by example option --auth-type none. This is -INSECURE, see Configuration/Authentication for more details.

-

Just note that default configuration for security reason binds the -server to localhost (IPv4: 127.0.0.1, IPv6: -::1). See Addresses and Configuration/Server for more details.

-
-
-
-
-

Basic Configuration

-

Installation instructions can be found in the simple 5-minute setup tutorial.

-

Radicale tries to load configuration files from -/etc/radicale/config and -~/.config/radicale/config. Custom paths can be specified -with the --config /path/to/config command line argument or -the RADICALE_CONFIG environment variable. Multiple -configuration files can be separated by : (resp. -; on Windows). Paths that start with ? are -optional.

-

You should create a new configuration file at the desired location. -(If the use of a configuration file is inconvenient, all options can be -passed via command line arguments.)

-

All configuration options are described in detail in the Configuration section.

-
-

Authentication

-

In its default configuration since version 3.5.0, Radicale rejects -all authentication attempts by using config option -type = denyall (introduced with 3.2.2) as default until -explicitly configured.

-

Versions before 3.5.0 did not check usernames or passwords at all, -unless explicitly configured. If such a server is reachable over a -network, you should change this as soon as possible.

-

First a users file with all usernames and passwords must -be created. It can be stored in the same directory as the configuration -file.

-
-
The secure way
-

The users file can be created and managed with htpasswd:

-

Note: some OSes or distributions contain outdated versions of -htpasswd (< 2.4.59) without support for SHA-256 or -SHA-512 (e.g. Ubuntu LTS 22). In these cases, use -htpasswd's command line option -B for the -bcrypt hash method (recommended), or stay with the insecure -(not recommended) MD5 (default) or SHA-1 (command line option --s).

-

Note: support of SHA-256 and 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:
-Re-type new password:
-# Add another user
-$ htpasswd -5 /path/to/users user2
-New password:
-Re-type new password:
-

Authentication can be enabled with the following configuration:

-
[auth]
-type = htpasswd
-htpasswd_filename = /path/to/users
-htpasswd_encryption = autodetect
-
-
-
The simple but insecure way
-

Create the users file by hand with lines containing the -username and password separated by :. Example:

-
user1:password1
-user2:password2
-

Authentication can be enabled with the following configuration:

-
[auth]
-type = htpasswd
-htpasswd_filename = /path/to/users
-# encryption method used in the htpasswd file
-htpasswd_encryption = plain
-
-
-
-

Addresses

-

The default configuration binds the server to localhost. It cannot be -reached from other computers. This can be changed with the following -configuration options (IPv4 and IPv6):

-
[server]
-hosts = 0.0.0.0:5232, [::]:5232
-
-
-

Storage

-

Data is stored in the folder -/var/lib/radicale/collections. The path can be changed with -the following configuration:

-
[storage]
-filesystem_folder = /path/to/storage
-
-

Security: The storage folder shall not be readable -by unauthorized users. Otherwise, they can read the calendar data and -lock the storage. You can find OS dependent instructions in the Running as a service section.

-
-
-
-

Limits

-

Radicale enforces limits on the maximum number of parallel -connections, the maximum file size (important for contacts with big -photos) and the rate of incorrect authentication attempts. Connections -are terminated after a timeout. The default values should be fine for -most scenarios.

-
[server]
-max_connections = 20
-# 100 Megabyte
-max_content_length = 100000000
-# 10 Megabyte (>= 3.5.10)
-max_resource_size = 10000000
-# 30 seconds
-timeout = 30
-
-[auth]
-# Average delay after failed login attempts in seconds
-# Also used for invalid/not-existing/not-enabled share-by-token (>= 3.7.0)
-delay = 1
-
-
-
-

Running as a service

-

The method to run Radicale as a service depends on your host -operating system. Follow one of the chapters below depending on your -operating system and requirements.

-
-

Linux with systemd system-wide

-

Recommendation: check support by Linux Distribution Packages -instead of manual setup / initial configuration.

-

Create the radicale user and group for the Radicale -service by running (as root):

-
useradd --system --user-group --home-dir / --shell /sbin/nologin radicale
-

The storage folder must be made writable by the -radicale user by running (as root):

-
mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections
-

If a dedicated cache folder is configured (see option filesystem_cache_folder), it also -must be made writable by radicale. To achieve that, run -(as root):

-
mkdir -p /var/cache/radicale && chown -R radicale:radicale /var/cache/radicale
-
-

Security: The storage shall not be readable by -others. To make sure this is the case, run (as root):

-
chmod -R o= /var/lib/radicale/collections
-
-

Create the file -/etc/systemd/system/radicale.service:

-
[Unit]
-Description=A simple CalDAV (calendar) and CardDAV (contact) server
-After=network.target
-Requires=network.target
-
-[Service]
-ExecStart=/usr/bin/env python3 -m radicale
-Restart=on-failure
-User=radicale
-# Deny other users access to the calendar data
-UMask=0027
-# Optional security settings
-PrivateTmp=true
-ProtectSystem=strict
-ProtectHome=true
-PrivateDevices=true
-ProtectKernelTunables=true
-ProtectKernelModules=true
-ProtectControlGroups=true
-NoNewPrivileges=true
-ReadWritePaths=/var/lib/radicale/
-# Replace with following in case dedicated cache folder should be used
-#ReadWritePaths=/var/lib/radicale/ /var/cache/radicale/
-
-[Install]
-WantedBy=multi-user.target
-

In this system-wide implementation, Radicale will load the -configuration from the file /etc/radicale/config.

-

To enable and manage the service run:

-
# Enable the service
-$ systemctl enable radicale
-# Start the service
-$ systemctl start radicale
-# Check the status of the service
-$ systemctl status radicale
-# View all log messages
-$ journalctl --unit radicale.service
-
-
-

Linux with systemd as a user

-

Create the file -~/.config/systemd/user/radicale.service:

-
[Unit]
-Description=A simple CalDAV (calendar) and CardDAV (contact) server
-
-[Service]
-ExecStart=/usr/bin/env python3 -m radicale
-Restart=on-failure
-
-[Install]
-WantedBy=default.target
-

In this user-specific configuration, Radicale will load the -configuration from the file ~/.config/radicale/config. You -should set the configuration option filesystem_folder in -the storage section to something like -~/.var/lib/radicale/collections.

-

To enable and manage the service run:

-
# Enable the service
-$ systemctl --user enable radicale
-# Start the service
-$ systemctl --user start radicale
-# Check the status of the service
-$ systemctl --user status radicale
-# View all log messages
-$ journalctl --user --unit radicale.service
-
-
-

Windows with "NSSM - the Non-Sucking Service Manager"

-

First install NSSM and start -nssm install in a command prompt. Apply the following -configuration:

-
    -
  • Service name: Radicale
    • -
  • Application -
      -
    • Path: C:\Path\To\Python\python.exe
      • -
    • Arguments: --config C:\Path\To\Config
      • -
    • -
  • I/O redirection -
      -
    • Error: C:\Path\To\Radicale.log
      • -
    • -
-
-

Security: Be aware that the service runs in the -local system account, you might want to change this. Managing user -accounts is beyond the scope of this manual. Also, make sure that the -storage folder and log file is not readable by unauthorized users.

-
-

The log file might grow very big over time, you can configure file -rotation in NSSM to prevent this.

-

The service is configured to start automatically when the computer -starts. To start the service manually open Services in -Computer Management and start the -Radicale service.

-
-
-
-

Reverse Proxy

-

When a reverse proxy is used, and Radicale should be made available -at a path below the root (such as /radicale/), then this -path must be provided via the X-Script-Name header (without -a trailing /). The proxy must remove the location from the -URL path that is forwarded to Radicale. If Radicale should be made -available at the root of the web server (in the nginx case using -location /), then the setting of the -X-Script-Name header should be removed from the example -below.

-

Example nginx configuration extension:

-

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/nginx/

-
location /radicale/ { # The trailing / is important!
-    proxy_pass        http://localhost:5232;
-    proxy_set_header  X-Script-Name /radicale;
-    proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header  X-Forwarded-Host $host;
-    proxy_set_header  X-Forwarded-Port $server_port;
-    proxy_set_header  X-Forwarded-Proto $scheme;
-    proxy_set_header  Host $http_host;
-    proxy_pass_header Authorization;
-}
-

Example Caddy configuration extension:

-

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/caddy/

-
handle_path /radicale/* {
-    uri strip_prefix /radicale
-    reverse_proxy localhost:5232 {
-        # replace "HOST" with configured hostname of URL (FQDN) in client
-        header_up Host HOST
-        # replace "PORT" with configured port of URL in client
-        header_up X-Forwarded-Port PORT
-    }
-}
-

Example Apache configuration extension:

-

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/apache/

-
RewriteEngine On
-RewriteRule ^/radicale$ /radicale/ [R,L]
-
-<Location "/radicale/">
-    ProxyPass        http://localhost:5232/ retry=0
-    ProxyPassReverse http://localhost:5232/
-    RequestHeader    set X-Script-Name /radicale
-    RequestHeader    set X-Forwarded-Port "%{SERVER_PORT}s"
-    RequestHeader    set X-Forwarded-Proto expr=%{REQUEST_SCHEME}
-    <IfVersion >= 2.4.40>
-    Proxy100Continue Off
-    </IfVersion>
-</Location>
-

Example Apache .htaccess configuration:

-
DirectoryIndex disabled
-RewriteEngine On
-RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]
-
-# Set to directory of .htaccess file:
-RequestHeader set X-Script-Name /radicale
-RequestHeader set X-Forwarded-Port "%{SERVER_PORT}s"
-RequestHeader unset X-Forwarded-Proto
-<If "%{HTTPS} =~ /on/">
-RequestHeader set X-Forwarded-Proto "https"
-</If>
-

Example lighttpd configuration:

-
server.modules += ( "mod_proxy" , "mod_setenv" )
-
-$HTTP["url"] =~ "^/radicale/" {
-  proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => "5232" )) )
-  setenv.add-request-header = ( "X-Script-Name" => "/radicale" )
-}
-

Be reminded that Radicale's default configuration enforces limits on -the maximum number of parallel connections, the maximum file size and -the rate of incorrect authentication attempts. Connections are -terminated after a timeout.

-
-

Manage user accounts with the reverse proxy

-

Set the configuration option type in the -auth section to http_x_remote_user. Radicale -uses the username provided in the X-Remote-User HTTP header -and disables its internal HTTP authentication.

-

Example nginx configuration:

-
location /radicale/ {
-    proxy_pass           http://localhost:5232/;
-    proxy_set_header     X-Script-Name /radicale;
-    proxy_set_header     X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header     X-Remote-User $remote_user;
-    proxy_set_header     Host $http_host;
-    auth_basic           "Radicale - Password Required";
-    auth_basic_user_file /etc/nginx/htpasswd;
-}
-

Example Caddy configuration:

-
handle_path /radicale/* {
-    uri strip_prefix /radicale
-    basicauth {
-        USER HASH
-    }
-    reverse_proxy localhost:5232 {
-        header_up X-Script-Name /radicale
-        header_up X-remote-user {http.auth.user.id}
-    }
-}
-

Example Apache configuration:

-
RewriteEngine On
-RewriteRule ^/radicale$ /radicale/ [R,L]
-
-<Location "/radicale/">
-    AuthType     Basic
-    AuthName     "Radicale - Password Required"
-    AuthUserFile "/etc/radicale/htpasswd"
-    Require      valid-user
-
-    ProxyPass        http://localhost:5232/ retry=0
-    ProxyPassReverse http://localhost:5232/
-    <IfVersion >= 2.4.40>
-    Proxy100Continue Off
-    </IfVersion>
-    RequestHeader    set X-Script-Name /radicale
-    RequestHeader    set X-Remote-User expr=%{REMOTE_USER}
-</Location>
-

Example Apache .htaccess configuration:

-
DirectoryIndex disabled
-RewriteEngine On
-RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]
-
-AuthType     Basic
-AuthName     "Radicale - Password Required"
-AuthUserFile "/etc/radicale/htpasswd"
-Require      valid-user
-
-# Set to directory of .htaccess file:
-RequestHeader set X-Script-Name /radicale
-RequestHeader set X-Remote-User expr=%{REMOTE_USER}
-
-

Security: Untrusted clients should not be able to -access the Radicale server directly. Otherwise, they can authenticate as -any user by simply setting related HTTP header. This can be prevented by -listening to the loopback interface only or local firewall rules.

-
-
-
-

Secure connection between Radicale and the reverse proxy

-

SSL certificates can be used to encrypt and authenticate the -connection between Radicale and the reverse proxy. First you need to -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, -these values do not really 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
-

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
-

If you are using the Let's Encrypt 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/;
-    ...
-    # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...).
-    proxy_ssl_certificate         /path/to/client_cert.pem;
-    proxy_ssl_certificate_key     /path/to/client_key.pem;
-}
-
-
-
-

WSGI Server

-

Radicale is compatible with the WSGI specification.

-

A configuration file can be set with the RADICALE_CONFIG -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
-

Example Gunicorn configuration:

-
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 -auth section to remote_user. This way Radicale -uses the username provided by the WSGI server and disables its internal -authentication over HTTP.

-
-
-
-

Versioning collections with Git

-

This tutorial describes how to keep track of all changes to calendars -and address books with git (or any other version -control system).

-

The repository must be initialized in the collection base directory -of the user running radicale daemon.

-
## assuming "radicale" user is starting "radicale" service
-# change to user "radicale"
-su -l -s /bin/bash radicale
-
-# change to collection base directory defined in [storage] -> filesystem_folder
-#  assumed here /var/lib/radicale/collections
-cd /var/lib/radicale/collections
-
-# initialize git repository
-git init
-
-# set user and e-mail, here minimum example
-git config user.name "$USER"
-git config user.email "$USER@$HOSTNAME"
-
-# define ignore of cache/lock/tmp files
-cat <<'END' >.gitignore
-.Radicale.cache
-.Radicale.lock
-.Radicale.tmp-*
-END
-

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

The command gets executed after every change to the storage and -commits the changes into the git repository.

-

Log of git can be investigated using

-
su -l -s /bin/bash radicale
-cd /var/lib/radicale/collections
-git log
-

In case of problems, make sure you run radicale with ---debug switch and inspect the log output. For more -information, please visit section on -logging.

-

Reason for problems can be

-
    -
  • SELinux status -> check related audit log
    • -
  • problematic file/directory permissions
    • -
  • command is not fond or cannot be executed or argument problem
    • -
-
-
-
-

Documentation

-
-

Options

-
-

General Options

-
-
--version
-

Print version

-
-
-
--verify-storage
-

Verification of local collections storage

-
-
-
--verify-item
-

(>= 3.6.0)

-

Verification of a particular item file

-
-
-
--verify-sharing
-

(>= 3.7.0)

-

Verification of local sharing database

-
-
-
-C|--config
-

Load one or more specified config file(s)

-
-
-
-D|--debug
-

Turns log level to debug

-
-
-
-

Configuration Options

-

Each supported option from config file can be provided/overridden by -command line replacing _ with - and prepending -the section followed by a -, e.g.

-
[logging]
-backtrace_on_debug = False
-

can be enabled using --logging-backtrace-on-debug=true -on command line.

-
-
-
-

Configuration

-

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.

-

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 = 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 -with the --config /path/to/config command line argument or -the RADICALE_CONFIG environment variable. Multiple -configuration files can be separated by : (resp. -; on Windows). Paths that start with ? are -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 autodetect
-

Add the argument --config "" to stop Radicale from -loading the default configuration files. Run -python3 -m radicale --help for more information.

-

You can also use command-line options in startup scripts as shown in -the following examples:

-
## simple variable containing multiple options
-RADICALE_OPTIONS="--logging-level=debug --config=/etc/radicale/config --logging-request-header-on-debug --logging-rights-rule-doesnt-match-on-debug"
-/usr/bin/radicale $RADICALE_OPTIONS
-
-## variable as array method #1
-RADICALE_OPTIONS=("--logging-level=debug" "--config=/etc/radicale/config" "--logging-request-header-on-debug" "--logging-rights-rule-doesnt-match-on-debug")
-/usr/bin/radicale ${RADICALE_OPTIONS[@]}
-
-## variable as array method #2
-RADICALE_OPTIONS=()
-RADICALE_OPTIONS+=("--logging-level=debug")
-RADICALE_OPTIONS+=("--config=/etc/radicale/config")
-/usr/bin/radicale ${RADICALE_OPTIONS[@]}
-

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

-
-
-
delay_on_error
-

(>= 3.7.0)

-

Base delay in case of error 5xx response (seconds)

-

Default: 1

-
-
-
max_content_length
-

The maximum size of the request body. (bytes)

-

Default: 100000000 (100 Mbyte)

-

In case of using a reverse proxy in front of check also there related -option.

-
-
-
max_resource_size
-

(>= 3.5.10)

-

The maximum size of a resource. (bytes)

-

Default: 10000000 (10 Mbyte)

-

Limited to 80% of max_content_length to cover plain base64 encoded -payload.

-

Announced to clients requesting "max-resource-size" via PROPFIND.

-
-
-
timeout
-

Socket timeout. (seconds)

-

Default: 30

-
-
-
ssl
-

Enable transport layer encryption.

-

Default: False

-
-
-
certificate
-

Path of the SSL certificate.

-

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)

-
-
-
-

[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 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_remote_user (>= 3.5.9) Takes the -username from the Remote-User HTTP header HTTP_REMOTE_USER -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.

    • -

  • http_x_remote_user
    -Takes the username from the X-Remote-User HTTP header -HTTP_X_REMOTE_USER 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 file.

-

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 or missing login attempts or -denied access.

-

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_security
-

(>= 3.5.2)

-

Use encryption on the LDAP connection.

-

One of

-
    -
  • none
    • -
  • tls
    • -
  • starttls
    • -
-

Default: none

-
-
-
ldap_ssl_verify_mode
-

(>= 3.3.0)

-

Certificate verification mode for tls and starttls.

-

One of

-
    -
  • NONE
    • -
  • OPTIONAL
    • -
  • REQUIRED.
    • -
-

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 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 search 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:

-
    -
  • AF_UNIX
    • -
  • AF_INET
    • -
  • AF_INET6
    • -
-

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:

-
    -
  • tls
    • -
  • starttls
    • -
  • none
    • -
-

Default: tls

-
-
-
oauth2_token_endpoint
-

(>= 3.5.0)

-

Endpoint URL for the OAuth2 token

-

Default: (unset)

-
-
-
oauth2_client_id
-

(>= 3.7.0)

-

Client ID used to request the Auth2 token

-

Default: radicale

-
-
-
oauth2_client_secret
-

(>= 3.7.0)

-

Client secret used to request the Auth2 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

-
-
-
-

[rights]

-
-
type
-

Authorization backend that is used to check the access rights to -collections.

-

The default and recommended backend is owner_only. If -access to calendars and address books outside the user's collection -directory (that's /username/) is granted, clients will not -detect these collections automatically and will not show them to the -users. Choosing any other authorization backend is only useful if you -access calendars and address books directly via URL.

-

Available backends are:

-
    -

  • 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
-

Name of the file containing the authorization rules for the -from_file backend. See the Rights section for details.

-

Default: /etc/radicale/rights

-
-
-
permit_delete_collection
-

(>= 3.1.9)

-

Global permission to delete complete collections.

-
    -
  • If False it can be explicitly granted per collection by -rights permissions: D
    • -
  • If True it can be explicitly forbidden per collection -by rights permissions: d
    • -
-

Default: True

-
-
-
permit_overwrite_collection
-

(>= 3.3.0)

-

Global permission to overwrite complete collections.

-
    -
  • If False it can be explicitly granted per collection by -rights permissions: O
    • -
  • If True it can be explicitly forbidden per collection -by rights permissions: o
    • -
-

Default: True

-
-
-
-

[storage]

-
-
type
-

Backend used to store data.

-

Available backends are:

-
    -

  • multifilesystem
    -Stores the data in the filesystem.

    • -

  • multifilesystem_nolock
    -The multifilesystem backend without file-based locking. -Must only be used with a single process.

    • -
-

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

-
-
-
strict_preconditions
-

(>= 3.5.8)

-

Strict preconditions check on PUT in case item already exists RFC6352#9.2

-

Default: False

-
-
-
validate_user_value
-

(>= 3.7.2)

-

Validate user value content

-

Available types are:

-
    -
  • none
    • -
  • minimal (control and some special chars)
    • -
  • unicode-letter (unicode letters)
    • -
  • no-unicode (no unicode)
    • -
  • strict (reduced ASCII set)
    • -
-

Default: minimum

-
-
-
validate_path_type
-

(>= 3.7.2)

-

Validate path value content

-
    -
  • none
    • -
  • minimal (control and some special chars)
    • -
  • unicode-letter (unicode letters)
    • -
  • no-unicode (no unicode)
    • -
  • strict (reduced ASCII set)
    • -
-

Default: minimum

-
-
-
hook
-

Command that is run after changes to storage. See 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)

-
-
-
-

[web]

-
-
type
-

The backend that provides the web interface of Radicale.

-

Available backends are:

-
    -

  • none
    -Simply shows the message "Radicale works!".

    • -

  • internal
    -Allows creation and management of address books and calendars.

    • -
-

Default: internal

-
-
-
-

[logging]

-
-
level
-

Set the logging level.

-

Available levels are:

-
    -
  • trace (>= 3.7.1)
    • -
  • debug
    • -
  • info
    • -
  • notice (>= 3.7.1)
    • -
  • warning
    • -
  • error
    • -
  • critical
    • -
  • alert (>= 3.7.1)
    • -
-

Default: warning (< 3.2.0) / -info (>= 3.2.0)

-
-
-
limit_content
-

(>= 3.7.0)

-

Limit content of wrapped text (chars)

-

Default: 3000

-
-
-
trace_on_debug
-

(> 3.5.4) && (< 3.7.1)

-

Do not filter debug messages starting with 'TRACE'

-

Default: False

-
-
-
trace_filter
-

(> 3.5.4) && (< 3.7.1)

-

Filter debug messages starting with 'TRACE/'

-

Prerequisite: trace_on_debug = True

-

(>= 3.7.1)

-

Filter trace messages starting with ''

-

Prerequisite: level = trace

-

Default: (empty)

-
-
-
mask_passwords
-

Do not include passwords in logs.

-

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 header on level = debug

-

Default: False

-
-
-
request_content_on_debug
-

(>= 3.2.2)

-

Log request content (body) on level = debug

-

Default: False

-
-
-
response_header_on_debug
-

(>= 3.5.10)

-

Log response header on level = debug

-

Default: False

-
-
-
response_content_on_debug
-

(>= 3.2.2)

-

Log response content (body) on level = debug

-

Default: False

-
-
-
rights_rule_doesnt_match_on_debug
-

(>= 3.2.3)

-

Log rights rule which doesn't match on level = debug

-

Default: False

-
-
-
storage_cache_actions_on_debug
-

(>= 3.3.2)

-

Log storage cache actions on level = debug

-

Default: False

-
-
-
profiling_per_request
-

(>= 3.5.10)

-

Log profiling data on level=info

-

Default: none

-

One of

-
    -
  • none (disabled)
    • -
  • per_request (above minimum duration)
    • -
  • per_request_method (regular interval)
    • -
-
-
-
profiling_per_request_min_duration
-

(>= 3.5.10)

-

Log profiling data per request minimum duration (seconds) before -logging, otherwise skip

-

Default: 3

-
-
-
profiling_per_request_header
-

(>= 3.5.10)

-

Log profiling request header (if passing minimum duration)

-

Default: False

-
-
-
profiling_per_request_xml
-

(>= 3.5.10)

-

Log profiling request XML (if passing minimum duration)

-

Default: False

-
-
-
profiling_per_request_method_interval
-

(>= 3.5.10)

-

Log profiling data per method interval (seconds) Triggered by -request, not active on idle systems

-

Default: 600

-
-
-
profiling_top_x_functions
-

(>= 3.5.10)

-

Log profiling top X functions (limit)

-

Default: 10

-
-
-
-

[headers]

-

This section can be used to specify additional HTTP headers that will -be sent to clients.

-

An example to relax the same-origin policy:

-
Access-Control-Allow-Origin = *
-

An example to set CSP to disallow execution of unknown -javascript:

-
Content-Security-Policy = default-src 'self'; object-src 'none'
-
-
-

[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:

-
    -
  • none
    • -
  • tls
    • -
  • starttls
    • -
-

Default: none

-
-
-
smtp_ssl_verify_mode
-

(>= 3.5.5)

-

The certificate verification mode for tls and starttls.

-

One of:

-
    -
  • NONE
    • -
  • OPTIONAL
    • -
  • REQUIRED
    • -
-

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.
-
-
-
-

[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 -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

-
-
-
-

[sharing]

-

(>= 3.7.0)

-

See also Collection -Sharing.

-
-
type
-

(>= 3.7.0)

-

Sharing database type

-

One of:

-
    -
  • none
    • -
  • csv
    • -
  • files
    • -
-

Default: none (implicit disabling the feature)

-
-
-
database_path
-

(>= 3.7.0)

-

Sharing database path

-

Default:

-
    -
  • type csv: -(filesystem_folder)/collection-db/sharing.csv
    • -
  • type files: -(filesystem_folder)/collection-db/files
    • -
-
-
-
collection_by_token
-

(>= 3.7.0)

-

Share collection by token

-

Default: false

-
-
-
collection_by_map
-

(>= 3.7.0)

-

Share collection by map

-

Default: false

-
-
-
permit_create_token
-

(>= 3.7.0)

-

Permit create of token-based sharing

-

Default: false

-
    -
  • If False it can be explicitly granted by -rights permissions: T
    • -
  • If True it can be explicitly forbidden by -rights permissions: t
    • -
-
-
-
permit_create_map
-

(>= 3.7.0)

-

Permit create of map-based sharing

-

Default: false

-
    -
  • If False it can be explicitly granted by -rights permissions: M
    • -
  • If True it can be explicitly forbidden by -rights permissions: m
    • -
-
-
-
permit_properties_overlay
-

(>= 3.7.0)

-

Permit (limited) properties overlay by user of shared collection

-

Default: false

-
    -
  • If False it can be explicitly granted by share -permissions: P
    • -
  • If True it can be explicitly forbidden by -share permissions: p
    • -
-
-
-
enforce_properties_overlay
-

(>= 3.7.0)

-

Enforce properties overlay even on write access

-

Default: true

-
    -
  • If False it can be explicitly enforced by -share permissions: E
    • -
  • If True it can be explicitly forbidden by -share permissions: e
    • -
-
-
-
default_permissions_create_token
-

Default permissions for create token-based sharing

-

Default: r

-

Supported: rwEePp

-
-
-
default_permissions_create_map
-

Default permissions for map-based sharing

-

Default: r

-

Supported: rwEePp

-
-
-
-
-
-

Supported Clients

-

Radicale has been tested with:

- -

Many clients do not support the creation of new calendars and address -books. You can use Radicale's web interface (e.g. http://localhost:5232) to create and -manage address books and calendars.

-

In some clients, it is sufficient to simply enter the URL of the -Radicale server (e.g. http://localhost:5232) and your -username. In others, you have to enter the URL of the collection -directly (e.g. http://localhost:5232/user/calendar).

-

Some clients (notably macOS's Calendar.app) may silently refuse to -include account credentials over unsecured HTTP, leading to unexpected -authentication failures. In these cases, you want to make sure the -Radicale server is accessible over HTTPS.

-
-

DAVx⁵

-

Enter the URL of the Radicale server (e.g. -http://localhost:5232) and your username. DAVx⁵ will show -all existing calendars and address books and you can create new -ones.

-
-
-

OneCalendar

-

When adding account, select CalDAV account type, then enter username, -password and the Radicale server (e.g. -https://yourdomain:5232). OneCalendar will show all -existing calendars and (FIXME: address books), you need to select which -ones you want to see. OneCalendar supports many other server types -too.

-
-
-

GNOME Calendar, Contacts

-

GNOME 46 added CalDAV and CardDAV support to GNOME Online -Accounts.

-

Open GNOME Settings, navigate to Online Accounts > -Connect an Account > Calendar, Contacts and Files. -Enter the URL (e.g. https://example.com/radicale) and your -credentials then click Sign In. In the pop-up dialog, turn off -Files. After adding Radicale in GNOME Online Accounts, -it should be available in GNOME Contacts and GNOME Calendar.

-
-
-

Evolution

-

In Evolution add a new calendar and address book -respectively with WebDAV. Enter the URL of the Radicale server (e.g. -http://localhost:5232) and your username. Clicking on the -search button will list the existing calendars and address books.

-

Adding CalDAV and CardDAV accounts in Evolution will automatically -make them available in GNOME Contacts and GNOME Calendar.

-
-
-

KDE PIM Applications

-

In Kontact add a DAV Groupware resource to -Akonadi under Settings > Configure Kontact > Calendar > -General > Calendars, select the protocol (CalDAV or CardDAV), -add the URL to the Radicale collections and enter the credentials. After -synchronization of the calendar resp. addressbook items, you can manage -them in Kontact.

-
-
-

Thunderbird

-

Add a new calendar on the network. Enter your username and the URL of -the Radicale server (e.g. http://localhost:5232). After -asking for your password, it will list the existing calendars.

-
-
Address books with CardBook add-on
-

Add a new address book on the network with CardDAV. Enter the URL of -the Radicale server (e.g. http://localhost:5232) and your -username and password. It will list your existing address books.

-
-
-
-

InfCloud, CalDavZAP and CardDavMATE

-

You can integrate InfCloud into Radicale's web interface with by -simply downloading the latest package from InfCloud -and extract the content into a folder named 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

-

This is not the recommended way of creating and managing your -calendars and address books. Use Radicale's web interface or a client -with support for it (e.g. DAVx⁵).

-

To create a new calendar run something like:

-
$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \
-'<?xml version="1.0" encoding="UTF-8" ?>
-<create xmlns="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:I="http://apple.com/ns/ical/">
-  <set>
-    <prop>
-      <resourcetype>
-        <collection />
-        <C:calendar />
-      </resourcetype>
-      <C:supported-calendar-component-set>
-        <C:comp name="VEVENT" />
-        <C:comp name="VJOURNAL" />
-        <C:comp name="VTODO" />
-      </C:supported-calendar-component-set>
-      <displayname>Calendar</displayname>
-      <C:calendar-description>Example calendar</C:calendar-description>
-      <I:calendar-color>#ff0000ff</I:calendar-color>
-    </prop>
-  </set>
-</create>'
-

To create a new address book run something like:

-
$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \
-'<?xml version="1.0" encoding="UTF-8" ?>
-<create xmlns="DAV:" xmlns:CR="urn:ietf:params:xml:ns:carddav">
-  <set>
-    <prop>
-      <resourcetype>
-        <collection />
-        <CR:addressbook />
-      </resourcetype>
-      <displayname>Address book</displayname>
-      <CR:addressbook-description>Example address book</CR:addressbook-description>
-    </prop>
-  </set>
-</create>'
-

The collection /USERNAME will be created automatically, -when the user authenticates to Radicale for the first time. Clients with -automatic discovery of collections will only show calendars and address -books that are direct children of the path /USERNAME/.

-

Delete the collections by running something like:

-
curl -u user -X DELETE 'http://localhost:5232/user/calendar'
-

Note: requires config/option -permit_delete_collection = True

-
-
-
-

Internals

-
-

Authorization and Rights

-

This section describes the format of the rights file for the -from_file authentication backend. The configuration option -file in the rights section must point to the -rights file.

-

The recommended rights method is owner_only. If access -is granted to calendars and address books outside the home directory of -users (that's /USERNAME/), clients will not detect these -collections automatically, and will not show them to the users. 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
-

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 -collection. Permissions from the first matching section are used. If no -section matches, access gets denied.

-

The username is empty for anonymous users. Therefore, the regex -.+ only matches authenticated users and .* -matches everyone (including anonymous users).

-

The path of the collection is separated by / and has no -leading or trailing /. Therefore, the path of the root -collection is empty.

-

In the collection regex you can use {user} -and get groups from the user regex with {0}, -{1}, etc.

-

In consequence of the parameter substitution you have to write -{{ and }} if you want to use regular curly -braces in the user and collection regexes.

-

The following permissions are recognized:

-
    -
  • R: read collections (excluding address books and -calendars)
    • -
  • r: read address book and calendar collections
    • -
  • i: subset of r that only allows -direct access via HTTP method GET (CalDAV/CardDAV is susceptible to -expensive search requests)
    • -
  • W: write collections (excluding address books and -calendars)
    • -
  • w: write address book and calendar collections
    • -
  • D: allow deleting a collection in case -permit_delete_collection=False (>= 3.3.0)
    • -
  • d: deny deleting a collection in case -permit_delete_collection=True (>= 3.3.0)
    • -
  • O: allow overwriting a collection in case -permit_overwrite_collection=False (>= -3.3.0)
    • -
  • o: deny overwriting a collection in case -permit_overwrite_collection=True (>= -3.3.0)
    • -
  • T: permit create of token-based sharing of -collection in case permit_create_token=False (>= -3.7.0)
    • -
  • t: deny create of token-based sharing of collection -in case permit_create_token=True (>= -3.7.0)
    • -
  • M: permit create of map-based sharing of collection -in case permit_create_map= False (>= -3.7.0)
    • -
  • m: deny create of map-based sharing of collection -in case permit_create_map=True (>= 3.7.0)
    • -
-
-
-

Storage

-

This document describes the layout and format of the file system -storage, the multifilesystem backend.

-

It is safe to access and manipulate the data by hand or with scripts. -Scripts can be invoked manually, periodically (e.g. using cron) -or after each change to the storage with the configuration option -hook in the storage section (e.g. Versioning collections with -Git).

-
-

Layout

-

The file system comprises the following files and folders:

-
    -
  • .Radicale.lock: The lock file for locking the -storage.
    • -
  • collection-root: This folder contains all collections -and items.
    • -
-

Each collection is represented by a folder. This folder may contain -the file .Radicale.props with all WebDAV properties of the -collection encoded as JSON.

-

Each item in a calendar or address book collection is represented by -a file containing the item's iCalendar resp. vCard data.

-

All files and folders, whose names start with a dot but not with -.Radicale. (internal files) are ignored.

-

Syntax errors in any of the files will cause all requests accessing -the faulty data to fail. The logging output should contain the names of -the culprits.

-

Caches and sync-tokens are stored in the .Radicale.cache -folder inside of collections. This folder may be created or modified, -while the storage is locked for shared access. In theory, it should be -safe to delete the folder. Caches will be recreated automatically and -clients will be told that their sync-token is not valid anymore.

-

You may encounter files or folders that start with -.Radicale.tmp-. Radicale uses them for atomic creation and -deletion of files and folders. They should be deleted after requests are -finished but it is possible that they are left behind when Radicale or -the computer crashes. You can safely delete them.

-
-
-

Locking

-

When the data is accessed by hand or by an externally invoked script, -the storage must be locked. The storage can be locked for exclusive or -shared access. It prevents Radicale from reading or writing the file -system. The storage is locked with exclusive access while the -hook runs.

-
-
Linux shell scripts
-

Use the flock -utility to acquire exclusive or shared locks for the commands you want -to run on Radicale's data.

-
# Exclusive lock for COMMAND
-$ flock --exclusive /path/to/storage/.Radicale.lock COMMAND
-# Shared lock for COMMAND
-$ flock --shared /path/to/storage/.Radicale.lock COMMAND
-
-
-
Linux and MacOS
-

Use the flock -syscall. Python provides it in the fcntl -module.

-
-
-
Windows
-

Use LockFile -for exclusive access or LockFileEx -which also supports shared access. Setting -nNumberOfBytesToLockLow to 1 and -nNumberOfBytesToLockHigh to 0 works.

-
-
-
-

Manually creating collections

-

To create a new collection, you need to create the corresponding -folder in the file system storage (e.g. -collection-root/user/calendar). To indicate to Radicale and -clients that the collection is a calendar, you have to create the file -.Radicale.props with the following content in the -folder:

-
{"tag": "VCALENDAR"}
-

The calendar is now available at the URL path (e.g. -/user/calendar). For address books -.Radicale.props must contain:

-
{"tag": "VADDRESSBOOK"}
-

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 -/USERNAME/.

-

Delete collections by deleting the corresponding folders.

-
-
-
-

Logging overview

-

Radicale logs to stderr. The verbosity of the log output -can be controlled with --debug command line argument or the -level configuration option in the logging section.

-
-
-

Architecture

-

Radicale is a small piece of software, but understanding it is not as -easy as it seems. But don't worry, reading this short section is enough -to understand what a CalDAV/CardDAV server is, and how Radicale's code -is organized.

-
-

Protocol overview

-

Here is a simple overview of the global architecture for reaching a -calendar or an address book through network:

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PartLayerProtocol or Format
ServerCalendar/Contact StorageiCal/vCard
''Calendar/Contact ServerCalDAV/CardDAV Server
TransferNetworkCalDAV/CardDAV (HTTP + TLS)
ClientCalendar/Contact ClientCalDAV/CardDAV Client
''GUITerminal, GTK, Web interface, etc.
-

Radicale is only the server part of this -architecture.

-

Please note:

-
    -
  • CalDAV and CardDAV are extension protocols of WebDAV,
    • -
  • WebDAV is an extension of the HTTP protocol.
    • -
-

Radicale being a CalDAV/CardDAV server, can also be seen as a special -WebDAV and HTTP server.

-

Radicale is not the client part of this -architecture. It means that Radicale never draws calendars, address -books, events and contacts on the screen. It only stores them and give -the possibility to share them online with other people.

-

If you want to see or edit your events and your contacts, you have to -use another software called a client, that can be a "normal" -applications with icons and buttons, a terminal or another web -application.

-
-
-

Code Architecture

-

The radicale package offers the following modules.

-
    -

  • __init__ : Contains the entry point for -WSGI.

    • -

  • __main__ : Provides the entry point for the -radicale executable and includes the command line parser. -It loads configuration files from the default (or specified) paths and -starts the internal server.

    • -

  • app : This is the core part of Radicale, with the -code for the CalDAV/CardDAV server. The code managing the different HTTP -requests according to the CalDAV/CardDAV specification can be found -here.

    • -

  • auth : Used for authenticating users based on -username and password, mapping usernames to internal users and -optionally retrieving credentials from the environment.

    • -

  • config : Contains the code for managing -configuration and loading settings from files.

    • -

  • ìtem : Internal representation of address book and -calendar entries. Based on VObject.

    • -

  • log : The logger for Radicale based on the default -Python logging module.

    • -

  • rights : This module is used by Radicale to manage -access rights to collections, address books and calendars.

    • -

  • server : The integrated HTTP server for standalone -use.

    • -

  • storage : This module contains the classes -representing collections in Radicale and the code for storing and -loading them in the filesystem.

    • -

  • sharing : This module contains the classes -representing collection sharing. (>= 3.7.0)

    • -

  • web : This module contains the web -interface.

    • -

  • utils : Contains general helper functions.

    • -

  • httputils : Contains helper functions for working -with HTTP.

    • -

  • pathutils : Helper functions for working with paths -and the filesystem.

    • -

  • xmlutils : Helper functions for working with the XML -part of CalDAV/CardDAV requests and responses. It's based on the -ElementTree XML API.

    • -
-
-
-
-

Plugins

-

Radicale can be extended by plugins for authentication, rights -management and storage. Plugins are python modules.

-
-

Getting started with plugin development

-

To get started we walk through the creation of a simple -authentication plugin, that accepts login attempts with a static -password.

-

The easiest way to develop and install python -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"])
-

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

Install the python module by running the following command in the -same folder as setup.py:

-
python3 -m pip install .
-

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
-

You can uninstall the module with:

-
python3 -m pip uninstall radicale_static_password_auth
-
-
-

Authentication plugins

-

This plugin type is used to check login credentials. The module must -contain a class Auth that extends -radicale.auth.BaseAuth. Take a look at the file -radicale/auth/__init__.py in Radicale's source code for -more information.

-
-
-

Rights management plugins

-

This plugin type is used to check if a user has access to a path. The -module must contain a class Rights that extends -radicale.rights.BaseRights. Take a look at the file -radicale/rights/__init__.py in Radicale's source code for -more information.

-
-
-

Web plugins

-

This plugin type is used to provide the web interface for Radicale. -The module must contain a class Web that extends -radicale.web.BaseWeb. Take a look at the file -radicale/web/__init__.py in Radicale's source code for more -information.

-
-
-

Storage plugins

-

This plugin is used to store collections and items. The module must -contain a class Storage that extends -radicale.storage.BaseStorage. Take a look at the file -radicale/storage/__init__.py in Radicale's source code for -more information.

-
-
-
-
-

Contribute

-
-

Report Bugs

-

Found a bug? Want a new feature? Report a new issue on the Radicale -bug-tracker.

-
-
-

Hack

-

Interested in hacking? Feel free to clone the git repository on GitHub if -you want to add new features, fix bugs or update the documentation.

-
-
-

Documentation

-

To change or complement the documentation create a pull request to DOCUMENTATION.md.

-
-
-
-

Download

-
-

PyPI

-

Radicale is available on PyPI. To -install, just type as superuser:

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

You can also download the content of the repository as an archive.

-
-
-

Source Packages

-

You can find the source packages of all releases on GitHub.

-
-
-

Docker

-

Radicale is available as a Docker image for platforms -linux/amd64 and linux/arm64 on:

- -

Here are the steps to install Radicale via Docker Compose:

-
    -

  1. Create required directories

    -

    Create a directory to store the data, configuration and compose -file.

    -

    For example, assuming ./radicale:

    -
    $ mkdir radicale
-$ cd radicale
    -

    Create directories to store data and configuration.

    -

    For example, assuming data directory as ./data and -configuration directory as ./config:

    -
    $ mkdir config data
    2. -

  2. Download the compose file

    -
    $ wget https://raw.githubusercontent.com/Kozea/Radicale/refs/heads/master/compose.yaml
    -

    The compose file assumes ./config and -./data directories. Review the file and modify as -needed.

    3. -

  3. Create Radicale configuration file as necessary

    -

    Create a new configuration file or place an existing one in the -./config directory.

    -

    Note: This section demonstrates only basic steps to -setup Radicale using docker compose. For details on -configuring Radicale, including authentication, please refer to the -documentation for Basic Configuration -or detailed Configuration

    4. -

  4. Start Radicale

    -
    $ docker compose up -d
    -

    This will start the Radicale container in detached mode.

    -

    To view the logs of the running container, run:

    -
    $ docker compose logs -f
    -

    To stop the container, run this from the current directory:

    -
    $ docker compose down
    5. -
-
-
Available tags
-
    -
  • stable: Points to the latest stable release. This is -recommended for most users.
    • -
  • Major.Minor.Patch (e.g. 3.6.1): Points to a specific -release version.
    • -
  • Major.Minor (e.g. 3.6): Tracks the latest release for a -minor version.
    • -
  • Major (e.g. 3): Tracks the latest release for a major -version.
    • -
  • nightly tags (e.g. nightly-20260206): Nightly -builds.
    • -
  • latest: Points to the most recent build. In most cases, -this is nightly.
    • -
-
-
-
-

Linux Distribution Packages

-

Radicale has been packaged for:

- -

Radicale is also available -on Cloudron.

-

If you are interested in creating packages for other Linux -distributions, read the "Contribute" -section.

-
-
-
-

About

-
-

Main Goals

-

Radicale is a complete calendar and contact storing and manipulating -solution. It can store multiple calendars and multiple address -books.

-

Calendar and contact manipulation is available from both local and -distant accesses, possibly limited through authentication policies.

-

It aims to be a lightweight solution, easy to use, easy to install, -easy to configure. As a consequence, it requires few software -dependencies and is preconfigured to work out-of-the-box.

-

Radicale is written in Python. It runs on most of the UNIX-like -platforms (Linux, *BSD, macOS) and Windows. It is free and open-source -software.

-
-
-

What Radicale Will Never Be

-

Radicale is a server, not a client. No interfaces will be created to -work with the server.

-

CalDAV and CardDAV are not perfect protocols. We think that their -main problem is their complexity, that is why we decided not to -implement the whole standard but just enough to understand some of its -client-side implementations.

-

CalDAV and CardDAV are the best open standards available, and they -are quite widely used by both clients and servers. We decided to use it, -and we will not use another one.

-
-
-

Technical Choices

-

Important global development choices have been decided before writing -code. They are very useful to understand why the Radicale Project is -different from other CalDAV and CardDAV servers, and why features are -included or not in the code.

-
-
Oriented to Calendar and Contact User Agents
-

Calendar and contact servers work with calendar and contact clients, -using a defined protocol. CalDAV and CardDAV are good protocols, -covering lots of features and use cases, but it is quite hard to -implement fully.

-

Some calendar servers have been created to follow the CalDAV and -CardDAV RFCs as much as possible: Davical, Baïkal and Darwin Calendar Server, for -example, are much more respectful of CalDAV and CardDAV and can be used -with many clients. They are very good choices if you want to develop and -test new CalDAV clients, or if you have a possibly heterogeneous list of -user agents.

-

Even if it tries it best to follow the RFCs, Radicale does not and -will not blindly implement the CalDAV and CardDAV -standards. It is mainly designed to support the CalDAV and CardDAV -implementations of different clients.

-
-
-
Simple
-

Radicale is designed to be simple to install, simple to configure, -simple to use.

-

The installation is very easy, particularly with Linux: one -dependency, no superuser rights needed, no configuration required, no -database. Installing and launching the main script out-of-the-box, as a -normal user, are often the only steps to have a simple remote calendar -and contact access.

-

Contrary to other servers that are often complicated, require high -privileges or need a strong configuration, the Radicale Server can -(sometimes, if not often) be launched in a couple of minutes, if you -follow the tutorial.

-
-
-
Lazy
-

The CalDAV RFC defines what must be done, what can be done and what -cannot be done. Many violations of the protocol are totally defined and -behaviors are given in such cases.

-

Radicale often assumes that the clients are perfect and that protocol -violations do not exist. That is why most of the errors in client -requests have undetermined consequences for the lazy server that can -reply good answers, bad answers, or even no answer.

-
-
-
-

History

-

Radicale has been started as a (free topic) stupid school project -replacing another (assigned topic) even more stupid school project.

-

At the beginning, it was just a proof-of-concept. The main goal was -to write a small, dirty and simple CalDAV server working with Lightning, -using no external libraries. That's how we created a piece of code -that's (quite) easy to understand, to use and to hack.

-

The first -lines have been added to the SVN (!) repository as I was drinking -(many) beers at the very end of 2008 (Python 2.6 and 3.0 were just -released). It's now packaged for a growing number of Linux -distributions.

-

And that was fun going from here to there thanks to you!

-
-
-
-
- diff --git a/md/master/00_index.md b/md/master/00_index.md new file mode 100644 index 000000000..1bfae5f76 --- /dev/null +++ b/md/master/00_index.md @@ -0,0 +1,36 @@ +## Translations of this page + +* [Telugu](https://github.com/Kozea/Radicale/blob/master/docs/DOCUMENTATION.te.md) + +## Getting started + +#### About Radicale + +Radicale is a small but powerful CalDAV (calendars, to-do lists) and CardDAV +(contacts) server, that: + +* Shares calendars and contact lists through CalDAV, CardDAV and HTTP. +* Supports events, todos, journal entries and business cards. +* Works out-of-the-box, no complicated setup or configuration required. +* Offers flexible authentication options. +* Can limit access by authorization. +* Can secure connections with TLS. +* Works with many + [CalDAV and CardDAV clients](#supported-clients). +* Stores all data on the file system in a simple folder structure. +* Can be extended with plugins. +* Is GPLv3-licensed free software. + +#### Installation + +Check + +* [Tutorials](#tutorials) +* [Documentation](#documentation-1) +* [Wiki on GitHub](https://github.com/Kozea/Radicale/wiki) +* [Discussions on GitHub](https://github.com/Kozea/Radicale/discussions) +* [Open and already Closed Issues on GitHub](https://github.com/Kozea/Radicale/issues?q=is%3Aissue) + +#### What's New? + +Read the [Changelog on GitHub](https://github.com/Kozea/Radicale/blob/master/CHANGELOG.md). diff --git a/md/master/01_tutorials.md b/md/master/01_tutorials.md new file mode 100644 index 000000000..8e8173f4d --- /dev/null +++ b/md/master/01_tutorials.md @@ -0,0 +1,675 @@ +## Tutorials + +### Simple 5-minute setup + +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! + +The server, configured with settings from this section, only binds to localhost +(i.e. it is not reachable over the network), and you can log in with any username and password. +When everything works, you may get a local [client](#supported-clients) +and start creating calendars and address books. +If Radicale fits your needs, it may be time for some [basic configuration](#basic-configuration) +to support remote clients and desired authentication type. + +Follow one of the chapters below depending on your operating system. + +#### Linux / \*BSD + +Hint: instead of downloading from PyPI, look for packages provided by your [distribution](#linux-distribution-packages). +They contain also startup scripts integrated into your distributions, that allow Radicale to run daemonized. + +First, make sure that **python** 3.9 or later and **pip** are installed. On most distributions it should be +enough to install the package ``python3-pip``. + +##### as normal user + +Recommended only for testing - open a console and type: + +```bash +# Run the following command to only install for the current user +python3 -m pip install --user --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz +``` + +If _install_ is not working and instead `error: externally-managed-environment` is displayed, +create and activate a virtual environment in advance. + +```bash +python3 -m venv ~/venv +source ~/venv/bin/activate +``` + +and try to install with + +```bash +python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz +``` + +Start the service manually, data is stored only for the current user + +```bash +# Start, data is stored for the current user only +python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections --auth-type none +``` + +##### as system user (or as root) + +Alternatively, you can install and run as system user or as root (not recommended): + +```bash +# Run the following command as root (not recommended) or non-root system user +# (the later may require --user in case dependencies are not available system-wide and/or virtual environment) +python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz +``` + +Start the service manually, with data stored in a system folder under `/var/lib/radicale/collections`: + +```bash +# Start, data is stored in a system folder (requires write permissions to /var/lib/radicale/collections) +python3 -m radicale --storage-filesystem-folder=/var/lib/radicale/collections --auth-type none +``` + +#### Windows + +The first step is to install Python. Go to +[python.org](https://python.org) and download the latest version of Python 3. +Then run the installer. +On the first window of the installer, check the "Add Python to PATH" box and +click on "Install now". Wait a couple of minutes, it's done! + +Launch a command prompt and type: + +```powershell +python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz +python -m radicale --storage-filesystem-folder=~/radicale/collections --auth-type none +``` + +##### Common + +Success!!! Open in your browser! +You can log in with any username and password as no authentication is required by example option `--auth-type none`. +This is **INSECURE**, see [Configuration/Authentication](#auth) for more details. + +Just note that default configuration for security reason binds the server to `localhost` (IPv4: `127.0.0.1`, IPv6: `::1`). +See [Addresses](#addresses) and [Configuration/Server](#server) for more details. + +### Basic Configuration + +Installation instructions can be found in the +[simple 5-minute setup](#simple-5-minute-setup) tutorial. + +Radicale tries to load configuration files from `/etc/radicale/config` and +`~/.config/radicale/config`. +Custom paths can be specified with the `--config /path/to/config` command +line argument or the `RADICALE_CONFIG` environment variable. +Multiple configuration files can be separated by `:` (resp. `;` on Windows). +Paths that start with `?` are optional. + +You should create a new configuration file at the desired location. +(If the use of a configuration file is inconvenient, all options can be +passed via command line arguments.) + +All configuration options are described in detail in the +[Configuration](#configuration) section. + +#### Authentication + +In its default configuration since version 3.5.0, Radicale rejects all +authentication attempts by using config option `type = denyall` (introduced +with 3.2.2) as default until explicitly configured. + +Versions before 3.5.0 did not check usernames or passwords at all, unless explicitly configured. +If such a server is reachable over a network, you should change this as soon as possible. + +First a `users` file with all usernames and passwords must be created. +It can be stored in the same directory as the configuration file. + +##### The secure way + +The `users` file can be created and managed with +[htpasswd](https://httpd.apache.org/docs/current/programs/htpasswd.html): + +Note: some OSes or distributions contain outdated versions of `htpasswd` (< 2.4.59) without +support for SHA-256 or SHA-512 (e.g. Ubuntu LTS 22). +In these cases, use `htpasswd`'s command line option `-B` for the `bcrypt` hash method (recommended), +or stay with the insecure (not recommended) MD5 (default) or SHA-1 (command line option `-s`). + +Note: support of SHA-256 and SHA-512 was introduced with 3.1.9 + +```bash +# Create a new htpasswd file with the user "user1" using SHA-512 as hash method +$ htpasswd -5 -c /path/to/users user1 +New password: +Re-type new password: +# Add another user +$ htpasswd -5 /path/to/users user2 +New password: +Re-type new password: +``` + +Authentication can be enabled with the following configuration: + +```ini +[auth] +type = htpasswd +htpasswd_filename = /path/to/users +htpasswd_encryption = autodetect +``` + +##### The simple but insecure way + +Create the `users` file by hand with lines containing the username and +password separated by `:`. Example: + +```htpasswd +user1:password1 +user2:password2 +``` + +Authentication can be enabled with the following configuration: + +```ini +[auth] +type = htpasswd +htpasswd_filename = /path/to/users +# encryption method used in the htpasswd file +htpasswd_encryption = plain +``` + +#### Addresses + +The default configuration binds the server to localhost. It cannot be reached +from other computers. This can be changed with the following configuration +options (IPv4 and IPv6): + +```ini +[server] +hosts = 0.0.0.0:5232, [::]:5232 +``` + +#### Storage + +Data is stored in the folder `/var/lib/radicale/collections`. The path can +be changed with the following configuration: + +```ini +[storage] +filesystem_folder = /path/to/storage +``` + +> **Security:** The storage folder shall not be readable by unauthorized users. +> Otherwise, they can read the calendar data and lock the storage. +> You can find OS dependent instructions in the +> [Running as a service](#running-as-a-service) section. + +#### Limits + +Radicale enforces limits on the maximum number of parallel connections, +the maximum file size (important for contacts with big photos) and the rate of +incorrect authentication attempts. Connections are terminated after a timeout. +The default values should be fine for most scenarios. + +```ini +[server] +max_connections = 20 +# 100 Megabyte +max_content_length = 100000000 +# 10 Megabyte (>= 3.5.10) +max_resource_size = 10000000 +# 30 seconds +timeout = 30 + +[auth] +# Average delay after failed login attempts in seconds +# Also used for invalid/not-existing/not-enabled share-by-token (>= 3.7.0) +delay = 1 +``` + +### Running as a service + +The method to run Radicale as a service depends on your host operating system. +Follow one of the chapters below depending on your operating system and +requirements. + +#### Linux with systemd system-wide + +Recommendation: check support by [Linux Distribution Packages](#linux-distribution-packages) +instead of manual setup / initial configuration. + +Create the **radicale** user and group for the Radicale service by running (as `root`): +```bash +useradd --system --user-group --home-dir / --shell /sbin/nologin radicale +``` + +The storage folder must be made writable by the **radicale** user by running (as `root`): +```bash +mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections +``` + +If a dedicated cache folder is configured (see option [filesystem_cache_folder](#filesystem_cache_folder)), +it also must be made writable by **radicale**. To achieve that, run (as `root`): +```bash +mkdir -p /var/cache/radicale && chown -R radicale:radicale /var/cache/radicale +```` + +> **Security:** The storage shall not be readable by others. +> To make sure this is the case, run (as `root`): +> ```bash +> chmod -R o= /var/lib/radicale/collections +> ``` + +Create the file `/etc/systemd/system/radicale.service`: + +```ini +[Unit] +Description=A simple CalDAV (calendar) and CardDAV (contact) server +After=network.target +Requires=network.target + +[Service] +ExecStart=/usr/bin/env python3 -m radicale +Restart=on-failure +User=radicale +# Deny other users access to the calendar data +UMask=0027 +# Optional security settings +PrivateTmp=true +ProtectSystem=strict +ProtectHome=true +PrivateDevices=true +ProtectKernelTunables=true +ProtectKernelModules=true +ProtectControlGroups=true +NoNewPrivileges=true +ReadWritePaths=/var/lib/radicale/ +# Replace with following in case dedicated cache folder should be used +#ReadWritePaths=/var/lib/radicale/ /var/cache/radicale/ + +[Install] +WantedBy=multi-user.target +``` + +In this system-wide implementation, Radicale will load the configuration from the file `/etc/radicale/config`. + +To enable and manage the service run: + +```bash +# Enable the service +$ systemctl enable radicale +# Start the service +$ systemctl start radicale +# Check the status of the service +$ systemctl status radicale +# View all log messages +$ journalctl --unit radicale.service +``` + +#### Linux with systemd as a user + +Create the file `~/.config/systemd/user/radicale.service`: + +```ini +[Unit] +Description=A simple CalDAV (calendar) and CardDAV (contact) server + +[Service] +ExecStart=/usr/bin/env python3 -m radicale +Restart=on-failure + +[Install] +WantedBy=default.target +``` + +In this user-specific configuration, Radicale will load the configuration from +the file `~/.config/radicale/config`. +You should set the configuration option `filesystem_folder` in the `storage` +section to something like `~/.var/lib/radicale/collections`. + +To enable and manage the service run: + +```bash +# Enable the service +$ systemctl --user enable radicale +# Start the service +$ systemctl --user start radicale +# Check the status of the service +$ systemctl --user status radicale +# View all log messages +$ journalctl --user --unit radicale.service +``` + +#### Windows with "NSSM - the Non-Sucking Service Manager" + +First install [NSSM](https://nssm.cc/) and start `nssm install` in a command +prompt. Apply the following configuration: + +* Service name: `Radicale` +* Application + * Path: `C:\Path\To\Python\python.exe` + * Arguments: `--config C:\Path\To\Config` +* I/O redirection + * Error: `C:\Path\To\Radicale.log` + +> **Security:** Be aware that the service runs in the local system account, +> you might want to change this. Managing user accounts is beyond the scope of +> this manual. Also, make sure that the storage folder and log file is not +> readable by unauthorized users. + +The log file might grow very big over time, you can configure file rotation +in **NSSM** to prevent this. + +The service is configured to start automatically when the computer starts. +To start the service manually open **Services** in **Computer Management** and +start the **Radicale** service. + +### Reverse Proxy + +When a reverse proxy is used, and Radicale should be made available at a path +below the root (such as `/radicale/`), then this path must be provided via +the `X-Script-Name` header (without a trailing `/`). The proxy must remove +the location from the URL path that is forwarded to Radicale. If Radicale +should be made available at the root of the web server (in the nginx case +using `location /`), then the setting of the `X-Script-Name` header should be +removed from the example below. + +Example **nginx** configuration extension: + +See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/nginx/ + +```nginx +location /radicale/ { # The trailing / is important! + proxy_pass http://localhost:5232; + proxy_set_header X-Script-Name /radicale; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Host $http_host; + proxy_pass_header Authorization; +} +``` + +Example **Caddy** configuration extension: + +See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/caddy/ + +``` +handle_path /radicale/* { + uri strip_prefix /radicale + reverse_proxy localhost:5232 { + # replace "HOST" with configured hostname of URL (FQDN) in client + header_up Host HOST + # replace "PORT" with configured port of URL in client + header_up X-Forwarded-Port PORT + } +} +``` + +Example **Apache** configuration extension: + +See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/apache/ + +```apache +RewriteEngine On +RewriteRule ^/radicale$ /radicale/ [R,L] + + + ProxyPass http://localhost:5232/ retry=0 + ProxyPassReverse http://localhost:5232/ + RequestHeader set X-Script-Name /radicale + RequestHeader set X-Forwarded-Port "%{SERVER_PORT}s" + RequestHeader set X-Forwarded-Proto expr=%{REQUEST_SCHEME} + = 2.4.40> + Proxy100Continue Off + + +``` + +Example **Apache .htaccess** configuration: + +```apache +DirectoryIndex disabled +RewriteEngine On +RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L] + +# Set to directory of .htaccess file: +RequestHeader set X-Script-Name /radicale +RequestHeader set X-Forwarded-Port "%{SERVER_PORT}s" +RequestHeader unset X-Forwarded-Proto + +RequestHeader set X-Forwarded-Proto "https" + +``` + +Example **lighttpd** configuration: + +```lighttpd +server.modules += ( "mod_proxy" , "mod_setenv" ) + +$HTTP["url"] =~ "^/radicale/" { + proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => "5232" )) ) + setenv.add-request-header = ( "X-Script-Name" => "/radicale" ) +} +``` + +Be reminded that Radicale's default configuration enforces limits on the +maximum number of parallel connections, the maximum file size and the rate of +incorrect authentication attempts. Connections are terminated after a timeout. + +#### Manage user accounts with the reverse proxy + +Set the configuration option `type` in the `auth` section to +`http_x_remote_user`. +Radicale uses the username provided in the `X-Remote-User` HTTP header and +disables its internal HTTP authentication. + +Example **nginx** configuration: + +```nginx +location /radicale/ { + proxy_pass http://localhost:5232/; + proxy_set_header X-Script-Name /radicale; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Remote-User $remote_user; + proxy_set_header Host $http_host; + auth_basic "Radicale - Password Required"; + auth_basic_user_file /etc/nginx/htpasswd; +} +``` + +Example **Caddy** configuration: + +``` +handle_path /radicale/* { + uri strip_prefix /radicale + basicauth { + USER HASH + } + reverse_proxy localhost:5232 { + header_up X-Script-Name /radicale + header_up X-remote-user {http.auth.user.id} + } +} +``` + +Example **Apache** configuration: + +```apache +RewriteEngine On +RewriteRule ^/radicale$ /radicale/ [R,L] + + + AuthType Basic + AuthName "Radicale - Password Required" + AuthUserFile "/etc/radicale/htpasswd" + Require valid-user + + ProxyPass http://localhost:5232/ retry=0 + ProxyPassReverse http://localhost:5232/ + = 2.4.40> + Proxy100Continue Off + + RequestHeader set X-Script-Name /radicale + RequestHeader set X-Remote-User expr=%{REMOTE_USER} + +``` + +Example **Apache .htaccess** configuration: + +```apache +DirectoryIndex disabled +RewriteEngine On +RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L] + +AuthType Basic +AuthName "Radicale - Password Required" +AuthUserFile "/etc/radicale/htpasswd" +Require valid-user + +# Set to directory of .htaccess file: +RequestHeader set X-Script-Name /radicale +RequestHeader set X-Remote-User expr=%{REMOTE_USER} +``` + +> **Security:** Untrusted clients should not be able to access the Radicale +> server directly. Otherwise, they can authenticate as any user by simply +> setting related HTTP header. This can be prevented by listening to the +> loopback interface only or local firewall rules. + +#### Secure connection between Radicale and the reverse proxy + +SSL certificates can be used to encrypt and authenticate the connection between +Radicale and the reverse proxy. First you need to 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, these values do not really matter, and you can +keep the defaults. + +```bash +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: + +```ini +[server] +ssl = True +certificate = /path/to/server_cert.pem +key = /path/to/server_key.pem +certificate_authority = /path/to/client_cert.pem +``` + +If you are using the Let's Encrypt Certbot, the configuration should look similar to this: + +```ini +[server] +ssl = True +certificate = /etc/letsencrypt/live/{Your Domain}/fullchain.pem +key = /etc/letsencrypt/live/{Your Domain}/privkey.pem +``` + +Example **nginx** configuration: + +```nginx +location /radicale/ { + proxy_pass https://localhost:5232/; + ... + # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...). + proxy_ssl_certificate /path/to/client_cert.pem; + proxy_ssl_certificate_key /path/to/client_key.pem; +} +``` + +### WSGI Server + +Radicale is compatible with the WSGI specification. + +A configuration file can be set with the `RADICALE_CONFIG` environment +variable, otherwise no configuration file is loaded and the default +configuration is used. + +Example **uWSGI** configuration: + +```ini +[uwsgi] +http-socket = 127.0.0.1:5232 +processes = 8 +plugin = python3 +module = radicale +env = RADICALE_CONFIG=/etc/radicale/config +``` + +Example **Gunicorn** configuration: + +```bash +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 `auth` section to `remote_user`. +This way Radicale uses the username provided by the WSGI server and disables +its internal authentication over HTTP. + +### Versioning collections with Git + +This tutorial describes how to keep track of all changes to calendars and +address books with **git** (or any other version control system). + +The repository must be initialized in the collection base directory +of the user running `radicale` daemon. + +```bash +## assuming "radicale" user is starting "radicale" service +# change to user "radicale" +su -l -s /bin/bash radicale + +# change to collection base directory defined in [storage] -> filesystem_folder +# assumed here /var/lib/radicale/collections +cd /var/lib/radicale/collections + +# initialize git repository +git init + +# set user and e-mail, here minimum example +git config user.name "$USER" +git config user.email "$USER@$HOSTNAME" + +# define ignore of cache/lock/tmp files +cat <<'END' >.gitignore +.Radicale.cache +.Radicale.lock +.Radicale.tmp-* +END +``` + +The configuration option `hook` in the `storage` section must be set to +the following command: + +```bash +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. + +Log of `git` can be investigated using + +```bash +su -l -s /bin/bash radicale +cd /var/lib/radicale/collections +git log +``` + +In case of problems, make sure you run radicale with ``--debug`` switch and +inspect the log output. For more information, please visit +[section on logging](#logging-overview). + +Reason for problems can be + - SELinux status -> check related audit log + - problematic file/directory permissions + - command is not fond or cannot be executed or argument problem diff --git a/md/master/02_documentation.md b/md/master/02_documentation.md new file mode 100644 index 000000000..54f934138 --- /dev/null +++ b/md/master/02_documentation.md @@ -0,0 +1,1517 @@ +## Documentation + +### Options + +#### General Options + +##### --version + +Print version + +##### --verify-storage + +Verification of local collections storage + +##### --verify-item + +_(>= 3.6.0)_ + +Verification of a particular item file + +##### --verify-sharing + +_(>= 3.7.0)_ + +Verification of local sharing database + +##### -C|--config + +Load one or more specified config file(s) + +##### -D|--debug + +Turns log level to debug + +#### Configuration Options + +Each supported option from config file can be provided/overridden by command line +replacing `_` with `-` and prepending the section followed by a `-`, e.g. + +``` +[logging] +backtrace_on_debug = False +``` + +can be enabled using `--logging-backtrace-on-debug=true` on command line. + +### Configuration + +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. + +An example configuration file looks like: + +```ini +[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 with the `--config /path/to/config` command +line argument or the `RADICALE_CONFIG` environment variable. +Multiple configuration files can be separated by `:` (resp. `;` on Windows). +Paths that start with `?` are optional. + +The same example configuration via command line arguments looks like: + +```bash +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. + +You can also use command-line options in startup scripts as shown in the following examples: + +```bash +## simple variable containing multiple options +RADICALE_OPTIONS="--logging-level=debug --config=/etc/radicale/config --logging-request-header-on-debug --logging-rights-rule-doesnt-match-on-debug" +/usr/bin/radicale $RADICALE_OPTIONS + +## variable as array method #1 +RADICALE_OPTIONS=("--logging-level=debug" "--config=/etc/radicale/config" "--logging-request-header-on-debug" "--logging-rights-rule-doesnt-match-on-debug") +/usr/bin/radicale ${RADICALE_OPTIONS[@]} + +## variable as array method #2 +RADICALE_OPTIONS=() +RADICALE_OPTIONS+=("--logging-level=debug") +RADICALE_OPTIONS+=("--config=/etc/radicale/config") +/usr/bin/radicale ${RADICALE_OPTIONS[@]} +``` + +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` + +##### delay_on_error + +_(>= 3.7.0)_ + +Base delay in case of error 5xx response (seconds) + +Default: `1` + +##### max_content_length + +The maximum size of the request body. (bytes) + +Default: `100000000` (100 Mbyte) + +In case of using a reverse proxy in front of check also there related option. + +##### max_resource_size + +_(>= 3.5.10)_ + +The maximum size of a resource. (bytes) + +Default: `10000000` (10 Mbyte) + +Limited to 80% of max_content_length to cover plain base64 encoded payload. + +Announced to clients requesting "max-resource-size" via PROPFIND. + +##### timeout + +Socket timeout. (seconds) + +Default: `30` + +##### ssl + +Enable transport layer encryption. + +Default: `False` + +##### certificate + +Path of the SSL certificate. + +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) + +#### [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 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](https://httpd.apache.org/docs/current/programs/htpasswd.html) + 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_remote_user` _(>= 3.5.9)_ + Takes the username from the Remote-User HTTP header `HTTP_REMOTE_USER` 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. + +* `http_x_remote_user` + Takes the username from the X-Remote-User HTTP header `HTTP_X_REMOTE_USER` 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](https://httpd.apache.org/docs/current/programs/htpasswd.html) +or similar to generate this file. + +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: + + ```htpasswd + 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 or missing login attempts or denied access. + +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 +```ini +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_security + +_(>= 3.5.2)_ + +Use encryption on the LDAP connection. + +One of +* `none` +* `tls` +* `starttls` + +Default: `none` + +##### ldap_ssl_verify_mode + +_(>= 3.3.0)_ + +Certificate verification mode for tls and starttls. + +One of +* `NONE` +* `OPTIONAL` +* `REQUIRED`. + +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 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](https://github.com/Kozea/Radicale/wiki/LDAP-authentication) 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 search 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: +* `AF_UNIX` +* `AF_INET` +* `AF_INET6` + +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 +* [address]:port (for IPv5 addresses) +* imap.server.tld + +Default: `localhost` + +##### imap_security + +_(>= 3.4.1)_ + +Secure the IMAP connection: + +One of: +* `tls` +* `starttls` +* `none` + +Default: `tls` + +##### oauth2_token_endpoint + +_(>= 3.5.0)_ + +Endpoint URL for the OAuth2 token + +Default: (unset) + +##### oauth2_client_id + +_(>= 3.7.0)_ + +Client ID used to request the Auth2 token + +Default: `radicale` + +##### oauth2_client_secret + +_(>= 3.7.0)_ + +Client secret used to request the Auth2 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` + + +#### [rights] + +##### type + +Authorization backend that is used to check the access rights to collections. + +The default and recommended backend is `owner_only`. If access to calendars +and address books outside the user's collection directory (that's `/username/`) +is granted, clients will not detect these collections automatically and +will not show them to the users. +Choosing any other authorization backend is only useful if you access +calendars and address books directly via URL. + +Available backends are: + +* `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 + +Name of the file containing the authorization rules for the `from_file` backend. +See the [Rights](#authorization-and-rights) section for details. + +Default: `/etc/radicale/rights` + +##### permit_delete_collection + +_(>= 3.1.9)_ + +Global permission to delete complete collections. +* If `False` it can be explicitly granted per collection by *rights* permissions: `D` +* If `True` it can be explicitly forbidden per collection by *rights* permissions: `d` + +Default: `True` + +##### permit_overwrite_collection + +_(>= 3.3.0)_ + +Global permission to overwrite complete collections. +* If `False` it can be explicitly granted per collection by *rights* permissions: `O` +* If `True` it can be explicitly forbidden per collection by *rights* permissions: `o` + +Default: `True` + +#### [storage] + +##### type + +Backend used to store data. + +Available backends are: + +* `multifilesystem` + Stores the data in the filesystem. + +* `multifilesystem_nolock` + The `multifilesystem` backend without file-based locking. + Must only be used with a single process. + +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` + +##### strict_preconditions + +_(>= 3.5.8)_ + +Strict preconditions check on PUT in case item already exists [RFC6352#9.2](https://www.rfc-editor.org/rfc/rfc6352#section-9.2) + +Default: `False` + +##### validate_user_value + +_(>= 3.7.2)_ + +Validate user value content + +Available types are: +* `none` +* `minimal` (control and some special chars) +* `unicode-letter` (unicode letters) +* `no-unicode` (no unicode) +* `strict` (reduced ASCII set) + +Default: `minimum` + +##### validate_path_type + +_(>= 3.7.2)_ + +Validate path value content + +* `none` +* `minimal` (control and some special chars) +* `unicode-letter` (unicode letters) +* `no-unicode` (no unicode) +* `strict` (reduced ASCII set) + +Default: `minimum` + +##### hook + +Command that is run after changes to storage. See the +[Versioning collections with Git](#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: +```json +{ + "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) + +#### [web] + +##### type + +The backend that provides the web interface of Radicale. + +Available backends are: + +* `none` + Simply shows the message "Radicale works!". + +* `internal` + Allows creation and management of address books and calendars. + +Default: `internal` + +#### [logging] + +##### level + +Set the logging level. + +Available levels are: +* `trace` _(>= 3.7.1)_ +* `debug` +* `info` +* `notice` _(>= 3.7.1)_ +* `warning` +* `error` +* `critical` +* `alert` _(>= 3.7.1)_ + +Default: `warning` _(< 3.2.0)_ / `info` _(>= 3.2.0)_ + +##### limit_content + +_(>= 3.7.0)_ + +Limit content of wrapped text (chars) + +Default: `3000` + +##### trace_on_debug + +_(> 3.5.4)_ && _(< 3.7.1)_ + +Do not filter debug messages starting with 'TRACE' + +Default: `False` + +##### trace_filter + +_(> 3.5.4)_ && _(< 3.7.1)_ + +Filter debug messages starting with 'TRACE/' + +Prerequisite: `trace_on_debug = True` + +_(>= 3.7.1)_ + +Filter trace messages starting with '' + +Prerequisite: `level = trace` + +Default: (empty) + +##### mask_passwords + +Do not include passwords in logs. + +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 header on `level = debug` + +Default: `False` + +##### request_content_on_debug + +_(>= 3.2.2)_ + +Log request content (body) on `level = debug` + +Default: `False` + +##### response_header_on_debug + +_(>= 3.5.10)_ + +Log response header on `level = debug` + +Default: `False` + +##### response_content_on_debug + +_(>= 3.2.2)_ + +Log response content (body) on `level = debug` + +Default: `False` + +##### rights_rule_doesnt_match_on_debug + +_(>= 3.2.3)_ + +Log rights rule which doesn't match on `level = debug` + +Default: `False` + +##### storage_cache_actions_on_debug + +_(>= 3.3.2)_ + +Log storage cache actions on `level = debug` + +Default: `False` + +##### profiling_per_request + +_(>= 3.5.10)_ + +Log profiling data on level=info + +Default: `none` + +One of +* `none` (disabled) +* `per_request` (above minimum duration) +* `per_request_method` (regular interval) + +##### profiling_per_request_min_duration + +_(>= 3.5.10)_ + +Log profiling data per request minimum duration (seconds) before logging, otherwise skip + +Default: `3` + +##### profiling_per_request_header + +_(>= 3.5.10)_ + +Log profiling request header (if passing minimum duration) + +Default: `False` + +##### profiling_per_request_xml + +_(>= 3.5.10)_ + +Log profiling request XML (if passing minimum duration) + +Default: `False` + +##### profiling_per_request_method_interval + +_(>= 3.5.10)_ + +Log profiling data per method interval (seconds) +Triggered by request, not active on idle systems + +Default: `600` + +##### profiling_top_x_functions + +_(>= 3.5.10)_ + +Log profiling top X functions (limit) + +Default: `10` + +#### [headers] + +This section can be used to specify additional HTTP headers that will be sent to clients. + +An example to relax the same-origin policy: + +```ini +Access-Control-Allow-Origin = * +``` + +An example to set CSP to disallow execution of unknown javascript: + +```ini +Content-Security-Policy = default-src 'self'; object-src 'none' +``` + + +#### [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: +* `none` +* `tls` +* `starttls` + +Default: `none` + +##### smtp_ssl_verify_mode + +_(>= 3.5.5)_ + +The certificate verification mode for tls and starttls. + +One of: +* `NONE` +* `OPTIONAL` +* `REQUIRED` + +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. +``` + +#### [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 +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 + +#### [sharing] + +_(>= 3.7.0)_ + +See also [Collection Sharing](https://github.com/Kozea/Radicale/blob/master/SHARING.md). + +##### type + +_(>= 3.7.0)_ + +Sharing database type + +One of: + * `none` + * `csv` + * `files` + +Default: `none` (implicit disabling the feature) + +##### database_path + +_(>= 3.7.0)_ + +Sharing database path + +Default: + * type `csv`: `(filesystem_folder)/collection-db/sharing.csv` + * type `files`: `(filesystem_folder)/collection-db/files` + +##### collection_by_token + +_(>= 3.7.0)_ + +Share collection by token + +Default: `false` + +##### collection_by_map + +_(>= 3.7.0)_ + +Share collection by map + +Default: `false` + +##### permit_create_token + +_(>= 3.7.0)_ + +Permit create of token-based sharing + +Default: `false` + +* If `False` it can be explicitly granted by *rights* permissions: `T` +* If `True` it can be explicitly forbidden by *rights* permissions: `t` + +##### permit_create_map + +_(>= 3.7.0)_ + +Permit create of map-based sharing + +Default: `false` + +* If `False` it can be explicitly granted by *rights* permissions: `M` +* If `True` it can be explicitly forbidden by *rights* permissions: `m` + +##### permit_properties_overlay + +_(>= 3.7.0)_ + +Permit (limited) properties overlay by user of shared collection + +Default: `false` + +* If `False` it can be explicitly granted by *share* permissions: `P` +* If `True` it can be explicitly forbidden by *share* permissions: `p` + +##### enforce_properties_overlay + +_(>= 3.7.0)_ + +Enforce properties overlay even on write access + +Default: `true` + +* If `False` it can be explicitly enforced by *share* permissions: `E` +* If `True` it can be explicitly forbidden by *share* permissions: `e` + +##### default_permissions_create_token + +Default permissions for create token-based sharing + +Default: `r` + +Supported: `rwEePp` + +##### default_permissions_create_map + +Default permissions for map-based sharing + +Default: `r` + +Supported: `rwEePp` diff --git a/md/master/03_supported-clients.md b/md/master/03_supported-clients.md new file mode 100644 index 000000000..d3c621949 --- /dev/null +++ b/md/master/03_supported-clients.md @@ -0,0 +1,158 @@ +## Supported Clients + +Radicale has been tested with: + +* [Android](https://android.com/) with + [DAVx⁵](https://www.davx5.com/) (formerly DAVdroid), +* [OneCalendar](https://www.onecalendar.nl/) +* [GNOME Calendar](https://wiki.gnome.org/Apps/Calendar), + [Contacts](https://wiki.gnome.org/Apps/Contacts) and + [Evolution](https://wiki.gnome.org/Apps/Evolution) +* [KDE PIM Applications](https://kontact.kde.org/), + [KDE Merkuro](https://apps.kde.org/de/merkuro/) +* [Mozilla Thunderbird](https://www.mozilla.org/thunderbird/) ([Thunderbird/Radicale](https://github.com/Kozea/Radicale/wiki/Client-Thunderbird)) with + [CardBook](https://addons.mozilla.org/thunderbird/addon/cardbook/) and + [Lightning](https://www.mozilla.org/projects/calendar/) +* [InfCloud](https://www.inf-it.com/open-source/clients/infcloud/) ([InfCloud/Radicale](https://github.com/Kozea/Radicale/wiki/Client-InfCloud)), + [CalDavZAP](https://www.inf-it.com/open-source/clients/caldavzap/), + [CardDavMATE](https://www.inf-it.com/open-source/clients/carddavmate/) and + [Open Calendar](https://github.com/algoo/open-calendar/) +* [pimsync](https://pimsync.whynothugo.nl/) ([pimsync/Radicale](https://github.com/Kozea/Radicale/wiki/Client-pimsync)) + +Many clients do not support the creation of new calendars and address books. +You can use Radicale's web interface +(e.g. ) to create and manage address books and calendars. + +In some clients, it is sufficient to simply enter the URL of the Radicale server +(e.g. `http://localhost:5232`) and your username. In others, you have to +enter the URL of the collection directly (e.g. `http://localhost:5232/user/calendar`). + +Some clients (notably macOS's Calendar.app) may silently refuse to include +account credentials over unsecured HTTP, leading to unexpected authentication +failures. In these cases, you want to make sure the Radicale server is +[accessible over HTTPS](#ssl). + +#### DAVx⁵ + +Enter the URL of the Radicale server (e.g. `http://localhost:5232`) and your +username. DAVx⁵ will show all existing calendars and address books and you +can create new ones. + +#### OneCalendar + +When adding account, select CalDAV account type, then enter username, password and the +Radicale server (e.g. `https://yourdomain:5232`). OneCalendar will show all +existing calendars and (FIXME: address books), you need to select which ones +you want to see. OneCalendar supports many other server types too. + +#### GNOME Calendar, Contacts + +GNOME 46 added CalDAV and CardDAV support to _GNOME Online Accounts_. + +Open GNOME Settings, navigate to _Online Accounts_ > _Connect an Account_ > _Calendar, Contacts and Files_. +Enter the URL (e.g. `https://example.com/radicale`) and your credentials then click _Sign In_. +In the pop-up dialog, turn off _Files_. After adding Radicale in _GNOME Online Accounts_, +it should be available in GNOME Contacts and GNOME Calendar. + +#### Evolution + +In **Evolution** add a new calendar and address book respectively with WebDAV. +Enter the URL of the Radicale server (e.g. `http://localhost:5232`) and your +username. Clicking on the search button will list the existing calendars and +address books. + +Adding CalDAV and CardDAV accounts in Evolution will automatically make them +available in GNOME Contacts and GNOME Calendar. + +#### KDE PIM Applications + +In **Kontact** add a _DAV Groupware resource_ to Akonadi under +_Settings > Configure Kontact > Calendar > General > Calendars_, +select the protocol (CalDAV or CardDAV), add the URL to the Radicale collections +and enter the credentials. After synchronization of the calendar resp. +addressbook items, you can manage them in Kontact. + +#### Thunderbird + +Add a new calendar on the network. Enter your username and the URL of the +Radicale server (e.g. `http://localhost:5232`). After asking for your password, +it will list the existing calendars. + +##### Address books with CardBook add-on + +Add a new address book on the network with CardDAV. Enter the URL of the +Radicale server (e.g. `http://localhost:5232`) and your username and password. +It will list your existing address books. + +#### InfCloud, CalDavZAP and CardDavMATE + +You can integrate InfCloud into Radicale's web interface with by simply +downloading the latest package from [InfCloud](https://www.inf-it.com/open-source/clients/infcloud/) +and extract the content into a folder named `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](https://github.com/Kozea/Radicale/wiki/Client-InfCloud). + +#### Command line + +This is not the recommended way of creating and managing your calendars and +address books. Use Radicale's web interface or a client with support for it +(e.g. **DAVx⁵**). + +To create a new calendar run something like: + +```bash +$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \ +' + + + + + + + + + + + + + Calendar + Example calendar + #ff0000ff + + +' +``` + +To create a new address book run something like: + +```bash +$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \ +' + + + + + + + + Address book + Example address book + + +' +``` + +The collection `/USERNAME` will be created automatically, when the user +authenticates to Radicale for the first time. Clients with automatic discovery +of collections will only show calendars and address books that are direct +children of the path `/USERNAME/`. + +Delete the collections by running something like: + +```bash +curl -u user -X DELETE 'http://localhost:5232/user/calendar' +``` + +Note: requires config/option `permit_delete_collection = True` diff --git a/md/master/04_internals.md b/md/master/04_internals.md new file mode 100644 index 000000000..86f6f90b9 --- /dev/null +++ b/md/master/04_internals.md @@ -0,0 +1,387 @@ +## Internals + +### Authorization and Rights + +This section describes the format of the rights file for the `from_file` +authentication backend. The configuration option `file` in the `rights` +section must point to the rights file. + +The recommended rights method is `owner_only`. If access is granted +to calendars and address books outside the home directory of users +(that's `/USERNAME/`), clients will not detect these collections automatically, +and will not show them to the users. +This is only useful if you access calendars and address books directly via URL. + +An example rights file: + +```ini +# 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 collection. Permissions from the first +matching section are used. If no section matches, access gets denied. + +The username is empty for anonymous users. Therefore, the regex `.+` only +matches authenticated users and `.*` matches everyone (including anonymous +users). + +The path of the collection is separated by `/` and has no leading or trailing +`/`. Therefore, the path of the root collection is empty. + +In the `collection` regex you can use `{user}` and get groups from the `user` +regex with `{0}`, `{1}`, etc. + +In consequence of the parameter substitution you have to write `{{` and `}}` +if you want to use regular curly braces in the `user` and `collection` regexes. + +The following `permissions` are recognized: + +* **R:** read collections (excluding address books and calendars) +* **r:** read address book and calendar collections +* **i:** subset of **r** that only allows direct access via HTTP method GET + (CalDAV/CardDAV is susceptible to expensive search requests) +* **W:** write collections (excluding address books and calendars) +* **w:** write address book and calendar collections +* **D:** allow deleting a collection in case `permit_delete_collection=False` _(>= 3.3.0)_ +* **d:** deny deleting a collection in case `permit_delete_collection=True` _(>= 3.3.0)_ +* **O:** allow overwriting a collection in case `permit_overwrite_collection=False` _(>= 3.3.0)_ +* **o:** deny overwriting a collection in case `permit_overwrite_collection=True` _(>= 3.3.0)_ +* **T:** permit create of token-based sharing of collection in case `permit_create_token=False` _(>= 3.7.0)_ +* **t:** deny create of token-based sharing of collection in case `permit_create_token=True` _(>= 3.7.0)_ +* **M:** permit create of map-based sharing of collection in case `permit_create_map= False` _(>= 3.7.0)_ +* **m:** deny create of map-based sharing of collection in case `permit_create_map=True` _(>= 3.7.0)_ + +### Storage + +This document describes the layout and format of the file system storage, +the `multifilesystem` backend. + +It is safe to access and manipulate the data by hand or with scripts. +Scripts can be invoked manually, periodically (e.g. using +[cron](https://manpages.debian.org/unstable/cron/cron.8.en.html)) or after each +change to the storage with the configuration option `hook` in the `storage` +section (e.g. [Versioning collections with Git](#versioning-collections-with-git)). + +#### Layout + +The file system comprises the following files and folders: +* `.Radicale.lock`: The lock file for locking the storage. +* `collection-root`: This folder contains all collections and items. + +Each collection is represented by a folder. This folder may contain the file +`.Radicale.props` with all WebDAV properties of the collection encoded +as [JSON](https://en.wikipedia.org/wiki/JSON). + +Each item in a calendar or address book collection is represented by +a file containing the item's iCalendar resp. vCard data. + +All files and folders, whose names start with a dot but not with `.Radicale.` +(internal files) are ignored. + +Syntax errors in any of the files will cause all requests accessing +the faulty data to fail. The logging output should contain the names of the +culprits. + +Caches and sync-tokens are stored in the `.Radicale.cache` folder inside of +collections. +This folder may be created or modified, while the storage is locked for shared +access. +In theory, it should be safe to delete the folder. Caches will be recreated +automatically and clients will be told that their sync-token is not valid +anymore. + +You may encounter files or folders that start with `.Radicale.tmp-`. +Radicale uses them for atomic creation and deletion of files and folders. +They should be deleted after requests are finished but it is possible that +they are left behind when Radicale or the computer crashes. +You can safely delete them. + +#### Locking + +When the data is accessed by hand or by an externally invoked script, +the storage must be locked. The storage can be locked for exclusive or +shared access. It prevents Radicale from reading or writing the file system. +The storage is locked with exclusive access while the `hook` runs. + +##### Linux shell scripts + +Use the +[flock](https://manpages.debian.org/unstable/util-linux/flock.1.en.html) +utility to acquire exclusive or shared locks for the commands you want to run +on Radicale's data. + +```bash +# Exclusive lock for COMMAND +$ flock --exclusive /path/to/storage/.Radicale.lock COMMAND +# Shared lock for COMMAND +$ flock --shared /path/to/storage/.Radicale.lock COMMAND +``` + +##### Linux and MacOS + +Use the +[flock](https://manpages.debian.org/unstable/manpages-dev/flock.2.en.html) +syscall. Python provides it in the +[fcntl](https://docs.python.org/3/library/fcntl.html#fcntl.flock) module. + +##### Windows + +Use +[LockFile](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365202%28v=vs.85%29.aspx) +for exclusive access or +[LockFileEx](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365203%28v=vs.85%29.aspx) +which also supports shared access. Setting `nNumberOfBytesToLockLow` to `1` +and `nNumberOfBytesToLockHigh` to `0` works. + +#### Manually creating collections + +To create a new collection, you need to create the corresponding folder in the +file system storage (e.g. `collection-root/user/calendar`). +To indicate to Radicale and clients that the collection is a calendar, you have to +create the file ``.Radicale.props`` with the following content in the folder: + +```json +{"tag": "VCALENDAR"} +``` + +The calendar is now available at the URL path (e.g. ``/user/calendar``). +For address books ``.Radicale.props`` must contain: + +```json +{"tag": "VADDRESSBOOK"} +``` + +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 `/USERNAME/`. + +Delete collections by deleting the corresponding folders. + +### Logging overview + +Radicale logs to `stderr`. The verbosity of the log output can be controlled +with `--debug` command line argument or the `level` configuration option in +the [logging](#logging) section. + +### Architecture + +Radicale is a small piece of software, but understanding it is not as +easy as it seems. But don't worry, reading this short section is enough to +understand what a CalDAV/CardDAV server is, and how Radicale's code is +organized. + +#### Protocol overview + +Here is a simple overview of the global architecture for reaching a calendar or +an address book through network: + +| Part | Layer | Protocol or Format | +|----------|--------------------------|------------------------------------| +| Server | Calendar/Contact Storage | iCal/vCard | +| '' | Calendar/Contact Server | CalDAV/CardDAV Server | +| Transfer | Network | CalDAV/CardDAV (HTTP + TLS) | +| Client | Calendar/Contact Client | CalDAV/CardDAV Client | +| '' | GUI | Terminal, GTK, Web interface, etc. | + +Radicale is **only the server part** of this architecture. + +Please note: + +* CalDAV and CardDAV are extension protocols of WebDAV, +* WebDAV is an extension of the HTTP protocol. + +Radicale being a CalDAV/CardDAV server, can also be seen as a special WebDAV +and HTTP server. + +Radicale is **not the client part** of this architecture. It means that +Radicale never draws calendars, address books, events and contacts on the +screen. It only stores them and give the possibility to share them online with +other people. + +If you want to see or edit your events and your contacts, you have to use +another software called a client, that can be a "normal" applications with +icons and buttons, a terminal or another web application. + +#### Code Architecture + +The ``radicale`` package offers the following modules. + +* `__init__` + : Contains the entry point for WSGI. + +* `__main__` + : Provides the entry point for the ``radicale`` executable and + includes the command line parser. It loads configuration files from + the default (or specified) paths and starts the internal server. + +* `app` + : This is the core part of Radicale, with the code for the CalDAV/CardDAV + server. The code managing the different HTTP requests according to the + CalDAV/CardDAV specification can be found here. + +* `auth` + : Used for authenticating users based on username and password, mapping + usernames to internal users and optionally retrieving credentials from + the environment. + +* `config` + : Contains the code for managing configuration and loading settings from files. + +* `ìtem` + : Internal representation of address book and calendar entries. Based on + [VObject](https://github.com/py-vobject/vobject/). + +* `log` + : The logger for Radicale based on the default Python logging module. + +* `rights` + : This module is used by Radicale to manage access rights to collections, + address books and calendars. + +* `server` +: The integrated HTTP server for standalone use. + +* `storage` + : This module contains the classes representing collections in Radicale and + the code for storing and loading them in the filesystem. + +* `sharing` + : This module contains the classes representing collection sharing. _(>= 3.7.0)_ + +* `web` + : This module contains the web interface. + +* `utils` + : Contains general helper functions. + +* `httputils` + : Contains helper functions for working with HTTP. + +* `pathutils` + : Helper functions for working with paths and the filesystem. + +* `xmlutils` + : Helper functions for working with the XML part of CalDAV/CardDAV requests + and responses. It's based on the ElementTree XML API. + +### Plugins + +Radicale can be extended by plugins for authentication, rights management and +storage. Plugins are **python** modules. + +#### Getting started with plugin development + +To get started we walk through the creation of a simple authentication +plugin, that accepts login attempts with a static password. + +The easiest way to develop and install **python** modules is +[Distutils](https://docs.python.org/3/distutils/setupscript.html). +For a minimal setup create the file `setup.py` with the following content +in an empty folder: + +```python +#!/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: + +```python +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`: + +```bash +python3 -m pip install . +``` + +To make use this great creation in Radicale, set the configuration option +`type` in the `auth` section to `radicale_static_password_auth`: + +```ini +[auth] +type = radicale_static_password_auth +password = secret +``` + +You can uninstall the module with: + +```bash +python3 -m pip uninstall radicale_static_password_auth +``` + +#### Authentication plugins + +This plugin type is used to check login credentials. +The module must contain a class `Auth` that extends +`radicale.auth.BaseAuth`. Take a look at the file `radicale/auth/__init__.py` +in Radicale's source code for more information. + +#### Rights management plugins + +This plugin type is used to check if a user has access to a path. +The module must contain a class `Rights` that extends +`radicale.rights.BaseRights`. Take a look at the file +`radicale/rights/__init__.py` in Radicale's source code for more information. + +#### Web plugins + +This plugin type is used to provide the web interface for Radicale. +The module must contain a class `Web` that extends +`radicale.web.BaseWeb`. Take a look at the file `radicale/web/__init__.py` in +Radicale's source code for more information. + +#### Storage plugins + +This plugin is used to store collections and items. +The module must contain a class `Storage` that extends +`radicale.storage.BaseStorage`. Take a look at the file +`radicale/storage/__init__.py` in Radicale's source code for more information. diff --git a/md/master/05_contribute.md b/md/master/05_contribute.md new file mode 100644 index 000000000..3b0ff857c --- /dev/null +++ b/md/master/05_contribute.md @@ -0,0 +1,17 @@ +## Contribute + +#### Report Bugs + +Found a bug? Want a new feature? Report a new issue on the +[Radicale bug-tracker](https://github.com/Kozea/Radicale/issues). + +#### Hack + +Interested in hacking? Feel free to clone the +[git repository on GitHub](https://github.com/Kozea/Radicale) if you want to +add new features, fix bugs or update the documentation. + +#### Documentation + +To change or complement the documentation create a pull request to +[DOCUMENTATION.md](https://github.com/Kozea/Radicale/blob/master/DOCUMENTATION.md). diff --git a/md/master/06_download.md b/md/master/06_download.md new file mode 100644 index 000000000..30f210a8d --- /dev/null +++ b/md/master/06_download.md @@ -0,0 +1,131 @@ +## Download + +#### PyPI + +Radicale is [available on PyPI](https://pypi.python.org/pypi/Radicale/). To +install, just type as superuser: + +```bash +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](https://github.com/Kozea/Radicale/), or install it +directly with: + +```bash +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](https://github.com/Kozea/Radicale/tarball/master). + +#### Source Packages + +You can find the source packages of all releases on +[GitHub](https://github.com/Kozea/Radicale/releases). + +#### Docker + +Radicale is available as a Docker image for platforms `linux/amd64` and `linux/arm64` on: + +* [Docker Hub](https://hub.docker.com/r/kozea/radicale), and +* [GitHub's Container Registry](https://github.com/Kozea/Radicale/pkgs/container/radicale) + +Here are the steps to install Radicale via Docker Compose: + +1. Create required directories + + Create a directory to store the data, configuration and compose file. + + For example, assuming `./radicale`: + + ```bash + $ mkdir radicale + $ cd radicale + ``` + Create directories to store data and configuration. + + For example, assuming data directory as `./data` and configuration directory as `./config`: + + ```bash + $ mkdir config data + ``` + +2. Download the compose file + + ```bash + $ wget https://raw.githubusercontent.com/Kozea/Radicale/refs/heads/master/compose.yaml + ``` + + The compose file assumes `./config` and `./data` directories. Review the file and modify as needed. + +3. Create Radicale configuration file as necessary + + Create a new configuration file or place an existing one in the `./config` directory. + + + **Note**: This section demonstrates only basic steps to setup Radicale using `docker compose`. For details on configuring Radicale, including authentication, please refer to the documentation for [Basic Configuration](#basic-configuration) or detailed [Configuration](#configuration) + + +4. Start Radicale + + ```bash + $ docker compose up -d + ``` + + This will start the Radicale container in detached mode. + + + To view the logs of the running container, run: + + ```bash + $ docker compose logs -f + ``` + + To stop the container, run this from the current directory: + + ```bash + $ docker compose down + ``` + +##### Available tags + +* `stable`: Points to the latest stable release. This is recommended for most users. +* Major.Minor.Patch (e.g. `3.6.1`): Points to a specific release version. +* Major.Minor (e.g. `3.6`): Tracks the latest release for a minor version. +* Major (e.g. `3`): Tracks the latest release for a major version. +* nightly tags (e.g. `nightly-20260206`): Nightly builds. +* `latest`: Points to the most recent build. In most cases, this is nightly. + +#### Linux Distribution Packages + +Radicale has been packaged for: + +* [ArchLinux](https://www.archlinux.org/packages/community/any/radicale/) by + David Runge +* [Debian](https://packages.debian.org/radicale) by Jonas Smedegaard +* [Gentoo](https://packages.gentoo.org/packages/www-apps/radicale) + by René Neumann, Maxim Koltsov and Manuel Rüger +* [Fedora/EnterpriseLinux](https://src.fedoraproject.org/rpms/radicale) by Jorti + and Peter Bieringer +* [Mageia](http://madb.mageia.org/package/show/application/0/name/radicale) + by Jani Välimaa +* [OpenBSD](http://openports.se/productivity/radicale) by Sergey Bronnikov, + Stuart Henderson and Ian Darwin +* [openSUSE](http://software.opensuse.org/package/Radicale?search_term=radicale) + by Ákos Szőts and Rueckert +* [PyPM](http://code.activestate.com/pypm/radicale/) +* [Slackware](http://schoepfer.info/slackware.xhtml#packages-network) by + Johannes Schöpfer +* [Trisquel](http://packages.trisquel.info/search?searchon=names&keywords=radicale) +* [Ubuntu](http://packages.ubuntu.com/radicale) by the MOTU and Jonas + Smedegaard + +Radicale is also +[available on Cloudron](https://cloudron.io/button.html?app=org.radicale.cloudronapp2). + +If you are interested in creating packages for other Linux distributions, read +the ["Contribute" section](#contribute). diff --git a/md/master/07_about.md b/md/master/07_about.md new file mode 100644 index 000000000..3ebd53e3d --- /dev/null +++ b/md/master/07_about.md @@ -0,0 +1,97 @@ +## About + +#### Main Goals + +Radicale is a complete calendar and contact storing and manipulating +solution. It can store multiple calendars and multiple address books. + +Calendar and contact manipulation is available from both local and distant +accesses, possibly limited through authentication policies. + +It aims to be a lightweight solution, easy to use, easy to install, easy to +configure. As a consequence, it requires few software dependencies and is +preconfigured to work out-of-the-box. + +Radicale is written in Python. It runs on most of the UNIX-like platforms +(Linux, \*BSD, macOS) and Windows. It is free and open-source software. + +#### What Radicale Will Never Be + +Radicale is a server, not a client. No interfaces will be created to work with +the server. + +CalDAV and CardDAV are not perfect protocols. We think that their main problem +is their complexity, that is why we decided not to implement the whole standard +but just enough to understand some of its client-side implementations. + +CalDAV and CardDAV are the best open standards available, and they are quite +widely used by both clients and servers. We decided to use it, and we will not +use another one. + +#### Technical Choices + +Important global development choices have been decided before writing +code. They are very useful to understand why the Radicale Project is different +from other CalDAV and CardDAV servers, and why features are included or not in +the code. + +##### Oriented to Calendar and Contact User Agents + +Calendar and contact servers work with calendar and contact clients, using a +defined protocol. CalDAV and CardDAV are good protocols, covering lots of +features and use cases, but it is quite hard to implement fully. + +Some calendar servers have been created to follow the CalDAV and CardDAV RFCs +as much as possible: [Davical](http://www.davical.org/), +[Baïkal](http://sabre.io/baikal/) and +[Darwin Calendar Server](http://trac.calendarserver.org/), for example, are +much more respectful of CalDAV and CardDAV and can be used with many clients. +They are very good choices if you want to develop and test new CalDAV clients, +or if you have a possibly heterogeneous list of user agents. + +Even if it tries it best to follow the RFCs, Radicale does not and **will not** +blindly implement the CalDAV and CardDAV standards. It is mainly designed to +support the CalDAV and CardDAV implementations of different clients. + +##### Simple + +Radicale is designed to be simple to install, simple to configure, simple to +use. + +The installation is very easy, particularly with Linux: one dependency, no +superuser rights needed, no configuration required, no database. Installing and +launching the main script out-of-the-box, as a normal user, are often the only +steps to have a simple remote calendar and contact access. + +Contrary to other servers that are often complicated, require high privileges +or need a strong configuration, the Radicale Server can (sometimes, if not +often) be launched in a couple of minutes, if you follow the +[tutorial](#simple-5-minute-setup). + +##### Lazy + +The CalDAV RFC defines what must be done, what can be done and what cannot be +done. Many violations of the protocol are totally defined and behaviors are +given in such cases. + +Radicale often assumes that the clients are perfect and that protocol +violations do not exist. That is why most of the errors in client requests have +undetermined consequences for the lazy server that can reply good answers, bad +answers, or even no answer. + +#### History + +Radicale has been started as a (free topic) stupid school project replacing +another (assigned topic) even more stupid school project. + +At the beginning, it was just a proof-of-concept. The main goal was to write a +small, dirty and simple CalDAV server working with Lightning, using no external +libraries. That's how we created a piece of code that's (quite) easy to +understand, to use and to hack. + +The [first lines](https://github.com/Kozea/Radicale/commit/b1591aea) have been +added to the SVN (!) repository as I was drinking (many) beers at the very end +of 2008 (Python 2.6 and 3.0 were just released). It's now packaged for a +growing number of Linux distributions. + +And that was fun going from here to there thanks to you! diff --git a/md/master/DOCUMENTATION.te.md b/md/master/DOCUMENTATION.te.md new file mode 100644 index 000000000..2187594ec --- /dev/null +++ b/md/master/DOCUMENTATION.te.md @@ -0,0 +1,288 @@ +> Last updated: 2025-10-20 by [@gowtham1412-p](https://github.com/gowtham1412-p) + +> Based on commit: [4fdc78760914040d5f74ece8978013b8836a712e] of [DOCUMENTATION.md](https://github.com/Kozea/Radicale/blob/master/DOCUMENTATION.md) + +\# డాక్యుమెంటేషన్ + + + +\## ప్రారంభించడం + + + +\#### రాడికేల్ గురించి + + + +రాడికేల్ అనేది ఒక చిన్న కానీ శక్తివంతమైన CalDAV (క్యాలెండర్లు, చేయవలసిన జాబితాలు) మరియు CardDAV + +(పరిచయాలు) సర్వర్, ఇది: + + + +\* CalDAV, CardDAV మరియు HTTP ద్వారా క్యాలెండర్లు మరియు పరిచయ జాబితాలను పంచుకుంటుంది. + +\* ఈవెంట్‌లు, టోడోలు, జర్నల్ ఎంట్రీలు మరియు వ్యాపార కార్డులకు మద్దతు ఇస్తుంది. + +\* బాక్స్ వెలుపల పనిచేస్తుంది, సంక్లిష్టమైన సెటప్ లేదా కాన్ఫిగరేషన్ అవసరం లేదు. + +\* సౌకర్యవంతమైన ప్రామాణీకరణ ఎంపికలను అందిస్తుంది. + +\* అధికారం ద్వారా యాక్సెస్‌ను పరిమితం చేయవచ్చు. + +\* TLSతో కనెక్షన్‌లను సురక్షితం చేయవచ్చు. + +\* చాలా మందితో పనిచేస్తుంది + +\[CalDAV మరియు CardDAV క్లయింట్లు](#సపోర్టెడ్-క్లయింట్లు). + +\* ఫైల్ సిస్టమ్‌లోని అన్ని డేటాను సాధారణ ఫోల్డర్ నిర్మాణంలో నిల్వ చేస్తుంది. + +\* ప్లగిన్‌లతో పొడిగించవచ్చు. + +\* GPLv3-లైసెన్స్ పొందిన ఉచిత సాఫ్ట్‌వేర్. + + + +\#### ఇన్‌స్టాలేషన్ + + + +తనిఖీ చేయండి + + + +\* \[ట్యుటోరియల్స్](#ట్యుటోరియల్స్) + +\* \[డాక్యుమెంటేషన్](#డాక్యుమెంటేషన్-1) + +\* \[GitHubలో వికీ](https://github.com/Kozea/Radicale/wiki) + +\* \[GitHubలో చర్చలు](https://github.com/Kozea/Radicale/discussions) + +\* \[GitHubలో తెరిచి ఉన్న మరియు ఇప్పటికే మూసివేయబడిన సమస్యలు](https://github.com/Kozea/Radicale/issues?q=is%3Aissue) + + + +\#### కొత్తగా ఏముంది? + + + +\[GitHubలో చేంజ్‌లాగ్](https://github.com/Kozea/Radicale/blob/master/CHANGELOG.md) చదవండి. + + + +\## ట్యుటోరియల్స్ + + + +\### 5 నిమిషాల సులభమైన సెటప్ + + + +మీరు Radicaleని ప్రయత్నించాలనుకుంటున్నారా కానీ మీ క్యాలెండర్‌లో 5 నిమిషాలు మాత్రమే ఖాళీగా ఉందా? + + + +ఇప్పుడే వెళ్లి Radicaleతో కొంచెం ఆడుదాం! + + + +ఈ విభాగం నుండి సెట్టింగ్‌లతో కాన్ఫిగర్ చేయబడిన సర్వర్, localhost + +కి మాత్రమే బైండ్ అవుతుంది (అంటే ఇది నెట్‌వర్క్ ద్వారా చేరుకోలేరు), మరియు మీరు ఏదైనా వినియోగదారు పేరు మరియు పాస్‌వర్డ్‌తో లాగిన్ అవ్వవచ్చు. + + + +ప్రతిదీ పనిచేసినప్పుడు, మీరు స్థానిక \[client](#supported-clients) + +ని పొందవచ్చు మరియు క్యాలెండర్‌లు మరియు చిరునామా పుస్తకాలను సృష్టించడం ప్రారంభించవచ్చు. + + + +Radicale మీ అవసరాలకు సరిపోతుంటే, రిమోట్ క్లయింట్‌లు మరియు కావలసిన ప్రామాణీకరణ రకానికి మద్దతు ఇవ్వడానికి కొంత \[ప్రాథమిక కాన్ఫిగరేషన్](#basic-configuration) + +కి సమయం కావచ్చు. + + + +మీ ఆపరేటింగ్ సిస్టమ్‌ను బట్టి దిగువన ఉన్న అధ్యాయాలలో ఒకదాన్ని అనుసరించండి. + + + +\#### Linux / \\\*BSD + + + +సూచన: PyPI నుండి డౌన్‌లోడ్ చేయడానికి బదులుగా, మీ \[distribution](#linux-distribution-packages) అందించిన ప్యాకేజీల కోసం చూడండి. + + + +అవి మీ పంపిణీలలో ఇంటిగ్రేట్ చేయబడిన స్టార్టప్ స్క్రిప్ట్‌లను కూడా కలిగి ఉంటాయి, ఇవి Radicaleని డెమోనైజ్ చేయడానికి అనుమతిస్తాయి. + + + +ముందుగా, \*\*python\*\* 3.9 లేదా తరువాత మరియు \*\*pip\*\* ఇన్‌స్టాల్ చేయబడిందని నిర్ధారించుకోండి. చాలా డిస్ట్రిబ్యూషన్లలో ``python3-pip`` ప్యాకేజీని ఇన్‌స్టాల్ చేయడానికి సరిపోతుంది. + + + +\##### సాధారణ వినియోగదారుగా + + + +పరీక్ష కోసం మాత్రమే సిఫార్సు చేయబడింది - కన్సోల్‌ను తెరిచి ఇలా టైప్ చేయండి: + + + +```bash + +\# ప్రస్తుత వినియోగదారు కోసం మాత్రమే ఇన్‌స్టాల్ చేయడానికి కింది ఆదేశాన్ని అమలు చేయండి + +python3 -m pip install --user --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +``` + + + +\_install\_ పని చేయకపోతే మరియు బదులుగా `error: externally-managed-environment` ప్రదర్శించబడితే, + +ముందుగానే వర్చువల్ వాతావరణాన్ని సృష్టించండి మరియు సక్రియం చేయండి. + + + +```bash + +python3 -m venv ~/venv + +source ~/venv/bin/activate + +``` + + + +మరియు దీనితో ఇన్‌స్టాల్ చేయడానికి ప్రయత్నించండి + + + +```bash + +python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +``` + + + +సేవను మాన్యువల్‌గా ప్రారంభించండి, డేటా ప్రస్తుత వినియోగదారు కోసం మాత్రమే నిల్వ చేయబడుతుంది + + + +```bash + +\# ప్రారంభించు, డేటా ప్రస్తుత వినియోగదారు కోసం మాత్రమే నిల్వ చేయబడుతుంది + +python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections --auth-type none + +``` + + + +\#### సిస్టమ్ వినియోగదారుగా (లేదా రూట్‌గా) + + + +ప్రత్యామ్నాయంగా, మీరు సిస్టమ్ వినియోగదారుగా లేదా రూట్‌గా ఇన్‌స్టాల్ చేసి అమలు చేయవచ్చు (సిఫార్సు చేయబడలేదు): + + + +```bash + +\# కింది ఆదేశాన్ని రూట్ (సిఫార్సు చేయబడలేదు) లేదా రూట్ కాని వ్యవస్థ వినియోగదారుగా అమలు చేయండి + +\# (డిపెండెన్సీలు లేనప్పుడు తరువాతి వాటికి --user అవసరం కావచ్చు సిస్టమ్-వైడ్ మరియు/లేదా వర్చువల్ ఎన్విరాన్మెంట్ అందుబాటులో ఉంది) + +python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +``` + + + +`/var/lib/radicale/collections` కింద సిస్టమ్ ఫోల్డర్‌లో నిల్వ చేయబడిన డేటాతో సేవను మాన్యువల్‌గా ప్రారంభించండి: + + + +```bash + +\# Start, డేటా సిస్టమ్ ఫోల్డర్‌లో నిల్వ చేయబడుతుంది (/var/lib/radicale/collections కు వ్రాయడానికి అనుమతులు అవసరం) + +python3 -m radicale --storage-filesystem-folder=/var/lib/radicale/collections --auth-type none + +``` + + + +\#### Windows + + + +మొదటి దశ పైథాన్‌ను ఇన్‌స్టాల్ చేయడం. + +\[python.org](https://python.org) కు వెళ్లి పైథాన్ 3 యొక్క తాజా వెర్షన్‌ను డౌన్‌లోడ్ చేసుకోండి. + +తర్వాత ఇన్‌స్టాలర్‌ను అమలు చేయండి. + +ఇన్‌స్టాలర్ యొక్క మొదటి విండోలో, "PATH కు పైథాన్‌ను జోడించు" బాక్స్‌ను తనిఖీ చేసి, + +"ఇప్పుడే ఇన్‌స్టాల్ చేయి"పై క్లిక్ చేయండి. రెండు నిమిషాలు వేచి ఉండండి, పూర్తయింది! + + + +కమాండ్ ప్రాంప్ట్‌ను ప్రారంభించి ఇలా టైప్ చేయండి: + + + +```powershell + +python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +python -m radicale --storage-filesystem-folder=~/radicale/collections --auth-type none + +``` + + + +\##### Common + + + +విజయవంతం!!! మీ బ్రౌజర్‌లో తెరవండి! + +ఉదాహరణ ఎంపిక `--auth-type none` ద్వారా ప్రామాణీకరణ అవసరం లేనందున మీరు ఏదైనా వినియోగదారు పేరు మరియు పాస్‌వర్డ్‌తో లాగిన్ అవ్వవచ్చు. + +ఇది \*\*సురక్షితం\*\*, మరిన్ని వివరాల కోసం \[కాన్ఫిగరేషన్/ప్రామాణీకరణ](#auth) చూడండి. + + + +భద్రతా కారణాల దృష్ట్యా డిఫాల్ట్ కాన్ఫిగరేషన్ సర్వర్‌ను `localhost` (IPv4: `127.0.0.1`, IPv6: `::1`) కు బంధిస్తుందని గమనించండి. + + + +మరిన్ని వివరాల కోసం \[చిరునామాలు](#చిరునామాలు) మరియు \[కాన్ఫిగరేషన్/సర్వర్](#సర్వర్) చూడండి. + + + +\### ప్రాథమిక కాన్ఫిగరేషన్ + + + +ఇన్‌స్టాలేషన్ సూచనలను + +\[సరళమైన 5-నిమిషాల సెటప్](#సింపుల్-5-నిమిషాల-సెటప్) ట్యుటోరియల్‌లో చూడవచ్చు. + + + +రాడికేల్ `/etc/radicale/config` మరియు + +`~/.config/radicale/config` నుండి కాన్ఫిగరేషన్ ఫైల్‌లను లోడ్ చేయడానికి ప్రయత్నిస్తుంది. + +Cu + diff --git a/md/master/translations/DOCUMENTATION.te.md b/md/master/translations/DOCUMENTATION.te.md new file mode 100644 index 000000000..2187594ec --- /dev/null +++ b/md/master/translations/DOCUMENTATION.te.md @@ -0,0 +1,288 @@ +> Last updated: 2025-10-20 by [@gowtham1412-p](https://github.com/gowtham1412-p) + +> Based on commit: [4fdc78760914040d5f74ece8978013b8836a712e] of [DOCUMENTATION.md](https://github.com/Kozea/Radicale/blob/master/DOCUMENTATION.md) + +\# డాక్యుమెంటేషన్ + + + +\## ప్రారంభించడం + + + +\#### రాడికేల్ గురించి + + + +రాడికేల్ అనేది ఒక చిన్న కానీ శక్తివంతమైన CalDAV (క్యాలెండర్లు, చేయవలసిన జాబితాలు) మరియు CardDAV + +(పరిచయాలు) సర్వర్, ఇది: + + + +\* CalDAV, CardDAV మరియు HTTP ద్వారా క్యాలెండర్లు మరియు పరిచయ జాబితాలను పంచుకుంటుంది. + +\* ఈవెంట్‌లు, టోడోలు, జర్నల్ ఎంట్రీలు మరియు వ్యాపార కార్డులకు మద్దతు ఇస్తుంది. + +\* బాక్స్ వెలుపల పనిచేస్తుంది, సంక్లిష్టమైన సెటప్ లేదా కాన్ఫిగరేషన్ అవసరం లేదు. + +\* సౌకర్యవంతమైన ప్రామాణీకరణ ఎంపికలను అందిస్తుంది. + +\* అధికారం ద్వారా యాక్సెస్‌ను పరిమితం చేయవచ్చు. + +\* TLSతో కనెక్షన్‌లను సురక్షితం చేయవచ్చు. + +\* చాలా మందితో పనిచేస్తుంది + +\[CalDAV మరియు CardDAV క్లయింట్లు](#సపోర్టెడ్-క్లయింట్లు). + +\* ఫైల్ సిస్టమ్‌లోని అన్ని డేటాను సాధారణ ఫోల్డర్ నిర్మాణంలో నిల్వ చేస్తుంది. + +\* ప్లగిన్‌లతో పొడిగించవచ్చు. + +\* GPLv3-లైసెన్స్ పొందిన ఉచిత సాఫ్ట్‌వేర్. + + + +\#### ఇన్‌స్టాలేషన్ + + + +తనిఖీ చేయండి + + + +\* \[ట్యుటోరియల్స్](#ట్యుటోరియల్స్) + +\* \[డాక్యుమెంటేషన్](#డాక్యుమెంటేషన్-1) + +\* \[GitHubలో వికీ](https://github.com/Kozea/Radicale/wiki) + +\* \[GitHubలో చర్చలు](https://github.com/Kozea/Radicale/discussions) + +\* \[GitHubలో తెరిచి ఉన్న మరియు ఇప్పటికే మూసివేయబడిన సమస్యలు](https://github.com/Kozea/Radicale/issues?q=is%3Aissue) + + + +\#### కొత్తగా ఏముంది? + + + +\[GitHubలో చేంజ్‌లాగ్](https://github.com/Kozea/Radicale/blob/master/CHANGELOG.md) చదవండి. + + + +\## ట్యుటోరియల్స్ + + + +\### 5 నిమిషాల సులభమైన సెటప్ + + + +మీరు Radicaleని ప్రయత్నించాలనుకుంటున్నారా కానీ మీ క్యాలెండర్‌లో 5 నిమిషాలు మాత్రమే ఖాళీగా ఉందా? + + + +ఇప్పుడే వెళ్లి Radicaleతో కొంచెం ఆడుదాం! + + + +ఈ విభాగం నుండి సెట్టింగ్‌లతో కాన్ఫిగర్ చేయబడిన సర్వర్, localhost + +కి మాత్రమే బైండ్ అవుతుంది (అంటే ఇది నెట్‌వర్క్ ద్వారా చేరుకోలేరు), మరియు మీరు ఏదైనా వినియోగదారు పేరు మరియు పాస్‌వర్డ్‌తో లాగిన్ అవ్వవచ్చు. + + + +ప్రతిదీ పనిచేసినప్పుడు, మీరు స్థానిక \[client](#supported-clients) + +ని పొందవచ్చు మరియు క్యాలెండర్‌లు మరియు చిరునామా పుస్తకాలను సృష్టించడం ప్రారంభించవచ్చు. + + + +Radicale మీ అవసరాలకు సరిపోతుంటే, రిమోట్ క్లయింట్‌లు మరియు కావలసిన ప్రామాణీకరణ రకానికి మద్దతు ఇవ్వడానికి కొంత \[ప్రాథమిక కాన్ఫిగరేషన్](#basic-configuration) + +కి సమయం కావచ్చు. + + + +మీ ఆపరేటింగ్ సిస్టమ్‌ను బట్టి దిగువన ఉన్న అధ్యాయాలలో ఒకదాన్ని అనుసరించండి. + + + +\#### Linux / \\\*BSD + + + +సూచన: PyPI నుండి డౌన్‌లోడ్ చేయడానికి బదులుగా, మీ \[distribution](#linux-distribution-packages) అందించిన ప్యాకేజీల కోసం చూడండి. + + + +అవి మీ పంపిణీలలో ఇంటిగ్రేట్ చేయబడిన స్టార్టప్ స్క్రిప్ట్‌లను కూడా కలిగి ఉంటాయి, ఇవి Radicaleని డెమోనైజ్ చేయడానికి అనుమతిస్తాయి. + + + +ముందుగా, \*\*python\*\* 3.9 లేదా తరువాత మరియు \*\*pip\*\* ఇన్‌స్టాల్ చేయబడిందని నిర్ధారించుకోండి. చాలా డిస్ట్రిబ్యూషన్లలో ``python3-pip`` ప్యాకేజీని ఇన్‌స్టాల్ చేయడానికి సరిపోతుంది. + + + +\##### సాధారణ వినియోగదారుగా + + + +పరీక్ష కోసం మాత్రమే సిఫార్సు చేయబడింది - కన్సోల్‌ను తెరిచి ఇలా టైప్ చేయండి: + + + +```bash + +\# ప్రస్తుత వినియోగదారు కోసం మాత్రమే ఇన్‌స్టాల్ చేయడానికి కింది ఆదేశాన్ని అమలు చేయండి + +python3 -m pip install --user --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +``` + + + +\_install\_ పని చేయకపోతే మరియు బదులుగా `error: externally-managed-environment` ప్రదర్శించబడితే, + +ముందుగానే వర్చువల్ వాతావరణాన్ని సృష్టించండి మరియు సక్రియం చేయండి. + + + +```bash + +python3 -m venv ~/venv + +source ~/venv/bin/activate + +``` + + + +మరియు దీనితో ఇన్‌స్టాల్ చేయడానికి ప్రయత్నించండి + + + +```bash + +python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +``` + + + +సేవను మాన్యువల్‌గా ప్రారంభించండి, డేటా ప్రస్తుత వినియోగదారు కోసం మాత్రమే నిల్వ చేయబడుతుంది + + + +```bash + +\# ప్రారంభించు, డేటా ప్రస్తుత వినియోగదారు కోసం మాత్రమే నిల్వ చేయబడుతుంది + +python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections --auth-type none + +``` + + + +\#### సిస్టమ్ వినియోగదారుగా (లేదా రూట్‌గా) + + + +ప్రత్యామ్నాయంగా, మీరు సిస్టమ్ వినియోగదారుగా లేదా రూట్‌గా ఇన్‌స్టాల్ చేసి అమలు చేయవచ్చు (సిఫార్సు చేయబడలేదు): + + + +```bash + +\# కింది ఆదేశాన్ని రూట్ (సిఫార్సు చేయబడలేదు) లేదా రూట్ కాని వ్యవస్థ వినియోగదారుగా అమలు చేయండి + +\# (డిపెండెన్సీలు లేనప్పుడు తరువాతి వాటికి --user అవసరం కావచ్చు సిస్టమ్-వైడ్ మరియు/లేదా వర్చువల్ ఎన్విరాన్మెంట్ అందుబాటులో ఉంది) + +python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +``` + + + +`/var/lib/radicale/collections` కింద సిస్టమ్ ఫోల్డర్‌లో నిల్వ చేయబడిన డేటాతో సేవను మాన్యువల్‌గా ప్రారంభించండి: + + + +```bash + +\# Start, డేటా సిస్టమ్ ఫోల్డర్‌లో నిల్వ చేయబడుతుంది (/var/lib/radicale/collections కు వ్రాయడానికి అనుమతులు అవసరం) + +python3 -m radicale --storage-filesystem-folder=/var/lib/radicale/collections --auth-type none + +``` + + + +\#### Windows + + + +మొదటి దశ పైథాన్‌ను ఇన్‌స్టాల్ చేయడం. + +\[python.org](https://python.org) కు వెళ్లి పైథాన్ 3 యొక్క తాజా వెర్షన్‌ను డౌన్‌లోడ్ చేసుకోండి. + +తర్వాత ఇన్‌స్టాలర్‌ను అమలు చేయండి. + +ఇన్‌స్టాలర్ యొక్క మొదటి విండోలో, "PATH కు పైథాన్‌ను జోడించు" బాక్స్‌ను తనిఖీ చేసి, + +"ఇప్పుడే ఇన్‌స్టాల్ చేయి"పై క్లిక్ చేయండి. రెండు నిమిషాలు వేచి ఉండండి, పూర్తయింది! + + + +కమాండ్ ప్రాంప్ట్‌ను ప్రారంభించి ఇలా టైప్ చేయండి: + + + +```powershell + +python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +python -m radicale --storage-filesystem-folder=~/radicale/collections --auth-type none + +``` + + + +\##### Common + + + +విజయవంతం!!! మీ బ్రౌజర్‌లో తెరవండి! + +ఉదాహరణ ఎంపిక `--auth-type none` ద్వారా ప్రామాణీకరణ అవసరం లేనందున మీరు ఏదైనా వినియోగదారు పేరు మరియు పాస్‌వర్డ్‌తో లాగిన్ అవ్వవచ్చు. + +ఇది \*\*సురక్షితం\*\*, మరిన్ని వివరాల కోసం \[కాన్ఫిగరేషన్/ప్రామాణీకరణ](#auth) చూడండి. + + + +భద్రతా కారణాల దృష్ట్యా డిఫాల్ట్ కాన్ఫిగరేషన్ సర్వర్‌ను `localhost` (IPv4: `127.0.0.1`, IPv6: `::1`) కు బంధిస్తుందని గమనించండి. + + + +మరిన్ని వివరాల కోసం \[చిరునామాలు](#చిరునామాలు) మరియు \[కాన్ఫిగరేషన్/సర్వర్](#సర్వర్) చూడండి. + + + +\### ప్రాథమిక కాన్ఫిగరేషన్ + + + +ఇన్‌స్టాలేషన్ సూచనలను + +\[సరళమైన 5-నిమిషాల సెటప్](#సింపుల్-5-నిమిషాల-సెటప్) ట్యుటోరియల్‌లో చూడవచ్చు. + + + +రాడికేల్ `/etc/radicale/config` మరియు + +`~/.config/radicale/config` నుండి కాన్ఫిగరేషన్ ఫైల్‌లను లోడ్ చేయడానికి ప్రయత్నిస్తుంది. + +Cu + diff --git a/md/v1/00_index.md b/md/v1/00_index.md new file mode 100644 index 000000000..bd37f0600 --- /dev/null +++ b/md/v1/00_index.md @@ -0,0 +1,36 @@ +## A Simple Calendar and Contact Server + +#### Presentation + +The Radicale Project is a complete CalDAV (calendar) and CardDAV +(contact) server solution. + +Calendars and address books are available for both local and remote +access, possibly limited through authentication policies. They can be +viewed and edited by calendar and contact clients on mobile phones or +computers. + +#### Technical Description + +Radicale aims to be a light solution, easy to use, easy to install, easy +to configure. As a consequence, it requires few software dependencies +and is pre-configured to work out-of-the-box. + +Radicale runs on most of the UNIX-like platforms (Linux, \*BSD, MacOS X) +and Windows. It is free and open-source software, written in Python, +released under GPL version 3. + +#### Main Features + + - Shares calendars through CalDAV, WebDAV and HTTP + - Shares contacts through CardDAV, WebDAV and HTTP + - Supports events, todos, journal entries and business cards + - Works out-of-the-box, no installation nor configuration required + - Warns users on concurrent editing + - Limits access by authentication + - Secures connections + +#### Supported Clients + +Radicale supports the latest versions of [many CalDAV and CardDAV +clients](#caldav-and-carddav-clients). diff --git a/md/v1/01_documentation.md b/md/v1/01_documentation.md new file mode 100644 index 000000000..2e44265b7 --- /dev/null +++ b/md/v1/01_documentation.md @@ -0,0 +1,1482 @@ +## Documentation + +#### User documentation + +This document describes how to install and configure the server. + + - [User documentation](#user-documentation-1) + +#### Project description + +This document defines the main goals of the Radicale Project, what it +covers and what it does not. + + - [Project description](#project-description-1) + +#### Technical choices + +This document describes the global technical choices of the Radicale +Project and the global architectures of its different parts. + + - [Technical choices](#technical-choices-1) + +### User Documentation + +#### Installation + +##### Dependencies + +Radicale is written in pure Python and does not depend on any library. +It is known to work on Python 2.6, 2.7, 3.1, 3.2, 3.3, 3.4 and PyPy \> +1.9. The dependencies are optional, as they are only needed for various +authentication methods[\[1\]](#1). + +Linux and MacOS users certainly have Python already installed. For +Windows users, please install Python[\[2\]](#2) thanks to the adequate +installer. + +##### Radicale + +Radicale can be freely downloaded on the [project website, download +section](#download). Just get the file and unzip +it in a folder of your choice. + +##### CalDAV and CardDAV Clients + +At this time Radicale has been tested and works fine with the latest +version of: + + - [Mozilla + Lightning](http://www.mozilla.org/projects/calendar/lightning/) + - [GNOME Evolution](http://projects.gnome.org/evolution/) + - [KDE KOrganizer](http://userbase.kde.org/KOrganizer/) + - [aCal](http://wiki.acal.me/wiki/Main_Page), + [ContactSync](https://play.google.com/store/apps/details?id=com.vcard.android.free), + [CalendarSync](https://play.google.com/store/apps/details?id=com.icalparse.free), + [CalDAV-Sync](https://play.google.com/store/apps/details?id=org.dmfs.caldav.lib) + [CardDAV-Sync](https://play.google.com/store/apps/details?id=org.dmfs.carddav.Sync) + and [DAVdroid](http://davdroid.bitfire.at) for [Google + Android](http://www.android.com/) + - [InfCloud](http://www.inf-it.com/open-source/clients/infcloud/), + [CalDavZAP](http://www.inf-it.com/open-source/clients/caldavzap/), + [CardDavMATE](http://www.inf-it.com/open-source/clients/carddavmate/) + - [Apple iPhone](http://www.apple.com/iphone/) + - [Apple Calendar](http://www.apple.com/macosx/apps/#calendar) + - [Apple Contacts](http://www.apple.com/macosx/apps/#contacts) + - [syncEvolution](https://syncevolution.org/) + +More clients will be supported in the future. However, it may work with +any calendar or contact client which implements CalDAV or CardDAV +specifications too (luck is highly recommended). + +#### Simple Usage + +##### Starting the Server + +To start Radicale CalDAV server, you have to launch the file called +`radicale.py` located in the root folder of the software package. + +##### Starting the Client + +###### Lightning + +After starting Lightning, click on `File` and `New Calendar`. Upcoming +window asks you about your calendar storage. Chose a calendar `On the +Network`, otherwise Lightning will use its own file system storage +instead of Radicale's one and your calendar won't be remotely +accessible. + +Next window asks you to provide information about remote calendar +access. Protocol used by Radicale is `CalDAV`. A standard location for a +basic use of a Radicale calendar is +`http://localhost:5232/user/calendar.ics/`, where you can replace `user` +and `calendar.ics` by some strings of your choice. Calendars are +automatically created if needed. Please note that **the trailing slash +is important**. + +You can now customize your calendar by giving it a nickname and a color. +This is only used by Lightning to identify calendars among others. + +If no warning sign appears next to the calendar name, you can now add +events and tasks to your calendar. All events and tasks are stored in +the server, they can be accessed and modified from multiple clients by +multiple users at the same time. + +Lightning and Thunderbird cannot access CardDAV servers yet. Also, as of +version 17.0.5 the SOGo Connector addon is not fully functionally and +will create extra address book entries with every sync. + +###### Evolution + +__Calendars__ + +First of all, show the calendar page in Evolution by clicking on the +calendar icon at the bottom of the side pane. Then add a new calendar by +choosing in the menu `File → New → Calendar`. + +A new window opens. The calendar `type` is `CalDAV`, and the location is +something like `http://localhost:5232/user/calendar.ics/`, where you can +replace `user` and `calendar` by some strings of your choice. Calendars +are automatically created if needed. Please note that **the trailing +slash is important**. + +You can fill other attributes like the color and the name, these are +only used for Evolution and are not uploaded. + +Click on `OK`, and your calendar should be ready for use. + +__Contacts__ + +Switch to the contacts page and click `File → New → Adress book`. In the +new window choose `WebDAV` as `type` and something like +`http://localhost:5232/user/addressbook.vcf/` as location. Remember to +enter the correct username. + +###### KOrganizer + +__Calendars__ + +*Tested with 4.8.3, you need one running on Akonadi for Cal/CarDav +support.* + +The procedure below can also be done trough the sidebar "Calendar +Manager". But to ensure it works for everyone this examples uses the +menu-bar. + +1. Click `Settings → Configure KOrganizer`. +2. Click on `General → Calendars`. +3. Click on `Add`. +4. Choose `DAV groupware resource` (and click `OK`). +5. Enter your username/passord (and click on `Next`). +6. Select `Configure the resource manually` (and click on `Finish`). +7. Fill in a Display name. +8. Fill in your Username and Password. +9. Click `Add`. +10. Choose `CalDav`. +11. For remote URL enter `http://myserver:5232/Username/Calendar.ics/` +12. Click `Fetch`. +13. Select desired calendar. +14. Hit `OK`. +15. Hit `OK` again. +16. Close the Configuration Window (Click `OK`). +17. Restart Korganizer for the calendar to appear in the "Calendar + Manager" sidebar (at least with version 4.8.3.) + +> **Note** +> +> After you created a calender in a collection you can also use +> `http://myserver:5232/Username/` as an URL This will then list all +> available calendars. + + +__Contacts__ + +You can add a address book analogously to the above instructions, just +choose CardDav and `http://myserver:5232/Username/AddressBook.vcf/` in +step 10 and 11. Also, if you already have a calendar set up you can add +an address book to its "DAV groupware resource" under Configure-Kontact +→ Calendar → General → Calendars → Modify. This way you don't have to +enter username and password twice. + +###### CalendarSync + +CalendarSync can be combined with any Android calendar app and can even +store the calendars in existing Android calendars which are synced by +other sync adapters. Of course it can also create its own calendars. + +So, to sync using CalendarSync you will have to: + + - start the app, + - press the `Menu` button, + - select `Create WebiCal`, + - choose to start with a guided configuration. + +Then enter your URL, Username and Password. As URL please use +`http(s)://server:port/username/`. + +If you can use HTTPS depends on your setup. Please replace `username` +with the name of your user account. + +Press test connection button. If everything signaled as OK then press +search calendars button, select the calendars which you want to sync, +and press the configure calendar button at the top of the display. Your +calendars are now configured. + +You can then start the first sync by going back to the main screen of +the app an pressing the `Process Webicals` button. Of course you can +also configure the app at its preferences to sync automatically. + +###### ContactSync + +ContactSync is designed to sync contacts from and to various sources. It +can also overtake contacts and push them to the server, also if they are +only available on the device (local only contacts). + +So to sync your contacts from the Radical server to your Android device: + + - start the app + - press the `Menu` button, + - select `Create WebContact`, + - select guided configuration mode. + +As URL please use `http(s)://server:port/username/`. + +At the URL you will have to replace `server:port` and `username` so that +it matches your specific setup. It also depends on your configuration if +you can use HTTPS or if you have to use HTTP. + +Press test connection button, if everything signaled as OK then press +search address book button. Select the address books which you want to +sync and press the configure address book button at the top of the +display. + +You can then start the first sync by going back to the main screen of +the app and pressing the `Handle WebContacts` button. Of course you can +also configure the app at its preferences to sync automatically. + +###### CalDAV-Sync + +CalDAV-Sync is implemented as sync adapter to integrate seamlessly with +any calendar app and widget. Therefore you have to access it via +`Accounts & Sync` settings after installing it from the Market. + +So, to add new calendars to your phone open `Accounts & Sync` settings +and tap on `Add account`, selecting CalDAV as type. In the next view, +you have to switch to Manual Mode. Enter the full CalDAV URL of your +Radicale account (e.g. `http://example.com:5232/Username/`) and +corresponding login data. If you want to create a new calendar you have +to specify its full URL e.g. +`http://example.com:5232/Username/Calendar.ics/`. Please note that **the +trailing slash is important**. + +Tap on `Next` and the app checks for all available calendars on your +account, listing them in the next view. (Note: CalDAV-Sync will not only +check under the url you entered but also under +`http://example.com:5232/UsernameYouEnteredForLogin/`. This might cause +strange errors.) You can now select calendars you want to sync and set a +local nickname and color for each. Hitting `Next` again brings up the +last page. Enter your email address and uncheck `Sync from server to +phone only` if you want to use two-way-sync. + +> **Note** +> +> CalDAV-Sync officially is in alpha state and two-way-sync is marked as +> an experimental feature. Though it works fine for me, using two-way-sync +> is on your own risk\! + + +Tap on `Finish` and you're done. You're now able to use the new +calendars in the same way you were using Google calendars before. + +###### CardDAV-Sync + +Set up works like CalDAV-Sync, just use .vcf instead of .ics if you +enter the URL, e.g. `http://example.com:5232/Username/AddressBook.vcf/`. + +###### DAVdroid + +[DAVdroid](http://davdroid.bitfire.at) is a free and open-source +CalDAV/CardDAV client that is available in Play Store for a small fee or +in FDroid for free. + +To make it working with Radicale, just add a new DAVdroid account and +enter `https://example.com/radicale/user/` as base URL (assuming that +your Radicale runs at `https://example.com/radicale/`; don't forget to +set base\_prefix correctly). + +###### aCal + +aCal is a CalDAV client for Android. It comes with its own calendar +application and does not integrate in the Android calendar. It is a +"CalDAV only" calendar, i.e. it only works in combination with a CalDAV +server. It can connect to several calendars on the server and will +display them all in one calendar. It works nice with Radicale. + +To configure aCal, start aCal, go to the `Settings` screen, select +`Server`, then `Add server`. Choose `Manual Configuration` and select +`Advanced` (bottom of the screen). Then enter the host name of your +server, check `Active`, enter your user name and password. The `Simple +Domain` of your server is the domain part of your fully qualified host +name (e.g. if your server is `myserver.mydomain.org`, choose +`mydomain.org`). + +As `Simple Path` you need to specify `/` where user is the user +you use to connect to Radicale. `Server Name` is the fully qualified +name of your server machine (`myserver.mydomain.org`). The `Server Path` +is `//`. + +For `Authentication Type` you need to specify the method you chose for +Radicale. Check `Use SSL` if your Radicale is configured to use SSL. + +As the last thing you need to specify the port Radicale listens to. When +your server is configured you can go back to the first `Settings` +screen, and select `Calendars and Addressbooks`. You should find all the +calendars that are available to your user on the Radicale server. You +can then configure each of them (display colour, notifications, etc.). + +###### InfCloud, CalDavZAP & CardDavMATE + +Because settings are the same for `InfCloud`, `CalDavZAP` and +`CardDavMATE` +only *InfCloud* is used in description below. + +__Radicale configuration__ + +Add/Modify the following section in Radicale main configuration file: + +``` ini +# Additional HTTP headers +[headers] +Access-Control-Allow-Origin = * +Access-Control-Allow-Methods = GET, POST, OPTIONS, PROPFIND, PROPPATCH, REPORT, PUT, MOVE, DELETE, LOCK, UNLOCK +Access-Control-Allow-Headers = Authorization, Content-type, Depth, Destination, If-match, If-None-Match, Lock-Token, Overwrite, Prefer, Timeout, User-Agent, X-Client, X-Requested-With +Access-Control-Expose-Headers = Etag +``` + +`InfCloud` needs read access for `everybody` (including anonymous users) +on Radicale's root directory. If using Radicales rights management add +the following section to rights file: + +``` ini +# Allow caldavzap, carddavmate and infcloud to work +[infcloud] +user: .* +collection: / +permission: r +``` + +Additional you need to change `[owner-write]` section to use the same +syntax for collection as shown in `[public]` section. + +``` ini +# Give write access to owners +[owner-write] +user: .+ +# collection: ^%(login)s/.+$ # DOES NOT WORK +collection: ^%(login)s(/.+)?$ +permission: rw +``` + +__InfCloud configuration__ + +Inside `InfCloud` configuration file `config.js` you need to set +`globalNetworkCheckSettings` like following example: + +``` JavaScript +// href: +// put in here your protocol, host and port where Radicale is listening +// additionalResources: +// put in here a comma separated list of collections you want additionally look at. +// Don't forget '' around each collections name +var globalNetworkCheckSettings={ + href: 'https://host.example.com:5232/', + hrefLabel: null, + crossDomain: null, + additionalResources: ['public'], + forceReadOnly: null, + withCredentials: false, + showHeader: true, + settingsAccount: true, + syncInterval: 60000, + timeOut: 30000, + lockTimeOut: 10000, + delegation: false, + ignoreAlarms: false, + backgroundCalendars: [] +} +``` + +> **Note** +> +> `InfCloud`, `CardDavMATE` and `CalDavZAP` cannot create calendars and/or +> address books. **They need to be created before first login.** Each user +> needs to have minimum of one calendar and/or one adressbook even if only +> using shared addresses and/or calendars. Client will not login, if the +> user collections don't exists. + + +You can easily create them by directly calling the URL's from your +browser: +  `http(s)://host.example.com:5232/user/calendar.ics/` +  `http(s)://host.example.com:5232/user/addresses.vcf/` + +Replace "http(s)" with the correct protocol, "host.example.com:5232" +with you host:port where Radicale is running, +"user" with the correct login name or the shared resource name i.e. +'public', +"calendar.ics" and "addresses.vcf" with the collection names you want to +use +and **do NOT forget the '/' at line end**. + +> **Note** +> +> If using self-signed certificates you need to do the following steps +> before using `InfCloud, CardDavMATE` or `CalDavZAP`. +> With your browser +> call one of the above URLs. +> Your browser warn you that you are trying +> to access an `Insecure` site. +> Download and accept the certificate +> offered by the Radicale server. +> After installing and accepting it you +> should restart your browser. + + +###### iPhone & iPad + +__Calendars__ + +For iOS devices, the setup is fairly straightforward but there are a few +settings that are critical for proper operation. + +1. From the Home screen, open `Settings` +2. Select `Mail, Contacts, Calendars` +3. Select `Add Account…` → `Other` → `Add CalDAV Account` +4. Enter the server URL here, including `https`, the port, and the + user/calendar path, ex: + `https://myserver.domain.com:3000/bob/birthdays.ics/` (please note + that **the trailing slash is important**) +5. Enter your username and password as defined in your server config +6. Enter a good description of the calendar in the `Description` field. + Otherwise it will put the whole servername in the field. +7. Now go back to the `Mail, Contacts, Calendars` screen and scroll + down to the `Calendars` section. You must change the `Sync` option + to sync `All events` otherwise new events won't show up on your iOS + devices\! + +> **Note** +> +> Everything should be working now so test creating events and make sure +> they stay created. If you create events on your iOS device and they +> disappear after the fetch period, you probably forgot to change the sync +> setting in step 7. Likewise, if you create events on another device and +> they don't appear on your iPad of iPhone, then make sure your sync +> settings are correct + + +> **Warning** +> +> In iOS 5.x, please check twice that the `Sync all entries` option is +> activated, otherwise some events may not be shown in your calendar. + + +__Contacts__ + +In Contacts on iOS 6: + +1. From the Home screen, open `Settings` +2. Select `Mail, Contacts, Calendars` +3. Select `Add Account…` → `Other` → `Add CardDAV Account` +4. As `Server` use the Radicale server URL with port, for example + `localhost:5232` +5. Add any `User name` you like (if you didn't configure + authentication) +6. Add any `Password` you like (again, if you didn't configure + authentication) +7. Change the `Description` to something more readable (optional) +8. Tap `Next` +9. An alert showing `Cannot Connect Using SSL` will pop up as we haven't configured SSL yet, `Continue` + for now +10. Back on the `Mail, Contacts, Calendars` screen you scroll to the + `Contacts` section, select the Radicale server as `Default Account` + when you want to save new contacts to the Radicale server +11. Exit to the Home screen and open `Contacts`, tap `Groups`, you + should see the Radicale server + +> **Note** +> +> You'll need version 0.8.1 or up for this to work. Earlier versions will +> forget your new settings after a reboot. + + +###### OS X + +> **Note** +> +> This description assumes you do not have any authentication or +> encryption configured. If you want to use iCal with authentication or +> encryption, you just have to fill in the corresponding fields in your +> calendar's configuration. + + +__Calendars__ + +In iCal 4.0 or iCal 5.0: + +1. Open the `Preferences` dialog and select the `Accounts` tab +2. Click the `+` button at the lower left to open the account creation + wizard +3. As `Account type` select `CalDAV` +4. Select any `User name` you like +5. The `Password` field can be left empty (we did not configure + authentication) +6. As `Server address` use `domain:port`, for example `localhost:5232` + (this would be the case if you start an unconfigured Radicale on + your local machine) + +Click `Create`. The wizard will now tell you, that no encryption is in +place (`Unsecured Connection`). This is expected and will change if you +configure Radicale to use SSL. Click `Continue`. + +> **Warning** +> +> In iCal 5.x, please check twice that the `Sync all entries` option is +> activated, otherwise some events may not be shown in your calendar. + + +The wizard will close, leaving you in the `Account` tab again. The +account is now set-up. You can close the `Preferences` window. + +> **Important** +> +> To add a calendar to your shiny new account you have to go to the menu +> and select `File → New Calendar → `. A new +> calendar appears in the left panel waiting for you to enter a name. +> +> This is needed because the behaviour of the big `+` button in the main +> window is confusing as you can't focus an empty account and iCal will +> just add a calendar to another account. + + +__Contacts__ + +In Contacts 7 (previously known as AddressBook): + +1. Open the `Preferences` dialog and select the `Accounts` tab. +2. Click the `+` button at the lower left to open the account creation + wizard. +3. As `Account type` select `CardDAV`. +4. Add any `User name` you like. +5. The `Password` field can be left empty (if we didn't configure + authentication). +6. As `Server address` use `domain:port`, for example `localhost:5232` + (this would be the case if you start an unconfigured Radicale server + on your local machine). +7. Click `Create`. Contacts will complain about an + `Unsecured Connection` if you don't + have SSL enabled. Click `Create` again. +8. You might want to change the `Description` of the newly added + account to something more readable. (optional) +9. Switch to the `General` tab in the preferences and select the + Radicale server as `Default Account` at the bottom of the screen. It + probably shows up as `` `domain:port `` or the name you choose if + you changed the description. Newly added contacts are added to the + default account and by default this will be the local + `On My Mac` account. + +> **Note** +> +> You'll need version 0.8.1 or up for this to work. Earlier versions can +> read CardDAV contacts but can't add new contacts. + + +###### syncEvolution + +You can find more information about syncEvolution and Radicale on the +[syncEvolution wiki +page](https://syncevolution.org/wiki/synchronizing-radicale). + +###### Nokia / Microsoft Windows Phones + +1. Go to "Settings" \> "email+accounts" +2. Click "add an account" \> "iCloud" +3. Enter random email address (e.g. "" and "qwerty") \> "sign + in" +4. A new account "iCloud" with the given email address appears on the + list. The status is "Not up to date". Click the account. +5. An error message is given. Click "close". +6. Enter new and "real" values to the account setting fields: + - "Account name": This name appears on the calendar etc. Examples: + "Home", "Word", "Sauna reservation" + - "Email address": Not used + - "Sync contacts and calendar": Select the sync interval + - "Content to sync": Uncheck "Contacts", check "Calendar" + - "Your name": Not used + - "Username": Username to your Radicale server + - "Password": Password to your Radicale server + - Click "advanced settings" + - "Calendar server (CalDAV)": Enter the full path to the calendar + .ics file. Don't forget the trailing slash. Example: + `https://my.server.fi:5232/myusername/calendarname.ics/` + +Don't forget to add your CA to the phone if you're using a self-signed +certificate on your Radicale. Make the CA downloadable to Internet +Explorer. The correct certificate format is X509 (with .cer file +extension). + +#### Complex Configuration + +> **Note** +> +> This section is written for Linux users, but can be easily adapted for +> Windows and MacOS users. + + +##### Installing the Server + +You can install Radicale thanks to the following command, with superuser +rights: + + python setup.py install + +Then, launching the server can be easily done by typing as a normal +user: + + radicale + +##### Configuring the Server + +###### Main Configuration File + +> **Note** +> +> This section is following the latest stable version changes. Please look +> at the default configuration file included in your package if you have +> an older version of Radicale. + + +The server configuration can be modified in `/etc/radicale/config` or in +`~/.config/radicale/config`. You can use the `--config` parameter in the +command line to choose a specific path. You can also set the +`RADICALE_CONFIG` environment variable to a path of your choice. Here is +the default configuration file, with the main parameters: + +``` ini +[server] + +# CalDAV server hostnames separated by a comma +# IPv4 syntax: address:port +# IPv6 syntax: [address]:port +# For example: 0.0.0.0:9999, [::]:9999 +# IPv6 adresses are configured to only allow IPv6 connections +#hosts = 0.0.0.0:5232 + +# Daemon flag +#daemon = False + +# File storing the PID in daemon mode +#pid = + +# SSL flag, enable HTTPS protocol +#ssl = False + +# SSL certificate path +#certificate = /etc/apache2/ssl/server.crt + +# SSL private key +#key = /etc/apache2/ssl/server.key + +# SSL Protocol used. See python's ssl module for available values +#protocol = PROTOCOL_SSLv23 + +# Ciphers available. See python's ssl module for available ciphers +#ciphers = + +# Reverse DNS to resolve client address in logs +#dns_lookup = True + +# Root URL of Radicale (starting and ending with a slash) +#base_prefix = / + +# Possibility to allow URLs cleaned by a HTTP server, without the base_prefix +#can_skip_base_prefix = False + +# Message displayed in the client when a password is needed +#realm = Radicale - Password Required + + +[encoding] + +# Encoding for responding requests +#request = utf-8 + +# Encoding for storing local collections +#stock = utf-8 + + +[well-known] + +# Path where /.well-known/caldav/ is redirected +#caldav = '/%(user)s/caldav/' + +# Path where /.well-known/carddav/ is redirected +#carddav = '/%(user)s/carddav/' + + +[auth] + +# Authentication method +# Value: None | htpasswd | IMAP | LDAP | PAM | courier | http | remote_user | custom +#type = None + +# Custom authentication handler +#custom_handler = + +# Htpasswd filename +#htpasswd_filename = /etc/radicale/users + +# Htpasswd encryption method +# Value: plain | sha1 | ssha | crypt | bcrypt | md5 +#htpasswd_encryption = crypt + +# LDAP server URL, with protocol and port +#ldap_url = ldap://localhost:389/ + +# LDAP base path +#ldap_base = ou=users,dc=example,dc=com + +# LDAP login attribute +#ldap_attribute = uid + +# LDAP filter string +# placed as X in a query of the form (&(...)X) +# example: (objectCategory=Person)(objectClass=User)(memberOf=cn=calenderusers,ou=users,dc=example,dc=org) +# leave empty if no additional filter is needed +#ldap_filter = + +# LDAP dn for initial login, used if LDAP server does not allow anonymous searches +# Leave empty if searches are anonymous +#ldap_binddn = + +# LDAP password for initial login, used with ldap_binddn +#ldap_password = + +# LDAP scope of the search +#ldap_scope = OneLevel + +# IMAP Configuration +#imap_hostname = localhost +#imap_port = 143 +#imap_ssl = False + +# PAM group user should be member of +#pam_group_membership = + +# Path to the Courier Authdaemon socket +#courier_socket = + +# HTTP authentication request URL endpoint +#http_url = +# POST parameter to use for username +#http_user_parameter = +# POST parameter to use for password +#http_password_parameter = + + +[git] + +# Git default options +#committer = Radicale + + +[rights] + +# Rights backend +# Value: None | authenticated | owner_only | owner_write | from_file | custom +#type = None + +# Custom rights handler +#custom_handler = + +# File for rights management from_file +#file = ~/.config/radicale/rights + + +[storage] + +# Storage backend +# ------- +# WARNING: ONLY "filesystem" IS DOCUMENTED AND TESTED, +# OTHER BACKENDS ARE NOT READY FOR PRODUCTION. +# ------- +# Value: filesystem | multifilesystem | database | custom +#type = filesystem + +# Custom storage handler +#custom_handler = + +# Folder for storing local collections, created if not present +#filesystem_folder = ~/.config/radicale/collections + +# Database URL for SQLAlchemy +# dialect+driver://user:password@host/dbname[?key=value..] +# For example: sqlite:///var/db/radicale.db, postgresql://user:password@localhost/radicale +# See http://docs.sqlalchemy.org/en/rel_0_8/core/engines.html#sqlalchemy.create_engine +#database_url = + + +[logging] + +# Logging configuration file +# If no config is given, simple information is printed on the standard output +# For more information about the syntax of the configuration file, see: +# http://docs.python.org/library/logging.config.html +#config = /etc/radicale/logging +# Set the default logging level to debug +#debug = False +# Store all environment variables (including those set in the shell) +#full_environment = False + + +[headers] + +# Additional HTTP headers +#Access-Control-Allow-Origin = * +``` + +This configuration file is read each time the server is launched. If +some values are not given, the default ones are used. If no +configuration file is available, all the default values are used. + +###### Logging Configuration File + +Radicale uses the default logging facility for Python. The default +configuration prints the information messages to the standard output. It +is possible to print debug messages thanks to: + + radicale --debug + +Radicale can also be configured to send the messages to the console, +logging files, syslog, etc. For more information about the syntax of the +configuration file, see: +. Here is an example +of logging configuration file: + +``` ini +# Loggers, handlers and formatters keys + +[loggers] +# Loggers names, main configuration slots +keys = root + +[handlers] +# Logging handlers, defining logging output methods +keys = console,file + +[formatters] +# Logging formatters +keys = simple,full + + +# Loggers + +[logger_root] +# Root logger +level = DEBUG +handlers = console,file + + +# Handlers + +[handler_console] +# Console handler +class = StreamHandler +level = INFO +args = (sys.stdout,) +formatter = simple + +[handler_file] +# File handler +class = FileHandler +args = ('/var/log/radicale',) +formatter = full + + +# Formatters + +[formatter_simple] +# Simple output format +format = %(message)s + +[formatter_full] +# Full output format +format = %(asctime)s - %(levelname)s: %(message)s +``` + +###### Command Line Options + +All the options of the `server` part can be changed with command line +options. These options are available by typing: + + radicale --help + +##### WSGI, CGI and FastCGI + +Radicale comes with a [WSGI](http://wsgi.org/) support, allowing the +software to be used behind any HTTP server supporting WSGI such as +Apache. + +Moreover, it is possible to use +[flup](https://pypi.python.org/pypi/flup/) to wrap Radicale into a CGI, +FastCGI, SCGI or AJP application, and therefore use it with Lighttpd, +Nginx or even Tomcat. + +###### Apache and mod\_wsgi + +To use Radicale with Apache's `mod_wsgi`, you first have to install the +Radicale module in your Python path and write your `.wsgi` file (in +`/var/www` for example): + +``` python +import radicale +radicale.log.start() +application = radicale.Application() +``` + +> **Note** +> +> The `hosts`, `daemon`, `pid`, `ssl`, `certificate`, `key`, `protocol` +> and `ciphers` keys of the `[server]` part of the configuration are +> ignored. + + +Next you have to create the Apache virtual host (adapt the configuration +to your environment): + +``` apache + + ServerName cal.yourdomain.org + + WSGIDaemonProcess radicale user=www-data group=www-data threads=1 + WSGIScriptAlias / /var/www/radicale.wsgi + + + WSGIProcessGroup radicale + WSGIApplicationGroup %{GLOBAL} + AllowOverride None + Order allow,deny + allow from all + + +``` + +> **Warning** +> +> You should use the root of the (sub)domain (`WSGIScriptAlias /`), else +> some CalDAV features may not work. + + +If you want to use authentication with Apache, you *really* should use +one of the Apache authentication modules, instead of the ones from +Radicale: they're just better. + +Deactivate any rights and module in Radicale and use your favourite +Apache authentication backend. You can then restrict the access: allow +the `alice` user to access `/alice/*` URLs, and everything should work +as expected. + +Here is one example of Apache configuration file: + +``` apache + + ServerName radicale.local + + WSGIDaemonProcess radicale user=radicale group=radicale threads=1 + WSGIScriptAlias / /usr/share/radicale/radicale.wsgi + + + WSGIProcessGroup radicale + WSGIApplicationGroup %{GLOBAL} + + AuthType Basic + AuthName "Radicale Authentication" + AuthBasicProvider file + AuthUserFile /usr/share/radicale/radicale.passwd + + AllowOverride None + Require valid-user + + RewriteEngine On + RewriteCond %{REMOTE_USER}%{PATH_INFO} !^([^/]+/)\1 + RewriteRule .* - [Forbidden] + + +``` + +If you're still convinced that access control is better with Radicale, +you have to add `WSGIPassAuthorization On` in your Apache configuration +files, as explained in [the mod\_wsgi +documentation](http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines#User_Authentication). + +> **Note** +> +> Read-only calendars or address books can also be served by a simple +> Apache HTTP server, as Radicale stores full-text icalendar and vcard +> files with the default configuration. + + +##### Authentication + +Authentication is possible through: + + - Courier-Authdaemon socket + - htpasswd file, including list of plain user/password couples + - HTTP, checking status code of a POST request + - IMAP + - LDAP + - PAM + - Remote user given by HTTP server + +Check the `[auth]` section of your configuration file to know the +different options offered by these authentication modules. + +Some authentication methods need additional modules, see [Python +Versions and OS Support](#python-versions-and-os-support) for further +information. + +You can also write and use a custom module handle authentication if you +use a different technology. + +Please note that these modules have not been verified by security +experts. If you need a really secure way to handle authentication, you +should put Radicale behind a real HTTP server and use its authentication +and rights management methods. + +##### Rights Management + +You can set read and write rights for collections according to the +authenticated user and the owner of the collection. + +The *owner of a collection* is determined by the URL of the collection. +For example, `http://my.server.com:5232/anna/calendar.ics/` is owned by +the user called `anna`. + +The *authenticated user* is the login used for authentication. + +5 different configurations are available, you can choose the one you +want in your configuration file. You can also write and use a custom +module handle rights management if you need a specific pattern. + +###### None + +Everybody (including anonymous users) has read and write access to all +collections. + +###### Authenticated + +An authenticated users has read and write access to all collections, +anonymous users have no access to these collections. + +###### Owner Only + +Only owners have read and write access to their own collections. The +other users, authenticated or anonymous, have no access to these +collections. + +###### Owner Write + +Authenticated users have read access to all collections, but only owners +have write access to their own collections. Anonymous users have no +access to collections. + +###### From File + +Rights are based on a regex-based file whose name is specified in the +config (section "right", key "file"). + +Authentication login is matched against the "user" key, and collection's +path is matched against the "collection" key. You can use Python's +ConfigParser interpolation values %(login)s and %(path)s. You can also +get groups from the user regex in the collection with {0}, {1}, etc. + +For example, for the "user" key, ".+" means "authenticated user" and +".\*" means "anybody" (including anonymous users). + +Section names are only used for naming the rule. + +Leading or ending slashes are trimmed from collection's path. + +Example: + +``` ini +# The default path for this kind of files is ~/.config/radicale/rights +# This can be changed in the configuration file +# +# This file gives independant examples to help users write their own +# configuration files. Using these examples together in the same configuration +# file is meaningless. +# +# The first rule matching both user and collection patterns will be returned. + +# This means all users starting with "admin" may read any collection +[admin] +user: ^admin.*$ +collection: .* +permission: r + +# This means all users may read and write any collection starting with public. +# We do so by just not testing against the user string. +[public] +user: .* +collection: ^public(/.+)?$ +permission: rw + +# A little more complex: give read access to users from a domain for all +# collections of all the users (ie. user@domain.tld can read domain/*). +[domain-wide-access] +user: ^.+@(.+)\..+$ +collection: ^{0}/.+$ +permission: r + +# Allow authenticated user to read all collections +[allow-everyone-read] +user: .+ +collection: .* +permission: r + +# Give write access to owners +[owner-write] +user: .+ +collection: ^%(login)s/.*$ +permission: w +``` + +##### Git Support + +> **Note** +> +> If the project doesn't comply with the requirements to use Git, Radicale +> will still work. Your collections will run fine but without the +> versionning system. + + +Git is now automatically supported on Radicale. It depends on +[dulwich](https://github.com/jelmer/dulwich). + +###### Configure Radicale + +Radicale automatically detects the *.git* folder in the path you +configured for the filesystem\_folder variable in the `[storage]` +section of your configuration file. Make sure a repository is created at +this location or create one (using *git init .* for instance) else it +won't work. + +To summarize : + + - Configure your Git installation + - Get Radicale and dulwich + - Create the repository where your collections are stored + - Run Radicale and it should work + +###### How it works + +Radicale will automatically commit any changes on your collections. It +will use your git config to find parameters such as the committer and +that's all. + +###### Issues + +A dulwich project ported on Python 3 exists but it seems that it doesn't +follow the current api (committer is mandatory and not retrieved from +the git config by default). Until this problem isn't fixed, the Git +support for Radicale on Python 3 will not be ensured. + +#### Python Versions and OS Support + +##### TLS Support + +Python 2.6 suffered [a bug](http://bugs.python.org/issue5103) causing +huge timeout problems with TLS. The bug is fixed since Python 2.6.6. + +IMAP authentication over TLS requires Python 3.2. + +Python 2.7 and Python 3.x do not suffer this bug. + +##### Crypt Support + +With the htpasswd access, many encryption methods are available, and +crypt is the default one in Radicale. Unfortunately, the `crypt` module +is unavailable on Windows, you have to pick another method on this OS. + +Additional `md5` and `bcrypt` methods are available when the `passlib` +module is installed. + +##### IMAP Authentication + +The IMAP authentication module relies on the imaplib module, available +with 2.x versions of Python. However, TLS is only available in Python +3.2. Older versions of Python or a non-modern server who does not +support STARTTLS can only authenticate against `localhost` as passwords +are transmitted in PLAIN. Legacy SSL mode on port 993 is not supported. + +##### LDAP Authentication + +The LDAP authentication module relies on [the python-ldap +module](http://www.python-ldap.org/), and thus only works with 2.x +versions of Python. + +##### PAM Authentication + +The PAM authentication module relies on [the python-pam +module](https://pypi.python.org/pypi/python-pam/). + +Bear in mind that on Linux systems, if you're authenticating against PAM +files (i.e. `/etc/shadow`), the user running Radicale must have the +right permissions. For instance, you might want to add the `radicale` +user to the `shadow` group. + +##### HTTP Authentication + +The HTTP authentication module relies on [the requests +module](http://docs.python-requests.org/en/latest/). + +##### Daemon Mode + +The daemon mode relies on forks, and thus only works on Unix-like OSes +(incuding Linux, OS X, BSD). + +### Project Description + +#### Main Goals + +The Radicale Project is a complete calendar and contact storing and +manipulating solution. It can store multiple calendars and multiple +address books. + +Calendar and contact manipulation is available from both local and +distant accesses, possibly limited through authentication policies. + +#### What Radicale Is + +##### Calendar and Contact Server + +The Radicale Project is mainly a calendar and contact server, giving +local and distant access for reading, creating, modifying and deleting +multiple calendars through simplified CalDAV and CardDAV protocols. + +Data can be encrypted by SSL, and their access can be restricted using +different authentication methods. + +#### What Radicale Is not and will not Be + +##### Calendar or Contact User Agent + +Radicale is a server, not a client. No interfaces will be created to +work with the server, as it is a really (really really) much more +difficult task[\[3\]](#3). + +##### Original Calendar or Contact Access Protocol + +CalDAV and CardDAV are not perfect protocols. We think that their main +problem is their complexity[\[4\]](#4), that is why we decided not to +implement the whole standard but just enough to understand some of its +client-side implementations [\[5\]](#5). + +CalDAV and CardDAV are the best open standards available and they are +quite widely used by both clients and servers[\[6\]](#6). We decided to use +it, and we will not use another one. + +### Technical Choices + +#### Global Technical Choices + +##### General Description + +The Radicale Project aims to be a light solution, easy to use, easy to +install, easy to configure. As a consequence, it requires few software +dependencies and is pre-configured to work out-of-the-box. + +The Radicale Project runs on most of the UNIX-like platforms (Linux, +\*BSD, MacOS X) and Windows. It is free and open-source software. + +##### Language + +The different parts of the Radicale Project are written in Python. This +is a high-level language, fully object-oriented, available for the main +operating systems and released with a lot of useful libraries. + +##### Protocols and Formats + +The main protocols and formats fully or partially implemented in the +Radicale Project are described by RFCs: + + - HyperText Transfer Protocol (HTTP) + [RFC 2616](http://www.faqs.org/rfcs/rfc2616.html "RFC 2616") + - WebDAV Access Control Protocol (ACL) + [RFC 3744](http://www.faqs.org/rfcs/rfc3744.html "RFC 3744") + - Calendaring Extensions to WebDAV (CalDAV) + [RFC 4791](http://www.faqs.org/rfcs/rfc4791.html "RFC 4791") + - HTTP Extensions for Web Distributed Authoring and Versioning + (WebDAV) + [RFC 4918](http://www.faqs.org/rfcs/rfc4918.html "RFC 4918") + - Transport Layer Security (TLS) + [RFC 5246](http://www.faqs.org/rfcs/rfc5246.html "RFC 5246") + - iCalendar format (iCal) + [RFC 5545](http://www.faqs.org/rfcs/rfc5545.html "RFC 5545") + - vCard Format Specification + [RFC 6350](http://www.faqs.org/rfcs/rfc6350.html "RFC 6350") + - vCard Extensions to Web Distributed Authoring and Versioning + (CardDAV) + [RFC 6352](http://www.faqs.org/rfcs/rfc6352.html "RFC 6352") + +> **Note** +> +> CalDAV and CardDAV implementations **require** iCal, vCard, ACL, WebDAV, +> HTTP and TLS. The Radicale Server **does not and will not implement +> correctly** these standards, as explained in the [Development +> Choices](#development-choices) part. + + +##### Development Choices + +Important global development choices have been decided before writing +code. They are very useful to understand why the Radicale Project is +different from other CalDAV and CardDAV servers, and why features are +included or not in the code. + +###### Oriented to Calendar and Contact User Agents + +Calendar and contact servers work with calendar and contact clients, +using a defined protocol. CalDAV and CardDAV are good protocols, +covering lots of features and use cases, but it is quite hard to +implement fully. + +Some calendar servers have been created to follow the CalDAV and CardDAV +RFCs as much as possible: Davical[\[7\]](#7), Cosmo[\[8\]](#8) and Darwin Calendar +Server[\[9\]](#9), for example, are much more respectful of CalDAV and CardDAV +and can be used with a large number of clients. They are very good +choices if you want to develop and test new CalDAV clients, or if you +have a possibly heterogeneous list of user agents. + +The Radicale Server does not and **will not** support the CalDAV and +CardDAV standards. It supports the CalDAV and CardDAV implementations of +different clients (Lightning, Evolution, Android, iPhone, iCal, and +more). + +###### Simple + +The Radicale Server is designed to be simple to install, simple to +configure, simple to use. + +The installation is very easy, particularly with Linux: no dependencies, +no superuser rights needed, no configuration required. Launching the +main script out-of-the-box, as a normal user, is often the only step to +have a simple remote calendar and contact access. + +Contrary to other servers that are often complicated, require high +privileges or need a strong configuration, the Radicale Server can +(sometimes, if not often) be launched in a couple of minutes, if you +follow the [User +Documentation](#user-documentation-1). + +###### Lazy + +We, Radicale Project developers, are lazy. That is why we have chosen +Python: no more `;` or `{}`[\[10\]](#10). This is also why our server is lazy. + +The CalDAV RFC defines what must be done, what can be done and what +cannot be done. Many violations of the protocol are totally defined and +behaviours are given in such cases. + +The Radicale Server assumes that the clients are perfect and that +protocol violations do not exist. That is why most of the errors in +client requests have undetermined consequences for the lazy server that +can reply good answers, bad answers, or even no answer. + +As already mentioned, the Radicale server doesn't fully support the +CalDAV and CardDAV RFCs. For example, nested filters in queries +currently don't work in all cases. Examples of not working queries can +be found in issues [\#120](https://github.com/Kozea/Radicale/issues/120) +and [\#121](https://github.com/Kozea/Radicale/issues/121). + +#### Architectures + +##### General Architecture + +Here is a simple overview of the global architecture for reaching a +calendar through network: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PartLayerProtocol or Format
ServerCalendar/Contact StorageiCal/vCard
Calendar/Contact ServerCalDAV/CardDAV Server
TransferNetworkCalDAV/CardDAV (HTTP + TLS)
ClientCalendar/Contact ClientCalDAV/CardDAV Client
GUITerminal, GTK, etc.
+ +The Radicale Project is **only the server part** of this architecture. + +##### Code Architecture + +The package offers 8 modules. + + - `__main__` + The main module provides a simple function called `run`. Its main + work is to read the configuration from the configuration file and + from the options given in the command line; then it creates a + server, according to the configuration. + + - `__init__` + This is the core part of the module, with the code for the CalDAV + server. The server inherits from a HTTP or HTTPS server class, which + relies on the default HTTP server class given by Python. The code + managing the different HTTP requests according to the CalDAV + normalization is written here. + + - `config` + This part gives a dict-like access to the server configuration, read + from the configuration file. The configuration can be altered when + launching the executable with some command line options. + + - `ical` + In this module are written the classes to represent collections and + items in Radicale. The simple iCalendar and vCard readers and + writers are included in this file. The readers and writers are small + and stupid: they do not fully understand the iCalendar format and do + not know at all what a date is. + + - `xmlutils` + The functions defined in this module are mainly called by the CalDAV + server class to read the XML part of the request, read or alter the + calendars, and create the XML part of the response. The main part of + this code relies on ElementTree. + + - `log` + The `start` function provided by this module starts a logging + mechanism based on the default Python logging module. Logging + options can be stored in a logging configuration file. + + - `acl` + This module is a set of Access Control Lists, a set of methods used + by Radicale to manage rights to access the calendars. When the + CalDAV server is launched, an Access Control List is chosen in the + set, according to the configuration. The HTTP requests are then + filtered to restrict the access using a list of login/password-based + access controls. + + - `storage` + This folder is a set of storage modules able to read and write + collections. Currently there are three storage modules: + `filesystem`, storing each collection into one flat plain-text file, + `multifilesystem`, storing each entries into separates plain-text + files, and `database`, storing entries in a database. `filesystem` + is stable and battle-tested, others are experimentals. + + diff --git a/md/v1/02_contribute.md b/md/v1/02_contribute.md new file mode 100644 index 000000000..fd23224ff --- /dev/null +++ b/md/v1/02_contribute.md @@ -0,0 +1,16 @@ +## Contribute + +#### Chat with Us on IRC + +Want to say something? Join our IRC room: \#\#kozea on Freenode. + +#### Report Bugs + +Found a bug? Want a new feature? Report a new issue on the `Radicale +bug-tracker`. + +#### Hack + +Interested in hacking? Feel free to clone the `git repository on +Github` if you want to add new features, fix bugs or update +documentation. diff --git a/md/v1/03_download.md b/md/v1/03_download.md new file mode 100644 index 000000000..7203a4c18 --- /dev/null +++ b/md/v1/03_download.md @@ -0,0 +1,97 @@ +## Download + +#### PyPI + +Radicale is [available on PyPI](http://pypi.python.org/pypi/Radicale/). +To install, just type as superuser: + + pip install radicale==1.1.* + +#### Git Repository + +If you want the development version of Radicale, take a look at the `git +repository on GitHub`, or clone it thanks to: + + git clone git://github.com/Kozea/Radicale.git + +You can also download [the Radicale package of the git +repository](https://github.com/Kozea/Radicale/tarball/master). + +#### Source Packages + +You can download the Radicale package for each release: + + - [Radicale-1.1.7.tar.gz](https://files.pythonhosted.org/packages/source/R/Radicale/Radicale-1.1.7.tar.gz) + - [Radicale-1.1.6.tar.gz](https://files.pythonhosted.org/packages/source/R/Radicale/Radicale-1.1.6.tar.gz) + - [Radicale-1.1.5.tar.gz](https://files.pythonhosted.org/packages/source/R/Radicale/Radicale-1.1.5.tar.gz) + - [Radicale-1.1.4.tar.gz](https://files.pythonhosted.org/packages/source/R/Radicale/Radicale-1.1.4.tar.gz) + - [Radicale-1.1.3.tar.gz](https://files.pythonhosted.org/packages/source/R/Radicale/Radicale-1.1.3.tar.gz) + - [Radicale-1.1.2.tar.gz](https://files.pythonhosted.org/packages/source/R/Radicale/Radicale-1.1.2.tar.gz) + (47 KiB) + - [Radicale-1.1.1.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-1.1.1.tar.gz) + (47 KiB) + - [Radicale-1.1.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-1.1.tar.gz) + (47 KiB) + - [Radicale-1.0.1.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-1.0.1.tar.gz) + (42 KiB) + - [Radicale-1.0.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-1.0.tar.gz) + (42 KiB) + - [Radicale-0.10.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.10.tar.gz) + (42 KiB) + - [Radicale-0.9.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.9.tar.gz) + (42 KiB) + - [Radicale-0.8.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.8.tar.gz) + (38 KiB) + - [Radicale-0.7.1.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.7.1.tar.gz) + (34 KiB) + - [Radicale-0.7.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.7.tar.gz) + (34 KiB) + - [Radicale-0.6.4.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.6.4.tar.gz) + (31 KiB) + - [Radicale-0.6.3.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.6.3.tar.gz) + (31 KiB) + - [Radicale-0.6.2.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.6.2.tar.gz) + (30 KiB) + - [Radicale-0.6.1.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.6.1.tar.gz) + (30 KiB) + - [Radicale-0.6.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.6.tar.gz) + (30 KiB) + - [Radicale-0.5.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.5.tar.gz) + (24 KiB) + - [Radicale-0.4.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.4.tar.gz) + (23 KiB) + - [Radicale-0.3.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.3.tar.gz) + (22 KiB) + - [Radicale-0.2.tar.gz](http://pypi.python.org/packages/source/R/Radicale/Radicale-0.2.tar.gz) + (22 KiB) + +#### Linux Distribution Packages + +Radicale has been packaged for: + + - [ArchLinux (AUR)](https://aur.archlinux.org/packages/radicale/) by + Guillaume Bouchard + - [Debian](http://packages.debian.org/radicale) by Jonas Smedegaard + - [Gentoo (Sunrise + Overlay)](http://bugs.gentoo.org/show_bug.cgi?id=322811) by René + Neumann + - [Fedora](https://admin.fedoraproject.org/pkgdb/package/radicale/) by + Jorti + - [Mandriva/Mageia](http://sophie.zarb.org/search/results?search=radicale) + by Jani Välimaa + - [OpenBSD](http://openports.se/productivity/radicale) by Sergey + Bronnikov, Stuart Henderson and Ian Darwin + - [openSUSE](http://software.opensuse.org/package/Radicale?search_term=radicale) + - [PyPM](http://code.activestate.com/pypm/radicale/) + - [Slackware](http://schoepfer.info/slackware.xhtml#packages-network) + by Johannes Schöpfer + - [Trisquel](http://packages.trisquel.info/search?searchon=names&keywords=radicale) + - [Ubuntu](http://packages.ubuntu.com/radicale) by the MOTU and Jonas + Smedegaard + +Radicale is also [available on +Cloudron](https://cloudron.io/button.html?app=org.radicale.cloudronapp) +and has a Dockerfile. + +If you are interested in creating packages for other Linux +distributions, read the ["Contribute" page](#contribute). diff --git a/md/v1/04_news.md b/md/v1/04_news.md new file mode 100644 index 000000000..c1bf8ce09 --- /dev/null +++ b/md/v1/04_news.md @@ -0,0 +1,900 @@ +## News + + +### May 19, 2020 - Radicale 1.1.7 + +Radicale 1.1.7 is out\! + +#### 1.1.7 - Third Law of Nature + + - Fix error in `--export-storage` + - Include documentation in source archive + +### Jul 24, 2017 - Radicale 1.1.6 + +Radicale 1.1.6 is out\! + +#### 1.1.6 - Third Law of Nature + + - Improve logging for `--export-storage` + +### Jul 24, 2017 - Radicale 1.1.5 + +Radicale 1.1.5 is out\! + +#### 1.1.5 - Third Law of Nature + + - Improve logging for `--export-storage` + +### Jun 25, 2017 - Radicale 1.1.4 + +Radicale 1.1.4 is out\! + +#### 1.1.4 - Third Law of Nature + + - Use shutil.move for `--export-storage` + +### May 27, 2017 - Radicale 1.1.3 + +Radicale 1.1.3 is out\! + +#### 1.1.3 - Third Law of Nature + + - Add a `--export-storage=FOLDER` command-line argument (by Unrud, see + [#606](https://github.com/Kozea/Radicale/pull/606)) + +### April 19, 2017 - Radicale 1.1.2 + +Radicale 1.1.2 is out\! + +#### 1.1.2 - Third Law of Nature + + - Security fix: Add a random timer to avoid timing oracles and simple + bruteforce attacks when using the htpasswd authentication method. + - Various minor fixes. + +### December 31, 2015 - Radicale 1.1 + +Radicale 1.1 is out\! + +#### 1.1 - Law of Nature + +One feature in this release is **not backward compatible**: + + - Use the first matching section for rights (inspired from daald) + +Now, the first section matching the path and current user in your custom +rights file is used. In the previous versions, the most permissive +rights of all the matching sections were applied. This new behaviour +gives a simple way to make specific rules at the top of the file +independant from the generic ones. + +Many **improvements in this release are related to security**, you +should upgrade Radicale as soon as possible: + + - Improve the regex used for well-known URIs (by Unrud) + - Prevent regex injection in rights management (by Unrud) + - Prevent crafted HTTP request from calling arbitrary functions (by + Unrud) + - Improve URI sanitation and conversion to filesystem path (by Unrud) + - Decouple the daemon from its parent environment (by Unrud) + +Some bugs have been fixed and little enhancements have been added: + + - Assign new items to corret key (by Unrud) + - Avoid race condition in PID file creation (by Unrud) + - Improve the docker version (by cdpb) + - Encode message and commiter for git commits + - Test with Python 3.5 + +### September 14, 2015 - Radicale 1.0, what's next? + +Radicale 1.0 is out\! + +#### 1.0 - Sunflower + + - Enhanced performances (by Mathieu Dupuy) + - Add MD5-APR1 and BCRYPT for htpasswd-based authentication (by + Jan-Philip Gehrcke) + - Use PAM service (by Stephen Paul Weber) + - Don't discard PROPPATCH on empty collections (Markus Unterwaditzer) + - Write the path of the collection in the git message (Matthew Monaco) + - Tests launched on Travis + +As explained in a previous +[mail](http://librelist.com/browser//radicale/2015/8/21/radicale-1-0-is-coming-what-s-next/), +this version is called 1.0 because: + + - there are no big changes since 0.10 but some small changes are + really useful, + - simple tests are now automatically launched on Travis, and more can + be added in the future (). + +This version will be maintained with only simple bug fixes on a separate +git branch called `1.0.x`. + +Now that this milestone is reached, it's time to think about the future. +When Radicale has been created, it was just a proof-of-concept. The main +goal was to write a small, stupid and simple CalDAV server working with +Lightning, using no external libraries. That's how we created a piece of +code that's (quite) easy to understand, to use and to hack. + +The first lines have been added to the SVN (\!) repository as I was +drinking beers at the very end of 2008. It's now packaged for a growing +number of Linux distributions. + +And that was fun going from here to there thanks to you. So… **Thank +you, you're amazing**. I'm so glad I've spent endless hours fixing +stupid bugs, arguing about databases and meeting invitations, reading +incredibly interesting RFCs and debugging with the fabulous clients from +Apple. I mean: that really, really was really, really cool :). + +During these years, a lot of things have changed and many users now rely +on Radicale in production. For example, I use it to manage medical +calendars, with thousands requests per day. Many people are happy to +install Radicale on their small home servers, but are also frustrated by +performance and unsupported specifications when they're trying to use it +seriously. + +So, now is THE FUTURE\! I think that Radicale 2.0 should: + + - rely on a few external libraries for simple critical points (dealing + with HTTP and iCal for example), + - be thread-safe, + - be small, + - be documented in a different way (for example by splitting the + client part from the server part, and by adding use cases), + - let most of the "auth" modules outside in external modules, + - have more and more tests, + - have reliable and faster filesystem and database storage mechanisms, + - get a new design :). + +I'd also secretly love to drop the Python 2.x support. + +These ideas are not all mine (except from the really, really, really +important "design" point :p), they have been proposed by many developers +and users. I've just tried to gather them and keep points that seem +important to me. + +Other points have been discussed with many users and contibutors, +including: + + - support of other clients, including Windows and BlackBerry phones, + - server-side meeting invitations, + - different storage system as default (or even unique?). + +I'm not a huge fan of these features, either because I can't do anything +about them, or because I think that they're Really Bad Ideas®™. But I'm +ready to talk about them, because, well, I may not be always right\! + +Need to talk about this? You know how to [contact us](#contribute)\! + +### January 12, 2015 - Radicale 0.10 + +Radicale 0.10 is out\! + +#### 0.10 - Lovely Endless Grass + + - Support well-known URLs (by Mathieu Dupuy) + - Fix collection discovery (by Markus Unterwaditzer) + - Reload logger config on SIGHUP (by Élie Bouttier) + - Remove props files when deleting a collection (by Vincent Untz) + - Support salted SHA1 passwords (by Marc Kleine-Budde) + - Don't spam the logs about non-SSL IMAP connections to localhost (by + Giel van Schijndel) + +This version should bring some interesting discovery and +auto-configuration features, mostly with Apple clients. + +Lots of love and kudos for the people who have spent hours to test +features and report issues, that was long but really useful (and some of +you have been really patient :p). + +Issues are welcome, I'm sure that you'll find horrible, terrible, crazy +bugs faster than me. I'll release a version 0.10.1 if needed. + +What's next? It's time to fix and improve the storage methods. A real +API for the storage modules is a good beginning, many pull requests are +already ready to be discussed and merged, and we will probably get some +good news about performance this time. Who said "databases, please"? + +### July 12, 2013 - Radicale 0.8 + +Radicale 0.8 is out\! + +#### 0.8 - Rainbow + + - New authentication and rights management modules (by Matthias + Jordan) + - Experimental database storage + - Command-line option for custom configuration file (by Mark Adams) + - Root URL not at the root of a domain (by Clint Adams, Fabrice + Bellet, Vincent Untz) + - Improved support for iCal, CalDAVSync, CardDAVSync, CalDavZAP and + CardDavMATE + - Empty PROPFIND requests handled (by Christoph Polcin) + - Colon allowed in passwords + - Configurable realm message + +This version brings some of the biggest changes since Radicale's +creation, including an experimental support of database storage, clean +authentication modules, and rights management finally designed for real +users. + +So, dear user, be careful: **this version changes important things in +the configuration file, so check twice that everything is OK when you +update to 0.8, or you can have big problems**. + +More and more clients are supported, as a lot of bug fixes and features +have been added for this purpose. And before you ask: yes, 2 web-based +clients, [CalDavZAP and +CardDavMATE](http://www.inf-it.com/open-source/clients/), are now +supported\! + +Even if there has been a lot of time to test these new features, I am +pretty sure that some really annoying bugs have been left in this +version. We will probably release minor versions with bugfixes during +the next weeks, and it will not take one more year to reach 0.8.1. + +The documentation has been updated, but some parts are missing and some +may be out of date. You can [report +bugs](https://github.com/Kozea/Radicale/issues) or even [write +documentation directly on +GitHub](https://github.com/Kozea/Radicale/blob/website/pages/user_documentation.rst) +if you find something strange (and you probably will). + +If anything is not clear, or if the way rights work is a bit complicated +to understand, or if you are so happy because everything works so well, +you can [share your thoughts](#contribute)\! + +It has been a real pleasure to work on this version, with brilliant +ideas and interesting bug reports from the community. I'd really like to +thank all the people reporting bugs, chatting on IRC, sending mails and +proposing pull requests: you are awesome. + +### August 3, 2012 - Radicale 0.7.1 + +Radicale 0.7.1 is out\! + +#### 0.7.1 - Waterfalls + + - Many address books fixes + - New IMAP ACL (by Daniel Aleksandersen) + - PAM ACL fixed (by Daniel Aleksandersen) + - Courier ACL fixed (by Benjamin Frank) + - Always set display name to collections (by Oskari Timperi) + - Various DELETE responses fixed + +It's been a long time since the last version… As usual, many people have +contributed to this new version, that's a pleasure to get these pull +requests. + +Most of the commits are bugfixes, especially about ACL backends and +address books. Many clients (including aCal and SyncEvolution) will be +much happier with this new version than with the previous one. + +By the way, one main new feature has been added: a new IMAP ACL backend, +by Daniel. And about authentication, exciting features are coming soon, +stay tuned\! + +Next time, as many mails have come from angry and desperate coders, +tests will be *finally* added to help them to add features and fix bugs. +And after that, who knows, it may be time to release Radicale 1.0… + +### March 22, 2012 - Radicale 0.7 + +Radicale 0.7 is out, at least\! + +#### 0.7 - Eternal Sunshine + + - Repeating events + - Collection deletion + - Courier and PAM authentication methods + - CardDAV support + - Custom LDAP filters supported + +**A lot** of people have reported bugs, proposed new features, added +useful code and tested many clients. Thank you Lynn, Ron, Bill, Patrick, +Hidde, Gerhard, Martin, Brendan, Vladimir, and everybody I've forgotten. + +### January 5, 2012 - Radicale 0.6.4, News from Calypso + +New year, new release. Radicale 0.6.4 has a really short changelog: + +#### 0.6.4 - Tulips + + - Fix the installation with Python 3.1 + +The bug was in fact caused by a [bug in +Python 3.1](http://bugs.python.org/issue9561), everything should be OK +now. + +#### Calypso + +After a lot of changes in Radicale, Keith Packard has decided to launch +a fork called [Calypso](http://keithp.com/blogs/calypso/), with nice +features such as a Git storage mechanism and a CardDAV support. + +There are lots of differences between the two projects, but the final +goal for Radicale is to provide these new features as soon as possible. +Thanks to the work of Keith and other people on GitHub, a basic CardDAV +support has been added in the [carddav +branch](https://github.com/Kozea/Radicale/tree/carddav) and already +works with Evolution. Korganizer also works with existing address books, +and CardDAV-Sync will be tested soon. If you want to test other clients, +please let us know\! + +### November 3, 2011 - Radicale 0.6.3 + +Radicale version 0.6.3 has been released, with bugfixes that could be +interesting for you\! + +#### 0.6.3 - Red Roses + + - MOVE requests fixed + - Faster REPORT answers + - Executable script moved into the package + +#### What's New Since 0.6.2? + +The MOVE requests were suffering a little bug that is fixed now. These +requests are only sent by Apple clients, Mac users will be happy. + +The REPORT request were really, really slow (several minutes for large +calendars). This was caused by an awful algorithm parsing the entire +calendar for each event in the calendar. The calendar is now only parsed +three times, and the events are found in a Python list, turning minutes +into seconds\! Much better, but far from perfection… + +Finally, the executable script parsing the command line options and +starting the HTTP servers has been moved from the `radicale.py` file +into the `radicale` package. Two executable are now present in the +archive: the good old `radicale.py`, and `bin/radicale`. The second one +is only used by `setup.py`, where the hack used to rename `radicale.py` +into `radicale` has therefore been removed. As a consequence, you can +now launch Radicale with the simple `python -m radicale` command, +without relying on an executable. + +#### Time for a Stable Release\! + +The next release may be a stable release, symbolically called 1.0. Guess +what's missing? Tests, of course\! + +A non-regression testing suite, based on the clients' requests, will +soon be added to Radicale. We're now thinking about a smart solution to +store the tests, to represent the expected answers and to launch the +requests. We've got crazy ideas, so be prepared: you'll definitely +*want* to write tests during the next weeks\! + +Repeating events, PAM and Courier authentication methods have already +been added in master. You'll find them in the 1.0 release\! + +#### What's Next? + +Being stable is one thing, being cool is another one. If you want some +cool new features, you may be interested in: + + - WebDAV and CardDAV support + - Filters and rights management + - Multiple storage backends, such as databases and git + - Freebusy periods + - Email alarms + +Issues have been reported in the bug tracker, you can follow there the +latest news about these features. Your beloved text editor is waiting +for you\! + +### September 27, 2011 - Radicale 0.6.2 + +0.6.2 is out with minor bugfixes. + +#### 0.6.2 - Seeds + + - iPhone and iPad support fixed + - Backslashes replaced by slashes in PROPFIND answers on Windows + - PyPI archive set as default download URL + +### August 28, 2011 - Radicale 0.6.1, Changes, Future + +As previously imagined, a new 0.6.1 version has been released, mainly +fixing obvious bugs. + +#### 0.6.1 - Growing Up + + - Example files included in the tarball + - htpasswd support fixed + - Redirection loop bug fixed + - Testing message on GET requests + +The changelog is really small, so there should be no real new problems +since 0.6. The example files for logging, FastCGI and WSGI are now +included in the tarball, for the pleasure of our dear packagers\! + +A new branch has been created for various future bug fixes. You can +expect to get more 0.6.x versions, making this branch a kind of "stable" +branch with no big changes. + +#### GitHub, Mailing List, New Website + +A lot of small changes occurred during the last weeks. + +If you're interested in code and new features, please note that we moved +the project from Gitorious to `GitHub`. Being hosted by Gitorious was a +nice experience, but the service was not that good and we were missing +some useful features such as git hooks. Moreover, GitHub is really +popular, we're sure that we'll meet a lot of kind users and coders +there. + +We've also created a `mailing-list on Librelist` to keep a public trace +of the mails we're receiving. It a bit empty now, but we're sure that +you'll soon write us some kind words. For example, you can tell us what +you think of our new website\! + +#### Future Features + +In the next weeks, new exciting features are coming in the master +branch\! Some of them are almost ready: + + - Henry-Nicolas has added the support for the PAM and + Courier-Authdaemon authentication mechanisms. + - An anonymous called Keith Packard has prepared some small changes, + such as one file per event, cache and git versioning. Yes. Really. + +As you can find in the [Radicale +Roadmap](http://redmine.kozea.fr/versions/), tests, rights and filters +are expected for 0.7. + +### August 1, 2011 - Radicale 0.6 Released + +Time for a new release with **a lot** of new exciting features\! + +#### 0.6 - Sapling + + - WSGI support + - IPv6 support + - Smart, verbose and configurable logs + - Apple iCal 4 and iPhone support (by Łukasz Langa) + - CalDAV-Sync support (by Marten Gajda) + - aCal support + - KDE KOrganizer support + - LDAP auth backend (by Corentin Le Bail) + - Public and private calendars (by René Neumann) + - PID file + - MOVE requests management + - Journal entries support + - Drop Python 2.5 support + +Well, it's been a little longer than expected, but for good reasons: a +lot of features have been added, and a lot of clients are known to work +with Radicale, thanks to kind contributors. That's definitely good +news\! But… + +Testing all the clients is really painful, moreover for the ones from +Apple (I have no Mac nor iPhone of my own). We should seriously think of +automated tests, even if it's really hard to maintain, and maybe not +that useful. If you're interested in tests, you can look at [the +wonderful regression suite of +DAViCal](http://repo.or.cz/w/davical.git/tree/HEAD:/testing/tests/regression-suite). + +The new features, for example the WSGI support, are also poorly +documented. If you have some Apache or lighttpd configuration working +with Radicale, you can make the world a little bit better by writing a +paragraph or two in the [Radicale +documentation](https://gitorious.org/radicale/website). It's simple +plain text, don't be afraid\! + +Because of all these changes, Radicale 0.6 may be a little bit buggy; a +0.6.1 will probably be released soon, fixing small problems with clients +and features. Get ready to report bugs, I'm sure that you can find one +(and fix it)\! + +### July 2, 2011 - Feature Freeze for 0.6 + +According to the +[roadmap](http://redmine.kozea.fr/projects/radicale/roadmap), a lot of +features have been added since Radicale 0.5, much more than expected. +It's now time to test Radicale with your favourite client and to report +bugs before we release the next stable version\! + +Last week, the iCal and iPhone support written by Łukasz has been fixed +in order to restore the broken Lightning support. After two afternoons +of tests with Rémi, we managed to access the same calendar with +Lightning, iCal, iPhone and Evolution, and finally discovered that +CalDAV could also be a perfect instant messaging protocol between a Mac, +a PC and a phone. + +After that, we've had the nice surprise to see events displayed without +a problem (but after some strange steps of configuration) by aCal on +Salem's Android phone. + +It was Friday, fun fun fun fun. + +So, that's it: Radicale supports Lightning, Evolution, Kontact, aCal for +Android, iPhone and iCal. Of course, before releasing a new tarball: + + - [documentation](#starting-the-client) + is needed for the new clients that are not documented yet (Kontact, + aCal and iPhone); + - tests are welcome, particularly for the Apple clients that I can't + test anymore; + - no more features will be added, they'll wait in separate branches + for the 0.7 development. + +Please [report bugs](http://redmine.kozea.fr/projects/radicale/issues) +if anything goes wrong during your tests, or just let us know [by Jabber +or by mail](#contribute) if everything is OK. + +### May 1, 2011 - Ready for WSGI + +Here it is\! Radicale is now ready to be launched behind your favourite +HTTP server (Apache, Lighttpd, Nginx or Tomcat for example). That's +really good news, because: + + - Real HTTP servers are much more efficient and reliable than the + default Python server used in Radicale; + - All the authentication backends available for your server will be + available for Radicale; + - Thanks to [flup](http://trac.saddi.com/flup), Radicale can be + interfaced with all the servers supporting CGI, AJP, FastCGI or + SCGI; + - Radicale works very well without any additional server, without any + dependencies, without configuration, just as it was working before; + - This one more feature removes useless code, less is definitely more. + +The WSGI support has only be tested as a stand-alone executable and +behind Lighttpd, you should definitely try if it works with you +favourite server too\! + +No more features will be added before (quite) a long time, because a lot +of documentation and test is waiting for us. If you want to write +tutorials for some CalDAV clients support (iCal, Android, iPhone), HTTP +servers support or logging management, feel free to fork the +[documentation git repository](https://gitorious.org/radicale/website) +and ask for a merge. It's plain text, I'm sure you can do it\! + +### April 30, 2011 - Apple iCal Support + +After a long, long work, the iCal support has finally been added to +Radicale\! Well, this support is only for iCal 4 and is highly +experimental, but you can test it right now with the git master branch. +Bug reports are welcome\! + +Dear MacOS users, you can thank all the gentlemen who sended a lot of +debugging iformation. Special thanks to Andrew from DAViCal, who helped +us a lot with his tips and his tests, and Rémi Hainaud who lent his +laptop for the final tests. + +The default server address is `localhost:5232/user/`, where calendars +can be added. Multiple calendars and owner-less calendars are not tested +yet, but they should work quite well. More documentation will be added +during the next days. It will then be time to release the Radicale 0.6 +version, and work on the WSGI support. + +### April 25, 2011 - Two Features and One New Roadmap + +Two features have just reached the master branch, and the roadmap has +been refreshed. + +#### LDAP Authentication + +Thanks to Corentin, the LDAP authentication is now included in Radicale. +The support is experimental and may suffer unstable connexions and +security problems. If you are interested in this feature (a lot of +people seem to be), you can try it and give some feedback. + +No SSL support is included yet, but this may be quite easy to add. By +the way, serious authentication methods will rely on a "real" HTTP +server, as soon as Radicale supports WSGI. + +#### Journal Entries + +Mehmet asked for the journal entries (aka. notes or memos) support, +that's done\! This also was an occasion to clean some code in the iCal +parser, and to add a much better management of multi-lines entries. +People experiencing crazy `X-RADICALE-NAME` entries can now clean their +files, Radicale won't pollute them again. + +#### New Roadmap + +Except from htpasswd and LDAP, most of the authentication backends +(database, SASL, PAM, user groups) are not really easy to include in +Radicale. The easiest solution to solve this problem is to give Radicale +a CGI support, to put it behind a solid server such as Apache. Of +course, CGI is not enough: a WSGI support is quite better, with the +FastCGI, AJP and SCGI backends offered by +[flup](http://trac.saddi.com/flup/). Quite exciting, isn't it? + +That's why it was important to add new versions on the roadmap. The 0.6 +version is now waiting for the Apple iCal support, and of course for +some tests to kill the last remaining bugs. The only 0.7 feature will be +WSGI, allowing many new authentication methods and a real multithread +support. + +After that, 0.8 may add CalDAV rights and filters, while 1.0 will draw +thousands of rainbows and pink unicorns (WebDAV sync, CardDAV, +Freebusy). A lot of funky work is waiting for you, hackers\! + +#### Bugs + +Many bugs have also been fixed, most of them due to the owner-less +calendars support. Radicale 0.6 may be out in a few weeks, you should +spend some time testing the master branch and filling the bug tracker. + +### April 10, 2011 - New Features + +Radicale 0.5 was released only 8 days ago, but 3 new features have +already been added to the master branch: + + - IPv6 support, with multiple addresses/ports support + - Logs and debug mode + - Owner-less calendars + +Most of the code has been written by Necoro and Corentin, and that was +not easy at all: Radicale is now multithreaded\! For sure, you can find +many bugs and report them on the [bug +tracker](http://redmine.kozea.fr/projects/radicale/issues). And if +you're fond of logging, you can even add a default configuration file +and more debug messages in the source. + +### April 2, 2011 - Radicale 0.5 Released + +Radicale 0.5 is out\! Here is what's new: + +#### 0.5 - Historical Artifacts + + - Calendar depth + - iPhone support + - MacOS and Windows support + - HEAD requests management + - htpasswd user from calendar path + +iPhone support, but no iCal support for 0.5, despite our hard work, +sorry\! After 1 month with no more activity on the dedicated bug, it was +time to forget it and hack on new awesome features. Thanks for your +help, dear Apple users, I keep the hope that one day, Radicale will work +with you\! + +So, what's next? As promised, some cool git branches will soon be +merged, with LDAP support, logging, IPv6 and anonymous calendars. Sounds +pretty cool, heh? Talking about new features, more and more people are +asking for a CardDAV support in Radicale. [A git +branch](https://www.gitorious.org/~deepdiver/radicale/deepdivers-radicale) +and [a feature request](http://redmine.kozea.fr/issues/247) are open, +feel free to hack and discuss. + +### February 3, 2011 - Jabber Room and iPhone Support + +After a lot of help and testing work from Andrew, Björn, Anders, Dorian +and Pete (and other ones we could have forgotten), a simple iPhone +support has been added in the git repository. If you are interested, you +can test this feature *right now* by [downloading the latest git +version](#git-repository) (a tarball is even +available too if you don't want or know how to use git). + +No documentation has been written yet, but using the right URL in the +configuration should be enough to synchronize your calendars. If you +have any problems, you can ask by joining our new Jabber room: +. + +Radicale 0.5 will be released as soon as the iCal support is ready. If +you have an Apple computer, Python skills and some time to spend, we'd +be glad to help you debugging Radicale. + +### October 21, 2010 - News from Radicale + +During the last weeks, Radicale has not been idle, even if no news have +been posted since August. Thanks to Pete, Pierre-Philipp and Andrew, +we're trying to add a better support on MacOS, Windows and mobile +devices like iPhone and Android-based phones. + +All the tests on Windows have been successful: launching Radicale and +using Lightning as client works without any problems. On Android too, +some testers have reported clients working with Radicale. These were the +good news. + +The bad news come from Apple: both iPhone and MacOS default clients are +not working yet, despite the latest enhancements given to the PROPFIND +requests. The problems are quite hard to debug due to our lack of Apple +hardware, but Pete is helping us in this difficult quest\! Radicale 0.5 +will be out as soon as these two clients are working. + +Some cool stuff is coming next, with calendar collections and groups, +and a simple web-based CalDAV client in early development. Stay tuned\! + +### August 8, 2010 - Radicale 0.4 Released + +Radicale 0.4 is out\! Here is what's new: + +#### 0.4 - Hot Days Back + + - Personal calendars + - HEAD requests + - Last-Modified HTTP header + - `no-ssl` and `foreground` options + - Default configuration file + +This release has mainly been released to help our dear packagers to +include a default configuration file and to write init scripts. Big +thanks to Necoro for his work on the new Gentoo ebuild\! + +### July 4, 2010 - Three Features Added Last Week + +Some features have been added in the git repository during the last +weeks, thanks to Jerome and Mariusz\! + + - Personal Calendars + Calendars accessed through the htpasswd ACL module can now be + personal. Thanks to the `personal` option, a user called `bob` can + access calendars at `/bob/*` but not to the `/alice/*` ones. + + - HEAD Requests + Radicale can now answer HEAD requests. HTTP headers can be retrieved + thanks to this request, without getting contents given by the GET + requests. + + - Last-Modified HTTP header + The Last-Modified header gives the last time when the calendar has + been modified. This is used by some clients to cache the calendars + and not retrieving them if they have not been modified. + +### June 14, 2010 - Radicale 0.3 Released + +Radicale 0.3 is out\! Here is what’s new: + +#### 0.3 - Dancing Flowers + + - Evolution support + - Version management + +The website changed a little bit too, with some small HTML5 and CSS3 +features such as articles, sections, transitions, opacity, box shadows +and rounded corners. If you’re reading this website with Internet +Explorer, you should consider using a standard-compliant browser\! + +Radicale is now included in Squeeze, the testing branch of Debian. A +[Radicale ebuild for +Gentoo](http://bugs.gentoo.org/show_bug.cgi?id=322811) has been proposed +too. If you want to package Radicale for another distribution, you’re +welcome\! + +Next step is 0.5, with calendar collections, and Windows and MacOS +support. + +### May 31, 2010 - May News + +#### News from contributors + +Jonas Smedegaard packaged Radicale for Debian last week. Two packages, +called `radicale` for the daemon and `python-radicale` for the module, +have been added to Sid, the unstable branch of Debian. Thank you, +Jonas\! + +Sven Guckes corrected some of the strange-English-sentences present on +this website. Thank you, Sven\! + +#### News from software + +A simple `VERSION` has been added in the library: you can now play with +`radicale.VERSION` and `$radicale --version`. + +After playing with the version (should not be too long), you may notice +that the next version is called 0.3, and not 0.5 as previously decided. +The 0.3 main goal is to offer the support for Evolution as soon as +possible, without waiting for the 0.5. After more than a month of test, +we corrected all the bugs we found and everything seems to be fine; we +can imagine that a brand new tarball will be released during the first +days of June. + +### April 19, 2010 - Evolution Supported + +Radicale now supports another CalDAV client: [Evolution, the default +mail, addressbook and calendaring client for +Gnome](http://projects.gnome.org/evolution/). This feature was quite +easy to add, as it required less than 20 new lines of code in the +requests handler. + +If you are interested, just clone the [git +repository](http://www.gitorious.org/radicale/radicale). + +### April 13, 2010 - Radicale 0.2 Released + +Radicale 0.2 is out\! Here is what’s new: + +#### 0.2 - Snowflakes + + - Sunbird pre-1.0 support + - SSL connection + - Htpasswd authentication + - Daemon mode + - User configuration + - Twisted dependency removed + - Python 3 support + - Real URLs for PUT and DELETE + - Concurrent modification reported to users + - Many bugs fixed by Roger Wenham + +First of all, we would like to thank Roger Wenham for his bugfixes and +his supercool words. + +You may have noticed that Sunbird 1.0 has not been released, but +according to the Mozilla developers, 1.0pre is something like a final +version. + +You may have noticed too that Radicale can be [downloaded from +PyPI](http://pypi.python.org/pypi/Radicale/0.2). Of course, it is also +available on the [download page](#download). + +### January 21, 2010 - HTTPS and Authentication + +HTTPS connections and authentication have been added to Radicale this +week. Command-line options and personal configuration files are also +ready for test. According to the TODO file included in the package, the +next version will finally be 0.2, when sunbird 1.0 is out. Go, Mozilla +hackers, go\! + + - HTTPS connection + HTTPS connections are now available using the standard TLS + mechanisms. Give Radicale a private key and a certificate, and your + data are now safe. + + - Authentication + A simple authentication architecture is now available, allowing + different methods thanks to different modules. The first two modules + are `fake` (no authentication) and `htpasswd` (authentication with + an `htpasswd` file created by the Apache tool). More methods such as + LDAP are coming soon\! + +### January 15, 2010 - Ready for Python 3 + +Dropping Twisted dependency was the first step leading to another big +feature: Radicale now works with Python 3\! The code was given a small +cleanup, with some simplifications mainly about encoding. Before the +0.1.1 release, feel free to test the git repository, all Python versions +from 2.5 should be OK. + +### January 11, 2010 - Twisted no Longer Required + +Good news\! Radicale 0.1.1 will support Sunbird 1.0, but it has another +great feature: it has no external dependency\! Twisted is no longer +required for the git version, removing about 50 lines of code. + +### December 31, 2009 - Lightning and Sunbird 1.0b2pre Support + +Lightning/Sunbird 1.0b2pre is out, adding minor changes in CalDAV +support. A [new +commit](http://www.gitorious.org/radicale/radicale/commit/330283e) makes +Radicale work with versions 0.9, 1.0b1 et 1.0b2. Moreover, etags are now +quoted according to the +[RFC 2616](http://www.faqs.org/rfcs/rfc2616.html "RFC 2616"). + +### December 9, 2009 - Thunderbird 3 released + +[Thunderbird 3 is +out](http://www.mozillamessaging.com/thunderbird/3.0/releasenotes/), and +Lightning/Sunbird 1.0 should be released in a few days. The [last commit +in git](http://gitorious.org/radicale/radicale/commit/6545bc8) should +make Radicale work with versions 0.9 and 1.0b1pre. Radicale 0.1.1 will +soon be released adding support for version 1.0. + +### September 1, 2009 - Radicale 0.1 Released + +First Radicale release\! Here is the changelog: + +#### 0.1 - Crazy Vegetables + + - First release + - Lightning/Sunbird 0.9 compatibility + - Easy installer + +You can download this version on the [download page](#download). + +### July 28, 2009 - Radicale on Gitorious + +Radicale code has been released on Gitorious\! Take a look at the +[Radicale main page on Gitorious](http://www.gitorious.org/radicale) to +view and download source code. + +### July 27, 2009 - Radicale Ready to Launch + +The Radicale Project is launched. The code has been cleaned up and will +be available soon… diff --git a/md/v1/05_footnotes.md b/md/v1/05_footnotes.md new file mode 100644 index 000000000..72d7bf75e --- /dev/null +++ b/md/v1/05_footnotes.md @@ -0,0 +1,54 @@ +## Footnotes + +#### 1 + +See [Python Versions and OS +Support](#python-versions-and-os-support) for further information. + +#### 2 + +[Python download page](http://python.org/download/). + +#### 3 + +I repeat: [we are +lazy](#lazy). + +#### 4 + +Try to read +[RFC 4791](http://www.faqs.org/rfcs/rfc4791.html "RFC 4791"). Then +try to understand it. Then try to implement it. Then try to read it +again. + +#### 5 + +Radicale is [oriented to calendar user +agents](#oriented-to-calendar-and-contact-user-agents). + +#### 6 + +[CalDAV +implementations](http://en.wikipedia.org/wiki/CalDAV#Implementations), +by Wikipedia. + +#### 7 + +[Davical](http://www.davical.org/), a standards-compliant calendar +server. + +#### 8 + +[Cosmo](http://chandlerproject.org/Projects/CosmoHome), the web +contents and calendars sharing server build to support the Chandler +Project. + +#### 9 + +[Darwin Calendar Server](http://trac.calendarserver.org/), a +standards-compliant calendar server mainly developed by Apple. + +#### 10 + +Who says "Ruby is even less verbose\!" should read the +[PEP 20](http://www.python.org/dev/peps/pep-0020/ "PEP 20"). diff --git a/md/v2/00_index.md b/md/v2/00_index.md new file mode 100644 index 000000000..09a6906ee --- /dev/null +++ b/md/v2/00_index.md @@ -0,0 +1,40 @@ +## Getting started + +#### About Radicale + +Radicale is a small but powerful CalDAV (calendars, todo-lists) and CardDAV +(contacts) server, that: + + * Shares calendars through CalDAV, WebDAV and HTTP. + * Shares contacts through CardDAV, WebDAV and HTTP. + * Supports events, todos, journal entries and business cards. + * Works out-of-the-box, no installation nor configuration required. + * Can warn users on concurrent editing. + * Can limit access by authentication. + * Can secure connections. + * Works with many CalDAV and CardDAV clients. + * Is GPLv3-licensed free software. + +#### Installation + +Radicale is really easy to install and works out-of-the-box. + +```bash +$ python3 -m pip install --upgrade radicale==2.1.* +$ python3 -m radicale --config "" --storage-filesystem-folder=~/.var/lib/radicale/collections +``` + +When your server is launched, you can check that everything's OK by going +to http://localhost:5232/ with your browser! +You can login with any username and password. + +Want more? Why don't you check our wonderful +[documentation](#documentation-1)? + +#### What's New? + +Latest version of Radicale is 2.1.12, +released on May 19, 2020 +([changelog](https://github.com/Kozea/Radicale/blob/2.1.12/NEWS.md)). + +[Read latest news…](#news) diff --git a/md/v2/01_documentation.md b/md/v2/01_documentation.md new file mode 100644 index 000000000..d3e95fd3d --- /dev/null +++ b/md/v2/01_documentation.md @@ -0,0 +1,1541 @@ +## Documentation + +This documentation page is written for version 2.x.x. If you want to update +Radicale from 1.x.x to 2.x.x, please follow +our [migration guide](#migration-from-1xx-to-2xx). You can find on GitHub the +[documentation page for the 1.1.x versions](1.1.x.html). + +#### Install and Set Up + +You're new to Radicale and you want to know how to use it? Welcome aboard! + +- [What is Radicale?](#about) +- [A really simple 5-minute tutorial.](#tutorial) +- [A simple but solid setup.](#basic-setup) +- [Run behind a reverse proxy.](#reverse-proxy) +- [Run with a WSGI server.](#wsgi) +- [Track all changes to calendars and address books with Git.](#versioning) + +#### Use + +- [Which clients are supported?](#clients) + +#### Configure + +Now that you have Radicale running, let's see what we can configure to make it +fit your needs. + +- [What can I configure?](#configuration-1) +- [Authentication & Rights.](#authentication-and-rights) +- [Storage.](#storage-2) +- [Logging.](#logging-1) + +#### Hack + +Using is fun, but hacking is soooooooo coooooool. Radicale is a really small +and simple piece of code, it may be the perfect project to start hacking! + +- [How does Radicale work?](#architecture) +- [Plugins.](#plugins) +- [Adding or fixing documentation.](#contribute) + +### Tutorial + +You want to try Radicale but only have 5 minutes free in your calendar? Let's +go right now! You won't have the best installation ever, but it will be enough +to play a little bit with Radicale. + +When everything works, you can get a [client](#clients) 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 +user name and password. If Radicale fits your needs, it may be time for +[some basic configuration](#basic-setup). + +Follow one of the chapters below depending on your operating system. + +#### Linux / \*BSD + +First of all, make sure that **python** 3.3 or later (**python** ≥ 3.6 is +recommended) and **pip** are installed. On most distributions it should be +enough to install the package ``python3-pip``. + +Then open a console and type: + +```bash +# Run the following command as root or +# add the --user argument to only install for the current user +$ python3 -m pip install --upgrade radicale==2.1.* +$ python3 -m radicale --config "" --storage-filesystem-folder=~/.var/lib/radicale/collections +``` + +Victory! Open [http://localhost:5232/](http://localhost:5232/) in your browser! +You can login with any username and password. + +#### Windows + +The first step is to install Python. Go to +[python.org](https://python.org) and download the latest version of Python 3. +Then run the installer. +On the first window of the installer, check the "Add Python to PATH" box and +click on "Install now". Wait a couple of minutes, it's done! + +Launch a command prompt and type: + +```powershell +C:\Users\User> python -m pip install --upgrade radicale==2.1.* +C:\Users\User> python -m radicale --config "" --storage-filesystem-folder=~/radicale/collections +``` + +If you are using PowerShell replace ``--config ""`` with ``--config '""'``. + +Victory! Open [http://localhost:5232/](http://localhost:5232/) in your browser! +You can login with any username and password. + +#### MacOS + +*To be written.* + +### Basic Setup + +Installation instructions can be found on the +[Tutorial](#tutorial) page. + +#### Configuration + +Radicale tries to load configuration files from `/etc/radicale/config`, +`~/.config/radicale/config` and the `RADICALE_CONFIG` environment variable. +A custom path can be specified with the `--config /path/to/config` command +line argument. + +You should create a new configuration file at the desired location. +(If the use of a configuration file is inconvenient, all options can be +passed via command line arguments.) + +All configuration options are described in detail on the +[Configuration](#configuration-1) page. + +#### Authentication + +In its default configuration Radicale doesn't check user names or passwords. +If the server is reachable over a network, you should change this. + +First a `users` file with all user names and passwords must be created. +It can be stored in the same directory as the configuration file. + +##### The secure way + +The `users` file can be created and managed with +[htpasswd](https://httpd.apache.org/docs/current/programs/htpasswd.html): +```bash +# Create a new htpasswd file with the user "user1" +$ htpasswd -B -c /path/to/users user1 +New password: +Re-type new password: +# Add another user +$ htpasswd -B /path/to/users user2 +New password: +Re-type new password: +``` +**bcrypt** is used to secure the passwords. Radicale requires additional +dependencies for this encryption method: +```bash +$ python3 -m pip install --upgrade radicale[bcrypt]==2.1.* +``` + +Authentication can be enabled with the following configuration: +```ini +[auth] +type = htpasswd +htpasswd_filename = /path/to/users +# encryption method used in the htpasswd file +htpasswd_encryption = bcrypt +``` + +##### The simple but insecure way + +Create the `users` file by hand with lines containing the user name and +password separated by `:`. Example: + +```htpasswd +user1:password1 +user2:password2 +``` + +Authentication can be enabled with the following configuration: +```ini +[auth] +type = htpasswd +htpasswd_filename = /path/to/users +# encryption method used in the htpasswd file +htpasswd_encryption = plain +``` + +#### Addresses + +The default configuration binds the server to localhost. It can't be reached +from other computers. This can be changed with the following configuration +options: + +```ini +[server] +hosts = 0.0.0.0:5232 +``` + +More addresses can be added (separated by commas). + +#### Storage + +Data is stored in the folder `/var/lib/radicale/collections`. The path can +be changed with the following configuration: + +```ini +[storage] +filesystem_folder = /path/to/storage +``` + +**Security:** The storage folder should not be readable by unauthorized users. +Otherwise, they can read the calendar data and lock the storage. +You can find OS dependent instructions in the **Running as a service** section. + +#### Limits + +Radicale enforces limits on the maximum number of parallel connections, +the maximum file size (important for contacts with big photos) and the rate of +incorrect authentication attempts. Connections are terminated after a timeout. +The default values should be fine for most scenarios. + +```ini +[server] +max_connections = 20 +# 100 Megabyte +max_content_length = 100000000 +# 30 seconds +timeout = 30 + +[auth] +# Average delay after failed login attempts in seconds +delay = 1 +``` + +#### Running as a service + +The method to run Radicale as a service depends on your host operating system. +Follow one of the chapters below depending on your operating system and +requirements. + +##### Linux with systemd as a user + +Create the file `~/.config/systemd/user/radicale.service`: +```ini +[Unit] +Description=A simple CalDAV (calendar) and CardDAV (contact) server + +[Service] +ExecStart=/usr/bin/env python3 -m radicale +Restart=on-failure + +[Install] +WantedBy=default.target +``` + +Radicale will load the configuration file from `~/.config/radicale/config`. +You should set the configuration option `filesystem_folder` in the `storage` +section to something like `~/.var/lib/radicale/collections`. + +To enable and manage the service run: +```bash +# Enable the service +$ systemctl --user enable radicale +# Start the service +$ systemctl --user start radicale +# Check the status of the service +$ systemctl --user status radicale +# View all log messages +$ journalctl --user --unit radicale.service +``` + +##### Linux with systemd system-wide + +Create the **radicale** user and group for the Radicale service. +(Run `useradd --system --home-dir / --shell /sbin/nologin radicale` as root.) +The storage folder must be writable by **radicale**. (Run +`mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections` +as root.) + +**Security:** The storage should not be readable by others. +(Run `chmod -R o= /var/lib/radicale/collections` as root.) + +Create the file `/etc/systemd/system/radicale.service`: +```ini +[Unit] +Description=A simple CalDAV (calendar) and CardDAV (contact) server +After=network.target +Requires=network.target + +[Service] +ExecStart=/usr/bin/env python3 -m radicale +Restart=on-failure +User=radicale +# Deny other users access to the calendar data +UMask=0027 +# Optional security settings +PrivateTmp=true +ProtectSystem=strict +ProtectHome=true +PrivateDevices=true +ProtectKernelTunables=true +ProtectKernelModules=true +ProtectControlGroups=true +NoNewPrivileges=true +ReadWritePaths=/var/lib/radicale/collections + +[Install] +WantedBy=multi-user.target +``` +Radicale will load the configuration file from `/etc/radicale/config`. + +To enable and manage the service run: +```bash +# Enable the service +$ systemctl enable radicale +# Start the service +$ systemctl start radicale +# Check the status of the service +$ systemctl status radicale +# View all log messages +$ journalctl --unit radicale.service +``` + +#### MacOS with launchd + +*To be written.* + +#### Classic daemonization + +Set the configuration option `daemon` in the section `server` to `True`. +You may want to set the option `pid` to the path of a PID file. + +After daemonization the server will not log anything. You have to configure +[Logging](#logging-1). + +If you start Radicale now, it will initialize and fork into the background. +The main process exits, after the PID file is written. + +**Security:** You can set the **umask** with `umask 0027` before you start the +daemon, to protect your calendar data and log files from other users. +Don't forget to set permissions of files that are already created! + +#### Windows with "NSSM - the Non-Sucking Service Manager" + +First install [NSSM](https://nssm.cc/) and start `nssm install` in a command +prompt. Apply the following configuration: + +* Service name: `Radicale` +* Application + * Path: `C:\Path\To\Python\python.exe` + * Arguments: `-m radicale --config C:\Path\To\Config` +* I/O redirection + * Error: `C:\Path\To\Radicale.log` + +**Security:** Be aware that the service runs in the local system account, +you might want to change this. Managing user accounts is beyond the scope of +this manual. Also make sure that the storage folder and log file is not readable +by unauthorized users. + +The log file might grow very big over time, you can configure file rotation +in **NSSM** to prevent this. + +The service is configured to start automatically when the computer starts. +To start the service manually open **Services** in **Computer Management** and +start the **Radicale** service. + +### Reverse Proxy + +When a reverse proxy is used, the path at which Radicale is available must +be provided via the `X-Script-Name` header. The proxy must remove the location +from the URL path that is forwarded to Radicale. + +Example **nginx** configuration: +```nginx +location /radicale/ { # The trailing / is important! + proxy_pass http://localhost:5232/; # The / is important! + proxy_set_header X-Script-Name /radicale; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_pass_header Authorization; +} +``` + +Example **Apache** configuration: +```apache +RewriteEngine On +RewriteRule ^/radicale$ /radicale/ [R,L] + + + ProxyPass http://localhost:5232/ retry=0 + ProxyPassReverse http://localhost:5232/ + RequestHeader set X-Script-Name /radicale/ + +``` + +Be reminded that Radicale's default configuration enforces limits on the +maximum number of parallel connections, the maximum file size and the rate of +incorrect authentication attempts. Connections are terminated after a timeout. + +#### Manage user accounts with the reverse proxy + +Set the configuration option `type` in the `auth` section to +`http_x_remote_user`. +Radicale uses the user name provided in the `X-Remote-User` HTTP header and +disables HTTP authentication. + +Example **nginx** configuration: + +```nginx +location /radicale/ { + proxy_pass http://localhost:5232/; + proxy_set_header X-Script-Name /radicale; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Remote-User $remote_user; + auth_basic "Radicale - Password Required"; + auth_basic_user_file /etc/nginx/htpasswd; +} +``` + +Example **Apache** configuration: +```apache +RewriteEngine On +RewriteRule ^/radicale$ /radicale/ [R,L] + + + AuthType Basic + AuthName "Radicale - Password Required" + AuthUserFile "/etc/radicale/htpasswd" + Require valid-user + + ProxyPass http://localhost:5232/ retry=0 + ProxyPassReverse http://localhost:5232/ + RequestHeader set X-Script-Name /radicale/ + RequestHeader set X-Remote-User expr=%{REMOTE_USER} + +``` + +**Security:** Untrusted clients should not be able to access the Radicale +server directly. Otherwise, they can authenticate as any user. + +#### Secure connection between Radicale and the reverse proxy + +SSL certificates can be used to encrypt and authenticate the connection between +Radicale and the reverse proxy. First you have to 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. + +```bash +$ 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: + +```ini +[server] +ssl = True +certificate = /path/to/server_cert.pem +key = /path/to/server_key.pem +certificate_authority = /path/to/client_cert.pem +``` + +Example **nginx** configuration: + +```nginx +location /radicale/ { + proxy_pass https://localhost:5232/; + ... + # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...). + proxy_ssl_certificate /path/to/client_cert.pem; + proxy_ssl_certificate_key /path/to/client_key.pem; + proxy_ssl_trusted_certificate /path/to/server_cert.pem; +} +``` + +### WSGI + +Radicale is compatible with the WSGI specification. + +A configuration file can be set with the `RADICALE_CONFIG` environment variable, +otherwise no configuration file is loaded and the default configuration is used. + +Be reminded that Radicale's default configuration enforces limits on the +maximum upload file size. + +**Security:** The `None` authentication type disables all rights checking. +Don't use it with `REMOTE_USER`. Use `remote_user` instead. + +Example **uWSGI** configuration: + +```ini +[uwsgi] +http-socket = 127.0.0.1:5232 +processes = 8 +plugin = python3 +module = radicale +env = RADICALE_CONFIG=/etc/radicale/config +``` + +Example **Gunicorn** configuration: + +```bash +gunicorn --bind '127.0.0.1:5232' --workers 8 --env 'RADICALE_CONFIG=/etc/radicale/config' radicale +``` + +#### Manage user accounts with the WSGI server + +Set the configuration option `type` in the `auth` section to `remote_user`. +Radicale uses the user name provided by the WSGI server and disables +authentication over HTTP. + +### Versioning + +This page describes how to keep track of all changes to calendars and +address books with **git** (or any other version control system). + +The repository must be initialized by running `git init` in the file +system folder. Internal files of Radicale can be excluded by creating the +file `.gitignore` with the following content: +``` +.Radicale.cache +.Radicale.lock +.Radicale.tmp-* +``` + +The configuration option `hook` in the `storage` section must be set to +the following command: +```bash +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. + +### Clients + +Radicale has been tested with: + + * [Android](https://android.com/) with + [DAVx⁵](https://www.davx5.com/) (formerly DAVdroid) + * [GNOME Calendar](https://wiki.gnome.org/Apps/Calendar), + [Contacts](https://wiki.gnome.org/Apps/Contacts) and + [Evolution](https://wiki.gnome.org/Apps/Evolution) + * [Mozilla Thunderbird](https://www.mozilla.org/thunderbird/) with + [CardBook](https://addons.mozilla.org/thunderbird/addon/cardbook/) and + [Lightning](https://www.mozilla.org/projects/calendar/) + * [InfCloud](https://www.inf-it.com/open-source/clients/infcloud/), + [CalDavZAP](https://www.inf-it.com/open-source/clients/caldavzap/) and + [CardDavMATE](https://www.inf-it.com/open-source/clients/carddavmate/) + +Many clients do not support the creation of new calendars and address books. +You can use Radicale's web interface +(e.g. [http://localhost:5232](http://localhost:5232)) to create and manage +collections. + +In some clients you can just enter the URL of the Radicale server +(e.g. `http://localhost:5232`) and your user name. In others, you have to +enter the URL of the collection directly +(e.g. `http://localhost:5232/user/calendar`). + +#### DAVx⁵ + +Enter the URL of the Radicale server (e.g. `http://localhost:5232`) and your +user name. DAVx⁵ will show all existing calendars and address books and you +can create new. + +#### GNOME Calendar, Contacts and Evolution + +**GNOME Calendar** and **Contacts** do not support adding WebDAV calendars +and address books directly, but you can add them in **Evolution**. + +In **Evolution** add a new calendar and address book respectively with WebDAV. +Enter the URL of the Radicale server (e.g. `http://localhost:5232`) and your +user name. Clicking on the search button will list the existing calendars and +address books. + +#### Thunderbird +##### CardBook + +Add a new address book on the network with CardDAV. You have to enter the full +URL of the collection (e.g. `http://localhost:5232/user/addressbook`) and +your user name. + +##### Lightning + +Add a new calendar on the network with `CalDAV`. (Don't use `iCalendar (ICS)`!) +You have to enter the full URL of the collection (e.g. +`http://localhost:5232/user/calendar`). If you want to add calendars from +different users on the same server, you can specify the user name in the URL +(e.g. `http://user@localhost...`) + +#### InfCloud, CalDavZAP and CardDavMATE + +You can integrate InfCloud into Radicale's web interface with +[RadicaleInfCloud](https://github.com/Unrud/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](https://en.wikipedia.org/wiki/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. + +#### Manual creation of calendars and address books + +This is not the recommended way of creating and managing your calendars and +address books. Use Radicale's web interface or a client with support for it +(e.g. **DAVx⁵**). + +##### Direct editing of the storage + +To create a new collection, you have to create the corresponding folder in the +file system storage (e.g. `collection-root/user/calendar`). +To tell Radicale and clients that the collection is a calendar, you have to +create the file ``.Radicale.props`` with the following content in the folder: + +```json +{"tag": "VCALENDAR"} +``` + +The calendar is now available at the URL path ``/user/calendar``. +For address books the file must contain: + +```json +{"tag": "VADDRESSBOOK"} +``` + +Calendar and address book collections must not have any child collections. +Clients with automatic discovery of collections will only show calendars and +addressbooks that are direct children of the path `/USERNAME/`. + +Delete collections by deleting the corresponding folders. + +##### HTTP requests with curl + +To create a new calendar run something like: + +```bash +$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \ +' + + + + + + + + + + + + + Calendar + Example calendar + #ff0000ff + + +' +``` + +To create a new address book run something like: + +```bash +$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \ +' + + + + + + + + Address book + Example address book + + +' +``` + +The collection `/USERNAME` will be created automatically, when the user +authenticates to Radicale for the first time. Clients with automatic discovery +of collections will only show calendars and address books that are direct +children of the path `/USERNAME/`. + +Delete the collections by running something like: + +```bash +$ curl -u user -X DELETE 'http://localhost:5232/user/calendar' +``` + +### Configuration + +Radicale can be configured with a configuration file or with +command line arguments. + +An example configuration file looks like: +```ini +[server] +# Bind all addresses +hosts = 0.0.0.0:5232 + +[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: +```bash +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:5232` + +##### daemon + +Daemonize the Radicale process. It does not reset the umask. + +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: `100000000` + +##### 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 user name from the certifcate. + +Default: + +##### 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. It also disables rights checking. + +`htpasswd` +: Use an [Apache htpasswd file](https://httpd.apache.org/docs/current/programs/htpasswd.html) to store + usernames and passwords. + +`remote_user` +: Takes the user name from the `REMOTE_USER` environment variable and disables + HTTP authentication. This can be used to provide the user name from a WSGI + server. + +`http_x_remote_user` +: Takes the user name from the `X-Remote-User` HTTP header and disables HTTP + authentication. This can be used to provide the user name from a reverse + proxy. + +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)](https://manpages.debian.org/unstable/manpages-dev/crypt.3.en.html). + It's insecure! + +Default: `bcrypt` + +##### delay + +Average delay after failed login attempts in seconds. + +Default: `1` + +#### rights +##### type + +The backend that is used to check the access rights of collections. + +The recommended backend is `owner_only`. If access to calendars +and address books outside of the home directory of users (that's `/USERNAME/`) +is granted, clients won't detect these collections and will not show them to +the user. Choosing any other method is only useful if you access calendars and +address books directly via URL. + +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](#authentication-and-rights) page. + +#### storage +##### type + +The backend that is used to store data. + +Available backends: + +`multifilesystem` +: Stores the data in the filesystem. + +Default: `multifilesystem` + +##### filesystem_folder + +Folder for storing local collections, created if not present. + +Default: `/var/lib/radicale/collections` + +##### filesystem_locking + +Lock the storage. This must be disabled if locking is not supported by the +underlying file system. Never start multiple instances of Radicale or edit the +storage externally while Radicale is running if disabled. + +Default: `True` + +##### max_sync_token_age + +Delete sync-token that are older than the specified time. (seconds) + +Default: `2592000` + +##### 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](#versioning) page for an example. + +Default: + +#### web +##### type + +The backend that provides the web interface of Radicale. + +Available backends: + +`none` +: Just shows the message "Radicale works!". + +`internal` +: Allows creation and management of address books and calendars. + +Default: `internal` + +#### 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](#logging-1) 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 = * +``` + +### Authentication and Rights + +This page describes the format of the rights file for the `from_file` +authentication backend. The configuration option `file` in the `rights` +section must point to the rights file. + +The recommended rights method is `owner_only`. If access to calendars +and address books outside of the home directory of users (that's `/USERNAME/`) +is granted, clients won't detect these 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: +```ini +# The user "admin" can read and write any collection. +[admin] +user = admin +collection = .* +permission = rw + +# Block access for the user "user" to everything. +[block] +user = user +collection = .* +permission = + +# Authenticated users can read and write their own collections. +[owner-write] +user = .+ +collection = %(login)s(/.*)? +permission = rw + +# Everyone can read the root collection +[read] +user = .* +collection = +permission = r +``` + +The titles of the sections are ignored (but must be unique). The keys `user` +and `collection` contain regular expressions, that are matched against the +user name and the path of the collection. Permissions from the first +matching section are used. If no section matches, access gets denied. + +The user name is empty for anonymous users. Therefore, the regex `.+` only +matches authenticated users and `.*` matches everyone (including anonymous +users). + +The path of the collection is separated by `/` and has no leading or trailing +`/`. Therefore, the path of the root collection is empty. + +`%(login)s` gets replaced by the user name and `%(path)s` by the path of +the collection. You can also get groups from the `user` regex in the +`collection` regex with `{0}`, `{1}`, etc. + +### Storage + +This document describes the layout and format of the file system storage +(`multifilesystem` backend). + +It's safe to access and manipulate the data by hand or with scripts. +Scripts can be invoked manually, periodically (e.g. with +[cron](https://manpages.debian.org/unstable/cron/cron.8.en.html)) or after each +change to the storage with the configuration option `hook` in the `storage` +section (e.g. [Git Versioning](#versioning)). + +#### Layout + +The file system contains the following files and folders: + + * `.Radicale.lock`: The lock file for locking the storage. + * `collection-root`: This folder contains all collections and items. + +A collection is represented by a folder. This folder may contain the file +`.Radicale.props` with all WebDAV properties of the collection encoded +as [JSON](https://en.wikipedia.org/wiki/JSON). + +An item is represented by a file containing the iCalendar data. + +All files and folders, whose names start with a dot but not `.Radicale.` +(internal files) are ignored. + +If you introduce syntax errors in any of the files, all requests that access +the faulty data will fail. The logging output should contain the names of the +culprits. + +Future releases of Radicale 2.x.x will store caches and sync-tokens in the +`.Radicale.cache` folder inside of collections. +This folder may be created or modified, while the storage is locked for shared +access. +In theory, it should be safe to delete the folder. Caches will be recreated +automatically and clients will be told that their sync-token isn't valid +anymore. + +You may encounter files or folders that start with `.Radicale.tmp-`. +Radicale uses them for atomic creation and deletion of files and folders. +They should be deleted after requests are finished but it's possible that +they are left behind when Radicale or the computer crashes. +It's safe to delete them. + +#### Locking + +When the data is accessed by hand or by an externally invoked script, +the storage must be locked. The storage can be locked for exclusive or +shared access. It prevents Radicale from reading or writing the file system. +The storage is locked with exclusive access while the `hook` runs. + +##### Linux shell scripts + +Use the +[flock](https://manpages.debian.org/unstable/util-linux/flock.1.en.html) +utility. + +```bash +# Exclusive +$ flock --exclusive /path/to/storage/.Radicale.lock COMMAND +# Shared +$ flock --shared /path/to/storage/.Radicale.lock COMMAND +``` + +##### Linux and MacOS + +Use the +[flock](https://manpages.debian.org/unstable/manpages-dev/flock.2.en.html) +syscall. Python provides it in the +[fcntl](https://docs.python.org/3/library/fcntl.html#fcntl.flock) module. + +##### Windows + +Use +[LockFile](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365202%28v=vs.85%29.aspx) +for exclusive access or +[LockFileEx](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365203%28v=vs.85%29.aspx) +which also supports shared access. Setting `nNumberOfBytesToLockLow` to `1` +and `nNumberOfBytesToLockHigh` to `0` works. + +### Logging + +Radicale logs to `stderr`. The verbosity of the log output can be controlled +with `--debug` command line argument or the `debug` configuration option in +the `logging` section. + +This is the recommended configuration for use with modern init systems +(like **systemd**) or if you just test Radicale in a terminal. + +You can configure Radicale to write its logging output to files (and even +rotate them). +This is useful if the process daemonizes or if your chosen method of running +Radicale doesn't handle logging output. + +A logging configuration file can be specified in the `config` configuration +option in the `logging` section. The file format is explained in the +[Python Logging Module](https://docs.python.org/3/library/logging.config.html#configuration-file-format). + +#### Logging to a file + +An example configuration to write the log output to the file `/var/log/radicale/log`: +```ini +[loggers] +keys = root + +[handlers] +keys = file + +[formatters] +keys = full + +[logger_root] +# Change this to DEBUG or INFO for higher verbosity. +level = WARNING +handlers = file + +[handler_file] +class = FileHandler +# Specify the output file here. +args = ('/var/log/radicale/log',) +formatter = full + +[formatter_full] +format = %(asctime)s - [%(thread)x] %(levelname)s: %(message)s +``` + +You can specify multiple **logger**, **handler** and **formatter** if you want +to have multiple simultaneous log outputs. + +The parent folder of the log files must exist and must be writable by Radicale. + +**Security:** The log files should not be readable by unauthorized users. Set +permissions accordingly. + +##### Timed rotation of disk log files + +An example **handler** configuration to write the log output to the file `/var/log/radicale/log` and rotate it. +Replace the section `handler_file` from the file logging example: +```ini +[handler_file] +class = handlers.TimedRotatingFileHandler +# Specify the output file and parameter for rotation here. +# See https://docs.python.org/3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler +# Example: rollover at midnight and keep 7 files (means one week) +args = ('/var/log/radicale/log', 'midnight', 1, 7) +formatter = full +``` + +##### Rotation of disk log files based on size + +An example **handler** configuration to write the log output to the file `/var/log/radicale/log` and rotate it . +Replace the section `handle_file` from the file logging example: +```ini +[handler_file] +class = handlers.RotatingFileHandler +# Specify the output file and parameter for rotation here. +# See https://docs.python.org/3/library/logging.handlers.html#logging.handlers.RotatingFileHandler +# Example: rollover at 100000 kB and keep 10 files (means 1 MB) +args = ('/var/log/radicale/log', 'a', 100000, 10) +formatter = full +``` + +### Architecture + +Radicale is a really small piece of software, but understanding it is not as +easy as it seems. But don't worry, reading this short page is enough to +understand what a CalDAV/CardDAV server is, and how Radicale's code is +organized. + +#### General Architecture + +Here is a simple overview of the global architecture for reaching a calendar or +an address book through network: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PartLayerProtocol or Format
ServerCalendar/Contact StorageiCal/vCard
Calendar/Contact ServerCalDAV/CardDAV Server
TransferNetworkCalDAV/CardDAV (HTTP + TLS)
ClientCalendar/Contact ClientCalDAV/CardDAV Client
GUITerminal, GTK, Web interface, etc.
+ +Radicale is **only the server part** of this architecture. + +Please note that: + +- CalDAV and CardDAV are superset protocols of WebDAV, +- WebDAV is a superset protocol of HTTP. + +Radicale being a CalDAV/CardDAV server, it also can be seen as a special WebDAV +and HTTP server. + +Radicale is **not the client part** of this architecture. It means that +Radicale never draws calendars, address books, events and contacts on the +screen. It only stores them and give the possibility to share them online with +other people. + +If you want to see or edit your events and your contacts, you have to use +another software called a client, that can be a "normal" applications with +icons and buttons, a terminal or another web application. + +#### Code Architecture + +The ``radicale`` package offers 9 modules. + +`__main__` +: The main module provides a simple function called run. Its main work is to + read the configuration from the configuration file and from the options given + in the command line; then it creates a server, according to the configuration. + +`__init__` +: This is the core part of the module, with the code for the CalDAV/CardDAV + server. The server inherits from a WSGIServer server class, which relies on + the default HTTP server class given by Python. The code managing the + different HTTP requests according to the CalDAV/CardDAV normalization is + written here. + +`config` +: This part gives a dict-like access to the server configuration, read from the + configuration file. The configuration can be altered when launching the + executable with some command line options. + +`xmlutils` +: The functions defined in this module are mainly called by the CalDAV/CardDAV + server class to read the XML part of the request, read or alter the + calendars, and create the XML part of the response. The main part of this + code relies on ElementTree. + +`log` +: The start function provided by this module starts a logging mechanism based + on the default Python logging module. Logging options can be stored in a + logging configuration file. + +`auth` +: This module provides a default authentication manager equivalent to Apache's + htpasswd. Login + password couples are stored in a file and used to + authenticate users. Passwords can be encrypted using various methods. Other + authentication methods can inherit from the base class in this file and be + provided as plugins. + +`rights` +: This module is a set of Access Control Lists, a set of methods used by + Radicale to manage rights to access the calendars. When the CalDAV/CardDAV + server is launched, an Access Control List is chosen in the set, according to + the configuration. The HTTP requests are then filtered to restrict the access + depending on who is authenticated. Other configurations can be written using + regex-based rules. Other rights managers can also inherit from the base class + in this file and be provided as plugins. + +`storage` +: In this module are written the classes representing collections and items in + Radicale, and the class storing these collections and items in your + filesystem. Other storage classes can inherit from the base class in this + file and be provided as plugins. + +`web` +: This module contains the web interface. + +### Plugins + +Radicale can be extended by plugins for authentication, rights management and +storage. Plugins are **python** modules. + +#### Getting started + +To get started we walk through the creation of a simple authentication +plugin, that accepts login attempts if the username and password are equal. + +The easiest way to develop and install **python** modules is +[Distutils](https://docs.python.org/3/distutils/setupscript.html). +For a minimal setup create the file `setup.py` with the following content +in an empty folder: + +```python +#!/usr/bin/env python3 + +from distutils.core import setup + +setup(name="radicale_silly_auth", packages=["radicale_silly_auth"]) +``` + +In the same folder create the sub-folder `radicale_silly_auth`. The folder +must have the same name as specified in `packages` above. + +Create the file `__init__.py` in the `radicale_silly_auth` folder with the +following content: + +```python +from radicale.auth import BaseAuth + + +class Auth(BaseAuth): + def is_authenticated(self, user, password): + # Example custom configuration option + foo = "" + if self.configuration.has_option("auth", "foo"): + foo = self.configuration.get("auth", "foo") + self.logger.info("Configuration option %r is %r", "foo", foo) + + # Check authentication + self.logger.info("Login attempt by %r with password %r", + user, password) + return user == password +``` + +Install the python module by running the following command in the same folder +as `setup.py`: +```bash +python3 -m pip install --upgrade . +``` + +To make use this great creation in Radicale, set the configuration option +`type` in the `auth` section to `radicale_silly_auth`: + +```ini +[auth] +type = radicale_silly_auth +foo = bar +``` + +You can uninstall the module with: +```bash +python3 -m pip uninstall radicale_silly_auth +``` + +#### Authentication plugins + +This plugin type is used to check login credentials. +The module must contain a class `Auth` that extends +`radicale.auth.BaseAuth`. Take a look at the file `radicale/auth.py` in +Radicale's source code for more information. + +#### Rights management plugins + +This plugin type is used to check if a user has access to a path. +The module must contain a class `Rights` that extends +`radicale.rights.BaseRights`. Take a look at the file `radicale/rights.py` in +Radicale's source code for more information. + +#### Web plugins + +This plugin type is used to provide the web interface for Radicale. +The module must contain a class `Web` that extends +`radicale.web.BaseWeb`. Take a look at the file `radicale/web.py` in +Radicale's source code for more information. + +#### Storage plugins + +This plugin is used to store collections and items. +The module must contain a class `Collection` that extends +`radicale.storage.BaseCollection`. Take a look at the file `radicale/storage.py` +in Radicale's source code for more information. + +### Migration from 1.x.x to 2.x.x +#### Why a Migration? + +Radicale 2.x.x is different from 1.x.x, here's everything you need to know about +this! **Please read this page carefully if you want to update Radicale.** + +You'll also find extra information +in [issue #372](https://github.com/Kozea/Radicale/issues/372). + +#### Python 3 Only + +Radicale 2.x.x works with Python >= 3.3, and **doesn't work anymore with +Python 2**. + +(No, Python 3.3 is not new, it's been released more than 4 years ago. +Debian stable provides Python 3.4.) + +#### Dependencies + +Radicale now depends on [VObject](https://eventable.github.io/vobject/), a +"full-featured Python package for parsing and creating iCalendar and vCard +files". That's the price to pay to correctly read crazy iCalendar files and +**support date-based filters, even on recurring events**. + +#### Storage + +Calendars and address books are stored in a different way between 1.x.x and 2.x.x +versions. **Launching 2.x.x without migrating your collections first will not +work, Radicale won't be able to read your previous data.** + +There's now only one way to store data in Radicale: collections are stored as +folders and events / contacts are stored in files. This new storage is close to +the `multifilesystem`, but **it's now thread-safe, with atomic writes and file +locks**. Other storage types can be used by creating +[plugins](#plugins). + +To migrate data to Radicale 2.x.x the command line argument +``--export-storage`` was added to Radicale 1.1.x. +Start Radicale 1.x.x as you would normally do, but add the argument +``--export-storage path/to/empty/folder``. Radicale will export the storage +into the specified folder. This folder can be directly used with the +default storage backend of Radicale 2.x.x. + +If you import big calendars or address books into Radicale 2.x.x the first +request might take a long time, because it has to initialize its internal +caches. Clients can time out, subsequent requests will be much faster. + +You can check the imported storage for errors by starting Radicale >= 2.1.5 +with the ``--verify-storage`` argument. + +You can install version 1.1.x with: + +```bash +$ python3 -m pip install --upgrade radicale==1.1.* +``` + +#### Authentication + +**Radicale 2.x.x only provides htpasswd authentication out-of-the-box.** Other +authentication methods can be added by creating or using +[plugins](#plugins). + +#### Rights + +In Radicale 2.x.x, rights are managed using regex-based rules based on the +login of the authenticated user and the URL of the resource. Default +configurations are built in for common cases, you'll find more about this on +the [Authentication & Rights](#authentication-and-rights) page. + +Other rights managers can be added by creating +[plugins](#plugins). + +#### Versioning + +Support for versioning with **git** was removed from Radicale 2.x.x. +Instead, the configuration option ``hook`` in the ``storage`` section was added, +the [Collection Versioning](#versioning) page explains its +usage for version control. diff --git a/md/v2/02_contribute.md b/md/v2/02_contribute.md new file mode 100644 index 000000000..22419a20c --- /dev/null +++ b/md/v2/02_contribute.md @@ -0,0 +1,21 @@ +## Contribute + +#### Chat with Us on IRC + +Want to say something? Join our IRC room: `##kozea` on Freenode. + +#### Report Bugs + +Found a bug? Want a new feature? Report a new issue on the +[Radicale bug-tracker](https://github.com/Kozea/Radicale/issues). + +#### Hack + +Interested in hacking? Feel free to clone the +[git repository on Github](https://github.com/Kozea/Radicale) if you want to +add new features, fix bugs or update the documentation. + +#### Documentation + +To change or complement the documentation create a pull request to +[DOCUMENTATION.md](https://github.com/Kozea/Radicale/blob/master/DOCUMENTATION.md). diff --git a/md/v2/03_download.md b/md/v2/03_download.md new file mode 100644 index 000000000..c54a09579 --- /dev/null +++ b/md/v2/03_download.md @@ -0,0 +1,81 @@ +## Download + +#### PyPI + +Radicale is [available on PyPI](https://pypi.python.org/pypi/Radicale/). To +install, just type as superuser: + + $ python3 -m pip install --upgrade radicale==2.1.* + +#### Git Repository + +If you want the development version of Radicale, take a look at the +[git repository on GitHub](https://github.com/Kozea/Radicale/), or install it +directly with: + + $ python3 -m pip install --upgrade git+https://github.com/Kozea/Radicale + +You can also download the content of the repository as an +[archive](https://github.com/Kozea/Radicale/tarball/master). + +#### Source Packages + +You can download the Radicale package for each release: + +- [**2.1.12 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.12) +- [**2.1.11 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.11) +- [**2.1.10 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.10) +- [**2.1.9 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.9) +- [**2.1.8 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.8) +- [**2.1.7 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.7) +- [**2.1.6 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.6) +- [**2.1.5 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.5) +- [**2.1.4 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.4) +- [**2.1.3 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.3) +- [**2.1.2 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.2) +- [**1.1.6 - Sixth Law of Nature**](https://api.github.com/repos/Kozea/Radicale/tarball/1.1.6) +- [**2.1.1 - Wild Radish Again**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.1) +- [**2.1.0 - Wild Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.0) +- [**1.1.4 - Fifth Law of Nature**](https://api.github.com/repos/Kozea/Radicale/tarball/1.1.4) +- [2.1.0rc3](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.0rc3) +- [2.1.0rc2](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.0rc2) +- [2.1.0rc1](https://api.github.com/repos/Kozea/Radicale/tarball/2.1.0rc1) +- [**2.0.0 - Little Big Radish**](https://api.github.com/repos/Kozea/Radicale/tarball/2.0.0) +- [**1.1.3 - Fourth Law of Nature**](https://api.github.com/repos/Kozea/Radicale/tarball/1.1.3) +- [2.0.0rc2](https://api.github.com/repos/Kozea/Radicale/tarball/2.0.0rc2) +- [**1.1.2 - Third Law of Nature**](https://api.github.com/repos/Kozea/Radicale/tarball/1.1.2) +- [2.0.0rc1](https://api.github.com/repos/Kozea/Radicale/tarball/2.0.0rc1) +- [**1.1.1 - Second Law of Nature**](https://api.github.com/repos/Kozea/Radicale/tarball/1.1.1) +- [**1.1 - Law of Nature**](https://api.github.com/repos/Kozea/Radicale/tarball/1.1) +- [**1.0.1 - Sunflower Again**](https://api.github.com/repos/Kozea/Radicale/tarball/1.0.1) +- [**1.0 - Sunflower**](https://api.github.com/repos/Kozea/Radicale/tarball/1.0) + +#### Linux Distribution Packages + +Radicale has been packaged for: + +- [ArchLinux](https://www.archlinux.org/packages/community/any/radicale/) by + David Runge +- [Debian](http://packages.debian.org/radicale) by Jonas Smedegaard +- [Gentoo](https://packages.gentoo.org/packages/www-apps/radicale) + by René Neumann, Maxim Koltsov and Manuel Rüger +- [Fedora](https://admin.fedoraproject.org/pkgdb/package/radicale/) by Jorti +- [Mageia](http://madb.mageia.org/package/show/application/0/name/radicale) by + Jani Välimaa +- [OpenBSD](http://openports.se/productivity/radicale) by Sergey Bronnikov, + Stuart Henderson and Ian Darwin +- [openSUSE](http://software.opensuse.org/package/Radicale?search_term=radicale) + by Ákos Szőts and Rueckert +- [PyPM](http://code.activestate.com/pypm/radicale/) +- [Slackware](http://schoepfer.info/slackware.xhtml#packages-network) by + Johannes Schöpfer +- [Trisquel](http://packages.trisquel.info/search?searchon=names&keywords=radicale) +- [Ubuntu](http://packages.ubuntu.com/radicale) by the MOTU and Jonas + Smedegaard + +Radicale is also +[available on Cloudron](https://cloudron.io/button.html?app=org.radicale.cloudronapp) +and has a Dockerfile. + +If you are interested in creating packages for other Linux distributions, read +the ["Contribute" page](#contribute). diff --git a/md/v2/04_about.md b/md/v2/04_about.md new file mode 100644 index 000000000..a6a7b91dc --- /dev/null +++ b/md/v2/04_about.md @@ -0,0 +1,97 @@ +## About + +#### Main Goals + +Radicale is a complete calendar and contact storing and manipulating +solution. It can store multiple calendars and multiple address books. + +Calendar and contact manipulation is available from both local and distant +accesses, possibly limited through authentication policies. + +It aims to be a lightweight solution, easy to use, easy to install, easy to +configure. As a consequence, it requires few software dependencies and is +pre-configured to work out-of-the-box. + +Radicale is written in Python. It runs on most of the UNIX-like platforms +(Linux, \*BSD, macOS) and Windows. It is free and open-source software. + +#### What Radicale Will Never Be + +Radicale is a server, not a client. No interfaces will be created to work with +the server, as it is a really (really really) much more difficult task. + +CalDAV and CardDAV are not perfect protocols. We think that their main problem +is their complexity, that is why we decided not to implement the whole standard +but just enough to understand some of its client-side implementations. + +CalDAV and CardDAV are the best open standards available and they are quite +widely used by both clients and servers. We decided to use it, and we will not +use another one. + +#### Technical Choices + +Important global development choices have been decided before writing +code. They are very useful to understand why the Radicale Project is different +from other CalDAV and CardDAV servers, and why features are included or not in +the code. + +##### Oriented to Calendar and Contact User Agents + +Calendar and contact servers work with calendar and contact clients, using a +defined protocol. CalDAV and CardDAV are good protocols, covering lots of +features and use cases, but it is quite hard to implement fully. + +Some calendar servers have been created to follow the CalDAV and CardDAV RFCs +as much as possible: [Davical](http://www.davical.org/), +[Baïkal](http://sabre.io/baikal/) and +[Darwin Calendar Server](http://trac.calendarserver.org/), for example, are +much more respectful of CalDAV and CardDAV and can be used with a large number +of clients. They are very good choices if you want to develop and test new +CalDAV clients, or if you have a possibly heterogeneous list of user agents. + +Even if it tries it best to follow the RFCs, Radicale does not and **will not** +blindly implements the CalDAV and CardDAV standards. It is mainly designed to +support the CalDAV and CardDAV implementations of different clients. + +##### Simple + +Radicale is designed to be simple to install, simple to configure, simple to +use. + +The installation is very easy, particularly with Linux: one dependency, no +superuser rights needed, no configuration required, no database. Installing and +launching the main script out-of-the-box, as a normal user, are often the only +steps to have a simple remote calendar and contact access. + +Contrary to other servers that are often complicated, require high privileges +or need a strong configuration, the Radicale Server can (sometimes, if not +often) be launched in a couple of minutes, if you follow the +[tutorial](#tutorial). + +##### Lazy + +The CalDAV RFC defines what must be done, what can be done and what cannot be +done. Many violations of the protocol are totally defined and behaviours are +given in such cases. + +Radicale often assumes that the clients are perfect and that protocol +violations do not exist. That is why most of the errors in client requests have +undetermined consequences for the lazy server that can reply good answers, bad +answers, or even no answer. + +#### History + +Radicale has been started as a (free topic) stupid school project replacing +another (assigned topic) even more stupid school project. + +At the beginning, it was just a proof-of-concept. The main goal was to write a +small, dirty and simple CalDAV server working with Lightning, using no external +libraries. That's how we created a piece of code that's (quite) easy to +understand, to use and to hack. + +The [first lines](https://github.com/Kozea/Radicale/commit/b1591aea) have been +added to the SVN (!) repository as I was drinking (many) beers at the very end +of 2008 (Python 2.6 and 3.0 were just released). It's now packaged for a +growing number of Linux distributions. + +And that was fun going from here to there thanks to you! diff --git a/md/v2/05_news.md b/md/v2/05_news.md new file mode 100644 index 000000000..86b7df34c --- /dev/null +++ b/md/v2/05_news.md @@ -0,0 +1,1078 @@ +## News + +Latest version of Radicale is 2.1.12, +released on May 19, 2020 +([changelog](https://github.com/Kozea/Radicale/blob/2.1.12/NEWS.md)). + +### May 19, 2020 - Radicale 2.1.12 + +Radicale 2.1.12 is out! + +#### 2.1.12 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Include documentation in source archive + +### November 5, 2018 - Radicale 2.1.11 + +Radicale 2.1.11 is out! + +#### 2.1.11 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Fix moving items between collections + +### August 16, 2018 - Radicale 2.1.10 + +Radicale 2.1.10 is out! + +#### 2.1.10 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Update required versions for dependencies +* Get ``RADICALE_CONFIG`` from WSGI environ +* Improve HTTP status codes +* Fix race condition in storage lock creation +* Raise default limits for content length and timeout +* Log output from hook + +### April 21, 2018 - Radicale 2.1.9 + +Radicale 2.1.9 is out! + +#### 2.1.9 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Specify versions for dependencies +* Move WSGI initialization into module +* Check if ``REPORT`` method is actually supported +* Include ``rights`` file in source distribution +* Specify ``md5`` and ``bcrypt`` as extras +* Improve logging messages +* Windows: Fix crash when item path is a directory + +### September 24, 2017 - Radicale 2.1.8 + +Radicale 2.1.8 is out! + +#### 2.1.8 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Flush files before fsync'ing + +### September 17, 2017 - Radicale 2.1.7 + +Radicale 2.1.7 is out! + +#### 2.1.7 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Don't print warning when cache format changes +* Add documentation for ``BaseAuth`` +* Add ``is_authenticated2(login, user, password)`` to ``BaseAuth`` +* Fix names of custom properties in PROPFIND requests with + ``D:propname`` or ``D:allprop`` +* Return all properties in PROPFIND requests with ``D:propname`` or + ``D:allprop`` +* Allow ``D:displayname`` property on all collections +* Answer with ``D:unauthenticated`` for ``D:current-user-principal`` property + when not logged in +* Remove non-existing ``ICAL:calendar-color`` and ``C:calendar-timezone`` + properties from PROPFIND requests with ``D:propname`` or ``D:allprop`` +* Add ``D:owner`` property to calendar and address book objects +* Remove ``D:getetag`` and ``D:getlastmodified`` properties from regular + collections + +### September 11, 2017 - Radicale 2.1.6 + +Radicale 2.1.6 is out! + +#### 2.1.6 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Fix content-type of VLIST +* Specify correct COMPONENT in content-type of VCALENDAR +* Cache COMPONENT of calendar objects (improves speed with some clients) +* Stricter parsing of filters +* Improve support for CardDAV filter +* Fix some smaller bugs in CalDAV filter +* Add X-WR-CALNAME and X-WR-CALDESC to calendars downloaded via HTTP/WebDAV +* Use X-WR-CALNAME and X-WR-CALDESC from calendars published via WebDAV + +### August 25, 2017 - Radicale 2.1.5 + +Radicale 2.1.5 is out! + +#### 2.1.5 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Add ``--verify-storage`` command-line argument +* Allow comments in the htpasswd file +* Don't strip whitespaces from user names and passwords in the htpasswd file +* Remove cookies from logging output +* Allow uploads of whole collections with many components +* Show warning message if server.timeout is used with Python < 3.5.2 + +### August 4, 2017 - Radicale 2.1.4 + +Radicale 2.1.4 is out! + +#### 2.1.4 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Fix incorrect time range matching and calculation for some edge-cases with + rescheduled recurrences +* Fix owner property + +### August 2, 2017 - Radicale 2.1.3 + +Radicale 2.1.3 is out! + +#### 2.1.3 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Enable timeout for SSL handshakes and move them out of the main thread +* Create cache entries during upload of items +* Stop built-in server on Windows when Ctrl+C is pressed +* Prevent slow down when multiple requests hit a collection during cache warm-up + +### July 24, 2017 - Radicale 2.1.2 + +Radicale 2.1.2 is out! + +#### 2.1.2 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Remove workarounds for bugs in VObject < 0.9.5 +* Error checking of collection tags and associated components +* Improve error checking of uploaded collections and components +* Don't delete empty collection properties implicitly +* Improve logging of VObject serialization + +### July 1, 2017 - Radicale 2.1.1 + +Radicale 2.1.1 is out! + +#### 2.1.1 - Wild Radish Again + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.x.x. + +* Add missing UIDs instead of failing +* Improve error checking of calendar and address book objects +* Fix upload of whole address books + +### June 25, 2017 - Radicale 2.1.0 + +Radicale 2.1.0 is out! + +#### 2.1.0 - Wild Radish + +This release is compatible with version 2.0.0. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.1.0. + +* Built-in web interface for creating and managing address books and calendars + * can be extended with web plugins +* Much faster storage backend +* Significant reduction in memory usage +* Improved logging + * Include paths (of invalid items / requests) in log messages + * Include configuration values causing problems in log messages + * Log warning message for invalid requests by clients + * Log error message for invalid files in the storage backend + * No stack traces unless debugging is enabled +* Time range filter also regards overwritten recurrences +* Items that couldn't be filtered because of bugs in VObject are always + returned (and a warning message is logged) +* Basic error checking of configuration files +* File system locking isn't disabled implicitly anymore, instead a new + configuration option gets introduced +* The permissions of the lock file are not changed anymore +* Support for sync-token +* Support for client-side SSL certificates +* Rights plugins can decide if access to an item is granted explicitly + * Respond with 403 instead of 404 for principal collections of non-existing + users when ``owner_only`` plugin is used (information leakage) +* Authentication plugins can provide the login and password from the + environment + * new ``remote_user`` plugin, that gets the login from the ``REMOTE_USER`` + environment variable (for WSGI server) + * new ``http_x_remote_user`` plugin, that gets the login from the + ``X-Remote-User`` HTTP header (for reverse proxies) + +### May 27, 2017 - Radicale 2.0.0 + +Radicale 2.0.0 is out! + +#### 2.0.0 - Little Big Radish + +This feature is not compatible with the 1.x.x versions. Follow our +[migration guide](#migration-from-1xx-to-2xx) if you want to switch +from 1.x.x to 2.0.0. + +- Support Python 3.3+ only, Python 2 is not supported anymore +- Keep only one simple filesystem-based storage system +- Remove built-in Git support +- Remove built-in authentication modules +- Keep the WSGI interface, use Python HTTP server by default +- Use a real iCal parser, rely on the "vobject" external module +- Add a solid calendar discovery +- Respect the difference between "files" and "folders", don't rely on slashes +- Remove the calendar creation with GET requests +- Be stateless +- Use a file locker +- Add threading +- Get atomic writes +- Support new filters +- Support read-only permissions +- Allow External plugins for authentication, rights management, storage and version control + +This release concludes endless months of hard work from the community. You, all +users and contributors, deserve a big **thank you**. + +This project has been an increadible experience for me, your dear Guillaume, +creator and maintainer of Radicale. After more than 8 years of fun, I think +that it's time to open this software to its contributors. Radicale can grow and +become more than the toy it used to be. I've always seen Radicale as a small +and simple piece of code, and I don't want to prevent people from adding +features just because I can't or don't want to maintain them. The community is +now large enough to handle this. + +If you're interested in Radicale, you can +read [#372](https://github.com/Kozea/Radicale/issues/372) and build its +future. + +### May 3, 2017 - Radicale 1.1.2 + +Radicale 1.1.2 is out! + +#### 1.1.2 - Third Law of Nature + +* **Security fix**: Add a random timer to avoid timing oracles and simple + bruteforce attacks when using the htpasswd authentication method. +* Various minor fixes. + +### December 31, 2015 - Radicale 1.1 + +Radicale 1.1 is out! + +#### 1.1 - Law of Nature + +One feature in this release is **not backward compatible**: + +* Use the first matching section for rights (inspired from daald) + +Now, the first section matching the path and current user in your custom rights +file is used. In the previous versions, the most permissive rights of all the +matching sections were applied. This new behaviour gives a simple way to make +specific rules at the top of the file independant from the generic ones. + +Many **improvements in this release are related to security**, you should +upgrade Radicale as soon as possible: + +* Improve the regex used for well-known URIs (by Unrud) +* Prevent regex injection in rights management (by Unrud) +* Prevent crafted HTTP request from calling arbitrary functions (by Unrud) +* Improve URI sanitation and conversion to filesystem path (by Unrud) +* Decouple the daemon from its parent environment (by Unrud) + +Some bugs have been fixed and little enhancements have been added: + +* Assign new items to corret key (by Unrud) +* Avoid race condition in PID file creation (by Unrud) +* Improve the docker version (by cdpb) +* Encode message and commiter for git commits +* Test with Python 3.5 + +### September 14, 2015 - Radicale 1.0, what's next? + +Radicale 1.0 is out! + +#### 1.0 - Sunflower + +* Enhanced performances (by Mathieu Dupuy) +* Add MD5-APR1 and BCRYPT for htpasswd-based authentication (by Jan-Philip Gehrcke) +* Use PAM service (by Stephen Paul Weber) +* Don't discard PROPPATCH on empty collections (Markus Unterwaditzer) +* Write the path of the collection in the git message (Matthew Monaco) +* Tests launched on Travis + +As explained in a previous [mail](http://librelist.com/browser//radicale/2015/8/21/radicale-1-0-is-coming-what-s-next/), +this version is called 1.0 because: + +- there are no big changes since 0.10 but some small changes are really useful, +- simple tests are now automatically launched on Travis, and more can be added + in the future (https://travis-ci.org/Kozea/Radicale). + +This version will be maintained with only simple bug fixes on a separate git +branch called ``1.0.x``. + +Now that this milestone is reached, it's time to think about the future. When +Radicale has been created, it was just a proof-of-concept. The main goal was to +write a small, stupid and simple CalDAV server working with Lightning, using no +external libraries. That's how we created a piece of code that's (quite) easy +to understand, to use and to hack. + +The first lines have been added to the SVN (!) repository as I was drinking +beers at the very end of 2008. It's now packaged for a growing number of Linux +distributions. + +And that was fun going from here to there thanks to you. So… **Thank you, +you're amazing**. I'm so glad I've spent endless hours fixing stupid bugs, +arguing about databases and meeting invitations, reading incredibly interesting +RFCs and debugging with the fabulous clients from Apple. I mean: that really, +really was really, really cool :). + +During these years, a lot of things have changed and many users now rely on +Radicale in production. For example, I use it to manage medical calendars, with +thousands requests per day. Many people are happy to install Radicale on their +small home servers, but are also frustrated by performance and unsupported +specifications when they're trying to use it seriously. + +So, now is THE FUTURE! I think that Radicale 2.0 should: + +- rely on a few external libraries for simple critical points (dealing with + HTTP and iCal for example), +- be thread-safe, +- be small, +- be documented in a different way (for example by splitting the client part + from the server part, and by adding use cases), +- let most of the "auth" modules outside in external modules, +- have more and more tests, +- have reliable and faster filesystem and database storage mechanisms, +- get a new design :). + +I'd also secretly love to drop the Python 2.x support. + +These ideas are not all mine (except from the really, really, really important +"design" point :p), they have been proposed by many developers and users. I've +just tried to gather them and keep points that seem important to me. + +Other points have been discussed with many users and contibutors, including: + +- support of other clients, including Windows and BlackBerry phones, +- server-side meeting invitations, +- different storage system as default (or even unique?). + +I'm not a huge fan of these features, either because I can't do anything about +them, or because I think that they're Really Bad Ideas®™. But I'm ready to talk +about them, because, well, I may not be always right! + +Need to talk about this? You know how to [contact us](#contribute)! + +### January 12, 2015 - Radicale 0.10 + +Radicale 0.10 is out! + +#### 0.10 - Lovely Endless Grass + +* Support well-known URLs (by Mathieu Dupuy) +* Fix collection discovery (by Markus Unterwaditzer) +* Reload logger config on SIGHUP (by Élie Bouttier) +* Remove props files when deleting a collection (by Vincent Untz) +* Support salted SHA1 passwords (by Marc Kleine-Budde) +* Don't spam the logs about non-SSL IMAP connections to localhost (by Giel van Schijndel) + +This version should bring some interesting discovery and auto-configuration +features, mostly with Apple clients. + +Lots of love and kudos for the people who have spent hours to test features and +report issues, that was long but really useful (and some of you have been +really patient :p). + +Issues are welcome, I'm sure that you'll find horrible, terrible, crazy bugs +faster than me. I'll release a version 0.10.1 if needed. + +What's next? It's time to fix and improve the storage methods. A real API for +the storage modules is a good beginning, many pull requests are already ready +to be discussed and merged, and we will probably get some good news about +performance this time. Who said "databases, please"? + +### July 12, 2013 - Radicale 0.8 + +Radicale 0.8 is out! + +#### 0.8 - Rainbow + +* New authentication and rights management modules (by Matthias Jordan) +* Experimental database storage +* Command-line option for custom configuration file (by Mark Adams) +* Root URL not at the root of a domain (by Clint Adams, Fabrice Bellet, Vincent Untz) +* Improved support for iCal, CalDAVSync, CardDAVSync, CalDavZAP and CardDavMATE +* Empty PROPFIND requests handled (by Christoph Polcin) +* Colon allowed in passwords +* Configurable realm message + +This version brings some of the biggest changes since Radicale's creation, +including an experimental support of database storage, clean authentication +modules, and rights management finally designed for real users. + +So, dear user, be careful: **this version changes important things in the +configuration file, so check twice that everything is OK when you update to +0.8, or you can have big problems**. + +More and more clients are supported, as a lot of bug fixes and features have +been added for this purpose. And before you ask: yes, 2 web-based clients, +[CalDavZAP and CardDavMATE](http://www.inf-it.com/open-source/clients/), are +now supported! + +Even if there has been a lot of time to test these new features, I am pretty +sure that some really annoying bugs have been left in this version. We will +probably release minor versions with bugfixes during the next weeks, and it +will not take one more year to reach 0.8.1. + +The documentation has been updated, but some parts are missing and some may be +out of date. You can [report bugs](https://github.com/Kozea/Radicale/issues) +or even [write documentation directly on GitHub](https://github.com/Kozea/Radicale/blob/website/pages/user_documentation.rst) +if you find something strange (and you probably will). + +If anything is not clear, or if the way rights work is a bit complicated to +understand, or if you are so happy because everything works so well, you can +[share your thoughts](#contribute)! + +It has been a real pleasure to work on this version, with brilliant ideas and +interesting bug reports from the community. I'd really like to thank all the +people reporting bugs, chatting on IRC, sending mails and proposing pull +requests: you are awesome. + +### August 3, 2012 - Radicale 0.7.1 + +Radicale 0.7.1 is out! + +#### 0.7.1 - Waterfalls + +* Many address books fixes +* New IMAP ACL (by Daniel Aleksandersen) +* PAM ACL fixed (by Daniel Aleksandersen) +* Courier ACL fixed (by Benjamin Frank) +* Always set display name to collections (by Oskari Timperi) +* Various DELETE responses fixed + +It's been a long time since the last version… As usual, many people have +contributed to this new version, that's a pleasure to get these pull requests. + +Most of the commits are bugfixes, especially about ACL backends and address +books. Many clients (including aCal and SyncEvolution) will be much happier +with this new version than with the previous one. + +By the way, one main new feature has been added: a new IMAP ACL backend, by +Daniel. And about authentication, exciting features are coming soon, stay +tuned! + +Next time, as many mails have come from angry and desperate coders, tests will +be *finally* added to help them to add features and fix bugs. And after that, +who knows, it may be time to release Radicale 1.0… + +### March 22, 2012 - Radicale 0.7 + +Radicale 0.7 is out, at least! + +#### 0.7 - Eternal Sunshine + +* Repeating events +* Collection deletion +* Courier and PAM authentication methods +* CardDAV support +* Custom LDAP filters supported + +**A lot** of people have reported bugs, proposed new features, added useful +code and tested many clients. Thank you Lynn, Ron, Bill, Patrick, Hidde, +Gerhard, Martin, Brendan, Vladimir, and everybody I've forgotten. + +### January 5, 2012 - Radicale 0.6.4, News from Calypso + +New year, new release. Radicale 0.6.4 has a really short changelog: + +#### 0.6.4 - Tulips + +* Fix the installation with Python 3.1 + +The bug was in fact caused by a +[bug in Python 3.1](http://bugs.python.org/issue9561), everything should be OK +now. + +#### Calypso + +After a lot of changes in Radicale, Keith Packard has decided to launch a fork +called [Calypso](http://keithp.com/blogs/calypso/), with nice features such +as a Git storage mechanism and a CardDAV support. + +There are lots of differences between the two projects, but the final goal for +Radicale is to provide these new features as soon as possible. Thanks to the +work of Keith and other people on GitHub, a basic CardDAV support has been +added in the [carddav branch](https://github.com/Kozea/Radicale/tree/carddav) +and already works with Evolution. Korganizer also works with existing address +books, and CardDAV-Sync will be tested soon. If you want to test other clients, +please let us know! + +### November 3, 2011 - Radicale 0.6.3 + +Radicale version 0.6.3 has been released, with bugfixes that could be +interesting for you! + +#### 0.6.3 - Red Roses + +* MOVE requests fixed +* Faster REPORT answers +* Executable script moved into the package + +#### What's New Since 0.6.2? + +The MOVE requests were suffering a little bug that is fixed now. These requests +are only sent by Apple clients, Mac users will be happy. + +The REPORT request were really, really slow (several minutes for large +calendars). This was caused by an awful algorithm parsing the entire calendar +for each event in the calendar. The calendar is now only parsed three times, +and the events are found in a Python list, turning minutes into seconds! Much +better, but far from perfection… + +Finally, the executable script parsing the command line options and starting +the HTTP servers has been moved from the ``radicale.py`` file into the +``radicale`` package. Two executable are now present in the archive: the good +old ``radicale.py``, and ``bin/radicale``. The second one is only used by +``setup.py``, where the hack used to rename ``radicale.py`` into ``radicale`` +has therefore been removed. As a consequence, you can now launch Radicale with +the simple ``python -m radicale`` command, without relying on an executable. + +#### Time for a Stable Release! + +The next release may be a stable release, symbolically called 1.0. Guess what's +missing? Tests, of course! + +A non-regression testing suite, based on the clients' requests, will soon be +added to Radicale. We're now thinking about a smart solution to store the +tests, to represent the expected answers and to launch the requests. We've got +crazy ideas, so be prepared: you'll definitely *want* to write tests during the +next weeks! + +Repeating events, PAM and Courier authentication methods have already been +added in master. You'll find them in the 1.0 release! + +#### What's Next? + +Being stable is one thing, being cool is another one. If you want some cool new +features, you may be interested in: + +- WebDAV and CardDAV support +- Filters and rights management +- Multiple storage backends, such as databases and git +- Freebusy periods +- Email alarms + +Issues have been reported in the bug tracker, you can follow there the latest +news about these features. Your beloved text editor is waiting for you! + +### September 27, 2011 - Radicale 0.6.2 + +0.6.2 is out with minor bugfixes. + +#### 0.6.2 - Seeds + +* iPhone and iPad support fixed +* Backslashes replaced by slashes in PROPFIND answers on Windows +* PyPI archive set as default download URL + +### August 28, 2011 - Radicale 0.6.1, Changes, Future + +As previously imagined, a new 0.6.1 version has been released, mainly fixing +obvious bugs. + +#### 0.6.1 - Growing Up + +* Example files included in the tarball +* htpasswd support fixed +* Redirection loop bug fixed +* Testing message on GET requests + +The changelog is really small, so there should be no real new problems since +0.6. The example files for logging, FastCGI and WSGI are now included in the +tarball, for the pleasure of our dear packagers! + +A new branch has been created for various future bug fixes. You can expect to +get more 0.6.x versions, making this branch a kind of "stable" branch with no +big changes. + +#### GitHub, Mailing List, New Website + +A lot of small changes occurred during the last weeks. + +If you're interested in code and new features, please note that we moved the +project from Gitorious to GitHub. Being hosted by Gitorious was a +nice experience, but the service was not that good and we were missing some +useful features such as git hooks. Moreover, GitHub is really popular, we're +sure that we'll meet a lot of kind users and coders there. + +We've also created a mailing-list on Librelist to keep a public +trace of the mails we're receiving. It a bit empty now, but we're sure that +you'll soon write us some kind words. For example, you can tell us what you +think of our new website! + +#### Future Features + +In the next weeks, new exciting features are coming in the master branch! Some +of them are almost ready: + +- Henry-Nicolas has added the support for the PAM and Courier-Authdaemon + authentication mechanisms. +- An anonymous called Keith Packard has prepared some small changes, such as + one file per event, cache and git versioning. Yes. Really. + +As you can find in the [Radicale Roadmap](http://redmine.kozea.fr/versions/), +tests, rights and filters are expected for 0.7. + +### August 1, 2011 - Radicale 0.6 Released + +Time for a new release with **a lot** of new exciting features! + +#### 0.6 - Sapling + +* WSGI support +* IPv6 support +* Smart, verbose and configurable logs +* Apple iCal 4 and iPhone support (by Łukasz Langa) +* CalDAV-Sync support (by Marten Gajda) +* aCal support +* KDE KOrganizer support +* LDAP auth backend (by Corentin Le Bail) +* Public and private calendars (by René Neumann) +* PID file +* MOVE requests management +* Journal entries support +* Drop Python 2.5 support + +Well, it's been a little longer than expected, but for good reasons: a lot of +features have been added, and a lot of clients are known to work with Radicale, +thanks to kind contributors. That's definitely good news! But… + +Testing all the clients is really painful, moreover for the ones from Apple (I +have no Mac nor iPhone of my own). We should seriously think of automated +tests, even if it's really hard to maintain, and maybe not that useful. If +you're interested in tests, you can look at +[the wonderful regression suite of DAViCal](http://repo.or.cz/w/davical.git/tree/HEAD:/testing/tests/regression-suite). + +The new features, for example the WSGI support, are also poorly documented. If +you have some Apache or lighttpd configuration working with Radicale, you can +make the world a little bit better by writing a paragraph or two in the +[Radicale documentation](https://gitorious.org/radicale/website). It's simple +plain text, don't be afraid! + +Because of all these changes, Radicale 0.6 may be a little bit buggy; a 0.6.1 +will probably be released soon, fixing small problems with clients and +features. Get ready to report bugs, I'm sure that you can find one (and fix +it)! + +### July 2, 2011 - Feature Freeze for 0.6 + +According to the [roadmap](http://redmine.kozea.fr/projects/radicale/roadmap), +a lot of features have been added since Radicale 0.5, much more than +expected. It's now time to test Radicale with your favourite client and to +report bugs before we release the next stable version! + +Last week, the iCal and iPhone support written by Łukasz has been fixed in +order to restore the broken Lightning support. After two afternoons of tests +with Rémi, we managed to access the same calendar with Lightning, iCal, iPhone +and Evolution, and finally discovered that CalDAV could also be a perfect +instant messaging protocol between a Mac, a PC and a phone. + +After that, we've had the nice surprise to see events displayed without a +problem (but after some strange steps of configuration) by aCal on Salem's +Android phone. + +It was Friday, fun fun fun fun. + +So, that's it: Radicale supports Lightning, Evolution, Kontact, aCal for +Android, iPhone and iCal. Of course, before releasing a new tarball: + +- [documentation](1.1.html#documentation/user-documentation/simple-usage/starting-the-client) is needed for the + new clients that are not documented yet (Kontact, aCal and iPhone); +- tests are welcome, particularly for the Apple clients that I can't test + anymore; +- no more features will be added, they'll wait in separate branches for the 0.7 + development. + +Please [report bugs](http://redmine.kozea.fr/projects/radicale/issues) if +anything goes wrong during your tests, or just let us know +[by Jabber or by mail](#contribute) if everything is OK. + +### May 1, 2011 - Ready for WSGI + +Here it is! Radicale is now ready to be launched behind your favourite HTTP +server (Apache, Lighttpd, Nginx or Tomcat for example). That's really good +news, because: + +- Real HTTP servers are much more efficient and reliable than the default + Python server used in Radicale; +- All the authentication backends available for your server will be available + for Radicale; +- Thanks to [flup](http://trac.saddi.com/flup), Radicale can be interfaced + with all the servers supporting CGI, AJP, FastCGI or SCGI; +- Radicale works very well without any additional server, without any + dependencies, without configuration, just as it was working before; +- This one more feature removes useless code, less is definitely more. + +The WSGI support has only be tested as a stand-alone executable and behind +Lighttpd, you should definitely try if it works with you favourite server too! + +No more features will be added before (quite) a long time, because a lot of +documentation and test is waiting for us. If you want to write tutorials for +some CalDAV clients support (iCal, Android, iPhone), HTTP servers support or +logging management, feel free to fork the documentation git repository and ask +for a merge. It's plain text, I'm sure you can do it! + +### April 30, 2011 - Apple iCal Support + +After a long, long work, the iCal support has finally been added to Radicale! +Well, this support is only for iCal 4 and is highly experimental, but you can +test it right now with the git master branch. Bug reports are welcome! + +Dear MacOS users, you can thank all the gentlemen who sended a lot of debugging +iformation. Special thanks to Andrew from DAViCal, who helped us a lot with his +tips and his tests, and Rémi Hainaud who lent his laptop for the final tests. + +The default server address is ``localhost:5232/user/``, where calendars can be +added. Multiple calendars and owner-less calendars are not tested yet, but they +should work quite well. More documentation will be added during the next +days. It will then be time to release the Radicale 0.6 version, and work on the +WSGI support. + +### April 25, 2011 - Two Features and One New Roadmap + +Two features have just reached the master branch, and the roadmap has been +refreshed. + +#### LDAP Authentication + +Thanks to Corentin, the LDAP authentication is now included in Radicale. The +support is experimental and may suffer unstable connexions and security +problems. If you are interested in this feature (a lot of people seem to be), +you can try it and give some feedback. + +No SSL support is included yet, but this may be quite easy to add. By the way, +serious authentication methods will rely on a "real" HTTP server, as soon as +Radicale supports WSGI. + +#### Journal Entries + +Mehmet asked for the journal entries (aka. notes or memos) support, that's +done! This also was an occasion to clean some code in the iCal parser, and to +add a much better management of multi-lines entries. People experiencing crazy +`X-RADICALE-NAME` entries can now clean their files, Radicale won't pollute +them again. + +#### New Roadmap + +Except from htpasswd and LDAP, most of the authentication backends (database, +SASL, PAM, user groups) are not really easy to include in Radicale. The easiest +solution to solve this problem is to give Radicale a CGI support, to put it +behind a solid server such as Apache. Of course, CGI is not enough: a WSGI +support is quite better, with the FastCGI, AJP and SCGI backends offered by +[flup](http://trac.saddi.com/flup/). Quite exciting, isn't it? + +That's why it was important to add new versions on the roadmap. The 0.6 version +is now waiting for the Apple iCal support, and of course for some tests to kill +the last remaining bugs. The only 0.7 feature will be WSGI, allowing many new +authentication methods and a real multithread support. + +After that, 0.8 may add CalDAV rights and filters, while 1.0 will draw +thousands of rainbows and pink unicorns (WebDAV sync, CardDAV, Freebusy). A lot +of funky work is waiting for you, hackers! + +#### Bugs + +Many bugs have also been fixed, most of them due to the owner-less calendars +support. Radicale 0.6 may be out in a few weeks, you should spend some time +testing the master branch and filling the bug tracker. + +### April 10, 2011 - New Features + +Radicale 0.5 was released only 8 days ago, but 3 new features have already been +added to the master branch: + +- IPv6 support, with multiple addresses/ports support +- Logs and debug mode +- Owner-less calendars + +Most of the code has been written by Necoro and Corentin, and that was not easy +at all: Radicale is now multithreaded! For sure, you can find many bugs and +report them on the +[bug tracker](http://redmine.kozea.fr/projects/radicale/issues). And if you're +fond of logging, you can even add a default configuration file and more debug +messages in the source. + +### April 2, 2011 - Radicale 0.5 Released + +Radicale 0.5 is out! Here is what's new: + +#### 0.5 - Historical Artifacts + +* Calendar depth +* iPhone support +* MacOS and Windows support +* HEAD requests management +* htpasswd user from calendar path + +iPhone support, but no iCal support for 0.5, despite our hard work, sorry! +After 1 month with no more activity on the dedicated bug, it was time to forget +it and hack on new awesome features. Thanks for your help, dear Apple users, I +keep the hope that one day, Radicale will work with you! + +So, what's next? As promised, some cool git branches will soon be merged, with +LDAP support, logging, IPv6 and anonymous calendars. Sounds pretty cool, heh? +Talking about new features, more and more people are asking for a CardDAV +support in Radicale. A git branch and a feature request are open, feel free to +hack and discuss. + +### February 3, 2011 - Jabber Room and iPhone Support + +After a lot of help and testing work from Andrew, Björn, Anders, Dorian and +Pete (and other ones we could have forgotten), a simple iPhone support has been +added in the git repository. If you are interested, you can test this feature +*right now* by +[downloading the latest git version](#git-repository) +(a tarball is even available too if you don't want or know how to use git). + +No documentation has been written yet, but using the right URL in the +configuration should be enough to synchronize your calendars. If you have any +problems, you can ask by joining our new Jabber room: +radicale@room.jabber.kozea.fr. + +Radicale 0.5 will be released as soon as the iCal support is ready. If you have +an Apple computer, Python skills and some time to spend, we'd be glad to help +you debugging Radicale. + +### October 21, 2010 - News from Radicale + +During the last weeks, Radicale has not been idle, even if no news have been +posted since August. Thanks to Pete, Pierre-Philipp and Andrew, we're trying to +add a better support on MacOS, Windows and mobile devices like iPhone and +Android-based phones. + +All the tests on Windows have been successful: launching Radicale and using +Lightning as client works without any problems. On Android too, some testers +have reported clients working with Radicale. These were the good news. + +The bad news come from Apple: both iPhone and MacOS default clients are not +working yet, despite the latest enhancements given to the PROPFIND +requests. The problems are quite hard to debug due to our lack of Apple +hardware, but Pete is helping us in this difficult quest! Radicale 0.5 will be +out as soon as these two clients are working. + +Some cool stuff is coming next, with calendar collections and groups, and a +simple web-based CalDAV client in early development. Stay tuned! + +### August 8, 2010 - Radicale 0.4 Released + +Radicale 0.4 is out! Here is what's new: + +#### 0.4 - Hot Days Back + +* Personal calendars +* HEAD requests +* Last-Modified HTTP header +* ``no-ssl`` and ``foreground`` options +* Default configuration file + +This release has mainly been released to help our dear packagers to include a default configuration file and to write init scripts. Big thanks to Necoro for his work on the new Gentoo ebuild! + +### July 4, 2010 - Three Features Added Last Week + +Some features have been added in the git repository during the last weeks, +thanks to Jerome and Mariusz! + +Personal Calendars + Calendars accessed through the htpasswd ACL module can now be + personal. Thanks to the ``personal`` option, a user called ``bob`` can access + calendars at ``/bob/*`` but not to the ``/alice/*`` ones. + +HEAD Requests + Radicale can now answer HEAD requests. HTTP headers can be retrieved thanks + to this request, without getting contents given by the GET requests. + +Last-Modified HTTP header + The Last-Modified header gives the last time when the calendar has been + modified. This is used by some clients to cache the calendars and not + retrieving them if they have not been modified. + +### June 14, 2010 - Radicale 0.3 Released + +Radicale 0.3 is out! Here is what’s new: + +#### 0.3 - Dancing Flowers + +* Evolution support +* Version management + +The website changed a little bit too, with some small HTML5 and CSS3 features +such as articles, sections, transitions, opacity, box shadows and rounded +corners. If you’re reading this website with Internet Explorer, you should +consider using a standard-compliant browser! + +Radicale is now included in Squeeze, the testing branch of Debian. A +[Radicale ebuild for Gentoo](http://bugs.gentoo.org/show_bug.cgi?id=322811) has +been proposed too. If you want to package Radicale for another distribution, +you’re welcome! + +Next step is 0.5, with calendar collections, and Windows and MacOS support. + +### May 31, 2010 - May News +#### News from contributors + +Jonas Smedegaard packaged Radicale for Debian last week. Two packages, called +``radicale`` for the daemon and ``python-radicale`` for the module, have been +added to Sid, the unstable branch of Debian. Thank you, Jonas! + +Sven Guckes corrected some of the strange-English-sentences present on this +website. Thank you, Sven! + +#### News from software + +A simple ``VERSION`` has been added in the library: you can now play with +``radicale.VERSION`` and ``$radicale --version``. + +After playing with the version (should not be too long), you may notice that +the next version is called 0.3, and not 0.5 as previously decided. The 0.3 main +goal is to offer the support for Evolution as soon as possible, without waiting +for the 0.5. After more than a month of test, we corrected all the bugs we +found and everything seems to be fine; we can imagine that a brand new tarball +will be released during the first days of June. + +### April 19, 2010 - Evolution Supported + +Radicale now supports another CalDAV client: +[Evolution, the default mail, addressbook and calendaring client for Gnome](http://projects.gnome.org/evolution/). +This feature was quite easy to add, as it required less than 20 new lines of +code in the requests handler. + +If you are interested, just clone the +[git repository](http://www.gitorious.org/radicale/radicale). + +### April 13, 2010 - Radicale 0.2 Released + +Radicale 0.2 is out! Here is what’s new: + +#### 0.2 - Snowflakes + +* Sunbird pre-1.0 support +* SSL connection +* Htpasswd authentication +* Daemon mode +* User configuration +* Twisted dependency removed +* Python 3 support +* Real URLs for PUT and DELETE +* Concurrent modification reported to users +* Many bugs fixed by Roger Wenham + +First of all, we would like to thank Roger Wenham for his bugfixes and his +supercool words. + +You may have noticed that Sunbird 1.0 has not been released, but according to +the Mozilla developers, 1.0pre is something like a final version. + +You may have noticed too that Radicale can be +[downloaded from PyPI](http://pypi.python.org/pypi/Radicale/0.2). Of course, it +is also available on the [download page](#download). + +### January 21, 2010 - HTTPS and Authentication + +HTTPS connections and authentication have been added to Radicale this +week. Command-line options and personal configuration files are also ready for +test. According to the TODO file included in the package, the next version will +finally be 0.2, when sunbird 1.0 is out. Go, Mozilla hackers, go! + +HTTPS connection + HTTPS connections are now available using the standard TLS mechanisms. Give + Radicale a private key and a certificate, and your data are now safe. + +Authentication + A simple authentication architecture is now available, allowing different + methods thanks to different modules. The first two modules are ``fake`` (no + authentication) and ``htpasswd`` (authentication with an ``htpasswd`` file + created by the Apache tool). More methods such as LDAP are coming soon! + +### January 15, 2010 - Ready for Python 3 + +Dropping Twisted dependency was the first step leading to another big feature: +Radicale now works with Python 3! The code was given a small cleanup, with some +simplifications mainly about encoding. Before the 0.1.1 release, feel free to +test the git repository, all Python versions from 2.5 should be OK. + +### January 11, 2010 - Twisted no Longer Required + +Good news! Radicale 0.1.1 will support Sunbird 1.0, but it has another great +feature: it has no external dependency! Twisted is no longer required for the +git version, removing about 50 lines of code. + +### December 31, 2009 - Lightning and Sunbird 1.0b2pre Support + +Lightning/Sunbird 1.0b2pre is out, adding minor changes in CalDAV support. A +[new commit](http://www.gitorious.org/radicale/radicale/commit/330283e) makes +Radicale work with versions 0.9, 1.0b1 et 1.0b2. Moreover, etags are now quoted +according to the RFC 2616. + +### December 9, 2009 - Thunderbird 3 released + +[Thunderbird 3 is out](http://www.mozillamessaging.com/thunderbird/3.0/releasenotes/), +and Lightning/Sunbird 1.0 should be released in a few days. The +[last commit in git](http://gitorious.org/radicale/radicale/commit/6545bc8) +should make Radicale work with versions 0.9 and 1.0b1pre. Radicale 0.1.1 will +soon be released adding support for version 1.0. + +### September 1, 2009 - Radicale 0.1 Released + +First Radicale release! Here is the changelog: + +#### 0.1 - Crazy Vegetables + +* First release +* Lightning/Sunbird 0.9 compatibility +* Easy installer + +You can download this version on the [download page](#download). + +### July 28, 2009 - Radicale on Gitorious + +Radicale code has been released on Gitorious! Take a look at the +[Radicale main page on Gitorious](http://www.gitorious.org/radicale) to view +and download source code. + +### July 27, 2009 - Radicale Ready to Launch + +The Radicale Project is launched. The code has been cleaned up and will be +available soon… diff --git a/md/v3/00_index.md b/md/v3/00_index.md new file mode 100644 index 000000000..5b9923f43 --- /dev/null +++ b/md/v3/00_index.md @@ -0,0 +1,34 @@ +## Translations of this page + +* [Telugu](https://github.com/Kozea/Radicale/blob/master/docs/DOCUMENTATION.te.md) + +## Getting started + +#### About Radicale + +Radicale is a small but powerful CalDAV (calendars, to-do lists) and CardDAV +(contacts) server, that: + +* Shares calendars and contact lists through CalDAV, CardDAV and HTTP. +* Supports events, todos, journal entries and business cards. +* Works out-of-the-box, no complicated setup or configuration required. +* Offers flexible authentication options. +* Can limit access by authorization. +* Can secure connections with TLS. +* Works with many + [CalDAV and CardDAV clients](#supported-clients). +* Stores all data on the file system in a simple folder structure. +* Can be extended with plugins. +* Is GPLv3-licensed free software. + +#### Installation + +Check + +* [Tutorials](#tutorials) +* [Documentation](#documentation-1) +* [Wiki on GitHub](https://github.com/Kozea/Radicale/wiki) +* [Discussions on GitHub](https://github.com/Kozea/Radicale/discussions) +* [Open and already Closed Issues on GitHub](https://github.com/Kozea/Radicale/issues?q=is%3Aissue) + +#### What's New? diff --git a/md/v3/01_tutorials.md b/md/v3/01_tutorials.md new file mode 100644 index 000000000..bcdaab3b1 --- /dev/null +++ b/md/v3/01_tutorials.md @@ -0,0 +1,672 @@ + +## Tutorials + +### Simple 5-minute setup + +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! + +The server, configured with settings from this section, only binds to localhost +(i.e. it is not reachable over the network), and you can log in with any username and password. +When everything works, you may get a local [client](#supported-clients) +and start creating calendars and address books. +If Radicale fits your needs, it may be time for some [basic configuration](#basic-configuration) +to support remote clients and desired authentication type. + +Follow one of the chapters below depending on your operating system. + +#### Linux / \*BSD + +Hint: instead of downloading from PyPI, look for packages provided by your [distribution](#linux-distribution-packages). +They contain also startup scripts integrated into your distributions, that allow Radicale to run daemonized. + +First, make sure that **python** 3.9 or later and **pip** are installed. On most distributions it should be +enough to install the package ``python3-pip``. + +##### as normal user + +Recommended only for testing - open a console and type: + +```bash +# Run the following command to only install for the current user +python3 -m pip install --user --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz +``` + +If _install_ is not working and instead `error: externally-managed-environment` is displayed, +create and activate a virtual environment in advance. + +```bash +python3 -m venv ~/venv +source ~/venv/bin/activate +``` + +and try to install with + +```bash +python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz +``` + +Start the service manually, data is stored only for the current user + +```bash +# Start, data is stored for the current user only +python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections --auth-type none +``` + +##### as system user (or as root) + +Alternatively, you can install and run as system user or as root (not recommended): + +```bash +# Run the following command as root (not recommended) or non-root system user +# (the later may require --user in case dependencies are not available system-wide and/or virtual environment) +python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz +``` + +Start the service manually, with data stored in a system folder under `/var/lib/radicale/collections`: + +```bash +# Start, data is stored in a system folder (requires write permissions to /var/lib/radicale/collections) +python3 -m radicale --storage-filesystem-folder=/var/lib/radicale/collections --auth-type none +``` + +#### Windows + +The first step is to install Python. Go to +[python.org](https://python.org) and download the latest version of Python 3. +Then run the installer. +On the first window of the installer, check the "Add Python to PATH" box and +click on "Install now". Wait a couple of minutes, it's done! + +Launch a command prompt and type: + +```powershell +python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz +python -m radicale --storage-filesystem-folder=~/radicale/collections --auth-type none +``` + +##### Common + +Success!!! Open in your browser! +You can log in with any username and password as no authentication is required by example option `--auth-type none`. +This is **INSECURE**, see [Configuration/Authentication](#auth) for more details. + +Just note that default configuration for security reason binds the server to `localhost` (IPv4: `127.0.0.1`, IPv6: `::1`). +See [Addresses](#addresses) and [Configuration/Server](#server) for more details. + +### Basic Configuration + +Installation instructions can be found in the +[simple 5-minute setup](#simple-5-minute-setup) tutorial. + +Radicale tries to load configuration files from `/etc/radicale/config` and +`~/.config/radicale/config`. +Custom paths can be specified with the `--config /path/to/config` command +line argument or the `RADICALE_CONFIG` environment variable. +Multiple configuration files can be separated by `:` (resp. `;` on Windows). +Paths that start with `?` are optional. + +You should create a new configuration file at the desired location. +(If the use of a configuration file is inconvenient, all options can be +passed via command line arguments.) + +All configuration options are described in detail in the +[Configuration](#configuration) section. + +#### Authentication + +In its default configuration since version 3.5.0, Radicale rejects all +authentication attempts by using config option `type = denyall` (introduced +with 3.2.2) as default until explicitly configured. + +Versions before 3.5.0 did not check usernames or passwords at all, unless explicitly configured. +If such a server is reachable over a network, you should change this as soon as possible. + +First a `users` file with all usernames and passwords must be created. +It can be stored in the same directory as the configuration file. + +##### The secure way + +The `users` file can be created and managed with +[htpasswd](https://httpd.apache.org/docs/current/programs/htpasswd.html): + +Note: some OSes or distributions contain outdated versions of `htpasswd` (< 2.4.59) without +support for SHA-256 or SHA-512 (e.g. Ubuntu LTS 22). +In these cases, use `htpasswd`'s command line option `-B` for the `bcrypt` hash method (recommended), +or stay with the insecure (not recommended) MD5 (default) or SHA-1 (command line option `-s`). + +Note: support of SHA-256 and SHA-512 was introduced with 3.1.9 + +```bash +# Create a new htpasswd file with the user "user1" using SHA-512 as hash method +$ htpasswd -5 -c /path/to/users user1 +New password: +Re-type new password: +# Add another user +$ htpasswd -5 /path/to/users user2 +New password: +Re-type new password: +``` + +Authentication can be enabled with the following configuration: + +```ini +[auth] +type = htpasswd +htpasswd_filename = /path/to/users +htpasswd_encryption = autodetect +``` + +##### The simple but insecure way + +Create the `users` file by hand with lines containing the username and +password separated by `:`. Example: + +```htpasswd +user1:password1 +user2:password2 +``` + +Authentication can be enabled with the following configuration: + +```ini +[auth] +type = htpasswd +htpasswd_filename = /path/to/users +# encryption method used in the htpasswd file +htpasswd_encryption = plain +``` + +#### Addresses + +The default configuration binds the server to localhost. It cannot be reached +from other computers. This can be changed with the following configuration +options (IPv4 and IPv6): + +```ini +[server] +hosts = 0.0.0.0:5232, [::]:5232 +``` + +#### Storage + +Data is stored in the folder `/var/lib/radicale/collections`. The path can +be changed with the following configuration: + +```ini +[storage] +filesystem_folder = /path/to/storage +``` + +> **Security:** The storage folder shall not be readable by unauthorized users. +> Otherwise, they can read the calendar data and lock the storage. +> You can find OS dependent instructions in the +> [Running as a service](#running-as-a-service) section. + +#### Limits + +Radicale enforces limits on the maximum number of parallel connections, +the maximum file size (important for contacts with big photos) and the rate of +incorrect authentication attempts. Connections are terminated after a timeout. +The default values should be fine for most scenarios. + +```ini +[server] +max_connections = 20 +# 100 Megabyte +max_content_length = 100000000 +# 10 Megabyte (>= 3.5.10) +max_resource_size = 10000000 +# 30 seconds +timeout = 30 + +[auth] +# Average delay after failed login attempts in seconds +# Also used for invalid/not-existing/not-enabled share-by-token (>= 3.7.0) +delay = 1 +``` + +### Running as a service + +The method to run Radicale as a service depends on your host operating system. +Follow one of the chapters below depending on your operating system and +requirements. + +#### Linux with systemd system-wide + +Recommendation: check support by [Linux Distribution Packages](#linux-distribution-packages) +instead of manual setup / initial configuration. + +Create the **radicale** user and group for the Radicale service by running (as `root`): +```bash +useradd --system --user-group --home-dir / --shell /sbin/nologin radicale +``` + +The storage folder must be made writable by the **radicale** user by running (as `root`): +```bash +mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections +``` + +If a dedicated cache folder is configured (see option [filesystem_cache_folder](#filesystem_cache_folder)), +it also must be made writable by **radicale**. To achieve that, run (as `root`): +```bash +mkdir -p /var/cache/radicale && chown -R radicale:radicale /var/cache/radicale +```` + +> **Security:** The storage shall not be readable by others. +> To make sure this is the case, run (as `root`): +> ```bash +> chmod -R o= /var/lib/radicale/collections +> ``` + +Create the file `/etc/systemd/system/radicale.service`: + +```ini +[Unit] +Description=A simple CalDAV (calendar) and CardDAV (contact) server +After=network.target +Requires=network.target + +[Service] +ExecStart=/usr/bin/env python3 -m radicale +Restart=on-failure +User=radicale +# Deny other users access to the calendar data +UMask=0027 +# Optional security settings +PrivateTmp=true +ProtectSystem=strict +ProtectHome=true +PrivateDevices=true +ProtectKernelTunables=true +ProtectKernelModules=true +ProtectControlGroups=true +NoNewPrivileges=true +ReadWritePaths=/var/lib/radicale/ +# Replace with following in case dedicated cache folder should be used +#ReadWritePaths=/var/lib/radicale/ /var/cache/radicale/ + +[Install] +WantedBy=multi-user.target +``` + +In this system-wide implementation, Radicale will load the configuration from the file `/etc/radicale/config`. + +To enable and manage the service run: + +```bash +# Enable the service +$ systemctl enable radicale +# Start the service +$ systemctl start radicale +# Check the status of the service +$ systemctl status radicale +# View all log messages +$ journalctl --unit radicale.service +``` + +#### Linux with systemd as a user + +Create the file `~/.config/systemd/user/radicale.service`: + +```ini +[Unit] +Description=A simple CalDAV (calendar) and CardDAV (contact) server + +[Service] +ExecStart=/usr/bin/env python3 -m radicale +Restart=on-failure + +[Install] +WantedBy=default.target +``` + +In this user-specific configuration, Radicale will load the configuration from +the file `~/.config/radicale/config`. +You should set the configuration option `filesystem_folder` in the `storage` +section to something like `~/.var/lib/radicale/collections`. + +To enable and manage the service run: + +```bash +# Enable the service +$ systemctl --user enable radicale +# Start the service +$ systemctl --user start radicale +# Check the status of the service +$ systemctl --user status radicale +# View all log messages +$ journalctl --user --unit radicale.service +``` + +#### Windows with "NSSM - the Non-Sucking Service Manager" + +First install [NSSM](https://nssm.cc/) and start `nssm install` in a command +prompt. Apply the following configuration: + +* Service name: `Radicale` +* Application + * Path: `C:\Path\To\Python\python.exe` + * Arguments: `--config C:\Path\To\Config` +* I/O redirection + * Error: `C:\Path\To\Radicale.log` + +> **Security:** Be aware that the service runs in the local system account, +> you might want to change this. Managing user accounts is beyond the scope of +> this manual. Also, make sure that the storage folder and log file is not +> readable by unauthorized users. + +The log file might grow very big over time, you can configure file rotation +in **NSSM** to prevent this. + +The service is configured to start automatically when the computer starts. +To start the service manually open **Services** in **Computer Management** and +start the **Radicale** service. + +### Reverse Proxy + +When a reverse proxy is used, and Radicale should be made available at a path +below the root (such as `/radicale/`), then this path must be provided via +the `X-Script-Name` header (without a trailing `/`). The proxy must remove +the location from the URL path that is forwarded to Radicale. If Radicale +should be made available at the root of the web server (in the nginx case +using `location /`), then the setting of the `X-Script-Name` header should be +removed from the example below. + +Example **nginx** configuration extension: + +See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/nginx/ + +```nginx +location /radicale/ { # The trailing / is important! + proxy_pass http://localhost:5232; + proxy_set_header X-Script-Name /radicale; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Host $http_host; + proxy_pass_header Authorization; +} +``` + +Example **Caddy** configuration extension: + +See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/caddy/ + +``` +handle_path /radicale/* { + uri strip_prefix /radicale + reverse_proxy localhost:5232 { + } +} +``` + +Example **Apache** configuration extension: + +See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/apache/ + +```apache +RewriteEngine On +RewriteRule ^/radicale$ /radicale/ [R,L] + + + ProxyPass http://localhost:5232/ retry=0 + ProxyPassReverse http://localhost:5232/ + RequestHeader set X-Script-Name /radicale + RequestHeader set X-Forwarded-Port "%{SERVER_PORT}s" + RequestHeader set X-Forwarded-Proto expr=%{REQUEST_SCHEME} + = 2.4.40> + Proxy100Continue Off + + +``` + +Example **Apache .htaccess** configuration: + +```apache +DirectoryIndex disabled +RewriteEngine On +RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L] + +# Set to directory of .htaccess file: +RequestHeader set X-Script-Name /radicale +RequestHeader set X-Forwarded-Port "%{SERVER_PORT}s" +RequestHeader unset X-Forwarded-Proto + +RequestHeader set X-Forwarded-Proto "https" + +``` + +Example **lighttpd** configuration: + +```lighttpd +server.modules += ( "mod_proxy" , "mod_setenv" ) + +$HTTP["url"] =~ "^/radicale/" { + proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => "5232" )) ) + setenv.add-request-header = ( "X-Script-Name" => "/radicale" ) +} +``` + +Be reminded that Radicale's default configuration enforces limits on the +maximum number of parallel connections, the maximum file size and the rate of +incorrect authentication attempts. Connections are terminated after a timeout. + +#### Manage user accounts with the reverse proxy + +Set the configuration option `type` in the `auth` section to +`http_x_remote_user`. +Radicale uses the username provided in the `X-Remote-User` HTTP header and +disables its internal HTTP authentication. + +Example **nginx** configuration: + +```nginx +location /radicale/ { + proxy_pass http://localhost:5232/; + proxy_set_header X-Script-Name /radicale; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Remote-User $remote_user; + proxy_set_header Host $http_host; + auth_basic "Radicale - Password Required"; + auth_basic_user_file /etc/nginx/htpasswd; +} +``` + +Example **Caddy** configuration: + +``` +handle_path /radicale/* { + uri strip_prefix /radicale + basicauth { + USER HASH + } + reverse_proxy localhost:5232 { + header_up X-Script-Name /radicale + header_up X-remote-user {http.auth.user.id} + } +} +``` + +Example **Apache** configuration: + +```apache +RewriteEngine On +RewriteRule ^/radicale$ /radicale/ [R,L] + + + AuthType Basic + AuthName "Radicale - Password Required" + AuthUserFile "/etc/radicale/htpasswd" + Require valid-user + + ProxyPass http://localhost:5232/ retry=0 + ProxyPassReverse http://localhost:5232/ + = 2.4.40> + Proxy100Continue Off + + RequestHeader set X-Script-Name /radicale + RequestHeader set X-Remote-User expr=%{REMOTE_USER} + +``` + +Example **Apache .htaccess** configuration: + +```apache +DirectoryIndex disabled +RewriteEngine On +RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L] + +AuthType Basic +AuthName "Radicale - Password Required" +AuthUserFile "/etc/radicale/htpasswd" +Require valid-user + +# Set to directory of .htaccess file: +RequestHeader set X-Script-Name /radicale +RequestHeader set X-Remote-User expr=%{REMOTE_USER} +``` + +> **Security:** Untrusted clients should not be able to access the Radicale +> server directly. Otherwise, they can authenticate as any user by simply +> setting related HTTP header. This can be prevented by listening to the +> loopback interface only or local firewall rules. + +#### Secure connection between Radicale and the reverse proxy + +SSL certificates can be used to encrypt and authenticate the connection between +Radicale and the reverse proxy. First you need to 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, these values do not really matter, and you can +keep the defaults. + +```bash +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: + +```ini +[server] +ssl = True +certificate = /path/to/server_cert.pem +key = /path/to/server_key.pem +certificate_authority = /path/to/client_cert.pem +``` + +If you are using the Let's Encrypt Certbot, the configuration should look similar to this: + +```ini +[server] +ssl = True +certificate = /etc/letsencrypt/live/{Your Domain}/fullchain.pem +key = /etc/letsencrypt/live/{Your Domain}/privkey.pem +``` + +Example **nginx** configuration: + +```nginx +location /radicale/ { + proxy_pass https://localhost:5232/; + ... + # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...). + proxy_ssl_certificate /path/to/client_cert.pem; + proxy_ssl_certificate_key /path/to/client_key.pem; +} +``` + +### WSGI Server + +Radicale is compatible with the WSGI specification. + +A configuration file can be set with the `RADICALE_CONFIG` environment +variable, otherwise no configuration file is loaded and the default +configuration is used. + +Example **uWSGI** configuration: + +```ini +[uwsgi] +http-socket = 127.0.0.1:5232 +processes = 8 +plugin = python3 +module = radicale +env = RADICALE_CONFIG=/etc/radicale/config +``` + +Example **Gunicorn** configuration: + +```bash +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 `auth` section to `remote_user`. +This way Radicale uses the username provided by the WSGI server and disables +its internal authentication over HTTP. + +### Versioning collections with Git + +This tutorial describes how to keep track of all changes to calendars and +address books with **git** (or any other version control system). + +The repository must be initialized in the collection base directory +of the user running `radicale` daemon. + +```bash +## assuming "radicale" user is starting "radicale" service +# change to user "radicale" +su -l -s /bin/bash radicale + +# change to collection base directory defined in [storage] -> filesystem_folder +# assumed here /var/lib/radicale/collections +cd /var/lib/radicale/collections + +# initialize git repository +git init + +# set user and e-mail, here minimum example +git config user.name "$USER" +git config user.email "$USER@$HOSTNAME" + +# define ignore of cache/lock/tmp files +cat <<'END' >.gitignore +.Radicale.cache +.Radicale.lock +.Radicale.tmp-* +END +``` + +The configuration option `hook` in the `storage` section must be set to +the following command: + +```bash +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. + +Log of `git` can be investigated using + +```bash +su -l -s /bin/bash radicale +cd /var/lib/radicale/collections +git log +``` + +In case of problems, make sure you run radicale with ``--debug`` switch and +inspect the log output. For more information, please visit +[section on logging](#logging-overview). + +Reason for problems can be + - SELinux status -> check related audit log + - problematic file/directory permissions + - command is not fond or cannot be executed or argument problem diff --git a/md/v3/02_documentation.md b/md/v3/02_documentation.md new file mode 100644 index 000000000..71efafd3d --- /dev/null +++ b/md/v3/02_documentation.md @@ -0,0 +1,1489 @@ +## Documentation + +### Options + +#### General Options + +##### --version + +Print version + +##### --verify-storage + +Verification of local collections storage + +##### --verify-item + +_(>= 3.6.0)_ + +Verification of a particular item file + +##### --verify-sharing + +_(>= 3.7.0)_ + +Verification of local sharing database + +##### -C|--config + +Load one or more specified config file(s) + +##### -D|--debug + +Turns log level to debug + +#### Configuration Options + +Each supported option from config file can be provided/overridden by command line +replacing `_` with `-` and prepending the section followed by a `-`, e.g. + +``` +[logging] +backtrace_on_debug = False +``` + +can be enabled using `--logging-backtrace-on-debug=true` on command line. + +### Configuration + +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. + +An example configuration file looks like: + +```ini +[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 with the `--config /path/to/config` command +line argument or the `RADICALE_CONFIG` environment variable. +Multiple configuration files can be separated by `:` (resp. `;` on Windows). +Paths that start with `?` are optional. + +The same example configuration via command line arguments looks like: + +```bash +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. + +You can also use command-line options in startup scripts as shown in the following examples: + +```bash +## simple variable containing multiple options +RADICALE_OPTIONS="--logging-level=debug --config=/etc/radicale/config --logging-request-header-on-debug --logging-rights-rule-doesnt-match-on-debug" +/usr/bin/radicale $RADICALE_OPTIONS + +## variable as array method #1 +RADICALE_OPTIONS=("--logging-level=debug" "--config=/etc/radicale/config" "--logging-request-header-on-debug" "--logging-rights-rule-doesnt-match-on-debug") +/usr/bin/radicale ${RADICALE_OPTIONS[@]} + +## variable as array method #2 +RADICALE_OPTIONS=() +RADICALE_OPTIONS+=("--logging-level=debug") +RADICALE_OPTIONS+=("--config=/etc/radicale/config") +/usr/bin/radicale ${RADICALE_OPTIONS[@]} +``` + +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` + +##### delay_on_error + +_(>= 3.7.0)_ + +Base delay in case of error 5xx response (seconds) + +Default: `1` + +##### max_content_length + +The maximum size of the request body. (bytes) + +Default: `100000000` (100 Mbyte) + +In case of using a reverse proxy in front of check also there related option. + +##### max_resource_size + +_(>= 3.5.10)_ + +The maximum size of a resource. (bytes) + +Default: `10000000` (10 Mbyte) + +Limited to 80% of max_content_length to cover plain base64 encoded payload. + +Announced to clients requesting "max-resource-size" via PROPFIND. + +##### timeout + +Socket timeout. (seconds) + +Default: `30` + +##### ssl + +Enable transport layer encryption. + +Default: `False` + +##### certificate + +Path of the SSL certificate. + +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) + +#### [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 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](https://httpd.apache.org/docs/current/programs/htpasswd.html) + 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_remote_user` _(>= 3.5.9)_ + Takes the username from the Remote-User HTTP header `HTTP_REMOTE_USER` 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. + +* `http_x_remote_user` + Takes the username from the X-Remote-User HTTP header `HTTP_X_REMOTE_USER` 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](https://httpd.apache.org/docs/current/programs/htpasswd.html) +or similar to generate this file. + +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: + + ```htpasswd + 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. + Also consider version of passlib(libpass): bcrypt >= 5.0.0 requires passlib(libpass) >= 1.9.3 + +* `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 or missing login attempts or denied access. + +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 +```ini +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_security + +_(>= 3.5.2)_ + +Use encryption on the LDAP connection. + +One of +* `none` +* `tls` +* `starttls` + +Default: `none` + +##### ldap_ssl_verify_mode + +_(>= 3.3.0)_ + +Certificate verification mode for tls and starttls. + +One of +* `NONE` +* `OPTIONAL` +* `REQUIRED`. + +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 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](https://github.com/Kozea/Radicale/wiki/LDAP-authentication) 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 search 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: +* `AF_UNIX` +* `AF_INET` +* `AF_INET6` + +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 +* [address]:port (for IPv5 addresses) +* imap.server.tld + +Default: `localhost` + +##### imap_security + +_(>= 3.4.1)_ + +Secure the IMAP connection: + +One of: +* `tls` +* `starttls` +* `none` + +Default: `tls` + +##### oauth2_token_endpoint + +_(>= 3.5.0)_ + +Endpoint URL for the OAuth2 token + +Default: (unset) + +##### oauth2_client_id + +_(>= 3.7.0)_ + +Client ID used to request the Auth2 token + +Default: `radicale` + +##### oauth2_client_secret + +_(>= 3.7.0)_ + +Client secret used to request the Auth2 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` + + +#### [rights] + +##### type + +Authorization backend that is used to check the access rights to collections. + +The default and recommended backend is `owner_only`. If access to calendars +and address books outside the user's collection directory (that's `/username/`) +is granted, clients will not detect these collections automatically and +will not show them to the users. +Choosing any other authorization backend is only useful if you access +calendars and address books directly via URL. + +Available backends are: + +* `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 + +Name of the file containing the authorization rules for the `from_file` backend. +See the [Rights](#authorization-and-rights) section for details. + +Default: `/etc/radicale/rights` + +##### permit_delete_collection + +_(>= 3.1.9)_ + +Global permission to delete complete collections. +* If `False` it can be explicitly granted per collection by *rights* permissions: `D` +* If `True` it can be explicitly forbidden per collection by *rights* permissions: `d` + +Default: `True` + +##### permit_overwrite_collection + +_(>= 3.3.0)_ + +Global permission to overwrite complete collections. +* If `False` it can be explicitly granted per collection by *rights* permissions: `O` +* If `True` it can be explicitly forbidden per collection by *rights* permissions: `o` + +Default: `True` + +#### [storage] + +##### type + +Backend used to store data. + +Available backends are: + +* `multifilesystem` + Stores the data in the filesystem. + +* `multifilesystem_nolock` + The `multifilesystem` backend without file-based locking. + Must only be used with a single process. + +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` + +##### strict_preconditions + +_(>= 3.5.8)_ + +Strict preconditions check on PUT in case item already exists [RFC6352#9.2](https://www.rfc-editor.org/rfc/rfc6352#section-9.2) + +Default: `False` + +##### hook + +Command that is run after changes to storage. See the +[Versioning collections with Git](#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: +```json +{ + "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) + +#### [web] + +##### type + +The backend that provides the web interface of Radicale. + +Available backends are: + +* `none` + Simply shows the message "Radicale works!". + +* `internal` + Allows creation and management of address books and calendars. + +Default: `internal` + +#### [logging] + +##### level + +Set the logging level. + +Available levels are: +* `trace` _(>= 3.7.1)_ +* `debug` +* `info` +* `notice` _(>= 3.7.1)_ +* `warning` +* `error` +* `critical` +* `alert` _(>= 3.7.1)_ + +Default: `warning` _(< 3.2.0)_ / `info` _(>= 3.2.0)_ + +##### limit_content + +_(>= 3.7.0)_ + +Limit content of wrapped text (chars) + +Default: `3000` + +##### trace_on_debug + +_(> 3.5.4)_ && _(< 3.7.1)_ + +Do not filter debug messages starting with 'TRACE' + +Default: `False` + +##### trace_filter + +_(> 3.5.4)_ && _(< 3.7.1)_ + +Filter debug messages starting with 'TRACE/' + +Prerequisite: `trace_on_debug = True` + +_(>= 3.7.1)_ + +Filter trace messages starting with '' + +Prerequisite: `level = trace` + +Default: (empty) + +##### mask_passwords + +Do not include passwords in logs. + +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 header on `level = debug` + +Default: `False` + +##### request_content_on_debug + +_(>= 3.2.2)_ + +Log request content (body) on `level = debug` + +Default: `False` + +##### response_header_on_debug + +_(>= 3.5.10)_ + +Log response header on `level = debug` + +Default: `False` + +##### response_content_on_debug + +_(>= 3.2.2)_ + +Log response content (body) on `level = debug` + +Default: `False` + +##### rights_rule_doesnt_match_on_debug + +_(>= 3.2.3)_ + +Log rights rule which doesn't match on `level = debug` + +Default: `False` + +##### storage_cache_actions_on_debug + +_(>= 3.3.2)_ + +Log storage cache actions on `level = debug` + +Default: `False` + +##### profiling_per_request + +_(>= 3.5.10)_ + +Log profiling data on level=info + +Default: `none` + +One of +* `none` (disabled) +* `per_request` (above minimum duration) +* `per_request_method` (regular interval) + +##### profiling_per_request_min_duration + +_(>= 3.5.10)_ + +Log profiling data per request minimum duration (seconds) before logging, otherwise skip + +Default: `3` + +##### profiling_per_request_header + +_(>= 3.5.10)_ + +Log profiling request header (if passing minimum duration) + +Default: `False` + +##### profiling_per_request_xml + +_(>= 3.5.10)_ + +Log profiling request XML (if passing minimum duration) + +Default: `False` + +##### profiling_per_request_method_interval + +_(>= 3.5.10)_ + +Log profiling data per method interval (seconds) +Triggered by request, not active on idle systems + +Default: `600` + +##### profiling_top_x_functions + +_(>= 3.5.10)_ + +Log profiling top X functions (limit) + +Default: `10` + +#### [headers] + +This section can be used to specify additional HTTP headers that will be sent to clients. + +An example to relax the same-origin policy: + +```ini +Access-Control-Allow-Origin = * +``` + +An example to set CSP to disallow execution of unknown javascript: + +```ini +Content-Security-Policy = default-src 'self'; object-src 'none' +``` + + +#### [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: +* `none` +* `tls` +* `starttls` + +Default: `none` + +##### smtp_ssl_verify_mode + +_(>= 3.5.5)_ + +The certificate verification mode for tls and starttls. + +One of: +* `NONE` +* `OPTIONAL` +* `REQUIRED` + +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. +``` + +#### [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 +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 + +#### [sharing] + +_(>= 3.7.0)_ + +See also [Collection Sharing](https://github.com/Kozea/Radicale/blob/master/SHARING.md). + +##### type + +_(>= 3.7.0)_ + +Sharing database type + +One of: + * `none` + * `csv` + * `files` + +Default: `none` (implicit disabling the feature) + +##### database_path + +_(>= 3.7.0)_ + +Sharing database path + +Default: + * type `csv`: `(filesystem_folder)/collection-db/sharing.csv` + * type `files`: `(filesystem_folder)/collection-db/files` + +##### collection_by_token + +_(>= 3.7.0)_ + +Share collection by token + +Default: `false` + +##### collection_by_map + +_(>= 3.7.0)_ + +Share collection by map + +Default: `false` + +##### permit_create_token + +_(>= 3.7.0)_ + +Permit create of token-based sharing + +Default: `false` + +* If `False` it can be explicitly granted by *rights* permissions: `T` +* If `True` it can be explicitly forbidden by *rights* permissions: `t` + +##### permit_create_map + +_(>= 3.7.0)_ + +Permit create of map-based sharing + +Default: `false` + +* If `False` it can be explicitly granted by *rights* permissions: `M` +* If `True` it can be explicitly forbidden by *rights* permissions: `m` + +##### permit_properties_overlay + +_(>= 3.7.0)_ + +Permit (limited) properties overlay by user of shared collection + +Default: `false` + +* If `False` it can be explicitly granted by *share* permissions: `P` +* If `True` it can be explicitly forbidden by *share* permissions: `p` + +##### enforce_properties_overlay + +_(>= 3.7.0)_ + +Enforce properties overlay even on write access + +Default: `true` + +* If `False` it can be explicitly enforced by *share* permissions: `E` +* If `True` it can be explicitly forbidden by *share* permissions: `e` + +##### default_permissions_create_token + +Default permissions for create token-based sharing + +Default: `r` + +Supported: `rwEePp` + +##### default_permissions_create_map + +Default permissions for map-based sharing + +Default: `r` + +Supported: `rwEePp` diff --git a/md/v3/03_supported-clients.md b/md/v3/03_supported-clients.md new file mode 100644 index 000000000..ec02388a8 --- /dev/null +++ b/md/v3/03_supported-clients.md @@ -0,0 +1,541 @@ +## Supported Clients + +Radicale has been tested with: + +* [Android](https://android.com/) with + [DAVx⁵](https://www.davx5.com/) (formerly DAVdroid), +* [OneCalendar](https://www.onecalendar.nl/) +* [GNOME Calendar](https://wiki.gnome.org/Apps/Calendar), + [Contacts](https://wiki.gnome.org/Apps/Contacts) and + [Evolution](https://wiki.gnome.org/Apps/Evolution) +* [KDE PIM Applications](https://kontact.kde.org/), + [KDE Merkuro](https://apps.kde.org/de/merkuro/) +* [Mozilla Thunderbird](https://www.mozilla.org/thunderbird/) ([Thunderbird/Radicale](https://github.com/Kozea/Radicale/wiki/Client-Thunderbird)) with + [CardBook](https://addons.mozilla.org/thunderbird/addon/cardbook/) and + [Lightning](https://www.mozilla.org/projects/calendar/) +* [InfCloud](https://www.inf-it.com/open-source/clients/infcloud/) ([InfCloud/Radicale](https://github.com/Kozea/Radicale/wiki/Client-InfCloud)), + [CalDavZAP](https://www.inf-it.com/open-source/clients/caldavzap/), + [CardDavMATE](https://www.inf-it.com/open-source/clients/carddavmate/) and + [Open Calendar](https://github.com/algoo/open-calendar/) +* [pimsync](https://pimsync.whynothugo.nl/) ([pimsync/Radicale](https://github.com/Kozea/Radicale/wiki/Client-pimsync)) + +Many clients do not support the creation of new calendars and address books. +You can use Radicale's web interface +(e.g. ) to create and manage address books and calendars. + +In some clients, it is sufficient to simply enter the URL of the Radicale server +(e.g. `http://localhost:5232`) and your username. In others, you have to +enter the URL of the collection directly (e.g. `http://localhost:5232/user/calendar`). + +Some clients (notably macOS's Calendar.app) may silently refuse to include +account credentials over unsecured HTTP, leading to unexpected authentication +failures. In these cases, you want to make sure the Radicale server is +[accessible over HTTPS](#ssl). + +#### DAVx⁵ + +Enter the URL of the Radicale server (e.g. `http://localhost:5232`) and your +username. DAVx⁵ will show all existing calendars and address books and you +can create new ones. + +#### OneCalendar + +When adding account, select CalDAV account type, then enter username, password and the +Radicale server (e.g. `https://yourdomain:5232`). OneCalendar will show all +existing calendars and (FIXME: address books), you need to select which ones +you want to see. OneCalendar supports many other server types too. + +#### GNOME Calendar, Contacts + +GNOME 46 added CalDAV and CardDAV support to _GNOME Online Accounts_. + +Open GNOME Settings, navigate to _Online Accounts_ > _Connect an Account_ > _Calendar, Contacts and Files_. +Enter the URL (e.g. `https://example.com/radicale`) and your credentials then click _Sign In_. +In the pop-up dialog, turn off _Files_. After adding Radicale in _GNOME Online Accounts_, +it should be available in GNOME Contacts and GNOME Calendar. + +#### Evolution + +In **Evolution** add a new calendar and address book respectively with WebDAV. +Enter the URL of the Radicale server (e.g. `http://localhost:5232`) and your +username. Clicking on the search button will list the existing calendars and +address books. + +Adding CalDAV and CardDAV accounts in Evolution will automatically make them +available in GNOME Contacts and GNOME Calendar. + +#### KDE PIM Applications + +In **Kontact** add a _DAV Groupware resource_ to Akonadi under +_Settings > Configure Kontact > Calendar > General > Calendars_, +select the protocol (CalDAV or CardDAV), add the URL to the Radicale collections +and enter the credentials. After synchronization of the calendar resp. +addressbook items, you can manage them in Kontact. + +#### Thunderbird + +Add a new calendar on the network. Enter your username and the URL of the +Radicale server (e.g. `http://localhost:5232`). After asking for your password, +it will list the existing calendars. + +##### Address books with CardBook add-on + +Add a new address book on the network with CardDAV. Enter the URL of the +Radicale server (e.g. `http://localhost:5232`) and your username and password. +It will list your existing address books. + +#### InfCloud, CalDavZAP and CardDavMATE + +You can integrate InfCloud into Radicale's web interface with by simply +downloading the latest package from [InfCloud](https://www.inf-it.com/open-source/clients/infcloud/) +and extract the content into a folder named `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](https://github.com/Kozea/Radicale/wiki/Client-InfCloud). + +#### Command line + +This is not the recommended way of creating and managing your calendars and +address books. Use Radicale's web interface or a client with support for it +(e.g. **DAVx⁵**). + +To create a new calendar run something like: + +```bash +$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \ +' + + + + + + + + + + + + + Calendar + Example calendar + #ff0000ff + + +' +``` + +To create a new address book run something like: + +```bash +$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \ +' + + + + + + + + Address book + Example address book + + +' +``` + +The collection `/USERNAME` will be created automatically, when the user +authenticates to Radicale for the first time. Clients with automatic discovery +of collections will only show calendars and address books that are direct +children of the path `/USERNAME/`. + +Delete the collections by running something like: + +```bash +curl -u user -X DELETE 'http://localhost:5232/user/calendar' +``` + +Note: requires config/option `permit_delete_collection = True` + +### Authorization and Rights + +This section describes the format of the rights file for the `from_file` +authentication backend. The configuration option `file` in the `rights` +section must point to the rights file. + +The recommended rights method is `owner_only`. If access is granted +to calendars and address books outside the home directory of users +(that's `/USERNAME/`), clients will not detect these collections automatically, +and will not show them to the users. +This is only useful if you access calendars and address books directly via URL. + +An example rights file: + +```ini +# 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 collection. Permissions from the first +matching section are used. If no section matches, access gets denied. + +The username is empty for anonymous users. Therefore, the regex `.+` only +matches authenticated users and `.*` matches everyone (including anonymous +users). + +The path of the collection is separated by `/` and has no leading or trailing +`/`. Therefore, the path of the root collection is empty. + +In the `collection` regex you can use `{user}` and get groups from the `user` +regex with `{0}`, `{1}`, etc. + +In consequence of the parameter substitution you have to write `{{` and `}}` +if you want to use regular curly braces in the `user` and `collection` regexes. + +The following `permissions` are recognized: + +* **R:** read collections (excluding address books and calendars) +* **r:** read address book and calendar collections +* **i:** subset of **r** that only allows direct access via HTTP method GET + (CalDAV/CardDAV is susceptible to expensive search requests) +* **W:** write collections (excluding address books and calendars) +* **w:** write address book and calendar collections +* **D:** allow deleting a collection in case `permit_delete_collection=False` _(>= 3.3.0)_ +* **d:** deny deleting a collection in case `permit_delete_collection=True` _(>= 3.3.0)_ +* **O:** allow overwriting a collection in case `permit_overwrite_collection=False` _(>= 3.3.0)_ +* **o:** deny overwriting a collection in case `permit_overwrite_collection=True` _(>= 3.3.0)_ +* **T:** permit create of token-based sharing of collection in case `permit_create_token=False` _(>= 3.7.0)_ +* **t:** deny create of token-based sharing of collection in case `permit_create_token=True` _(>= 3.7.0)_ +* **M:** permit create of map-based sharing of collection in case `permit_create_map= False` _(>= 3.7.0)_ +* **m:** deny create of map-based sharing of collection in case `permit_create_map=True` _(>= 3.7.0)_ + +### Storage + +This document describes the layout and format of the file system storage, +the `multifilesystem` backend. + +It is safe to access and manipulate the data by hand or with scripts. +Scripts can be invoked manually, periodically (e.g. using +[cron](https://manpages.debian.org/unstable/cron/cron.8.en.html)) or after each +change to the storage with the configuration option `hook` in the `storage` +section (e.g. [Versioning collections with Git](#versioning-collections-with-git)). + +#### Layout + +The file system comprises the following files and folders: +* `.Radicale.lock`: The lock file for locking the storage. +* `collection-root`: This folder contains all collections and items. + +Each collection is represented by a folder. This folder may contain the file +`.Radicale.props` with all WebDAV properties of the collection encoded +as [JSON](https://en.wikipedia.org/wiki/JSON). + +Each item in a calendar or address book collection is represented by +a file containing the item's iCalendar resp. vCard data. + +All files and folders, whose names start with a dot but not with `.Radicale.` +(internal files) are ignored. + +Syntax errors in any of the files will cause all requests accessing +the faulty data to fail. The logging output should contain the names of the +culprits. + +Caches and sync-tokens are stored in the `.Radicale.cache` folder inside of +collections. +This folder may be created or modified, while the storage is locked for shared +access. +In theory, it should be safe to delete the folder. Caches will be recreated +automatically and clients will be told that their sync-token is not valid +anymore. + +You may encounter files or folders that start with `.Radicale.tmp-`. +Radicale uses them for atomic creation and deletion of files and folders. +They should be deleted after requests are finished but it is possible that +they are left behind when Radicale or the computer crashes. +You can safely delete them. + +#### Locking + +When the data is accessed by hand or by an externally invoked script, +the storage must be locked. The storage can be locked for exclusive or +shared access. It prevents Radicale from reading or writing the file system. +The storage is locked with exclusive access while the `hook` runs. + +##### Linux shell scripts + +Use the +[flock](https://manpages.debian.org/unstable/util-linux/flock.1.en.html) +utility to acquire exclusive or shared locks for the commands you want to run +on Radicale's data. + +```bash +# Exclusive lock for COMMAND +$ flock --exclusive /path/to/storage/.Radicale.lock COMMAND +# Shared lock for COMMAND +$ flock --shared /path/to/storage/.Radicale.lock COMMAND +``` + +##### Linux and MacOS + +Use the +[flock](https://manpages.debian.org/unstable/manpages-dev/flock.2.en.html) +syscall. Python provides it in the +[fcntl](https://docs.python.org/3/library/fcntl.html#fcntl.flock) module. + +##### Windows + +Use +[LockFile](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365202%28v=vs.85%29.aspx) +for exclusive access or +[LockFileEx](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365203%28v=vs.85%29.aspx) +which also supports shared access. Setting `nNumberOfBytesToLockLow` to `1` +and `nNumberOfBytesToLockHigh` to `0` works. + +#### Manually creating collections + +To create a new collection, you need to create the corresponding folder in the +file system storage (e.g. `collection-root/user/calendar`). +To indicate to Radicale and clients that the collection is a calendar, you have to +create the file ``.Radicale.props`` with the following content in the folder: + +```json +{"tag": "VCALENDAR"} +``` + +The calendar is now available at the URL path (e.g. ``/user/calendar``). +For address books ``.Radicale.props`` must contain: + +```json +{"tag": "VADDRESSBOOK"} +``` + +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 `/USERNAME/`. + +Delete collections by deleting the corresponding folders. + +### Logging overview + +Radicale logs to `stderr`. The verbosity of the log output can be controlled +with `--debug` command line argument or the `level` configuration option in +the [logging](#logging) section. + +### Architecture + +Radicale is a small piece of software, but understanding it is not as +easy as it seems. But don't worry, reading this short section is enough to +understand what a CalDAV/CardDAV server is, and how Radicale's code is +organized. + +#### Protocol overview + +Here is a simple overview of the global architecture for reaching a calendar or +an address book through network: + +| Part | Layer | Protocol or Format | +|----------|--------------------------|------------------------------------| +| Server | Calendar/Contact Storage | iCal/vCard | +| '' | Calendar/Contact Server | CalDAV/CardDAV Server | +| Transfer | Network | CalDAV/CardDAV (HTTP + TLS) | +| Client | Calendar/Contact Client | CalDAV/CardDAV Client | +| '' | GUI | Terminal, GTK, Web interface, etc. | + +Radicale is **only the server part** of this architecture. + +Please note: + +* CalDAV and CardDAV are extension protocols of WebDAV, +* WebDAV is an extension of the HTTP protocol. + +Radicale being a CalDAV/CardDAV server, can also be seen as a special WebDAV +and HTTP server. + +Radicale is **not the client part** of this architecture. It means that +Radicale never draws calendars, address books, events and contacts on the +screen. It only stores them and give the possibility to share them online with +other people. + +If you want to see or edit your events and your contacts, you have to use +another software called a client, that can be a "normal" applications with +icons and buttons, a terminal or another web application. + +#### Code Architecture + +The ``radicale`` package offers the following modules. + +* `__init__` + : Contains the entry point for WSGI. + +* `__main__` + : Provides the entry point for the ``radicale`` executable and + includes the command line parser. It loads configuration files from + the default (or specified) paths and starts the internal server. + +* `app` + : This is the core part of Radicale, with the code for the CalDAV/CardDAV + server. The code managing the different HTTP requests according to the + CalDAV/CardDAV specification can be found here. + +* `auth` + : Used for authenticating users based on username and password, mapping + usernames to internal users and optionally retrieving credentials from + the environment. + +* `config` + : Contains the code for managing configuration and loading settings from files. + +* `ìtem` + : Internal representation of address book and calendar entries. Based on + [VObject](https://github.com/py-vobject/vobject/). + +* `log` + : The logger for Radicale based on the default Python logging module. + +* `rights` + : This module is used by Radicale to manage access rights to collections, + address books and calendars. + +* `server` +: The integrated HTTP server for standalone use. + +* `storage` + : This module contains the classes representing collections in Radicale and + the code for storing and loading them in the filesystem. + +* `web` + : This module contains the web interface. + +* `utils` + : Contains general helper functions. + +* `httputils` + : Contains helper functions for working with HTTP. + +* `pathutils` + : Helper functions for working with paths and the filesystem. + +* `xmlutils` + : Helper functions for working with the XML part of CalDAV/CardDAV requests + and responses. It's based on the ElementTree XML API. + +### Plugins + +Radicale can be extended by plugins for authentication, rights management and +storage. Plugins are **python** modules. + +#### Getting started with plugin development + +To get started we walk through the creation of a simple authentication +plugin, that accepts login attempts with a static password. + +The easiest way to develop and install **python** modules is +[Distutils](https://docs.python.org/3/distutils/setupscript.html). +For a minimal setup create the file `setup.py` with the following content +in an empty folder: + +```python +#!/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: + +```python +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`: + +```bash +python3 -m pip install . +``` + +To make use this great creation in Radicale, set the configuration option +`type` in the `auth` section to `radicale_static_password_auth`: + +```ini +[auth] +type = radicale_static_password_auth +password = secret +``` + +You can uninstall the module with: + +```bash +python3 -m pip uninstall radicale_static_password_auth +``` + +#### Authentication plugins + +This plugin type is used to check login credentials. +The module must contain a class `Auth` that extends +`radicale.auth.BaseAuth`. Take a look at the file `radicale/auth/__init__.py` +in Radicale's source code for more information. + +#### Rights management plugins + +This plugin type is used to check if a user has access to a path. +The module must contain a class `Rights` that extends +`radicale.rights.BaseRights`. Take a look at the file +`radicale/rights/__init__.py` in Radicale's source code for more information. + +#### Web plugins + +This plugin type is used to provide the web interface for Radicale. +The module must contain a class `Web` that extends +`radicale.web.BaseWeb`. Take a look at the file `radicale/web/__init__.py` in +Radicale's source code for more information. + +#### Storage plugins + +This plugin is used to store collections and items. +The module must contain a class `Storage` that extends +`radicale.storage.BaseStorage`. Take a look at the file +`radicale/storage/__init__.py` in Radicale's source code for more information. diff --git a/md/v3/04_contribute.md b/md/v3/04_contribute.md new file mode 100644 index 000000000..3b0ff857c --- /dev/null +++ b/md/v3/04_contribute.md @@ -0,0 +1,17 @@ +## Contribute + +#### Report Bugs + +Found a bug? Want a new feature? Report a new issue on the +[Radicale bug-tracker](https://github.com/Kozea/Radicale/issues). + +#### Hack + +Interested in hacking? Feel free to clone the +[git repository on GitHub](https://github.com/Kozea/Radicale) if you want to +add new features, fix bugs or update the documentation. + +#### Documentation + +To change or complement the documentation create a pull request to +[DOCUMENTATION.md](https://github.com/Kozea/Radicale/blob/master/DOCUMENTATION.md). diff --git a/md/v3/05_download.md b/md/v3/05_download.md new file mode 100644 index 000000000..30f210a8d --- /dev/null +++ b/md/v3/05_download.md @@ -0,0 +1,131 @@ +## Download + +#### PyPI + +Radicale is [available on PyPI](https://pypi.python.org/pypi/Radicale/). To +install, just type as superuser: + +```bash +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](https://github.com/Kozea/Radicale/), or install it +directly with: + +```bash +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](https://github.com/Kozea/Radicale/tarball/master). + +#### Source Packages + +You can find the source packages of all releases on +[GitHub](https://github.com/Kozea/Radicale/releases). + +#### Docker + +Radicale is available as a Docker image for platforms `linux/amd64` and `linux/arm64` on: + +* [Docker Hub](https://hub.docker.com/r/kozea/radicale), and +* [GitHub's Container Registry](https://github.com/Kozea/Radicale/pkgs/container/radicale) + +Here are the steps to install Radicale via Docker Compose: + +1. Create required directories + + Create a directory to store the data, configuration and compose file. + + For example, assuming `./radicale`: + + ```bash + $ mkdir radicale + $ cd radicale + ``` + Create directories to store data and configuration. + + For example, assuming data directory as `./data` and configuration directory as `./config`: + + ```bash + $ mkdir config data + ``` + +2. Download the compose file + + ```bash + $ wget https://raw.githubusercontent.com/Kozea/Radicale/refs/heads/master/compose.yaml + ``` + + The compose file assumes `./config` and `./data` directories. Review the file and modify as needed. + +3. Create Radicale configuration file as necessary + + Create a new configuration file or place an existing one in the `./config` directory. + + + **Note**: This section demonstrates only basic steps to setup Radicale using `docker compose`. For details on configuring Radicale, including authentication, please refer to the documentation for [Basic Configuration](#basic-configuration) or detailed [Configuration](#configuration) + + +4. Start Radicale + + ```bash + $ docker compose up -d + ``` + + This will start the Radicale container in detached mode. + + + To view the logs of the running container, run: + + ```bash + $ docker compose logs -f + ``` + + To stop the container, run this from the current directory: + + ```bash + $ docker compose down + ``` + +##### Available tags + +* `stable`: Points to the latest stable release. This is recommended for most users. +* Major.Minor.Patch (e.g. `3.6.1`): Points to a specific release version. +* Major.Minor (e.g. `3.6`): Tracks the latest release for a minor version. +* Major (e.g. `3`): Tracks the latest release for a major version. +* nightly tags (e.g. `nightly-20260206`): Nightly builds. +* `latest`: Points to the most recent build. In most cases, this is nightly. + +#### Linux Distribution Packages + +Radicale has been packaged for: + +* [ArchLinux](https://www.archlinux.org/packages/community/any/radicale/) by + David Runge +* [Debian](https://packages.debian.org/radicale) by Jonas Smedegaard +* [Gentoo](https://packages.gentoo.org/packages/www-apps/radicale) + by René Neumann, Maxim Koltsov and Manuel Rüger +* [Fedora/EnterpriseLinux](https://src.fedoraproject.org/rpms/radicale) by Jorti + and Peter Bieringer +* [Mageia](http://madb.mageia.org/package/show/application/0/name/radicale) + by Jani Välimaa +* [OpenBSD](http://openports.se/productivity/radicale) by Sergey Bronnikov, + Stuart Henderson and Ian Darwin +* [openSUSE](http://software.opensuse.org/package/Radicale?search_term=radicale) + by Ákos Szőts and Rueckert +* [PyPM](http://code.activestate.com/pypm/radicale/) +* [Slackware](http://schoepfer.info/slackware.xhtml#packages-network) by + Johannes Schöpfer +* [Trisquel](http://packages.trisquel.info/search?searchon=names&keywords=radicale) +* [Ubuntu](http://packages.ubuntu.com/radicale) by the MOTU and Jonas + Smedegaard + +Radicale is also +[available on Cloudron](https://cloudron.io/button.html?app=org.radicale.cloudronapp2). + +If you are interested in creating packages for other Linux distributions, read +the ["Contribute" section](#contribute). diff --git a/md/v3/06_about.md b/md/v3/06_about.md new file mode 100644 index 000000000..3ebd53e3d --- /dev/null +++ b/md/v3/06_about.md @@ -0,0 +1,97 @@ +## About + +#### Main Goals + +Radicale is a complete calendar and contact storing and manipulating +solution. It can store multiple calendars and multiple address books. + +Calendar and contact manipulation is available from both local and distant +accesses, possibly limited through authentication policies. + +It aims to be a lightweight solution, easy to use, easy to install, easy to +configure. As a consequence, it requires few software dependencies and is +preconfigured to work out-of-the-box. + +Radicale is written in Python. It runs on most of the UNIX-like platforms +(Linux, \*BSD, macOS) and Windows. It is free and open-source software. + +#### What Radicale Will Never Be + +Radicale is a server, not a client. No interfaces will be created to work with +the server. + +CalDAV and CardDAV are not perfect protocols. We think that their main problem +is their complexity, that is why we decided not to implement the whole standard +but just enough to understand some of its client-side implementations. + +CalDAV and CardDAV are the best open standards available, and they are quite +widely used by both clients and servers. We decided to use it, and we will not +use another one. + +#### Technical Choices + +Important global development choices have been decided before writing +code. They are very useful to understand why the Radicale Project is different +from other CalDAV and CardDAV servers, and why features are included or not in +the code. + +##### Oriented to Calendar and Contact User Agents + +Calendar and contact servers work with calendar and contact clients, using a +defined protocol. CalDAV and CardDAV are good protocols, covering lots of +features and use cases, but it is quite hard to implement fully. + +Some calendar servers have been created to follow the CalDAV and CardDAV RFCs +as much as possible: [Davical](http://www.davical.org/), +[Baïkal](http://sabre.io/baikal/) and +[Darwin Calendar Server](http://trac.calendarserver.org/), for example, are +much more respectful of CalDAV and CardDAV and can be used with many clients. +They are very good choices if you want to develop and test new CalDAV clients, +or if you have a possibly heterogeneous list of user agents. + +Even if it tries it best to follow the RFCs, Radicale does not and **will not** +blindly implement the CalDAV and CardDAV standards. It is mainly designed to +support the CalDAV and CardDAV implementations of different clients. + +##### Simple + +Radicale is designed to be simple to install, simple to configure, simple to +use. + +The installation is very easy, particularly with Linux: one dependency, no +superuser rights needed, no configuration required, no database. Installing and +launching the main script out-of-the-box, as a normal user, are often the only +steps to have a simple remote calendar and contact access. + +Contrary to other servers that are often complicated, require high privileges +or need a strong configuration, the Radicale Server can (sometimes, if not +often) be launched in a couple of minutes, if you follow the +[tutorial](#simple-5-minute-setup). + +##### Lazy + +The CalDAV RFC defines what must be done, what can be done and what cannot be +done. Many violations of the protocol are totally defined and behaviors are +given in such cases. + +Radicale often assumes that the clients are perfect and that protocol +violations do not exist. That is why most of the errors in client requests have +undetermined consequences for the lazy server that can reply good answers, bad +answers, or even no answer. + +#### History + +Radicale has been started as a (free topic) stupid school project replacing +another (assigned topic) even more stupid school project. + +At the beginning, it was just a proof-of-concept. The main goal was to write a +small, dirty and simple CalDAV server working with Lightning, using no external +libraries. That's how we created a piece of code that's (quite) easy to +understand, to use and to hack. + +The [first lines](https://github.com/Kozea/Radicale/commit/b1591aea) have been +added to the SVN (!) repository as I was drinking (many) beers at the very end +of 2008 (Python 2.6 and 3.0 were just released). It's now packaged for a +growing number of Linux distributions. + +And that was fun going from here to there thanks to you! diff --git a/md/v3/translations/DOCUMENTATION.te.md b/md/v3/translations/DOCUMENTATION.te.md new file mode 100644 index 000000000..2187594ec --- /dev/null +++ b/md/v3/translations/DOCUMENTATION.te.md @@ -0,0 +1,288 @@ +> Last updated: 2025-10-20 by [@gowtham1412-p](https://github.com/gowtham1412-p) + +> Based on commit: [4fdc78760914040d5f74ece8978013b8836a712e] of [DOCUMENTATION.md](https://github.com/Kozea/Radicale/blob/master/DOCUMENTATION.md) + +\# డాక్యుమెంటేషన్ + + + +\## ప్రారంభించడం + + + +\#### రాడికేల్ గురించి + + + +రాడికేల్ అనేది ఒక చిన్న కానీ శక్తివంతమైన CalDAV (క్యాలెండర్లు, చేయవలసిన జాబితాలు) మరియు CardDAV + +(పరిచయాలు) సర్వర్, ఇది: + + + +\* CalDAV, CardDAV మరియు HTTP ద్వారా క్యాలెండర్లు మరియు పరిచయ జాబితాలను పంచుకుంటుంది. + +\* ఈవెంట్‌లు, టోడోలు, జర్నల్ ఎంట్రీలు మరియు వ్యాపార కార్డులకు మద్దతు ఇస్తుంది. + +\* బాక్స్ వెలుపల పనిచేస్తుంది, సంక్లిష్టమైన సెటప్ లేదా కాన్ఫిగరేషన్ అవసరం లేదు. + +\* సౌకర్యవంతమైన ప్రామాణీకరణ ఎంపికలను అందిస్తుంది. + +\* అధికారం ద్వారా యాక్సెస్‌ను పరిమితం చేయవచ్చు. + +\* TLSతో కనెక్షన్‌లను సురక్షితం చేయవచ్చు. + +\* చాలా మందితో పనిచేస్తుంది + +\[CalDAV మరియు CardDAV క్లయింట్లు](#సపోర్టెడ్-క్లయింట్లు). + +\* ఫైల్ సిస్టమ్‌లోని అన్ని డేటాను సాధారణ ఫోల్డర్ నిర్మాణంలో నిల్వ చేస్తుంది. + +\* ప్లగిన్‌లతో పొడిగించవచ్చు. + +\* GPLv3-లైసెన్స్ పొందిన ఉచిత సాఫ్ట్‌వేర్. + + + +\#### ఇన్‌స్టాలేషన్ + + + +తనిఖీ చేయండి + + + +\* \[ట్యుటోరియల్స్](#ట్యుటోరియల్స్) + +\* \[డాక్యుమెంటేషన్](#డాక్యుమెంటేషన్-1) + +\* \[GitHubలో వికీ](https://github.com/Kozea/Radicale/wiki) + +\* \[GitHubలో చర్చలు](https://github.com/Kozea/Radicale/discussions) + +\* \[GitHubలో తెరిచి ఉన్న మరియు ఇప్పటికే మూసివేయబడిన సమస్యలు](https://github.com/Kozea/Radicale/issues?q=is%3Aissue) + + + +\#### కొత్తగా ఏముంది? + + + +\[GitHubలో చేంజ్‌లాగ్](https://github.com/Kozea/Radicale/blob/master/CHANGELOG.md) చదవండి. + + + +\## ట్యుటోరియల్స్ + + + +\### 5 నిమిషాల సులభమైన సెటప్ + + + +మీరు Radicaleని ప్రయత్నించాలనుకుంటున్నారా కానీ మీ క్యాలెండర్‌లో 5 నిమిషాలు మాత్రమే ఖాళీగా ఉందా? + + + +ఇప్పుడే వెళ్లి Radicaleతో కొంచెం ఆడుదాం! + + + +ఈ విభాగం నుండి సెట్టింగ్‌లతో కాన్ఫిగర్ చేయబడిన సర్వర్, localhost + +కి మాత్రమే బైండ్ అవుతుంది (అంటే ఇది నెట్‌వర్క్ ద్వారా చేరుకోలేరు), మరియు మీరు ఏదైనా వినియోగదారు పేరు మరియు పాస్‌వర్డ్‌తో లాగిన్ అవ్వవచ్చు. + + + +ప్రతిదీ పనిచేసినప్పుడు, మీరు స్థానిక \[client](#supported-clients) + +ని పొందవచ్చు మరియు క్యాలెండర్‌లు మరియు చిరునామా పుస్తకాలను సృష్టించడం ప్రారంభించవచ్చు. + + + +Radicale మీ అవసరాలకు సరిపోతుంటే, రిమోట్ క్లయింట్‌లు మరియు కావలసిన ప్రామాణీకరణ రకానికి మద్దతు ఇవ్వడానికి కొంత \[ప్రాథమిక కాన్ఫిగరేషన్](#basic-configuration) + +కి సమయం కావచ్చు. + + + +మీ ఆపరేటింగ్ సిస్టమ్‌ను బట్టి దిగువన ఉన్న అధ్యాయాలలో ఒకదాన్ని అనుసరించండి. + + + +\#### Linux / \\\*BSD + + + +సూచన: PyPI నుండి డౌన్‌లోడ్ చేయడానికి బదులుగా, మీ \[distribution](#linux-distribution-packages) అందించిన ప్యాకేజీల కోసం చూడండి. + + + +అవి మీ పంపిణీలలో ఇంటిగ్రేట్ చేయబడిన స్టార్టప్ స్క్రిప్ట్‌లను కూడా కలిగి ఉంటాయి, ఇవి Radicaleని డెమోనైజ్ చేయడానికి అనుమతిస్తాయి. + + + +ముందుగా, \*\*python\*\* 3.9 లేదా తరువాత మరియు \*\*pip\*\* ఇన్‌స్టాల్ చేయబడిందని నిర్ధారించుకోండి. చాలా డిస్ట్రిబ్యూషన్లలో ``python3-pip`` ప్యాకేజీని ఇన్‌స్టాల్ చేయడానికి సరిపోతుంది. + + + +\##### సాధారణ వినియోగదారుగా + + + +పరీక్ష కోసం మాత్రమే సిఫార్సు చేయబడింది - కన్సోల్‌ను తెరిచి ఇలా టైప్ చేయండి: + + + +```bash + +\# ప్రస్తుత వినియోగదారు కోసం మాత్రమే ఇన్‌స్టాల్ చేయడానికి కింది ఆదేశాన్ని అమలు చేయండి + +python3 -m pip install --user --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +``` + + + +\_install\_ పని చేయకపోతే మరియు బదులుగా `error: externally-managed-environment` ప్రదర్శించబడితే, + +ముందుగానే వర్చువల్ వాతావరణాన్ని సృష్టించండి మరియు సక్రియం చేయండి. + + + +```bash + +python3 -m venv ~/venv + +source ~/venv/bin/activate + +``` + + + +మరియు దీనితో ఇన్‌స్టాల్ చేయడానికి ప్రయత్నించండి + + + +```bash + +python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +``` + + + +సేవను మాన్యువల్‌గా ప్రారంభించండి, డేటా ప్రస్తుత వినియోగదారు కోసం మాత్రమే నిల్వ చేయబడుతుంది + + + +```bash + +\# ప్రారంభించు, డేటా ప్రస్తుత వినియోగదారు కోసం మాత్రమే నిల్వ చేయబడుతుంది + +python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections --auth-type none + +``` + + + +\#### సిస్టమ్ వినియోగదారుగా (లేదా రూట్‌గా) + + + +ప్రత్యామ్నాయంగా, మీరు సిస్టమ్ వినియోగదారుగా లేదా రూట్‌గా ఇన్‌స్టాల్ చేసి అమలు చేయవచ్చు (సిఫార్సు చేయబడలేదు): + + + +```bash + +\# కింది ఆదేశాన్ని రూట్ (సిఫార్సు చేయబడలేదు) లేదా రూట్ కాని వ్యవస్థ వినియోగదారుగా అమలు చేయండి + +\# (డిపెండెన్సీలు లేనప్పుడు తరువాతి వాటికి --user అవసరం కావచ్చు సిస్టమ్-వైడ్ మరియు/లేదా వర్చువల్ ఎన్విరాన్మెంట్ అందుబాటులో ఉంది) + +python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +``` + + + +`/var/lib/radicale/collections` కింద సిస్టమ్ ఫోల్డర్‌లో నిల్వ చేయబడిన డేటాతో సేవను మాన్యువల్‌గా ప్రారంభించండి: + + + +```bash + +\# Start, డేటా సిస్టమ్ ఫోల్డర్‌లో నిల్వ చేయబడుతుంది (/var/lib/radicale/collections కు వ్రాయడానికి అనుమతులు అవసరం) + +python3 -m radicale --storage-filesystem-folder=/var/lib/radicale/collections --auth-type none + +``` + + + +\#### Windows + + + +మొదటి దశ పైథాన్‌ను ఇన్‌స్టాల్ చేయడం. + +\[python.org](https://python.org) కు వెళ్లి పైథాన్ 3 యొక్క తాజా వెర్షన్‌ను డౌన్‌లోడ్ చేసుకోండి. + +తర్వాత ఇన్‌స్టాలర్‌ను అమలు చేయండి. + +ఇన్‌స్టాలర్ యొక్క మొదటి విండోలో, "PATH కు పైథాన్‌ను జోడించు" బాక్స్‌ను తనిఖీ చేసి, + +"ఇప్పుడే ఇన్‌స్టాల్ చేయి"పై క్లిక్ చేయండి. రెండు నిమిషాలు వేచి ఉండండి, పూర్తయింది! + + + +కమాండ్ ప్రాంప్ట్‌ను ప్రారంభించి ఇలా టైప్ చేయండి: + + + +```powershell + +python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz + +python -m radicale --storage-filesystem-folder=~/radicale/collections --auth-type none + +``` + + + +\##### Common + + + +విజయవంతం!!! మీ బ్రౌజర్‌లో తెరవండి! + +ఉదాహరణ ఎంపిక `--auth-type none` ద్వారా ప్రామాణీకరణ అవసరం లేనందున మీరు ఏదైనా వినియోగదారు పేరు మరియు పాస్‌వర్డ్‌తో లాగిన్ అవ్వవచ్చు. + +ఇది \*\*సురక్షితం\*\*, మరిన్ని వివరాల కోసం \[కాన్ఫిగరేషన్/ప్రామాణీకరణ](#auth) చూడండి. + + + +భద్రతా కారణాల దృష్ట్యా డిఫాల్ట్ కాన్ఫిగరేషన్ సర్వర్‌ను `localhost` (IPv4: `127.0.0.1`, IPv6: `::1`) కు బంధిస్తుందని గమనించండి. + + + +మరిన్ని వివరాల కోసం \[చిరునామాలు](#చిరునామాలు) మరియు \[కాన్ఫిగరేషన్/సర్వర్](#సర్వర్) చూడండి. + + + +\### ప్రాథమిక కాన్ఫిగరేషన్ + + + +ఇన్‌స్టాలేషన్ సూచనలను + +\[సరళమైన 5-నిమిషాల సెటప్](#సింపుల్-5-నిమిషాల-సెటప్) ట్యుటోరియల్‌లో చూడవచ్చు. + + + +రాడికేల్ `/etc/radicale/config` మరియు + +`~/.config/radicale/config` నుండి కాన్ఫిగరేషన్ ఫైల్‌లను లోడ్ చేయడానికి ప్రయత్నిస్తుంది. + +Cu + diff --git a/redirect.json b/redirect.json deleted file mode 100644 index 6a218c883..000000000 --- a/redirect.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "index": ":DEFAULT_BRANCH:", - "3.3": "v3", - "2.1": "v2", - "1.1": "v1" -} diff --git a/v1.html b/v1.html deleted file mode 100644 index 987bbfec1..000000000 --- a/v1.html +++ /dev/null @@ -1,2883 +0,0 @@ - - - - - - - - - - - - - - -Radicale v1 Documentation - - - - - -
-
-

-Radicale - -v1 - - -

-

Free and Open-Source CalDAV and CardDAV Server

-
-
- -
-
-
- - -
-
-

A Simple Calendar and Contact Server

-
-

Presentation

-

The Radicale Project is a complete CalDAV (calendar) and CardDAV -(contact) server solution.

-

Calendars and address books are available for both local and remote -access, possibly limited through authentication policies. They can be -viewed and edited by calendar and contact clients on mobile phones or -computers.

-
-
-

Technical Description

-

Radicale aims to be a light solution, easy to use, easy to install, -easy to configure. As a consequence, it requires few software -dependencies and is pre-configured to work out-of-the-box.

-

Radicale runs on most of the UNIX-like platforms (Linux, *BSD, -MacOS X) and Windows. It is free and open-source software, written in -Python, released under GPL version 3.

-
-
-

Main Features

-
    -
  • Shares calendars through CalDAV, WebDAV and HTTP
    • -
  • Shares contacts through CardDAV, WebDAV and HTTP
    • -
  • Supports events, todos, journal entries and business cards
    • -
  • Works out-of-the-box, no installation nor configuration -required
    • -
  • Warns users on concurrent editing
    • -
  • Limits access by authentication
    • -
  • Secures connections
    • -
-
-
-

Supported Clients

-

Radicale supports the latest versions of many CalDAV and CardDAV -clients.

-
-
-
-

Documentation

-
-

User documentation

-

This document describes how to install and configure the server.

- -
-
-

Project description

-

This document defines the main goals of the Radicale Project, what it -covers and what it does not.

- -
-
-

Technical choices

-

This document describes the global technical choices of the Radicale -Project and the global architectures of its different parts.

- -
-
-

User Documentation

-
-

Installation

-
-
Dependencies
-

Radicale is written in pure Python and does not depend on any -library. It is known to work on Python 2.6, 2.7, 3.1, 3.2, 3.3, 3.4 and -PyPy > 1.9. The dependencies are optional, as they are only needed -for various authentication methods[1].

-

Linux and MacOS users certainly have Python already installed. For -Windows users, please install Python[2] thanks to the -adequate installer.

-
-
-
Radicale
-

Radicale can be freely downloaded on the project -website, download section. Just get the file and unzip it in a -folder of your choice.

-
-
-
CalDAV and CardDAV Clients
-

At this time Radicale has been tested and works fine with the latest -version of:

- -

More clients will be supported in the future. However, it may work -with any calendar or contact client which implements CalDAV or CardDAV -specifications too (luck is highly recommended).

-
-
-
-

Simple Usage

-
-
Starting the Server
-

To start Radicale CalDAV server, you have to launch the file called -radicale.py located in the root folder of the software -package.

-
-
-
Starting the Client
-
-
Lightning
-

After starting Lightning, click on File and -New Calendar. Upcoming window asks you about your calendar -storage. Chose a calendar On the Network, otherwise -Lightning will use its own file system storage instead of Radicale's one -and your calendar won't be remotely accessible.

-

Next window asks you to provide information about remote calendar -access. Protocol used by Radicale is CalDAV. A standard -location for a basic use of a Radicale calendar is -http://localhost:5232/user/calendar.ics/, where you can -replace user and calendar.ics by some strings -of your choice. Calendars are automatically created if needed. Please -note that the trailing slash is important.

-

You can now customize your calendar by giving it a nickname and a -color. This is only used by Lightning to identify calendars among -others.

-

If no warning sign appears next to the calendar name, you can now add -events and tasks to your calendar. All events and tasks are stored in -the server, they can be accessed and modified from multiple clients by -multiple users at the same time.

-

Lightning and Thunderbird cannot access CardDAV servers yet. Also, as -of version 17.0.5 the SOGo Connector addon is not fully functionally and -will create extra address book entries with every sync.

-
-
-
Evolution
-

Calendars

-

First of all, show the calendar page in Evolution by clicking on the -calendar icon at the bottom of the side pane. Then add a new calendar by -choosing in the menu File → New → Calendar.

-

A new window opens. The calendar type is -CalDAV, and the location is something like -http://localhost:5232/user/calendar.ics/, where you can -replace user and calendar by some strings of -your choice. Calendars are automatically created if needed. Please note -that the trailing slash is important.

-

You can fill other attributes like the color and the name, these are -only used for Evolution and are not uploaded.

-

Click on OK, and your calendar should be ready for -use.

-

Contacts

-

Switch to the contacts page and click -File → New → Adress book. In the new window choose -WebDAV as type and something like -http://localhost:5232/user/addressbook.vcf/ as location. -Remember to enter the correct username.

-
-
-
KOrganizer
-

Calendars

-

Tested with 4.8.3, you need one running on Akonadi for Cal/CarDav -support.

-

The procedure below can also be done trough the sidebar "Calendar -Manager". But to ensure it works for everyone this examples uses the -menu-bar.

-
    -
  1. Click Settings → Configure KOrganizer.
    2. -
  2. Click on General → Calendars.
    3. -
  3. Click on Add.
    4. -
  4. Choose DAV groupware resource (and click -OK).
    5. -
  5. Enter your username/passord (and click on Next).
    6. -
  6. Select Configure the resource manually (and click on -Finish).
    7. -
  7. Fill in a Display name.
    8. -
  8. Fill in your Username and Password.
    9. -
  9. Click Add.
    10. -
  10. Choose CalDav.
    11. -
  11. For remote URL enter -http://myserver:5232/Username/Calendar.ics/
    12. -
  12. Click Fetch.
    13. -
  13. Select desired calendar.
    14. -
  14. Hit OK.
    15. -
  15. Hit OK again.
    16. -
  16. Close the Configuration Window (Click OK).
    17. -
  17. Restart Korganizer for the calendar to appear in the "Calendar -Manager" sidebar (at least with version 4.8.3.)
    18. -
-
-

Note

-

After you created a calender in a collection you can also use -http://myserver:5232/Username/ as an URL This will then -list all available calendars.

-
-

Contacts

-

You can add a address book analogously to the above instructions, -just choose CardDav and -http://myserver:5232/Username/AddressBook.vcf/ in step 10 -and 11. Also, if you already have a calendar set up you can add an -address book to its "DAV groupware resource" under Configure-Kontact → -Calendar → General → Calendars → Modify. This way you don't have to -enter username and password twice.

-
-
-
CalendarSync
-

CalendarSync can be combined with any Android calendar app and can -even store the calendars in existing Android calendars which are synced -by other sync adapters. Of course it can also create its own -calendars.

-

So, to sync using CalendarSync you will have to:

-
    -
  • start the app,
    • -
  • press the Menu button,
    • -
  • select Create WebiCal,
    • -
  • choose to start with a guided configuration.
    • -
-

Then enter your URL, Username and Password. As URL please use -http(s)://server:port/username/.

-

If you can use HTTPS depends on your setup. Please replace -username with the name of your user account.

-

Press test connection button. If everything signaled as OK then press -search calendars button, select the calendars which you want to sync, -and press the configure calendar button at the top of the display. Your -calendars are now configured.

-

You can then start the first sync by going back to the main screen of -the app an pressing the Process Webicals button. Of course -you can also configure the app at its preferences to sync -automatically.

-
-
-
ContactSync
-

ContactSync is designed to sync contacts from and to various sources. -It can also overtake contacts and push them to the server, also if they -are only available on the device (local only contacts).

-

So to sync your contacts from the Radical server to your Android -device:

-
    -
  • start the app
    • -
  • press the Menu button,
    • -
  • select Create WebContact,
    • -
  • select guided configuration mode.
    • -
-

As URL please use http(s)://server:port/username/.

-

At the URL you will have to replace server:port and -username so that it matches your specific setup. It also -depends on your configuration if you can use HTTPS or if you have to use -HTTP.

-

Press test connection button, if everything signaled as OK then press -search address book button. Select the address books which you want to -sync and press the configure address book button at the top of the -display.

-

You can then start the first sync by going back to the main screen of -the app and pressing the Handle WebContacts button. Of -course you can also configure the app at its preferences to sync -automatically.

-
-
-
CalDAV-Sync
-

CalDAV-Sync is implemented as sync adapter to integrate seamlessly -with any calendar app and widget. Therefore you have to access it via -Accounts & Sync settings after installing it from the -Market.

-

So, to add new calendars to your phone open -Accounts & Sync settings and tap on -Add account, selecting CalDAV as type. In the next view, -you have to switch to Manual Mode. Enter the full CalDAV URL of your -Radicale account (e.g. http://example.com:5232/Username/) -and corresponding login data. If you want to create a new calendar you -have to specify its full URL e.g. -http://example.com:5232/Username/Calendar.ics/. Please note -that the trailing slash is important.

-

Tap on Next and the app checks for all available -calendars on your account, listing them in the next view. (Note: -CalDAV-Sync will not only check under the url you entered but also under -http://example.com:5232/UsernameYouEnteredForLogin/. This -might cause strange errors.) You can now select calendars you want to -sync and set a local nickname and color for each. Hitting -Next again brings up the last page. Enter your email -address and uncheck Sync from server to phone only if you -want to use two-way-sync.

-
-

Note

-

CalDAV-Sync officially is in alpha state and two-way-sync is marked -as an experimental feature. Though it works fine for me, using -two-way-sync is on your own risk!

-
-

Tap on Finish and you're done. You're now able to use -the new calendars in the same way you were using Google calendars -before.

-
-
-
CardDAV-Sync
-

Set up works like CalDAV-Sync, just use .vcf instead of .ics if you -enter the URL, e.g. -http://example.com:5232/Username/AddressBook.vcf/.

-
-
-
DAVdroid
-

DAVdroid is a free and -open-source CalDAV/CardDAV client that is available in Play Store for a -small fee or in FDroid for free.

-

To make it working with Radicale, just add a new DAVdroid account and -enter https://example.com/radicale/user/ as base URL -(assuming that your Radicale runs at -https://example.com/radicale/; don't forget to set -base_prefix correctly).

-
-
-
aCal
-

aCal is a CalDAV client for Android. It comes with its own calendar -application and does not integrate in the Android calendar. It is a -"CalDAV only" calendar, i.e. it only works in combination with a CalDAV -server. It can connect to several calendars on the server and will -display them all in one calendar. It works nice with Radicale.

-

To configure aCal, start aCal, go to the Settings -screen, select Server, then Add server. Choose -Manual Configuration and select Advanced -(bottom of the screen). Then enter the host name of your server, check -Active, enter your user name and password. The -Simple Domain of your server is the domain part of your -fully qualified host name (e.g. if your server is -myserver.mydomain.org, choose -mydomain.org).

-

As Simple Path you need to specify -/<user> where user is the user you use to connect to -Radicale. Server Name is the fully qualified name of your -server machine (myserver.mydomain.org). The -Server Path is /<user>/.

-

For Authentication Type you need to specify the method -you chose for Radicale. Check Use SSL if your Radicale is -configured to use SSL.

-

As the last thing you need to specify the port Radicale listens to. -When your server is configured you can go back to the first -Settings screen, and select -Calendars and Addressbooks. You should find all the -calendars that are available to your user on the Radicale server. You -can then configure each of them (display colour, notifications, -etc.).

-
-
-
InfCloud, CalDavZAP & CardDavMATE
-

Because settings are the same for InfCloud, -CalDavZAP and CardDavMATE
-only InfCloud is used in description below.

-

Radicale configuration

-

Add/Modify the following section in Radicale main configuration -file:

-
# Additional HTTP headers
-[headers]
-Access-Control-Allow-Origin = *
-Access-Control-Allow-Methods = GET, POST, OPTIONS, PROPFIND, PROPPATCH, REPORT, PUT, MOVE, DELETE, LOCK, UNLOCK
-Access-Control-Allow-Headers = Authorization, Content-type, Depth, Destination, If-match, If-None-Match, Lock-Token, Overwrite, Prefer, Timeout, User-Agent, X-Client, X-Requested-With
-Access-Control-Expose-Headers = Etag
-

InfCloud needs read access for everybody -(including anonymous users) on Radicale's root directory. If using -Radicales rights management add the following section to rights -file:

-
# Allow caldavzap, carddavmate and infcloud to work
-[infcloud]
-user: .*
-collection: /
-permission: r
-

Additional you need to change [owner-write] section to -use the same syntax for collection as shown in [public] -section.

-
# Give write access to owners
-[owner-write]
-user: .+
-# collection: ^%(login)s/.+$    # DOES NOT WORK
-collection: ^%(login)s(/.+)?$
-permission: rw
-

InfCloud configuration

-

Inside InfCloud configuration file -config.js you need to set -globalNetworkCheckSettings like following example:

-
// href: 
-// put in here your protocol, host and port where Radicale is listening
-// additionalResources:
-// put in here a comma separated list of collections you want additionally look at.
-// Don't forget '' around each collections name
-var globalNetworkCheckSettings={
-    href: 'https://host.example.com:5232/',
-    hrefLabel: null,
-    crossDomain: null,
-    additionalResources: ['public'],
-    forceReadOnly: null,
-    withCredentials: false,
-    showHeader: true,
-    settingsAccount: true,
-    syncInterval: 60000,
-    timeOut: 30000,
-    lockTimeOut: 10000,
-    delegation: false,
-    ignoreAlarms: false,
-    backgroundCalendars: []
-}
-
-

Note

-

InfCloud, CardDavMATE and -CalDavZAP cannot create calendars and/or address books. -They need to be created before first login. Each user -needs to have minimum of one calendar and/or one adressbook even if only -using shared addresses and/or calendars. Client will not login, if the -user collections don't exists.

-
-

You can easily create them by directly calling the URL's from your -browser:
-  http(s)://host.example.com:5232/user/calendar.ics/
-  http(s)://host.example.com:5232/user/addresses.vcf/

-

Replace "http(s)" with the correct protocol, "host.example.com:5232" -with you host:port where Radicale is running,
-"user" with the correct login name or the shared resource name i.e. -'public',
-"calendar.ics" and "addresses.vcf" with the collection names you want to -use
-and do NOT forget the '/' at line end.

-
-

Note

-

If using self-signed certificates you need to do the following steps -before using InfCloud, CardDavMATE or -CalDavZAP.
-With your browser call one of the above URLs.
-Your browser warn you that you are trying to access an -Insecure site.
-Download and accept the certificate offered by the Radicale -server.
-After installing and accepting it you should restart your browser.

-
-
-
-
iPhone & iPad
-

Calendars

-

For iOS devices, the setup is fairly straightforward but there are a -few settings that are critical for proper operation.

-
    -
  1. From the Home screen, open Settings
    2. -
  2. Select Mail, Contacts, Calendars
    3. -
  3. Select Add Account… → Other → -Add CalDAV Account
    4. -
  4. Enter the server URL here, including https, the port, -and the user/calendar path, ex: -https://myserver.domain.com:3000/bob/birthdays.ics/ (please -note that the trailing slash is important)
    5. -
  5. Enter your username and password as defined in your server -config
    6. -
  6. Enter a good description of the calendar in the -Description field. Otherwise it will put the whole -servername in the field.
    7. -
  7. Now go back to the Mail, Contacts, Calendars screen and -scroll down to the Calendars section. You must change the -Sync option to sync All events otherwise new -events won't show up on your iOS devices!
    8. -
-
-

Note

-

Everything should be working now so test creating events and make -sure they stay created. If you create events on your iOS device and they -disappear after the fetch period, you probably forgot to change the sync -setting in step 7. Likewise, if you create events on another device and -they don't appear on your iPad of iPhone, then make sure your sync -settings are correct

-
-
-

Warning

-

In iOS 5.x, please check twice that the Sync all entries -option is activated, otherwise some events may not be shown in your -calendar.

-
-

Contacts

-

In Contacts on iOS 6:

-
    -
  1. From the Home screen, open Settings
    2. -
  2. Select Mail, Contacts, Calendars
    3. -
  3. Select Add Account… → Other → -Add CardDAV Account
    4. -
  4. As Server use the Radicale server URL with port, for -example localhost:5232
    5. -
  5. Add any User name you like (if you didn't configure -authentication)
    6. -
  6. Add any Password you like (again, if you didn't -configure authentication)
    7. -
  7. Change the Description to something more readable -(optional)
    8. -
  8. Tap Next
    9. -
  9. An alert showing Cannot Connect Using SSL will pop up -as we haven't configured SSL yet, Continue for now
    10. -
  10. Back on the Mail, Contacts, Calendars screen you scroll -to the Contacts section, select the Radicale server as -Default Account when you want to save new contacts to the -Radicale server
    11. -
  11. Exit to the Home screen and open Contacts, tap -Groups, you should see the Radicale server
    12. -
-
-

Note

-

You'll need version 0.8.1 or up for this to work. Earlier versions -will forget your new settings after a reboot.

-
-
-
-
OS X
-
-

Note

-

This description assumes you do not have any authentication or -encryption configured. If you want to use iCal with authentication or -encryption, you just have to fill in the corresponding fields in your -calendar's configuration.

-
-

Calendars

-

In iCal 4.0 or iCal 5.0:

-
    -
  1. Open the Preferences dialog and select the -Accounts tab
    2. -
  2. Click the + button at the lower left to open the -account creation wizard
    3. -
  3. As Account type select CalDAV
    4. -
  4. Select any User name you like
    5. -
  5. The Password field can be left empty (we did not -configure authentication)
    6. -
  6. As Server address use domain:port, for -example localhost:5232 (this would be the case if you start -an unconfigured Radicale on your local machine)
    7. -
-

Click Create. The wizard will now tell you, that no -encryption is in place (Unsecured Connection). This is -expected and will change if you configure Radicale to use SSL. Click -Continue.

-
-

Warning

-

In iCal 5.x, please check twice that the -Sync all entries option is activated, otherwise some events -may not be shown in your calendar.

-
-

The wizard will close, leaving you in the Account tab -again. The account is now set-up. You can close the -Preferences window.

-
-

Important

-

To add a calendar to your shiny new account you have to go to the -menu and select -File → New Calendar → <your shiny new account>. A new -calendar appears in the left panel waiting for you to enter a name.

-

This is needed because the behaviour of the big + button -in the main window is confusing as you can't focus an empty account and -iCal will just add a calendar to another account.

-
-

Contacts

-

In Contacts 7 (previously known as AddressBook):

-
    -
  1. Open the Preferences dialog and select the -Accounts tab.
    2. -
  2. Click the + button at the lower left to open the -account creation wizard.
    3. -
  3. As Account type select CardDAV.
    4. -
  4. Add any User name you like.
    5. -
  5. The Password field can be left empty (if we didn't -configure authentication).
    6. -
  6. As Server address use domain:port, for -example localhost:5232 (this would be the case if you start -an unconfigured Radicale server on your local machine).
    7. -
  7. Click Create. Contacts will complain about an -Unsecured Connection if you don't have SSL enabled. Click -Create again.
    8. -
  8. You might want to change the Description of the newly -added account to something more readable. (optional)
    9. -
  9. Switch to the General tab in the preferences and select -the Radicale server as Default Account at the bottom of the -screen. It probably shows up as `domain:port or the name -you choose if you changed the description. Newly added contacts are -added to the default account and by default this will be the local -On My Mac account.
    10. -
-
-

Note

-

You'll need version 0.8.1 or up for this to work. Earlier versions -can read CardDAV contacts but can't add new contacts.

-
-
-
-
syncEvolution
-

You can find more information about syncEvolution and Radicale on the -syncEvolution -wiki page.

-
-
-
Nokia / Microsoft Windows Phones
-
    -
  1. Go to "Settings" > "email+accounts"
    2. -
  2. Click "add an account" > "iCloud"
    3. -
  3. Enter random email address (e.g. "foo@bar" and "qwerty") > "sign in"
    4. -
  4. A new account "iCloud" with the given email address appears on the -list. The status is "Not up to date". Click the account.
    5. -
  5. An error message is given. Click "close".
    6. -
  6. Enter new and "real" values to the account setting fields: -
      -
    • "Account name": This name appears on the calendar etc. Examples: -"Home", "Word", "Sauna reservation"
      • -
    • "Email address": Not used
      • -
    • "Sync contacts and calendar": Select the sync interval
      • -
    • "Content to sync": Uncheck "Contacts", check "Calendar"
      • -
    • "Your name": Not used
      • -
    • "Username": Username to your Radicale server
      • -
    • "Password": Password to your Radicale server
      • -
    • Click "advanced settings"
      • -
    • "Calendar server (CalDAV)": Enter the full path to the calendar .ics -file. Don't forget the trailing slash. Example: -https://my.server.fi:5232/myusername/calendarname.ics/
      • -
    7. -
-

Don't forget to add your CA to the phone if you're using a -self-signed certificate on your Radicale. Make the CA downloadable to -Internet Explorer. The correct certificate format is X509 (with .cer -file extension).

-
-
-
-
-

Complex Configuration

-
-

Note

-

This section is written for Linux users, but can be easily adapted -for Windows and MacOS users.

-
-
-
Installing the Server
-

You can install Radicale thanks to the following command, with -superuser rights:

-
python setup.py install
-

Then, launching the server can be easily done by typing as a normal -user:

-
radicale
-
-
-
Configuring the Server
-
-
Main Configuration File
-
-

Note

-

This section is following the latest stable version changes. Please -look at the default configuration file included in your package if you -have an older version of Radicale.

-
-

The server configuration can be modified in -/etc/radicale/config or in -~/.config/radicale/config. You can use the ---config parameter in the command line to choose a specific -path. You can also set the RADICALE_CONFIG environment -variable to a path of your choice. Here is the default configuration -file, with the main parameters:

-
[server]
-
-# CalDAV server hostnames separated by a comma
-# IPv4 syntax: address:port
-# IPv6 syntax: [address]:port
-# For example: 0.0.0.0:9999, [::]:9999
-# IPv6 adresses are configured to only allow IPv6 connections
-#hosts = 0.0.0.0:5232
-
-# Daemon flag
-#daemon = False
-
-# File storing the PID in daemon mode
-#pid =
-
-# SSL flag, enable HTTPS protocol
-#ssl = False
-
-# SSL certificate path
-#certificate = /etc/apache2/ssl/server.crt
-
-# SSL private key
-#key = /etc/apache2/ssl/server.key
-
-# SSL Protocol used. See python's ssl module for available values
-#protocol = PROTOCOL_SSLv23
-
-# Ciphers available. See python's ssl module for available ciphers
-#ciphers =
-
-# Reverse DNS to resolve client address in logs
-#dns_lookup = True
-
-# Root URL of Radicale (starting and ending with a slash)
-#base_prefix = /
-
-# Possibility to allow URLs cleaned by a HTTP server, without the base_prefix
-#can_skip_base_prefix = False
-
-# Message displayed in the client when a password is needed
-#realm = Radicale - Password Required
-
-
-[encoding]
-
-# Encoding for responding requests
-#request = utf-8
-
-# Encoding for storing local collections
-#stock = utf-8
-
-
-[well-known]
-
-# Path where /.well-known/caldav/ is redirected
-#caldav = '/%(user)s/caldav/'
-
-# Path where /.well-known/carddav/ is redirected
-#carddav = '/%(user)s/carddav/'
-
-
-[auth]
-
-# Authentication method
-# Value: None | htpasswd | IMAP | LDAP | PAM | courier | http | remote_user | custom
-#type = None
-
-# Custom authentication handler
-#custom_handler =
-
-# Htpasswd filename
-#htpasswd_filename = /etc/radicale/users
-
-# Htpasswd encryption method
-# Value: plain | sha1 | ssha | crypt | bcrypt | md5
-#htpasswd_encryption = crypt
-
-# LDAP server URL, with protocol and port
-#ldap_url = ldap://localhost:389/
-
-# LDAP base path
-#ldap_base = ou=users,dc=example,dc=com
-
-# LDAP login attribute
-#ldap_attribute = uid
-
-# LDAP filter string
-# placed as X in a query of the form (&(...)X)
-# example: (objectCategory=Person)(objectClass=User)(memberOf=cn=calenderusers,ou=users,dc=example,dc=org)
-# leave empty if no additional filter is needed
-#ldap_filter =
-
-# LDAP dn for initial login, used if LDAP server does not allow anonymous searches
-# Leave empty if searches are anonymous
-#ldap_binddn =
-
-# LDAP password for initial login, used with ldap_binddn
-#ldap_password =
-
-# LDAP scope of the search
-#ldap_scope = OneLevel
-
-# IMAP Configuration
-#imap_hostname = localhost
-#imap_port = 143
-#imap_ssl = False
-
-# PAM group user should be member of
-#pam_group_membership =
-
-# Path to the Courier Authdaemon socket
-#courier_socket =
-
-# HTTP authentication request URL endpoint
-#http_url =
-# POST parameter to use for username
-#http_user_parameter =
-# POST parameter to use for password
-#http_password_parameter =
-
-
-[git]
-
-# Git default options
-#committer = Radicale <radicale@example.com>
-
-
-[rights]
-
-# Rights backend
-# Value: None | authenticated | owner_only | owner_write | from_file | custom
-#type = None
-
-# Custom rights handler
-#custom_handler =
-
-# File for rights management from_file
-#file = ~/.config/radicale/rights
-
-
-[storage]
-
-# Storage backend
-# -------
-# WARNING: ONLY "filesystem" IS DOCUMENTED AND TESTED,
-#          OTHER BACKENDS ARE NOT READY FOR PRODUCTION.
-# -------
-# Value: filesystem | multifilesystem | database | custom
-#type = filesystem
-
-# Custom storage handler
-#custom_handler =
-
-# Folder for storing local collections, created if not present
-#filesystem_folder = ~/.config/radicale/collections
-
-# Database URL for SQLAlchemy
-# dialect+driver://user:password@host/dbname[?key=value..]
-# For example: sqlite:///var/db/radicale.db, postgresql://user:password@localhost/radicale
-# See http://docs.sqlalchemy.org/en/rel_0_8/core/engines.html#sqlalchemy.create_engine
-#database_url =
-
-
-[logging]
-
-# Logging configuration file
-# If no config is given, simple information is printed on the standard output
-# For more information about the syntax of the configuration file, see:
-# http://docs.python.org/library/logging.config.html
-#config = /etc/radicale/logging
-# Set the default logging level to debug
-#debug = False
-# Store all environment variables (including those set in the shell)
-#full_environment = False
-
-
-[headers]
-
-# Additional HTTP headers
-#Access-Control-Allow-Origin = *
-

This configuration file is read each time the server is launched. If -some values are not given, the default ones are used. If no -configuration file is available, all the default values are used.

-
-
-
Logging Configuration File
-

Radicale uses the default logging facility for Python. The default -configuration prints the information messages to the standard output. It -is possible to print debug messages thanks to:

-
radicale --debug
-

Radicale can also be configured to send the messages to the console, -logging files, syslog, etc. For more information about the syntax of the -configuration file, see: http://docs.python.org/library/logging.config.html. -Here is an example of logging configuration file:

-
# Loggers, handlers and formatters keys
-
-[loggers]
-# Loggers names, main configuration slots
-keys = root
-
-[handlers]
-# Logging handlers, defining logging output methods
-keys = console,file
-
-[formatters]
-# Logging formatters
-keys = simple,full
-
-
-# Loggers
-
-[logger_root]
-# Root logger
-level = DEBUG
-handlers = console,file
-
-
-# Handlers
-
-[handler_console]
-# Console handler
-class = StreamHandler
-level = INFO
-args = (sys.stdout,)
-formatter = simple
-
-[handler_file]
-# File handler
-class = FileHandler
-args = ('/var/log/radicale',)
-formatter = full
-
-
-# Formatters
-
-[formatter_simple]
-# Simple output format
-format = %(message)s
-
-[formatter_full]
-# Full output format
-format = %(asctime)s - %(levelname)s: %(message)s
-
-
-
Command Line Options
-

All the options of the server part can be changed with -command line options. These options are available by typing:

-
radicale --help
-
-
-
-
WSGI, CGI and FastCGI
-

Radicale comes with a WSGI support, -allowing the software to be used behind any HTTP server supporting WSGI -such as Apache.

-

Moreover, it is possible to use flup to wrap Radicale into -a CGI, FastCGI, SCGI or AJP application, and therefore use it with -Lighttpd, Nginx or even Tomcat.

-
-
Apache and mod_wsgi
-

To use Radicale with Apache's mod_wsgi, you first have -to install the Radicale module in your Python path and write your -.wsgi file (in /var/www for example):

-
import radicale
-radicale.log.start()
-application = radicale.Application()
-
-

Note

-

The hosts, daemon, pid, -ssl, certificate, key, -protocol and ciphers keys of the -[server] part of the configuration are ignored.

-
-

Next you have to create the Apache virtual host (adapt the -configuration to your environment):

-
<VirtualHost *:80>
-    ServerName cal.yourdomain.org
-
-    WSGIDaemonProcess radicale user=www-data group=www-data threads=1
-    WSGIScriptAlias / /var/www/radicale.wsgi
-
-    <Directory /var/www>
-        WSGIProcessGroup radicale
-        WSGIApplicationGroup %{GLOBAL}
-        AllowOverride None
-        Order allow,deny
-        allow from all
-    </Directory>
-</VirtualHost>
-
-

Warning

-

You should use the root of the (sub)domain -(WSGIScriptAlias /), else some CalDAV features may not -work.

-
-

If you want to use authentication with Apache, you really -should use one of the Apache authentication modules, instead of the ones -from Radicale: they're just better.

-

Deactivate any rights and module in Radicale and use your favourite -Apache authentication backend. You can then restrict the access: allow -the alice user to access /alice/* URLs, and -everything should work as expected.

-

Here is one example of Apache configuration file:

-
<VirtualHost *:80>
-    ServerName radicale.local
-
-    WSGIDaemonProcess radicale user=radicale group=radicale threads=1
-    WSGIScriptAlias / /usr/share/radicale/radicale.wsgi
-
-    <Directory /usr/share/radicale/>
-        WSGIProcessGroup radicale
-        WSGIApplicationGroup %{GLOBAL}
-
-        AuthType Basic
-        AuthName "Radicale Authentication"
-        AuthBasicProvider file
-        AuthUserFile /usr/share/radicale/radicale.passwd
-
-        AllowOverride None
-        Require valid-user
-
-        RewriteEngine On
-        RewriteCond %{REMOTE_USER}%{PATH_INFO} !^([^/]+/)\1
-        RewriteRule .* - [Forbidden]
-    </Directory>
-</VirtualHost>
-

If you're still convinced that access control is better with -Radicale, you have to add WSGIPassAuthorization On in your -Apache configuration files, as explained in the -mod_wsgi documentation.

-
-

Note

-

Read-only calendars or address books can also be served by a simple -Apache HTTP server, as Radicale stores full-text icalendar and vcard -files with the default configuration.

-
-
-
-
-
Authentication
-

Authentication is possible through:

-
    -
  • Courier-Authdaemon socket
    • -
  • htpasswd file, including list of plain user/password couples
    • -
  • HTTP, checking status code of a POST request
    • -
  • IMAP
    • -
  • LDAP
    • -
  • PAM
    • -
  • Remote user given by HTTP server
    • -
-

Check the [auth] section of your configuration file to -know the different options offered by these authentication modules.

-

Some authentication methods need additional modules, see Python Versions and OS -Support for further information.

-

You can also write and use a custom module handle authentication if -you use a different technology.

-

Please note that these modules have not been verified by security -experts. If you need a really secure way to handle authentication, you -should put Radicale behind a real HTTP server and use its authentication -and rights management methods.

-
-
-
Rights Management
-

You can set read and write rights for collections according to the -authenticated user and the owner of the collection.

-

The owner of a collection is determined by the URL of the -collection. For example, -http://my.server.com:5232/anna/calendar.ics/ is owned by -the user called anna.

-

The authenticated user is the login used for -authentication.

-

5 different configurations are available, you can choose the one you -want in your configuration file. You can also write and use a custom -module handle rights management if you need a specific pattern.

-
-
None
-

Everybody (including anonymous users) has read and write access to -all collections.

-
-
-
Authenticated
-

An authenticated users has read and write access to all collections, -anonymous users have no access to these collections.

-
-
-
Owner Only
-

Only owners have read and write access to their own collections. The -other users, authenticated or anonymous, have no access to these -collections.

-
-
-
Owner Write
-

Authenticated users have read access to all collections, but only -owners have write access to their own collections. Anonymous users have -no access to collections.

-
-
-
From File
-

Rights are based on a regex-based file whose name is specified in the -config (section "right", key "file").

-

Authentication login is matched against the "user" key, and -collection's path is matched against the "collection" key. You can use -Python's ConfigParser interpolation values %(login)s and %(path)s. You -can also get groups from the user regex in the collection with {0}, {1}, -etc.

-

For example, for the "user" key, ".+" means "authenticated user" and -".*" means "anybody" (including anonymous users).

-

Section names are only used for naming the rule.

-

Leading or ending slashes are trimmed from collection's path.

-

Example:

-
# The default path for this kind of files is ~/.config/radicale/rights
-# This can be changed in the configuration file
-#
-# This file gives independant examples to help users write their own
-# configuration files. Using these examples together in the same configuration
-# file is meaningless.
-#
-# The first rule matching both user and collection patterns will be returned.
-
-# This means all users starting with "admin" may read any collection
-[admin]
-user: ^admin.*$
-collection: .*
-permission: r
-
-# This means all users may read and write any collection starting with public.
-# We do so by just not testing against the user string.
-[public]
-user: .*
-collection: ^public(/.+)?$
-permission: rw
-
-# A little more complex: give read access to users from a domain for all
-# collections of all the users (ie. user@domain.tld can read domain/*).
-[domain-wide-access]
-user: ^.+@(.+)\..+$
-collection: ^{0}/.+$
-permission: r
-
-# Allow authenticated user to read all collections
-[allow-everyone-read]
-user: .+
-collection: .*
-permission: r
-
-# Give write access to owners
-[owner-write]
-user: .+
-collection: ^%(login)s/.*$
-permission: w
-
-
-
-
Git Support
-
-

Note

-

If the project doesn't comply with the requirements to use Git, -Radicale will still work. Your collections will run fine but without the -versionning system.

-
-

Git is now automatically supported on Radicale. It depends on dulwich.

-
-
Configure Radicale
-

Radicale automatically detects the .git folder in the path -you configured for the filesystem_folder variable in the -[storage] section of your configuration file. Make sure a -repository is created at this location or create one (using git init -. for instance) else it won't work.

-

To summarize :

-
    -
  • Configure your Git installation
    • -
  • Get Radicale and dulwich
    • -
  • Create the repository where your collections are stored
    • -
  • Run Radicale and it should work
    • -
-
-
-
How it works
-

Radicale will automatically commit any changes on your collections. -It will use your git config to find parameters such as the committer and -that's all.

-
-
-
Issues
-

A dulwich project ported on Python 3 exists but it seems that it -doesn't follow the current api (committer is mandatory and not retrieved -from the git config by default). Until this problem isn't fixed, the Git -support for Radicale on Python 3 will not be ensured.

-
-
-
-
-

Python Versions and OS Support

-
-
TLS Support
-

Python 2.6 suffered a -bug causing huge timeout problems with TLS. The bug is fixed since -Python 2.6.6.

-

IMAP authentication over TLS requires Python 3.2.

-

Python 2.7 and Python 3.x do not suffer this bug.

-
-
-
Crypt Support
-

With the htpasswd access, many encryption methods are available, and -crypt is the default one in Radicale. Unfortunately, the -crypt module is unavailable on Windows, you have to pick -another method on this OS.

-

Additional md5 and bcrypt methods are -available when the passlib module is installed.

-
-
-
IMAP Authentication
-

The IMAP authentication module relies on the imaplib module, -available with 2.x versions of Python. However, TLS is only available in -Python 3.2. Older versions of Python or a non-modern server who does not -support STARTTLS can only authenticate against localhost as -passwords are transmitted in PLAIN. Legacy SSL mode on port 993 is not -supported.

-
-
-
LDAP Authentication
-

The LDAP authentication module relies on the python-ldap module, and thus -only works with 2.x versions of Python.

-
-
-
PAM Authentication
-

The PAM authentication module relies on the python-pam -module.

-

Bear in mind that on Linux systems, if you're authenticating against -PAM files (i.e. /etc/shadow), the user running Radicale -must have the right permissions. For instance, you might want to add the -radicale user to the shadow group.

-
-
-
HTTP Authentication
-

The HTTP authentication module relies on the requests -module.

-
-
-
Daemon Mode
-

The daemon mode relies on forks, and thus only works on Unix-like -OSes (incuding Linux, OS X, BSD).

-
-
-
-
-

Project Description

-
-

Main Goals

-

The Radicale Project is a complete calendar and contact storing and -manipulating solution. It can store multiple calendars and multiple -address books.

-

Calendar and contact manipulation is available from both local and -distant accesses, possibly limited through authentication policies.

-
-
-

What Radicale Is

-
-
Calendar and Contact Server
-

The Radicale Project is mainly a calendar and contact server, giving -local and distant access for reading, creating, modifying and deleting -multiple calendars through simplified CalDAV and CardDAV protocols.

-

Data can be encrypted by SSL, and their access can be restricted -using different authentication methods.

-
-
-
-

What Radicale Is not and will not Be

-
-
Calendar or Contact User Agent
-

Radicale is a server, not a client. No interfaces will be created to -work with the server, as it is a really (really really) much more -difficult task[3].

-
-
-
Original Calendar or Contact Access Protocol
-

CalDAV and CardDAV are not perfect protocols. We think that their -main problem is their complexity[4], that is why we -decided not to implement the whole standard but just enough to -understand some of its client-side implementations [5].

-

CalDAV and CardDAV are the best open standards available and they are -quite widely used by both clients and servers[6]. We -decided to use it, and we will not use another one.

-
-
-
-
-

Technical Choices

-
-

Global Technical Choices

-
-
General Description
-

The Radicale Project aims to be a light solution, easy to use, easy -to install, easy to configure. As a consequence, it requires few -software dependencies and is pre-configured to work out-of-the-box.

-

The Radicale Project runs on most of the UNIX-like platforms (Linux, -*BSD, MacOS X) and Windows. It is free and open-source software.

-
-
-
Language
-

The different parts of the Radicale Project are written in Python. -This is a high-level language, fully object-oriented, available for the -main operating systems and released with a lot of useful libraries.

-
-
-
Protocols and Formats
-

The main protocols and formats fully or partially implemented in the -Radicale Project are described by RFCs:

-
    -
  • HyperText Transfer Protocol (HTTP) RFC -2616
    • -
  • WebDAV Access Control Protocol (ACL) RFC -3744
    • -
  • Calendaring Extensions to WebDAV (CalDAV) RFC -4791
    • -
  • HTTP Extensions for Web Distributed Authoring and Versioning -(WebDAV) RFC 4918
    • -
  • Transport Layer Security (TLS) RFC -5246
    • -
  • iCalendar format (iCal) RFC -5545
    • -
  • vCard Format Specification RFC -6350
    • -
  • vCard Extensions to Web Distributed Authoring and Versioning -(CardDAV) RFC 6352
    • -
-
-

Note

-

CalDAV and CardDAV implementations require iCal, -vCard, ACL, WebDAV, HTTP and TLS. The Radicale Server does not -and will not implement correctly these standards, as explained -in the Development Choices part.

-
-
-
-
Development Choices
-

Important global development choices have been decided before writing -code. They are very useful to understand why the Radicale Project is -different from other CalDAV and CardDAV servers, and why features are -included or not in the code.

-
-
Oriented to Calendar and Contact User Agents
-

Calendar and contact servers work with calendar and contact clients, -using a defined protocol. CalDAV and CardDAV are good protocols, -covering lots of features and use cases, but it is quite hard to -implement fully.

-

Some calendar servers have been created to follow the CalDAV and -CardDAV RFCs as much as possible: Davical[7], Cosmo[8] and Darwin Calendar Server[9], for -example, are much more respectful of CalDAV and CardDAV and can be used -with a large number of clients. They are very good choices if you want -to develop and test new CalDAV clients, or if you have a possibly -heterogeneous list of user agents.

-

The Radicale Server does not and will not support -the CalDAV and CardDAV standards. It supports the CalDAV and CardDAV -implementations of different clients (Lightning, Evolution, Android, -iPhone, iCal, and more).

-
-
-
Simple
-

The Radicale Server is designed to be simple to install, simple to -configure, simple to use.

-

The installation is very easy, particularly with Linux: no -dependencies, no superuser rights needed, no configuration required. -Launching the main script out-of-the-box, as a normal user, is often the -only step to have a simple remote calendar and contact access.

-

Contrary to other servers that are often complicated, require high -privileges or need a strong configuration, the Radicale Server can -(sometimes, if not often) be launched in a couple of minutes, if you -follow the User Documentation.

-
-
-
Lazy
-

We, Radicale Project developers, are lazy. That is why we have chosen -Python: no more ; or {}[10]. -This is also why our server is lazy.

-

The CalDAV RFC defines what must be done, what can be done and what -cannot be done. Many violations of the protocol are totally defined and -behaviours are given in such cases.

-

The Radicale Server assumes that the clients are perfect and that -protocol violations do not exist. That is why most of the errors in -client requests have undetermined consequences for the lazy server that -can reply good answers, bad answers, or even no answer.

-

As already mentioned, the Radicale server doesn't fully support the -CalDAV and CardDAV RFCs. For example, nested filters in queries -currently don't work in all cases. Examples of not working queries can -be found in issues #120 and #121.

-
-
-
-
-

Architectures

-
-
General Architecture
-

Here is a simple overview of the global architecture for reaching a -calendar through network:

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PartLayerProtocol or Format
ServerCalendar/Contact StorageiCal/vCard
Calendar/Contact ServerCalDAV/CardDAV Server
TransferNetworkCalDAV/CardDAV (HTTP + TLS)
ClientCalendar/Contact ClientCalDAV/CardDAV Client
GUITerminal, GTK, etc.
-

The Radicale Project is only the server part of this -architecture.

-
-
-
Code Architecture
-

The package offers 8 modules.

-
    -

  • __main__
    -The main module provides a simple function called run. Its -main work is to read the configuration from the configuration file and -from the options given in the command line; then it creates a server, -according to the configuration.

    • -

  • __init__
    -This is the core part of the module, with the code for the CalDAV -server. The server inherits from a HTTP or HTTPS server class, which -relies on the default HTTP server class given by Python. The code -managing the different HTTP requests according to the CalDAV -normalization is written here.

    • -

  • config
    -This part gives a dict-like access to the server configuration, read -from the configuration file. The configuration can be altered when -launching the executable with some command line options.

    • -

  • ical
    -In this module are written the classes to represent collections and -items in Radicale. The simple iCalendar and vCard readers and writers -are included in this file. The readers and writers are small and stupid: -they do not fully understand the iCalendar format and do not know at all -what a date is.

    • -

  • xmlutils
    -The functions defined in this module are mainly called by the CalDAV -server class to read the XML part of the request, read or alter the -calendars, and create the XML part of the response. The main part of -this code relies on ElementTree.

    • -

  • log
    -The start function provided by this module starts a logging -mechanism based on the default Python logging module. Logging options -can be stored in a logging configuration file.

    • -

  • acl
    -This module is a set of Access Control Lists, a set of methods used by -Radicale to manage rights to access the calendars. When the CalDAV -server is launched, an Access Control List is chosen in the set, -according to the configuration. The HTTP requests are then filtered to -restrict the access using a list of login/password-based access -controls.

    • -

  • storage
    -This folder is a set of storage modules able to read and write -collections. Currently there are three storage modules: -filesystem, storing each collection into one flat -plain-text file, multifilesystem, storing each entries into -separates plain-text files, and database, storing entries -in a database. filesystem is stable and battle-tested, -others are experimentals.

    • -
- -
-
-
-
-
-

Contribute

-
-

Chat with Us on IRC

-

Want to say something? Join our IRC room: ##kozea on Freenode.

-
-
-

Report Bugs

-

Found a bug? Want a new feature? Report a new issue on the -Radicale bug-tracker.

-
-
-

Hack

-

Interested in hacking? Feel free to clone the -git repository on Github if you want to add new features, -fix bugs or update documentation.

-
-
-
-

Download

-
-

PyPI

-

Radicale is available -on PyPI. To install, just type as superuser:

-
pip install radicale==1.1.*
-
-
-

Git Repository

-

If you want the development version of Radicale, take a look at the -git repository on GitHub, or clone it thanks to:

-
git clone git://github.com/Kozea/Radicale.git
-

You can also download the Radicale -package of the git repository.

-
-
-

Source Packages

-

You can download the Radicale package for each release:

- -
-
-

Linux Distribution Packages

-

Radicale has been packaged for:

- -

Radicale is also available -on Cloudron and has a Dockerfile.

-

If you are interested in creating packages for other Linux -distributions, read the "Contribute" page.

-
-
-
-

News

-
-

May 19, 2020 - Radicale 1.1.7

-

Radicale 1.1.7 is out!

-
-

1.1.7 - Third Law of Nature

-
    -
  • Fix error in --export-storage
    • -
  • Include documentation in source archive
    • -
-
-
-
-

Jul 24, 2017 - Radicale 1.1.6

-

Radicale 1.1.6 is out!

-
-

1.1.6 - Third Law of Nature

-
    -
  • Improve logging for --export-storage
    • -
-
-
-
-

Jul 24, 2017 - Radicale 1.1.5

-

Radicale 1.1.5 is out!

-
-

1.1.5 - Third Law of Nature

-
    -
  • Improve logging for --export-storage
    • -
-
-
-
-

Jun 25, 2017 - Radicale 1.1.4

-

Radicale 1.1.4 is out!

-
-

1.1.4 - Third Law of Nature

-
    -
  • Use shutil.move for --export-storage
    • -
-
-
-
-

May 27, 2017 - Radicale 1.1.3

-

Radicale 1.1.3 is out!

-
-

1.1.3 - Third Law of Nature

-
    -
  • Add a --export-storage=FOLDER command-line argument (by -Unrud, see #606)
    • -
-
-
-
-

April 19, 2017 - Radicale 1.1.2

-

Radicale 1.1.2 is out!

-
-

1.1.2 - Third Law of Nature

-
    -
  • Security fix: Add a random timer to avoid timing oracles and simple -bruteforce attacks when using the htpasswd authentication method.
    • -
  • Various minor fixes.
    • -
-
-
-
-

December 31, 2015 - Radicale 1.1

-

Radicale 1.1 is out!

-
-

1.1 - Law of Nature

-

One feature in this release is not backward -compatible:

-
    -
  • Use the first matching section for rights (inspired from daald)
    • -
-

Now, the first section matching the path and current user in your -custom rights file is used. In the previous versions, the most -permissive rights of all the matching sections were applied. This new -behaviour gives a simple way to make specific rules at the top of the -file independant from the generic ones.

-

Many improvements in this release are related to -security, you should upgrade Radicale as soon as possible:

-
    -
  • Improve the regex used for well-known URIs (by Unrud)
    • -
  • Prevent regex injection in rights management (by Unrud)
    • -
  • Prevent crafted HTTP request from calling arbitrary functions (by -Unrud)
    • -
  • Improve URI sanitation and conversion to filesystem path (by -Unrud)
    • -
  • Decouple the daemon from its parent environment (by Unrud)
    • -
-

Some bugs have been fixed and little enhancements have been -added:

-
    -
  • Assign new items to corret key (by Unrud)
    • -
  • Avoid race condition in PID file creation (by Unrud)
    • -
  • Improve the docker version (by cdpb)
    • -
  • Encode message and commiter for git commits
    • -
  • Test with Python 3.5
    • -
-
-
-
-

September 14, 2015 - Radicale 1.0, what's next?

-

Radicale 1.0 is out!

-
-

1.0 - Sunflower

-
    -
  • Enhanced performances (by Mathieu Dupuy)
    • -
  • Add MD5-APR1 and BCRYPT for htpasswd-based authentication (by -Jan-Philip Gehrcke)
    • -
  • Use PAM service (by Stephen Paul Weber)
    • -
  • Don't discard PROPPATCH on empty collections (Markus -Unterwaditzer)
    • -
  • Write the path of the collection in the git message (Matthew -Monaco)
    • -
  • Tests launched on Travis
    • -
-

As explained in a previous mail, -this version is called 1.0 because:

-
    -
  • there are no big changes since 0.10 but some small changes are -really useful,
    • -
  • simple tests are now automatically launched on Travis, and more can -be added in the future (https://travis-ci.org/Kozea/Radicale).
    • -
-

This version will be maintained with only simple bug fixes on a -separate git branch called 1.0.x.

-

Now that this milestone is reached, it's time to think about the -future. When Radicale has been created, it was just a proof-of-concept. -The main goal was to write a small, stupid and simple CalDAV server -working with Lightning, using no external libraries. That's how we -created a piece of code that's (quite) easy to understand, to use and to -hack.

-

The first lines have been added to the SVN (!) repository as I was -drinking beers at the very end of 2008. It's now packaged for a growing -number of Linux distributions.

-

And that was fun going from here to there thanks to you. So… -Thank you, you're amazing. I'm so glad I've spent -endless hours fixing stupid bugs, arguing about databases and meeting -invitations, reading incredibly interesting RFCs and debugging with the -fabulous clients from Apple. I mean: that really, really was really, -really cool :).

-

During these years, a lot of things have changed and many users now -rely on Radicale in production. For example, I use it to manage medical -calendars, with thousands requests per day. Many people are happy to -install Radicale on their small home servers, but are also frustrated by -performance and unsupported specifications when they're trying to use it -seriously.

-

So, now is THE FUTURE! I think that Radicale 2.0 should:

-
    -
  • rely on a few external libraries for simple critical points (dealing -with HTTP and iCal for example),
    • -
  • be thread-safe,
    • -
  • be small,
    • -
  • be documented in a different way (for example by splitting the -client part from the server part, and by adding use cases),
    • -
  • let most of the "auth" modules outside in external modules,
    • -
  • have more and more tests,
    • -
  • have reliable and faster filesystem and database storage -mechanisms,
    • -
  • get a new design :).
    • -
-

I'd also secretly love to drop the Python 2.x support.

-

These ideas are not all mine (except from the really, really, really -important "design" point :p), they have been proposed by many developers -and users. I've just tried to gather them and keep points that seem -important to me.

-

Other points have been discussed with many users and contibutors, -including:

-
    -
  • support of other clients, including Windows and BlackBerry -phones,
    • -
  • server-side meeting invitations,
    • -
  • different storage system as default (or even unique?).
    • -
-

I'm not a huge fan of these features, either because I can't do -anything about them, or because I think that they're Really Bad Ideas®™. -But I'm ready to talk about them, because, well, I may not be always -right!

-

Need to talk about this? You know how to contact us!

-
-
-
-

January 12, 2015 - Radicale 0.10

-

Radicale 0.10 is out!

-
-

0.10 - Lovely Endless Grass

-
    -
  • Support well-known URLs (by Mathieu Dupuy)
    • -
  • Fix collection discovery (by Markus Unterwaditzer)
    • -
  • Reload logger config on SIGHUP (by Élie Bouttier)
    • -
  • Remove props files when deleting a collection (by Vincent Untz)
    • -
  • Support salted SHA1 passwords (by Marc Kleine-Budde)
    • -
  • Don't spam the logs about non-SSL IMAP connections to localhost (by -Giel van Schijndel)
    • -
-

This version should bring some interesting discovery and -auto-configuration features, mostly with Apple clients.

-

Lots of love and kudos for the people who have spent hours to test -features and report issues, that was long but really useful (and some of -you have been really patient :p).

-

Issues are welcome, I'm sure that you'll find horrible, terrible, -crazy bugs faster than me. I'll release a version 0.10.1 if needed.

-

What's next? It's time to fix and improve the storage methods. A real -API for the storage modules is a good beginning, many pull requests are -already ready to be discussed and merged, and we will probably get some -good news about performance this time. Who said "databases, please"?

-
-
-
-

July 12, 2013 - Radicale 0.8

-

Radicale 0.8 is out!

-
-

0.8 - Rainbow

-
    -
  • New authentication and rights management modules (by Matthias -Jordan)
    • -
  • Experimental database storage
    • -
  • Command-line option for custom configuration file (by Mark -Adams)
    • -
  • Root URL not at the root of a domain (by Clint Adams, Fabrice -Bellet, Vincent Untz)
    • -
  • Improved support for iCal, CalDAVSync, CardDAVSync, CalDavZAP and -CardDavMATE
    • -
  • Empty PROPFIND requests handled (by Christoph Polcin)
    • -
  • Colon allowed in passwords
    • -
  • Configurable realm message
    • -
-

This version brings some of the biggest changes since Radicale's -creation, including an experimental support of database storage, clean -authentication modules, and rights management finally designed for real -users.

-

So, dear user, be careful: this version changes important -things in the configuration file, so check twice that everything is OK -when you update to 0.8, or you can have big problems.

-

More and more clients are supported, as a lot of bug fixes and -features have been added for this purpose. And before you ask: yes, 2 -web-based clients, CalDavZAP and -CardDavMATE, are now supported!

-

Even if there has been a lot of time to test these new features, I am -pretty sure that some really annoying bugs have been left in this -version. We will probably release minor versions with bugfixes during -the next weeks, and it will not take one more year to reach 0.8.1.

-

The documentation has been updated, but some parts are missing and -some may be out of date. You can report bugs or even -write -documentation directly on GitHub if you find something strange (and -you probably will).

-

If anything is not clear, or if the way rights work is a bit -complicated to understand, or if you are so happy because everything -works so well, you can share your -thoughts!

-

It has been a real pleasure to work on this version, with brilliant -ideas and interesting bug reports from the community. I'd really like to -thank all the people reporting bugs, chatting on IRC, sending mails and -proposing pull requests: you are awesome.

-
-
-
-

August 3, 2012 - Radicale 0.7.1

-

Radicale 0.7.1 is out!

-
-

0.7.1 - Waterfalls

-
    -
  • Many address books fixes
    • -
  • New IMAP ACL (by Daniel Aleksandersen)
    • -
  • PAM ACL fixed (by Daniel Aleksandersen)
    • -
  • Courier ACL fixed (by Benjamin Frank)
    • -
  • Always set display name to collections (by Oskari Timperi)
    • -
  • Various DELETE responses fixed
    • -
-

It's been a long time since the last version… As usual, many people -have contributed to this new version, that's a pleasure to get these -pull requests.

-

Most of the commits are bugfixes, especially about ACL backends and -address books. Many clients (including aCal and SyncEvolution) will be -much happier with this new version than with the previous one.

-

By the way, one main new feature has been added: a new IMAP ACL -backend, by Daniel. And about authentication, exciting features are -coming soon, stay tuned!

-

Next time, as many mails have come from angry and desperate coders, -tests will be finally added to help them to add features and -fix bugs. And after that, who knows, it may be time to release Radicale -1.0…

-
-
-
-

March 22, 2012 - Radicale 0.7

-

Radicale 0.7 is out, at least!

-
-

0.7 - Eternal Sunshine

-
    -
  • Repeating events
    • -
  • Collection deletion
    • -
  • Courier and PAM authentication methods
    • -
  • CardDAV support
    • -
  • Custom LDAP filters supported
    • -
-

A lot of people have reported bugs, proposed new -features, added useful code and tested many clients. Thank you Lynn, -Ron, Bill, Patrick, Hidde, Gerhard, Martin, Brendan, Vladimir, and -everybody I've forgotten.

-
-
-
-

January 5, 2012 - Radicale 0.6.4, News from Calypso

-

New year, new release. Radicale 0.6.4 has a really short -changelog:

-
-

0.6.4 - Tulips

-
    -
  • Fix the installation with Python 3.1
    • -
-

The bug was in fact caused by a bug in Python 3.1, -everything should be OK now.

-
-
-

Calypso

-

After a lot of changes in Radicale, Keith Packard has decided to -launch a fork called Calypso, with nice features -such as a Git storage mechanism and a CardDAV support.

-

There are lots of differences between the two projects, but the final -goal for Radicale is to provide these new features as soon as possible. -Thanks to the work of Keith and other people on GitHub, a basic CardDAV -support has been added in the carddav branch -and already works with Evolution. Korganizer also works with existing -address books, and CardDAV-Sync will be tested soon. If you want to test -other clients, please let us know!

-
-
-
-

November 3, 2011 - Radicale 0.6.3

-

Radicale version 0.6.3 has been released, with bugfixes that could be -interesting for you!

-
-

0.6.3 - Red Roses

-
    -
  • MOVE requests fixed
    • -
  • Faster REPORT answers
    • -
  • Executable script moved into the package
    • -
-
-
-

What's New Since 0.6.2?

-

The MOVE requests were suffering a little bug that is fixed now. -These requests are only sent by Apple clients, Mac users will be -happy.

-

The REPORT request were really, really slow (several minutes for -large calendars). This was caused by an awful algorithm parsing the -entire calendar for each event in the calendar. The calendar is now only -parsed three times, and the events are found in a Python list, turning -minutes into seconds! Much better, but far from perfection…

-

Finally, the executable script parsing the command line options and -starting the HTTP servers has been moved from the -radicale.py file into the radicale package. -Two executable are now present in the archive: the good old -radicale.py, and bin/radicale. The second one -is only used by setup.py, where the hack used to rename -radicale.py into radicale has therefore been -removed. As a consequence, you can now launch Radicale with the simple -python -m radicale command, without relying on an -executable.

-
-
-

Time for a Stable Release!

-

The next release may be a stable release, symbolically called 1.0. -Guess what's missing? Tests, of course!

-

A non-regression testing suite, based on the clients' requests, will -soon be added to Radicale. We're now thinking about a smart solution to -store the tests, to represent the expected answers and to launch the -requests. We've got crazy ideas, so be prepared: you'll definitely -want to write tests during the next weeks!

-

Repeating events, PAM and Courier authentication methods have already -been added in master. You'll find them in the 1.0 release!

-
-
-

What's Next?

-

Being stable is one thing, being cool is another one. If you want -some cool new features, you may be interested in:

-
    -
  • WebDAV and CardDAV support
    • -
  • Filters and rights management
    • -
  • Multiple storage backends, such as databases and git
    • -
  • Freebusy periods
    • -
  • Email alarms
    • -
-

Issues have been reported in the bug tracker, you can follow there -the latest news about these features. Your beloved text editor is -waiting for you!

-
-
-
-

September 27, 2011 - Radicale 0.6.2

-

0.6.2 is out with minor bugfixes.

-
-

0.6.2 - Seeds

-
    -
  • iPhone and iPad support fixed
    • -
  • Backslashes replaced by slashes in PROPFIND answers on Windows
    • -
  • PyPI archive set as default download URL
    • -
-
-
-
-

August 28, 2011 - Radicale 0.6.1, Changes, Future

-

As previously imagined, a new 0.6.1 version has been released, mainly -fixing obvious bugs.

-
-

0.6.1 - Growing Up

-
    -
  • Example files included in the tarball
    • -
  • htpasswd support fixed
    • -
  • Redirection loop bug fixed
    • -
  • Testing message on GET requests
    • -
-

The changelog is really small, so there should be no real new -problems since 0.6. The example files for logging, FastCGI and WSGI are -now included in the tarball, for the pleasure of our dear packagers!

-

A new branch has been created for various future bug fixes. You can -expect to get more 0.6.x versions, making this branch a kind of "stable" -branch with no big changes.

-
-
-

GitHub, Mailing List, New Website

-

A lot of small changes occurred during the last weeks.

-

If you're interested in code and new features, please note that we -moved the project from Gitorious to GitHub. Being hosted by -Gitorious was a nice experience, but the service was not that good and -we were missing some useful features such as git hooks. Moreover, GitHub -is really popular, we're sure that we'll meet a lot of kind users and -coders there.

-

We've also created a mailing-list on Librelist to keep a -public trace of the mails we're receiving. It a bit empty now, but we're -sure that you'll soon write us some kind words. For example, you can -tell us what you think of our new website!

-
-
-

Future Features

-

In the next weeks, new exciting features are coming in the master -branch! Some of them are almost ready:

-
    -
  • Henry-Nicolas has added the support for the PAM and -Courier-Authdaemon authentication mechanisms.
    • -
  • An anonymous called Keith Packard has prepared some small changes, -such as one file per event, cache and git versioning. Yes. Really.
    • -
-

As you can find in the Radicale Roadmap, tests, -rights and filters are expected for 0.7.

-
-
-
-

August 1, 2011 - Radicale 0.6 Released

-

Time for a new release with a lot of new exciting -features!

-
-

0.6 - Sapling

-
    -
  • WSGI support
    • -
  • IPv6 support
    • -
  • Smart, verbose and configurable logs
    • -
  • Apple iCal 4 and iPhone support (by Łukasz Langa)
    • -
  • CalDAV-Sync support (by Marten Gajda)
    • -
  • aCal support
    • -
  • KDE KOrganizer support
    • -
  • LDAP auth backend (by Corentin Le Bail)
    • -
  • Public and private calendars (by René Neumann)
    • -
  • PID file
    • -
  • MOVE requests management
    • -
  • Journal entries support
    • -
  • Drop Python 2.5 support
    • -
-

Well, it's been a little longer than expected, but for good reasons: -a lot of features have been added, and a lot of clients are known to -work with Radicale, thanks to kind contributors. That's definitely good -news! But…

-

Testing all the clients is really painful, moreover for the ones from -Apple (I have no Mac nor iPhone of my own). We should seriously think of -automated tests, even if it's really hard to maintain, and maybe not -that useful. If you're interested in tests, you can look at the -wonderful regression suite of DAViCal.

-

The new features, for example the WSGI support, are also poorly -documented. If you have some Apache or lighttpd configuration working -with Radicale, you can make the world a little bit better by writing a -paragraph or two in the Radicale -documentation. It's simple plain text, don't be afraid!

-

Because of all these changes, Radicale 0.6 may be a little bit buggy; -a 0.6.1 will probably be released soon, fixing small problems with -clients and features. Get ready to report bugs, I'm sure that you can -find one (and fix it)!

-
-
-
-

July 2, 2011 - Feature Freeze for 0.6

-

According to the roadmap, a -lot of features have been added since Radicale 0.5, much more than -expected. It's now time to test Radicale with your favourite client and -to report bugs before we release the next stable version!

-

Last week, the iCal and iPhone support written by Łukasz has been -fixed in order to restore the broken Lightning support. After two -afternoons of tests with Rémi, we managed to access the same calendar -with Lightning, iCal, iPhone and Evolution, and finally discovered that -CalDAV could also be a perfect instant messaging protocol between a Mac, -a PC and a phone.

-

After that, we've had the nice surprise to see events displayed -without a problem (but after some strange steps of configuration) by -aCal on Salem's Android phone.

-

It was Friday, fun fun fun fun.

-

So, that's it: Radicale supports Lightning, Evolution, Kontact, aCal -for Android, iPhone and iCal. Of course, before releasing a new -tarball:

-
    -
  • documentation is needed for the -new clients that are not documented yet (Kontact, aCal and iPhone);
    • -
  • tests are welcome, particularly for the Apple clients that I can't -test anymore;
    • -
  • no more features will be added, they'll wait in separate branches -for the 0.7 development.
    • -
-

Please report bugs -if anything goes wrong during your tests, or just let us know by Jabber or by mail if everything is OK.

-
-
-

May 1, 2011 - Ready for WSGI

-

Here it is! Radicale is now ready to be launched behind your -favourite HTTP server (Apache, Lighttpd, Nginx or Tomcat for example). -That's really good news, because:

-
    -
  • Real HTTP servers are much more efficient and reliable than the -default Python server used in Radicale;
    • -
  • All the authentication backends available for your server will be -available for Radicale;
    • -
  • Thanks to flup, Radicale -can be interfaced with all the servers supporting CGI, AJP, FastCGI or -SCGI;
    • -
  • Radicale works very well without any additional server, without any -dependencies, without configuration, just as it was working before;
    • -
  • This one more feature removes useless code, less is definitely -more.
    • -
-

The WSGI support has only be tested as a stand-alone executable and -behind Lighttpd, you should definitely try if it works with you -favourite server too!

-

No more features will be added before (quite) a long time, because a -lot of documentation and test is waiting for us. If you want to write -tutorials for some CalDAV clients support (iCal, Android, iPhone), HTTP -servers support or logging management, feel free to fork the documentation git -repository and ask for a merge. It's plain text, I'm sure you can do -it!

-
-
-

April 30, 2011 - Apple iCal Support

-

After a long, long work, the iCal support has finally been added to -Radicale! Well, this support is only for iCal 4 and is highly -experimental, but you can test it right now with the git master branch. -Bug reports are welcome!

-

Dear MacOS users, you can thank all the gentlemen who sended a lot of -debugging iformation. Special thanks to Andrew from DAViCal, who helped -us a lot with his tips and his tests, and Rémi Hainaud who lent his -laptop for the final tests.

-

The default server address is localhost:5232/user/, -where calendars can be added. Multiple calendars and owner-less -calendars are not tested yet, but they should work quite well. More -documentation will be added during the next days. It will then be time -to release the Radicale 0.6 version, and work on the WSGI support.

-
-
-

April 25, 2011 - Two Features and One New Roadmap

-

Two features have just reached the master branch, and the roadmap has -been refreshed.

-
-

LDAP Authentication

-

Thanks to Corentin, the LDAP authentication is now included in -Radicale. The support is experimental and may suffer unstable connexions -and security problems. If you are interested in this feature (a lot of -people seem to be), you can try it and give some feedback.

-

No SSL support is included yet, but this may be quite easy to add. By -the way, serious authentication methods will rely on a "real" HTTP -server, as soon as Radicale supports WSGI.

-
-
-

Journal Entries

-

Mehmet asked for the journal entries (aka. notes or memos) support, -that's done! This also was an occasion to clean some code in the iCal -parser, and to add a much better management of multi-lines entries. -People experiencing crazy X-RADICALE-NAME entries can now -clean their files, Radicale won't pollute them again.

-
-
-

New Roadmap

-

Except from htpasswd and LDAP, most of the authentication backends -(database, SASL, PAM, user groups) are not really easy to include in -Radicale. The easiest solution to solve this problem is to give Radicale -a CGI support, to put it behind a solid server such as Apache. Of -course, CGI is not enough: a WSGI support is quite better, with the -FastCGI, AJP and SCGI backends offered by flup. Quite exciting, isn't -it?

-

That's why it was important to add new versions on the roadmap. The -0.6 version is now waiting for the Apple iCal support, and of course for -some tests to kill the last remaining bugs. The only 0.7 feature will be -WSGI, allowing many new authentication methods and a real multithread -support.

-

After that, 0.8 may add CalDAV rights and filters, while 1.0 will -draw thousands of rainbows and pink unicorns (WebDAV sync, CardDAV, -Freebusy). A lot of funky work is waiting for you, hackers!

-
-
-

Bugs

-

Many bugs have also been fixed, most of them due to the owner-less -calendars support. Radicale 0.6 may be out in a few weeks, you should -spend some time testing the master branch and filling the bug -tracker.

-
-
-
-

April 10, 2011 - New Features

-

Radicale 0.5 was released only 8 days ago, but 3 new features have -already been added to the master branch:

-
    -
  • IPv6 support, with multiple addresses/ports support
    • -
  • Logs and debug mode
    • -
  • Owner-less calendars
    • -
-

Most of the code has been written by Necoro and Corentin, and that -was not easy at all: Radicale is now multithreaded! For sure, you can -find many bugs and report them on the bug tracker. -And if you're fond of logging, you can even add a default configuration -file and more debug messages in the source.

-
-
-

April 2, 2011 - Radicale 0.5 Released

-

Radicale 0.5 is out! Here is what's new:

-
-

0.5 - Historical Artifacts

-
    -
  • Calendar depth
    • -
  • iPhone support
    • -
  • MacOS and Windows support
    • -
  • HEAD requests management
    • -
  • htpasswd user from calendar path
    • -
-

iPhone support, but no iCal support for 0.5, despite our hard work, -sorry! After 1 month with no more activity on the dedicated bug, it was -time to forget it and hack on new awesome features. Thanks for your -help, dear Apple users, I keep the hope that one day, Radicale will work -with you!

-

So, what's next? As promised, some cool git branches will soon be -merged, with LDAP support, logging, IPv6 and anonymous calendars. Sounds -pretty cool, heh? Talking about new features, more and more people are -asking for a CardDAV support in Radicale. A -git branch and a -feature request are open, feel free to hack and discuss.

-
-
-
-

February 3, 2011 - Jabber Room and iPhone Support

-

After a lot of help and testing work from Andrew, Björn, Anders, -Dorian and Pete (and other ones we could have forgotten), a simple -iPhone support has been added in the git repository. If you are -interested, you can test this feature right now by downloading the latest git version (a tarball -is even available too if you don't want or know how to use git).

-

No documentation has been written yet, but using the right URL in the -configuration should be enough to synchronize your calendars. If you -have any problems, you can ask by joining our new Jabber room: radicale@room.jabber.kozea.fr.

-

Radicale 0.5 will be released as soon as the iCal support is ready. -If you have an Apple computer, Python skills and some time to spend, -we'd be glad to help you debugging Radicale.

-
-
-

October 21, 2010 - News from Radicale

-

During the last weeks, Radicale has not been idle, even if no news -have been posted since August. Thanks to Pete, Pierre-Philipp and -Andrew, we're trying to add a better support on MacOS, Windows and -mobile devices like iPhone and Android-based phones.

-

All the tests on Windows have been successful: launching Radicale and -using Lightning as client works without any problems. On Android too, -some testers have reported clients working with Radicale. These were the -good news.

-

The bad news come from Apple: both iPhone and MacOS default clients -are not working yet, despite the latest enhancements given to the -PROPFIND requests. The problems are quite hard to debug due to our lack -of Apple hardware, but Pete is helping us in this difficult quest! -Radicale 0.5 will be out as soon as these two clients are working.

-

Some cool stuff is coming next, with calendar collections and groups, -and a simple web-based CalDAV client in early development. Stay -tuned!

-
-
-

August 8, 2010 - Radicale 0.4 Released

-

Radicale 0.4 is out! Here is what's new:

-
-

0.4 - Hot Days Back

-
    -
  • Personal calendars
    • -
  • HEAD requests
    • -
  • Last-Modified HTTP header
    • -
  • no-ssl and foreground options
    • -
  • Default configuration file
    • -
-

This release has mainly been released to help our dear packagers to -include a default configuration file and to write init scripts. Big -thanks to Necoro for his work on the new Gentoo ebuild!

-
-
-
-

July 4, 2010 - Three Features Added Last Week

-

Some features have been added in the git repository during the last -weeks, thanks to Jerome and Mariusz!

-
    -

  • Personal Calendars
    -Calendars accessed through the htpasswd ACL module can now be personal. -Thanks to the personal option, a user called -bob can access calendars at /bob/* but not to -the /alice/* ones.

    • -

  • HEAD Requests
    -Radicale can now answer HEAD requests. HTTP headers can be retrieved -thanks to this request, without getting contents given by the GET -requests.

    • -

  • Last-Modified HTTP header
    -The Last-Modified header gives the last time when the calendar has been -modified. This is used by some clients to cache the calendars and not -retrieving them if they have not been modified.

    • -
-
-
-

June 14, 2010 - Radicale 0.3 Released

-

Radicale 0.3 is out! Here is what’s new:

-
-

0.3 - Dancing Flowers

-
    -
  • Evolution support
    • -
  • Version management
    • -
-

The website changed a little bit too, with some small HTML5 and CSS3 -features such as articles, sections, transitions, opacity, box shadows -and rounded corners. If you’re reading this website with Internet -Explorer, you should consider using a standard-compliant browser!

-

Radicale is now included in Squeeze, the testing branch of Debian. A -Radicale ebuild -for Gentoo has been proposed too. If you want to package Radicale -for another distribution, you’re welcome!

-

Next step is 0.5, with calendar collections, and Windows and MacOS -support.

-
-
-
-

May 31, 2010 - May News

-
-

News from contributors

-

Jonas Smedegaard packaged Radicale for Debian last week. Two -packages, called radicale for the daemon and -python-radicale for the module, have been added to Sid, the -unstable branch of Debian. Thank you, Jonas!

-

Sven Guckes corrected some of the strange-English-sentences present -on this website. Thank you, Sven!

-
-
-

News from software

-

A simple VERSION has been added in the library: you can -now play with radicale.VERSION and -$radicale --version.

-

After playing with the version (should not be too long), you may -notice that the next version is called 0.3, and not 0.5 as previously -decided. The 0.3 main goal is to offer the support for Evolution as soon -as possible, without waiting for the 0.5. After more than a month of -test, we corrected all the bugs we found and everything seems to be -fine; we can imagine that a brand new tarball will be released during -the first days of June.

-
-
-
-

April 19, 2010 - Evolution Supported

-

Radicale now supports another CalDAV client: Evolution, the default mail, -addressbook and calendaring client for Gnome. This feature was quite -easy to add, as it required less than 20 new lines of code in the -requests handler.

-

If you are interested, just clone the git -repository.

-
-
-

April 13, 2010 - Radicale 0.2 Released

-

Radicale 0.2 is out! Here is what’s new:

-
-

0.2 - Snowflakes

-
    -
  • Sunbird pre-1.0 support
    • -
  • SSL connection
    • -
  • Htpasswd authentication
    • -
  • Daemon mode
    • -
  • User configuration
    • -
  • Twisted dependency removed
    • -
  • Python 3 support
    • -
  • Real URLs for PUT and DELETE
    • -
  • Concurrent modification reported to users
    • -
  • Many bugs fixed by Roger Wenham
    • -
-

First of all, we would like to thank Roger Wenham for his bugfixes -and his supercool words.

-

You may have noticed that Sunbird 1.0 has not been released, but -according to the Mozilla developers, 1.0pre is something like a final -version.

-

You may have noticed too that Radicale can be downloaded from -PyPI. Of course, it is also available on the download page.

-
-
-
-

January 21, 2010 - HTTPS and Authentication

-

HTTPS connections and authentication have been added to Radicale this -week. Command-line options and personal configuration files are also -ready for test. According to the TODO file included in the package, the -next version will finally be 0.2, when sunbird 1.0 is out. Go, Mozilla -hackers, go!

-
    -

  • HTTPS connection
    -HTTPS connections are now available using the standard TLS mechanisms. -Give Radicale a private key and a certificate, and your data are now -safe.

    • -

  • Authentication
    -A simple authentication architecture is now available, allowing -different methods thanks to different modules. The first two modules are -fake (no authentication) and htpasswd -(authentication with an htpasswd file created by the Apache -tool). More methods such as LDAP are coming soon!

    • -
-
-
-

January 15, 2010 - Ready for Python 3

-

Dropping Twisted dependency was the first step leading to another big -feature: Radicale now works with Python 3! The code was given a small -cleanup, with some simplifications mainly about encoding. Before the -0.1.1 release, feel free to test the git repository, all Python versions -from 2.5 should be OK.

-
-
-

January 11, 2010 - Twisted no Longer Required

-

Good news! Radicale 0.1.1 will support Sunbird 1.0, but it has -another great feature: it has no external dependency! Twisted is no -longer required for the git version, removing about 50 lines of -code.

-
-
-

December 31, 2009 - Lightning and Sunbird 1.0b2pre Support

-

Lightning/Sunbird 1.0b2pre is out, adding minor changes in CalDAV -support. A new -commit makes Radicale work with versions 0.9, 1.0b1 et 1.0b2. -Moreover, etags are now quoted according to the RFC -2616.

-
-
-

December 9, 2009 - Thunderbird 3 released

-

Thunderbird -3 is out, and Lightning/Sunbird 1.0 should be released in a few -days. The last commit -in git should make Radicale work with versions 0.9 and 1.0b1pre. -Radicale 0.1.1 will soon be released adding support for version 1.0.

-
-
-

September 1, 2009 - Radicale 0.1 Released

-

First Radicale release! Here is the changelog:

-
-

0.1 - Crazy Vegetables

-
    -
  • First release
    • -
  • Lightning/Sunbird 0.9 compatibility
    • -
  • Easy installer
    • -
-

You can download this version on the download -page.

-
-
-
-

July 28, 2009 - Radicale on Gitorious

-

Radicale code has been released on Gitorious! Take a look at the Radicale main page on -Gitorious to view and download source code.

-
-
-

July 27, 2009 - Radicale Ready to Launch

-

The Radicale Project is launched. The code has been cleaned up and -will be available soon…

-
-
-
-

Footnotes

-
-

1

-

See Python Versions and OS -Support for further information.

-
-
-

2

-

Python download page.

-
-
-

3

-

I repeat: we are lazy.

-
-
-

4

-

Try to read RFC 4791. Then try to understand it. Then try to -implement it. Then try to read it again.

-
-
-

5

-

Radicale is oriented to -calendar user agents.

-
-
-

6

-

CalDAV -implementations, by Wikipedia.

-
-
-

7

-

Davical, a standards-compliant -calendar server.

-
-
-

8

-

Cosmo, -the web contents and calendars sharing server build to support the -Chandler Project.

-
-
-

9

-

Darwin Calendar Server, -a standards-compliant calendar server mainly developed by Apple.

-
-
-

10

-

Who says "Ruby is even less verbose!" should read the PEP -20.

-
-
-
-
- diff --git a/v2.html b/v2.html deleted file mode 100644 index 808f3ac79..000000000 --- a/v2.html +++ /dev/null @@ -1,3228 +0,0 @@ - - - - - - - - - - - - - - -Radicale v2 Documentation - - - - - -
-
-

-Radicale - -v2 - - -

-

Free and Open-Source CalDAV and CardDAV Server

-
-
- -
-
-
- - -
-
-

Getting started

-
-

About Radicale

-

Radicale is a small but powerful CalDAV (calendars, todo-lists) and -CardDAV (contacts) server, that:

-
    -
  • Shares calendars through CalDAV, WebDAV and HTTP.
    • -
  • Shares contacts through CardDAV, WebDAV and HTTP.
    • -
  • Supports events, todos, journal entries and business cards.
    • -
  • Works out-of-the-box, no installation nor configuration -required.
    • -
  • Can warn users on concurrent editing.
    • -
  • Can limit access by authentication.
    • -
  • Can secure connections.
    • -
  • Works with many CalDAV and CardDAV clients.
    • -
  • Is GPLv3-licensed free software.
    • -
-
-
-

Installation

-

Radicale is really easy to install and works out-of-the-box.

-
$ python3 -m pip install --upgrade radicale==2.1.*
-$ python3 -m radicale --config "" --storage-filesystem-folder=~/.var/lib/radicale/collections
-

When your server is launched, you can check that everything's OK by -going to http://localhost:5232/ with your browser! You can login with -any username and password.

-

Want more? Why don't you check our wonderful documentation?

-
-
-

What's New?

-

Latest version of Radicale is 2.1.12, released on May 19, 2020 (changelog).

-

Read latest news…

-
-
-
-

Documentation

-

This documentation page is written for version 2.x.x. If you want to -update Radicale from 1.x.x to 2.x.x, please follow our migration guide. You can find on -GitHub the documentation page for the 1.1.x -versions.

-
-

Install and Set Up

-

You're new to Radicale and you want to know how to use it? Welcome -aboard!

- -
-
-

Use

- -
-
-

Configure

-

Now that you have Radicale running, let's see what we can configure -to make it fit your needs.

- -
-
-

Hack

-

Using is fun, but hacking is soooooooo coooooool. Radicale is a -really small and simple piece of code, it may be the perfect project to -start hacking!

- -
-
-

Tutorial

-

You want to try Radicale but only have 5 minutes free in your -calendar? Let's go right now! You won't have the best installation ever, -but it will be enough to play a little 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 user name and -password. If Radicale fits your needs, it may be time for some basic configuration.

-

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

-
-

Linux / *BSD

-

First of all, make sure that python 3.3 or later -(python ≥ 3.6 is recommended) and pip -are installed. On most distributions it should be enough to install the -package python3-pip.

-

Then open a console and type:

-
# Run the following command as root or
-# add the --user argument to only install for the current user
-$ python3 -m pip install --upgrade radicale==2.1.*
-$ python3 -m radicale --config "" --storage-filesystem-folder=~/.var/lib/radicale/collections
-

Victory! Open http://localhost:5232/ in your -browser! You can login with any username and password.

-
-
-

Windows

-

The first step is to install Python. Go to python.org and download the latest version -of Python 3. Then run the installer. On the first window of the -installer, check the "Add Python to PATH" box and click on "Install -now". Wait a couple of minutes, it's done!

-

Launch a command prompt and type:

-
C:\Users\User> python -m pip install --upgrade radicale==2.1.*
-C:\Users\User> python -m radicale --config "" --storage-filesystem-folder=~/radicale/collections
-

If you are using PowerShell replace --config "" with ---config '""'.

-

Victory! Open http://localhost:5232/ in your -browser! You can login with any username and password.

-
-
-

MacOS

-

To be written.

-
-
-
-

Basic Setup

-

Installation instructions can be found on the Tutorial page.

-
-

Configuration

-

Radicale tries to load configuration files from -/etc/radicale/config, -~/.config/radicale/config and the -RADICALE_CONFIG environment variable. A custom path can be -specified with the --config /path/to/config command line -argument.

-

You should create a new configuration file at the desired location. -(If the use of a configuration file is inconvenient, all options can be -passed via command line arguments.)

-

All configuration options are described in detail on the Configuration page.

-
-
-

Authentication

-

In its default configuration Radicale doesn't check user names or -passwords. If the server is reachable over a network, you should change -this.

-

First a users file with all user names and passwords -must be created. It can be stored in the same directory as the -configuration file.

-
-
The secure way
-

The users file can be created and managed with htpasswd:

-
# Create a new htpasswd file with the user "user1"
-$ htpasswd -B -c /path/to/users user1
-New password:
-Re-type new password:
-# Add another user
-$ htpasswd -B /path/to/users user2
-New password:
-Re-type new password:
-

bcrypt is used to secure the passwords. Radicale -requires additional dependencies for this encryption method:

-
$ python3 -m pip install --upgrade radicale[bcrypt]==2.1.*
-

Authentication can be enabled with the following configuration:

-
[auth]
-type = htpasswd
-htpasswd_filename = /path/to/users
-# encryption method used in the htpasswd file
-htpasswd_encryption = bcrypt
-
-
-
The simple but insecure way
-

Create the users file by hand with lines containing the -user name and password separated by :. Example:

-
user1:password1
-user2:password2
-

Authentication can be enabled with the following configuration:

-
[auth]
-type = htpasswd
-htpasswd_filename = /path/to/users
-# encryption method used in the htpasswd file
-htpasswd_encryption = plain
-
-
-
-

Addresses

-

The default configuration binds the server to localhost. It can't be -reached from other computers. This can be changed with the following -configuration options:

-
[server]
-hosts = 0.0.0.0:5232
-

More addresses can be added (separated by commas).

-
-
-

Storage

-

Data is stored in the folder -/var/lib/radicale/collections. The path can be changed with -the following configuration:

-
[storage]
-filesystem_folder = /path/to/storage
-

Security: The storage folder should not be readable -by unauthorized users. Otherwise, they can read the calendar data and -lock the storage. You can find OS dependent instructions in the -Running as a service section.

-
-
-

Limits

-

Radicale enforces limits on the maximum number of parallel -connections, the maximum file size (important for contacts with big -photos) and the rate of incorrect authentication attempts. Connections -are terminated after a timeout. The default values should be fine for -most scenarios.

-
[server]
-max_connections = 20
-# 100 Megabyte
-max_content_length = 100000000
-# 30 seconds
-timeout = 30
-
-[auth]
-# Average delay after failed login attempts in seconds
-delay = 1
-
-
-

Running as a service

-

The method to run Radicale as a service depends on your host -operating system. Follow one of the chapters below depending on your -operating system and requirements.

-
-
Linux with systemd as a user
-

Create the file -~/.config/systemd/user/radicale.service:

-
[Unit]
-Description=A simple CalDAV (calendar) and CardDAV (contact) server
-
-[Service]
-ExecStart=/usr/bin/env python3 -m radicale
-Restart=on-failure
-
-[Install]
-WantedBy=default.target
-

Radicale will load the configuration file from -~/.config/radicale/config. You should set the configuration -option filesystem_folder in the storage -section to something like -~/.var/lib/radicale/collections.

-

To enable and manage the service run:

-
# Enable the service
-$ systemctl --user enable radicale
-# Start the service
-$ systemctl --user start radicale
-# Check the status of the service
-$ systemctl --user status radicale
-# View all log messages
-$ journalctl --user --unit radicale.service
-
-
-
Linux with systemd system-wide
-

Create the radicale user and group for the Radicale -service. (Run -useradd --system --home-dir / --shell /sbin/nologin radicale -as root.) The storage folder must be writable by -radicale. (Run -mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections -as root.)

-

Security: The storage should not be readable by -others. (Run chmod -R o= /var/lib/radicale/collections as -root.)

-

Create the file -/etc/systemd/system/radicale.service:

-
[Unit]
-Description=A simple CalDAV (calendar) and CardDAV (contact) server
-After=network.target
-Requires=network.target
-
-[Service]
-ExecStart=/usr/bin/env python3 -m radicale
-Restart=on-failure
-User=radicale
-# Deny other users access to the calendar data
-UMask=0027
-# Optional security settings
-PrivateTmp=true
-ProtectSystem=strict
-ProtectHome=true
-PrivateDevices=true
-ProtectKernelTunables=true
-ProtectKernelModules=true
-ProtectControlGroups=true
-NoNewPrivileges=true
-ReadWritePaths=/var/lib/radicale/collections
-
-[Install]
-WantedBy=multi-user.target
-

Radicale will load the configuration file from -/etc/radicale/config.

-

To enable and manage the service run:

-
# Enable the service
-$ systemctl enable radicale
-# Start the service
-$ systemctl start radicale
-# Check the status of the service
-$ systemctl status radicale
-# View all log messages
-$ journalctl --unit radicale.service
-
-
-
-

MacOS with launchd

-

To be written.

-
-
-

Classic daemonization

-

Set the configuration option daemon in the section -server to True. You may want to set the option -pid to the path of a PID file.

-

After daemonization the server will not log anything. You have to -configure Logging.

-

If you start Radicale now, it will initialize and fork into the -background. The main process exits, after the PID file is written.

-

Security: You can set the umask -with umask 0027 before you start the daemon, to protect -your calendar data and log files from other users. Don't forget to set -permissions of files that are already created!

-
-
-

Windows with "NSSM - the Non-Sucking Service Manager"

-

First install NSSM and start -nssm install in a command prompt. Apply the following -configuration:

-
    -
  • Service name: Radicale
    • -
  • Application -
      -
    • Path: C:\Path\To\Python\python.exe
      • -
    • Arguments: -m radicale --config C:\Path\To\Config
      • -
    • -
  • I/O redirection -
      -
    • Error: C:\Path\To\Radicale.log
      • -
    • -
-

Security: Be aware that the service runs in the -local system account, you might want to change this. Managing user -accounts is beyond the scope of this manual. Also make sure that the -storage folder and log file is not readable by unauthorized users.

-

The log file might grow very big over time, you can configure file -rotation in NSSM to prevent this.

-

The service is configured to start automatically when the computer -starts. To start the service manually open Services in -Computer Management and start the -Radicale service.

-
-
-
-

Reverse Proxy

-

When a reverse proxy is used, the path at which Radicale is available -must be provided via the X-Script-Name header. The proxy -must remove the location from the URL path that is forwarded to -Radicale.

-

Example nginx configuration:

-
location /radicale/ { # The trailing / is important!
-    proxy_pass        http://localhost:5232/; # The / is important!
-    proxy_set_header  X-Script-Name /radicale;
-    proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_pass_header Authorization;
-}
-

Example Apache configuration:

-
RewriteEngine On
-RewriteRule ^/radicale$ /radicale/ [R,L]
-
-<Location "/radicale/">
-    ProxyPass        http://localhost:5232/ retry=0
-    ProxyPassReverse http://localhost:5232/
-    RequestHeader    set X-Script-Name /radicale/
-</Location>
-

Be reminded that Radicale's default configuration enforces limits on -the maximum number of parallel connections, the maximum file size and -the rate of incorrect authentication attempts. Connections are -terminated after a timeout.

-
-

Manage user accounts with the reverse proxy

-

Set the configuration option type in the -auth section to http_x_remote_user. Radicale -uses the user name provided in the X-Remote-User HTTP -header and disables HTTP authentication.

-

Example nginx configuration:

-
location /radicale/ {
-    proxy_pass           http://localhost:5232/;
-    proxy_set_header     X-Script-Name /radicale;
-    proxy_set_header     X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header     X-Remote-User $remote_user;
-    auth_basic           "Radicale - Password Required";
-    auth_basic_user_file /etc/nginx/htpasswd;
-}
-

Example Apache configuration:

-
RewriteEngine On
-RewriteRule ^/radicale$ /radicale/ [R,L]
-
-<Location "/radicale/">
-    AuthType      Basic
-    AuthName      "Radicale - Password Required"
-    AuthUserFile  "/etc/radicale/htpasswd"
-    Require       valid-user
-
-    ProxyPass        http://localhost:5232/ retry=0
-    ProxyPassReverse http://localhost:5232/
-    RequestHeader    set X-Script-Name /radicale/
-    RequestHeader    set X-Remote-User expr=%{REMOTE_USER}
-</Location>
-

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

-
-
-

Secure connection between Radicale and the reverse proxy

-

SSL certificates can be used to encrypt and authenticate the -connection between Radicale and the reverse proxy. First you have to -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
-

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
-

Example nginx configuration:

-
location /radicale/ {
-    proxy_pass https://localhost:5232/;
-    ...
-    # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...).
-    proxy_ssl_certificate         /path/to/client_cert.pem;
-    proxy_ssl_certificate_key     /path/to/client_key.pem;
-    proxy_ssl_trusted_certificate /path/to/server_cert.pem;
-}
-
-
-
-

WSGI

-

Radicale is compatible with the WSGI specification.

-

A configuration file can be set with the RADICALE_CONFIG -environment variable, otherwise no configuration file is loaded and the -default configuration is used.

-

Be reminded that Radicale's default configuration enforces limits on -the maximum upload file size.

-

Security: The None authentication type -disables all rights checking. Don't use it with -REMOTE_USER. Use remote_user instead.

-

Example uWSGI configuration:

-
[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' --workers 8 --env 'RADICALE_CONFIG=/etc/radicale/config' radicale
-
-

Manage user accounts with the WSGI server

-

Set the configuration option type in the -auth section to remote_user. Radicale uses the -user name provided by the WSGI server and disables authentication over -HTTP.

-
-
-
-

Versioning

-

This page describes how to keep track of all changes to calendars and -address books with git (or any other version control -system).

-

The repository must be initialized by running git init -in the file system folder. Internal files of Radicale can be excluded by -creating the file .gitignore with the following -content:

-
.Radicale.cache
-.Radicale.lock
-.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)
-

The command gets executed after every change to the storage and -commits the changes into the git repository.

-
-
-

Clients

-

Radicale has been tested with:

- -

Many clients do not support the creation of new calendars and address -books. You can use Radicale's web interface (e.g. http://localhost:5232) to create and -manage collections.

-

In some clients you can just enter the URL of the Radicale server -(e.g. http://localhost:5232) and your user name. In others, -you have to enter the URL of the collection directly (e.g. -http://localhost:5232/user/calendar).

-
-

DAVx⁵

-

Enter the URL of the Radicale server (e.g. -http://localhost:5232) and your user name. DAVx⁵ will show -all existing calendars and address books and you can create new.

-
-
-

GNOME Calendar, Contacts and Evolution

-

GNOME Calendar and Contacts do not -support adding WebDAV calendars and address books directly, but you can -add them in Evolution.

-

In Evolution add a new calendar and address book -respectively with WebDAV. Enter the URL of the Radicale server (e.g. -http://localhost:5232) and your user name. Clicking on the -search button will list the existing calendars and address books.

-
-
-

Thunderbird

-
-
CardBook
-

Add a new address book on the network with CardDAV. You have to enter -the full URL of the collection (e.g. -http://localhost:5232/user/addressbook) and your user -name.

-
-
-
Lightning
-

Add a new calendar on the network with CalDAV. (Don't -use iCalendar (ICS)!) You have to enter the full URL of the -collection (e.g. http://localhost:5232/user/calendar). If -you want to add calendars from different users on the same server, you -can specify the user name in the URL (e.g. -http://user@localhost...)

-
-
-
-

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.

-
-
-

Manual creation of calendars and address books

-

This is not the recommended way of creating and managing your -calendars and address books. Use Radicale's web interface or a client -with support for it (e.g. DAVx⁵).

-
-
Direct editing of the storage
-

To create a new collection, you have to create the corresponding -folder in the file system storage (e.g. -collection-root/user/calendar). To tell Radicale and -clients that the collection is a calendar, you have to create the file -.Radicale.props with the following content in the -folder:

-
{"tag": "VCALENDAR"}
-

The calendar is now available at the URL path -/user/calendar. For address books the file must -contain:

-
{"tag": "VADDRESSBOOK"}
-

Calendar and address book collections must not have any child -collections. Clients with automatic discovery of collections will only -show calendars and addressbooks that are direct children of the path -/USERNAME/.

-

Delete collections by deleting the corresponding folders.

-
-
-
HTTP requests with curl
-

To create a new calendar run something like:

-
$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \
-'<?xml version="1.0" encoding="UTF-8" ?>
-<create xmlns="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:I="http://apple.com/ns/ical/">
-  <set>
-    <prop>
-      <resourcetype>
-        <collection />
-        <C:calendar />
-      </resourcetype>
-      <C:supported-calendar-component-set>
-        <C:comp name="VEVENT" />
-        <C:comp name="VJOURNAL" />
-        <C:comp name="VTODO" />
-      </C:supported-calendar-component-set>
-      <displayname>Calendar</displayname>
-      <C:calendar-description>Example calendar</C:calendar-description>
-      <I:calendar-color>#ff0000ff</I:calendar-color>
-    </prop>
-  </set>
-</create>'
-

To create a new address book run something like:

-
$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \
-'<?xml version="1.0" encoding="UTF-8" ?>
-<create xmlns="DAV:" xmlns:CR="urn:ietf:params:xml:ns:carddav">
-  <set>
-    <prop>
-      <resourcetype>
-        <collection />
-        <CR:addressbook />
-      </resourcetype>
-      <displayname>Address book</displayname>
-      <CR:addressbook-description>Example address book</CR:addressbook-description>
-    </prop>
-  </set>
-</create>'
-

The collection /USERNAME will be created automatically, -when the user authenticates to Radicale for the first time. Clients with -automatic discovery of collections will only show calendars and address -books that are direct children of the path /USERNAME/.

-

Delete the collections by running something like:

-
$ curl -u user -X DELETE 'http://localhost:5232/user/calendar'
-
-
-
-
-

Configuration

-

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
-
-[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:

-
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:5232

-
-
-
daemon
-

Daemonize the Radicale process. It does not reset the umask.

-

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: 100000000

-
-
-
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 user name -from the certifcate.

-

Default:

-
-
-
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. It also -disables rights checking.

-

htpasswd : Use an Apache -htpasswd file to store usernames and passwords.

-

remote_user : Takes the user name from the -REMOTE_USER environment variable and disables HTTP -authentication. This can be used to provide the user name from a WSGI -server.

-

http_x_remote_user : Takes the user name from the -X-Remote-User HTTP header and disables HTTP authentication. -This can be used to provide the user name from a reverse proxy.

-

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 -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:

-
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). -It's insecure!

-

Default: bcrypt

-
-
-
delay
-

Average delay after failed login attempts in seconds.

-

Default: 1

-
-
-
-

rights

-
-
type
-

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

-

The recommended backend is owner_only. If access to -calendars and address books outside of the home directory of users -(that's /USERNAME/) is granted, clients won't detect these -collections and will not show them to the user. Choosing any other -method is only useful if you access calendars and address books directly -via URL.

-

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 page.

-
-
-
-

storage

-
-
type
-

The backend that is used to store data.

-

Available backends:

-

multifilesystem : Stores the data in the filesystem.

-

Default: multifilesystem

-
-
-
filesystem_folder
-

Folder for storing local collections, created if not present.

-

Default: /var/lib/radicale/collections

-
-
-
filesystem_locking
-

Lock the storage. This must be disabled if locking is not supported -by the underlying file system. Never start multiple instances of -Radicale or edit the storage externally while Radicale is running if -disabled.

-

Default: True

-
-
-
max_sync_token_age
-

Delete sync-token that are older than the specified time. -(seconds)

-

Default: 2592000

-
-
-
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 page for an example.

-

Default:

-
-
-
-

web

-
-
type
-

The backend that provides the web interface of Radicale.

-

Available backends:

-

none : Just shows the message "Radicale works!".

-

internal : Allows creation and management of address -books and calendars.

-

Default: internal

-
-
-
-

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 -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:

-
Access-Control-Allow-Origin = *
-
-
-
-

Authentication and Rights

-

This page describes the format of the rights file for the -from_file authentication backend. The configuration option -file in the rights section must point to the -rights file.

-

The recommended rights method is owner_only. If access -to calendars and address books outside of the home directory of users -(that's /USERNAME/) is granted, clients won't detect these -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:

-
# The user "admin" can read and write any collection.
-[admin]
-user = admin
-collection = .*
-permission = rw
-
-# Block access for the user "user" to everything.
-[block]
-user = user
-collection = .*
-permission =
-
-# Authenticated users can read and write their own collections.
-[owner-write]
-user = .+
-collection = %(login)s(/.*)?
-permission = rw
-
-# Everyone can read the root collection
-[read]
-user = .*
-collection =
-permission = r
-

The titles of the sections are ignored (but must be unique). The keys -user and collection contain regular -expressions, that are matched against the user name and the path of the -collection. Permissions from the first matching section are used. If no -section matches, access gets denied.

-

The user name is empty for anonymous users. Therefore, the regex -.+ only matches authenticated users and .* -matches everyone (including anonymous users).

-

The path of the collection is separated by / and has no -leading or trailing /. Therefore, the path of the root -collection is empty.

-

%(login)s gets replaced by the user name and -%(path)s by the path of the collection. You can also get -groups from the user regex in the collection -regex with {0}, {1}, etc.

-
-
-

Storage

-

This document describes the layout and format of the file system -storage (multifilesystem backend).

-

It's safe to access and manipulate the data by hand or with scripts. -Scripts can be invoked manually, periodically (e.g. with cron) -or after each change to the storage with the configuration option -hook in the storage section (e.g. Git Versioning).

-
-

Layout

-

The file system contains the following files and folders:

-
    -
  • .Radicale.lock: The lock file for locking the -storage.
    • -
  • collection-root: This folder contains all collections -and items.
    • -
-

A collection is represented by a folder. This folder may contain the -file .Radicale.props with all WebDAV properties of the -collection encoded as JSON.

-

An item is represented by a file containing the iCalendar data.

-

All files and folders, whose names start with a dot but not -.Radicale. (internal files) are ignored.

-

If you introduce syntax errors in any of the files, all requests that -access the faulty data will fail. The logging output should contain the -names of the culprits.

-

Future releases of Radicale 2.x.x will store caches and sync-tokens -in the .Radicale.cache folder inside of collections. This -folder may be created or modified, while the storage is locked for -shared access. In theory, it should be safe to delete the folder. Caches -will be recreated automatically and clients will be told that their -sync-token isn't valid anymore.

-

You may encounter files or folders that start with -.Radicale.tmp-. Radicale uses them for atomic creation and -deletion of files and folders. They should be deleted after requests are -finished but it's possible that they are left behind when Radicale or -the computer crashes. It's safe to delete them.

-
-
-

Locking

-

When the data is accessed by hand or by an externally invoked script, -the storage must be locked. The storage can be locked for exclusive or -shared access. It prevents Radicale from reading or writing the file -system. The storage is locked with exclusive access while the -hook runs.

-
-
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
-
-
-
Linux and MacOS
-

Use the flock -syscall. Python provides it in the fcntl -module.

-
-
-
Windows
-

Use LockFile -for exclusive access or LockFileEx -which also supports shared access. Setting -nNumberOfBytesToLockLow to 1 and -nNumberOfBytesToLockHigh to 0 works.

-
-
-
-
-

Logging

-

Radicale logs to stderr. The verbosity of the log output -can be controlled with --debug command line argument or the -debug configuration option in the logging -section.

-

This is the recommended configuration for use with modern init -systems (like systemd) or if you just test Radicale in -a terminal.

-

You can configure Radicale to write its logging output to files (and -even rotate them). This is useful if the process daemonizes or if your -chosen method of running Radicale doesn't handle logging output.

-

A logging configuration file can be specified in the -config configuration option in the logging -section. The file format is explained in the Python -Logging Module.

-
-

Logging to a file

-

An example configuration to write the log output to the file -/var/log/radicale/log:

-
[loggers]
-keys = root
-
-[handlers]
-keys = file
-
-[formatters]
-keys = full
-
-[logger_root]
-# Change this to DEBUG or INFO for higher verbosity.
-level = WARNING
-handlers = file
-
-[handler_file]
-class = FileHandler
-# Specify the output file here.
-args = ('/var/log/radicale/log',)
-formatter = full
-
-[formatter_full]
-format = %(asctime)s - [%(thread)x] %(levelname)s: %(message)s
-

You can specify multiple logger, -handler and formatter if you want to -have multiple simultaneous log outputs.

-

The parent folder of the log files must exist and must be writable by -Radicale.

-

Security: The log files should not be readable by -unauthorized users. Set permissions accordingly.

-
-
Timed rotation of disk log files
-

An example handler configuration to write the log -output to the file /var/log/radicale/log and rotate it. -Replace the section handler_file from the file logging -example:

-
[handler_file]
-class = handlers.TimedRotatingFileHandler
-# Specify the output file and parameter for rotation here.
-# See https://docs.python.org/3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler
-# Example: rollover at midnight and keep 7 files (means one week)
-args = ('/var/log/radicale/log', 'midnight', 1, 7)
-formatter = full
-
-
-
Rotation of disk log files based on size
-

An example handler configuration to write the log -output to the file /var/log/radicale/log and rotate it . -Replace the section handle_file from the file logging -example:

-
[handler_file]
-class = handlers.RotatingFileHandler
-# Specify the output file and parameter for rotation here.
-# See https://docs.python.org/3/library/logging.handlers.html#logging.handlers.RotatingFileHandler
-# Example: rollover at 100000 kB and keep 10 files (means 1 MB)
-args = ('/var/log/radicale/log', 'a', 100000, 10)
-formatter = full
-
-
-
-
-

Architecture

-

Radicale is a really small piece of software, but understanding it is -not as easy as it seems. But don't worry, reading this short page is -enough to understand what a CalDAV/CardDAV server is, and how Radicale's -code is organized.

-
-

General Architecture

-

Here is a simple overview of the global architecture for reaching a -calendar or an address book through network:

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PartLayerProtocol or Format
ServerCalendar/Contact StorageiCal/vCard
Calendar/Contact ServerCalDAV/CardDAV Server
TransferNetworkCalDAV/CardDAV (HTTP + TLS)
ClientCalendar/Contact ClientCalDAV/CardDAV Client
GUITerminal, GTK, Web interface, etc.
-

Radicale is only the server part of this -architecture.

-

Please note that:

-
    -
  • CalDAV and CardDAV are superset protocols of WebDAV,
    • -
  • WebDAV is a superset protocol of HTTP.
    • -
-

Radicale being a CalDAV/CardDAV server, it also can be seen as a -special WebDAV and HTTP server.

-

Radicale is not the client part of this -architecture. It means that Radicale never draws calendars, address -books, events and contacts on the screen. It only stores them and give -the possibility to share them online with other people.

-

If you want to see or edit your events and your contacts, you have to -use another software called a client, that can be a "normal" -applications with icons and buttons, a terminal or another web -application.

-
-
-

Code Architecture

-

The radicale package offers 9 modules.

-

__main__ : The main module provides a simple function -called run. Its main work is to read the configuration from the -configuration file and from the options given in the command line; then -it creates a server, according to the configuration.

-

__init__ : This is the core part of the module, with the -code for the CalDAV/CardDAV server. The server inherits from a -WSGIServer server class, which relies on the default HTTP server class -given by Python. The code managing the different HTTP requests according -to the CalDAV/CardDAV normalization is written here.

-

config : This part gives a dict-like access to the -server configuration, read from the configuration file. The -configuration can be altered when launching the executable with some -command line options.

-

xmlutils : The functions defined in this module are -mainly called by the CalDAV/CardDAV server class to read the XML part of -the request, read or alter the calendars, and create the XML part of the -response. The main part of this code relies on ElementTree.

-

log : The start function provided by this module starts -a logging mechanism based on the default Python logging module. Logging -options can be stored in a logging configuration file.

-

auth : This module provides a default authentication -manager equivalent to Apache's htpasswd. Login + password couples are -stored in a file and used to authenticate users. Passwords can be -encrypted using various methods. Other authentication methods can -inherit from the base class in this file and be provided as plugins.

-

rights : This module is a set of Access Control Lists, a -set of methods used by Radicale to manage rights to access the -calendars. When the CalDAV/CardDAV server is launched, an Access Control -List is chosen in the set, according to the configuration. The HTTP -requests are then filtered to restrict the access depending on who is -authenticated. Other configurations can be written using regex-based -rules. Other rights managers can also inherit from the base class in -this file and be provided as plugins.

-

storage : In this module are written the classes -representing collections and items in Radicale, and the class storing -these collections and items in your filesystem. Other storage classes -can inherit from the base class in this file and be provided as -plugins.

-

web : This module contains the web interface.

-
-
-
-

Plugins

-

Radicale can be extended by plugins for authentication, rights -management and storage. Plugins are python modules.

-
-

Getting started

-

To get started we walk through the creation of a simple -authentication plugin, that accepts login attempts if the username and -password are equal.

-

The easiest way to develop and install python -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_silly_auth", packages=["radicale_silly_auth"])
-

In the same folder create the sub-folder -radicale_silly_auth. The folder must have the same name as -specified in packages above.

-

Create the file __init__.py in the -radicale_silly_auth folder with the following content:

-
from radicale.auth import BaseAuth
-
-
-class Auth(BaseAuth):
-    def is_authenticated(self, user, password):
-        # Example custom configuration option
-        foo = ""
-        if self.configuration.has_option("auth", "foo"):
-            foo = self.configuration.get("auth", "foo")
-        self.logger.info("Configuration option %r is %r", "foo", foo)
-
-        # Check authentication
-        self.logger.info("Login attempt by %r with password %r",
-                         user, password)
-        return user == password
-

Install the python module by running the following command in the -same folder as setup.py:

-
python3 -m pip install --upgrade .
-

To make use this great creation in Radicale, set the configuration -option type in the auth section to -radicale_silly_auth:

-
[auth]
-type = radicale_silly_auth
-foo = bar
-

You can uninstall the module with:

-
python3 -m pip uninstall radicale_silly_auth
-
-
-

Authentication plugins

-

This plugin type is used to check login credentials. The module must -contain a class Auth that extends -radicale.auth.BaseAuth. Take a look at the file -radicale/auth.py in Radicale's source code for more -information.

-
-
-

Rights management plugins

-

This plugin type is used to check if a user has access to a path. The -module must contain a class Rights that extends -radicale.rights.BaseRights. Take a look at the file -radicale/rights.py in Radicale's source code for more -information.

-
-
-

Web plugins

-

This plugin type is used to provide the web interface for Radicale. -The module must contain a class Web that extends -radicale.web.BaseWeb. Take a look at the file -radicale/web.py in Radicale's source code for more -information.

-
-
-

Storage plugins

-

This plugin is used to store collections and items. The module must -contain a class Collection that extends -radicale.storage.BaseCollection. Take a look at the file -radicale/storage.py in Radicale's source code for more -information.

-
-
-
-

Migration from 1.x.x to 2.x.x

-
-

Why a Migration?

-

Radicale 2.x.x is different from 1.x.x, here's everything you need to -know about this! Please read this page carefully if you want to -update Radicale.

-

You'll also find extra information in issue #372.

-
-
-

Python 3 Only

-

Radicale 2.x.x works with Python >= 3.3, and doesn't work -anymore with Python 2.

-

(No, Python 3.3 is not new, it's been released more than 4 years ago. -Debian stable provides Python 3.4.)

-
-
-

Dependencies

-

Radicale now depends on VObject, a -"full-featured Python package for parsing and creating iCalendar and -vCard files". That's the price to pay to correctly read crazy iCalendar -files and support date-based filters, even on recurring -events.

-
-
-

Storage

-

Calendars and address books are stored in a different way between -1.x.x and 2.x.x versions. Launching 2.x.x without migrating your -collections first will not work, Radicale won't be able to read your -previous data.

-

There's now only one way to store data in Radicale: collections are -stored as folders and events / contacts are stored in files. This new -storage is close to the multifilesystem, but it's -now thread-safe, with atomic writes and file locks. Other -storage types can be used by creating plugins.

-

To migrate data to Radicale 2.x.x the command line argument ---export-storage was added to Radicale 1.1.x. Start -Radicale 1.x.x as you would normally do, but add the argument ---export-storage path/to/empty/folder. Radicale will export -the storage into the specified folder. This folder can be directly used -with the default storage backend of Radicale 2.x.x.

-

If you import big calendars or address books into Radicale 2.x.x the -first request might take a long time, because it has to initialize its -internal caches. Clients can time out, subsequent requests will be much -faster.

-

You can check the imported storage for errors by starting Radicale ->= 2.1.5 with the --verify-storage argument.

-

You can install version 1.1.x with:

-
$ python3 -m pip install --upgrade radicale==1.1.*
-
-
-

Authentication

-

Radicale 2.x.x only provides htpasswd authentication -out-of-the-box. Other authentication methods can be added by -creating or using plugins.

-
-
-

Rights

-

In Radicale 2.x.x, rights are managed using regex-based rules based -on the login of the authenticated user and the URL of the resource. -Default configurations are built in for common cases, you'll find more -about this on the Authentication -& Rights page.

-

Other rights managers can be added by creating plugins.

-
-
-

Versioning

-

Support for versioning with git was removed from -Radicale 2.x.x. Instead, the configuration option hook in -the storage section was added, the Collection Versioning page explains its usage for -version control.

-
-
-
-
-

Contribute

-
-

Chat with Us on IRC

-

Want to say something? Join our IRC room: ##kozea on -Freenode.

-
-
-

Report Bugs

-

Found a bug? Want a new feature? Report a new issue on the Radicale -bug-tracker.

-
-
-

Hack

-

Interested in hacking? Feel free to clone the git repository on Github if -you want to add new features, fix bugs or update the documentation.

-
-
-

Documentation

-

To change or complement the documentation create a pull request to DOCUMENTATION.md.

-
-
-
-

Download

-
-

PyPI

-

Radicale is available on PyPI. To -install, just type as superuser:

-
$ python3 -m pip install --upgrade radicale==2.1.*
-
-
-

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 git+https://github.com/Kozea/Radicale
-

You can also download the content of the repository as an archive.

-
-
-

Source Packages

-

You can download the Radicale package for each release:

- -
-
-

Linux Distribution Packages

-

Radicale has been packaged for:

- -

Radicale is also available -on Cloudron and has a Dockerfile.

-

If you are interested in creating packages for other Linux -distributions, read the "Contribute" page.

-
-
-
-

About

-
-

Main Goals

-

Radicale is a complete calendar and contact storing and manipulating -solution. It can store multiple calendars and multiple address -books.

-

Calendar and contact manipulation is available from both local and -distant accesses, possibly limited through authentication policies.

-

It aims to be a lightweight solution, easy to use, easy to install, -easy to configure. As a consequence, it requires few software -dependencies and is pre-configured to work out-of-the-box.

-

Radicale is written in Python. It runs on most of the UNIX-like -platforms (Linux, *BSD, macOS) and Windows. It is free and open-source -software.

-
-
-

What Radicale Will Never Be

-

Radicale is a server, not a client. No interfaces will be created to -work with the server, as it is a really (really really) much more -difficult task.

-

CalDAV and CardDAV are not perfect protocols. We think that their -main problem is their complexity, that is why we decided not to -implement the whole standard but just enough to understand some of its -client-side implementations.

-

CalDAV and CardDAV are the best open standards available and they are -quite widely used by both clients and servers. We decided to use it, and -we will not use another one.

-
-
-

Technical Choices

-

Important global development choices have been decided before writing -code. They are very useful to understand why the Radicale Project is -different from other CalDAV and CardDAV servers, and why features are -included or not in the code.

-
-
Oriented to Calendar and Contact User Agents
-

Calendar and contact servers work with calendar and contact clients, -using a defined protocol. CalDAV and CardDAV are good protocols, -covering lots of features and use cases, but it is quite hard to -implement fully.

-

Some calendar servers have been created to follow the CalDAV and -CardDAV RFCs as much as possible: Davical, Baïkal and Darwin Calendar Server, for -example, are much more respectful of CalDAV and CardDAV and can be used -with a large number of clients. They are very good choices if you want -to develop and test new CalDAV clients, or if you have a possibly -heterogeneous list of user agents.

-

Even if it tries it best to follow the RFCs, Radicale does not and -will not blindly implements the CalDAV and CardDAV -standards. It is mainly designed to support the CalDAV and CardDAV -implementations of different clients.

-
-
-
Simple
-

Radicale is designed to be simple to install, simple to configure, -simple to use.

-

The installation is very easy, particularly with Linux: one -dependency, no superuser rights needed, no configuration required, no -database. Installing and launching the main script out-of-the-box, as a -normal user, are often the only steps to have a simple remote calendar -and contact access.

-

Contrary to other servers that are often complicated, require high -privileges or need a strong configuration, the Radicale Server can -(sometimes, if not often) be launched in a couple of minutes, if you -follow the tutorial.

-
-
-
Lazy
-

The CalDAV RFC defines what must be done, what can be done and what -cannot be done. Many violations of the protocol are totally defined and -behaviours are given in such cases.

-

Radicale often assumes that the clients are perfect and that protocol -violations do not exist. That is why most of the errors in client -requests have undetermined consequences for the lazy server that can -reply good answers, bad answers, or even no answer.

-
-
-
-

History

-

Radicale has been started as a (free topic) stupid school project -replacing another (assigned topic) even more stupid school project.

-

At the beginning, it was just a proof-of-concept. The main goal was -to write a small, dirty and simple CalDAV server working with Lightning, -using no external libraries. That's how we created a piece of code -that's (quite) easy to understand, to use and to hack.

-

The first -lines have been added to the SVN (!) repository as I was drinking -(many) beers at the very end of 2008 (Python 2.6 and 3.0 were just -released). It's now packaged for a growing number of Linux -distributions.

-

And that was fun going from here to there thanks to you!

-
-
-
-

News

-

Latest version of Radicale is 2.1.12, released on May 19, 2020 (changelog).

-
-

May 19, 2020 - Radicale 2.1.12

-

Radicale 2.1.12 is out!

-
-

2.1.12 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Include documentation in source archive
    • -
-
-
-
-

November 5, 2018 - Radicale 2.1.11

-

Radicale 2.1.11 is out!

-
-

2.1.11 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Fix moving items between collections
    • -
-
-
-
-

August 16, 2018 - Radicale 2.1.10

-

Radicale 2.1.10 is out!

-
-

2.1.10 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Update required versions for dependencies
    • -
  • Get RADICALE_CONFIG from WSGI environ
    • -
  • Improve HTTP status codes
    • -
  • Fix race condition in storage lock creation
    • -
  • Raise default limits for content length and timeout
    • -
  • Log output from hook
    • -
-
-
-
-

April 21, 2018 - Radicale 2.1.9

-

Radicale 2.1.9 is out!

-
-

2.1.9 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Specify versions for dependencies
    • -
  • Move WSGI initialization into module
    • -
  • Check if REPORT method is actually supported
    • -
  • Include rights file in source distribution
    • -
  • Specify md5 and bcrypt as extras
    • -
  • Improve logging messages
    • -
  • Windows: Fix crash when item path is a directory
    • -
-
-
-
-

September 24, 2017 - Radicale 2.1.8

-

Radicale 2.1.8 is out!

-
-

2.1.8 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Flush files before fsync'ing
    • -
-
-
-
-

September 17, 2017 - Radicale 2.1.7

-

Radicale 2.1.7 is out!

-
-

2.1.7 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Don't print warning when cache format changes
    • -
  • Add documentation for BaseAuth
    • -
  • Add is_authenticated2(login, user, password) to -BaseAuth
    • -
  • Fix names of custom properties in PROPFIND requests with -D:propname or D:allprop
    • -
  • Return all properties in PROPFIND requests with -D:propname or D:allprop
    • -
  • Allow D:displayname property on all collections
    • -
  • Answer with D:unauthenticated for -D:current-user-principal property when not logged in
    • -
  • Remove non-existing ICAL:calendar-color and -C:calendar-timezone properties from PROPFIND requests with -D:propname or D:allprop
    • -
  • Add D:owner property to calendar and address book -objects
    • -
  • Remove D:getetag and D:getlastmodified -properties from regular collections
    • -
-
-
-
-

September 11, 2017 - Radicale 2.1.6

-

Radicale 2.1.6 is out!

-
-

2.1.6 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Fix content-type of VLIST
    • -
  • Specify correct COMPONENT in content-type of VCALENDAR
    • -
  • Cache COMPONENT of calendar objects (improves speed with some -clients)
    • -
  • Stricter parsing of filters
    • -
  • Improve support for CardDAV filter
    • -
  • Fix some smaller bugs in CalDAV filter
    • -
  • Add X-WR-CALNAME and X-WR-CALDESC to calendars downloaded via -HTTP/WebDAV
    • -
  • Use X-WR-CALNAME and X-WR-CALDESC from calendars published via -WebDAV
    • -
-
-
-
-

August 25, 2017 - Radicale 2.1.5

-

Radicale 2.1.5 is out!

-
-

2.1.5 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Add --verify-storage command-line argument
    • -
  • Allow comments in the htpasswd file
    • -
  • Don't strip whitespaces from user names and passwords in the -htpasswd file
    • -
  • Remove cookies from logging output
    • -
  • Allow uploads of whole collections with many components
    • -
  • Show warning message if server.timeout is used with Python < -3.5.2
    • -
-
-
-
-

August 4, 2017 - Radicale 2.1.4

-

Radicale 2.1.4 is out!

-
-

2.1.4 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Fix incorrect time range matching and calculation for some -edge-cases with rescheduled recurrences
    • -
  • Fix owner property
    • -
-
-
-
-

August 2, 2017 - Radicale 2.1.3

-

Radicale 2.1.3 is out!

-
-

2.1.3 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Enable timeout for SSL handshakes and move them out of the main -thread
    • -
  • Create cache entries during upload of items
    • -
  • Stop built-in server on Windows when Ctrl+C is pressed
    • -
  • Prevent slow down when multiple requests hit a collection during -cache warm-up
    • -
-
-
-
-

July 24, 2017 - Radicale 2.1.2

-

Radicale 2.1.2 is out!

-
-

2.1.2 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Remove workarounds for bugs in VObject < 0.9.5
    • -
  • Error checking of collection tags and associated components
    • -
  • Improve error checking of uploaded collections and components
    • -
  • Don't delete empty collection properties implicitly
    • -
  • Improve logging of VObject serialization
    • -
-
-
-
-

July 1, 2017 - Radicale 2.1.1

-

Radicale 2.1.1 is out!

-
-

2.1.1 - Wild Radish Again

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.x.x.

-
    -
  • Add missing UIDs instead of failing
    • -
  • Improve error checking of calendar and address book objects
    • -
  • Fix upload of whole address books
    • -
-
-
-
-

June 25, 2017 - Radicale 2.1.0

-

Radicale 2.1.0 is out!

-
-

2.1.0 - Wild Radish

-

This release is compatible with version 2.0.0. Follow our migration guide if you want to -switch from 1.x.x to 2.1.0.

-
    -
  • Built-in web interface for creating and managing address books and -calendars -
      -
    • can be extended with web plugins
      • -
    • -
  • Much faster storage backend
    • -
  • Significant reduction in memory usage
    • -
  • Improved logging -
      -
    • Include paths (of invalid items / requests) in log messages
      • -
    • Include configuration values causing problems in log messages
      • -
    • Log warning message for invalid requests by clients
      • -
    • Log error message for invalid files in the storage backend
      • -
    • No stack traces unless debugging is enabled
      • -
    • -
  • Time range filter also regards overwritten recurrences
    • -
  • Items that couldn't be filtered because of bugs in VObject are -always returned (and a warning message is logged)
    • -
  • Basic error checking of configuration files
    • -
  • File system locking isn't disabled implicitly anymore, instead a new -configuration option gets introduced
    • -
  • The permissions of the lock file are not changed anymore
    • -
  • Support for sync-token
    • -
  • Support for client-side SSL certificates
    • -
  • Rights plugins can decide if access to an item is granted explicitly -
      -
    • Respond with 403 instead of 404 for principal collections of -non-existing users when owner_only plugin is used -(information leakage)
      • -
    • -
  • Authentication plugins can provide the login and password from the -environment -
      -
    • new remote_user plugin, that gets the login from the -REMOTE_USER environment variable (for WSGI server)
      • -
    • new http_x_remote_user plugin, that gets the login from -the X-Remote-User HTTP header (for reverse proxies)
      • -
    • -
-
-
-
-

May 27, 2017 - Radicale 2.0.0

-

Radicale 2.0.0 is out!

-
-

2.0.0 - Little Big Radish

-

This feature is not compatible with the 1.x.x versions. Follow our migration guide if you want to -switch from 1.x.x to 2.0.0.

-
    -
  • Support Python 3.3+ only, Python 2 is not supported anymore
    • -
  • Keep only one simple filesystem-based storage system
    • -
  • Remove built-in Git support
    • -
  • Remove built-in authentication modules
    • -
  • Keep the WSGI interface, use Python HTTP server by default
    • -
  • Use a real iCal parser, rely on the "vobject" external module
    • -
  • Add a solid calendar discovery
    • -
  • Respect the difference between "files" and "folders", don't rely on -slashes
    • -
  • Remove the calendar creation with GET requests
    • -
  • Be stateless
    • -
  • Use a file locker
    • -
  • Add threading
    • -
  • Get atomic writes
    • -
  • Support new filters
    • -
  • Support read-only permissions
    • -
  • Allow External plugins for authentication, rights management, -storage and version control
    • -
-

This release concludes endless months of hard work from the -community. You, all users and contributors, deserve a big thank -you.

-

This project has been an increadible experience for me, your dear -Guillaume, creator and maintainer of Radicale. After more than 8 years -of fun, I think that it's time to open this software to its -contributors. Radicale can grow and become more than the toy it used to -be. I've always seen Radicale as a small and simple piece of code, and I -don't want to prevent people from adding features just because I can't -or don't want to maintain them. The community is now large enough to -handle this.

-

If you're interested in Radicale, you can read #372 and build -its future.

-
-
-
-

May 3, 2017 - Radicale 1.1.2

-

Radicale 1.1.2 is out!

-
-

1.1.2 - Third Law of Nature

-
    -
  • Security fix: Add a random timer to avoid timing -oracles and simple bruteforce attacks when using the htpasswd -authentication method.
    • -
  • Various minor fixes.
    • -
-
-
-
-

December 31, 2015 - Radicale 1.1

-

Radicale 1.1 is out!

-
-

1.1 - Law of Nature

-

One feature in this release is not backward -compatible:

-
    -
  • Use the first matching section for rights (inspired from daald)
    • -
-

Now, the first section matching the path and current user in your -custom rights file is used. In the previous versions, the most -permissive rights of all the matching sections were applied. This new -behaviour gives a simple way to make specific rules at the top of the -file independant from the generic ones.

-

Many improvements in this release are related to -security, you should upgrade Radicale as soon as possible:

-
    -
  • Improve the regex used for well-known URIs (by Unrud)
    • -
  • Prevent regex injection in rights management (by Unrud)
    • -
  • Prevent crafted HTTP request from calling arbitrary functions (by -Unrud)
    • -
  • Improve URI sanitation and conversion to filesystem path (by -Unrud)
    • -
  • Decouple the daemon from its parent environment (by Unrud)
    • -
-

Some bugs have been fixed and little enhancements have been -added:

-
    -
  • Assign new items to corret key (by Unrud)
    • -
  • Avoid race condition in PID file creation (by Unrud)
    • -
  • Improve the docker version (by cdpb)
    • -
  • Encode message and commiter for git commits
    • -
  • Test with Python 3.5
    • -
-
-
-
-

September 14, 2015 - Radicale 1.0, what's next?

-

Radicale 1.0 is out!

-
-

1.0 - Sunflower

-
    -
  • Enhanced performances (by Mathieu Dupuy)
    • -
  • Add MD5-APR1 and BCRYPT for htpasswd-based authentication (by -Jan-Philip Gehrcke)
    • -
  • Use PAM service (by Stephen Paul Weber)
    • -
  • Don't discard PROPPATCH on empty collections (Markus -Unterwaditzer)
    • -
  • Write the path of the collection in the git message (Matthew -Monaco)
    • -
  • Tests launched on Travis
    • -
-

As explained in a previous mail, -this version is called 1.0 because:

-
    -
  • there are no big changes since 0.10 but some small changes are -really useful,
    • -
  • simple tests are now automatically launched on Travis, and more can -be added in the future (https://travis-ci.org/Kozea/Radicale).
    • -
-

This version will be maintained with only simple bug fixes on a -separate git branch called 1.0.x.

-

Now that this milestone is reached, it's time to think about the -future. When Radicale has been created, it was just a proof-of-concept. -The main goal was to write a small, stupid and simple CalDAV server -working with Lightning, using no external libraries. That's how we -created a piece of code that's (quite) easy to understand, to use and to -hack.

-

The first lines have been added to the SVN (!) repository as I was -drinking beers at the very end of 2008. It's now packaged for a growing -number of Linux distributions.

-

And that was fun going from here to there thanks to you. So… -Thank you, you're amazing. I'm so glad I've spent -endless hours fixing stupid bugs, arguing about databases and meeting -invitations, reading incredibly interesting RFCs and debugging with the -fabulous clients from Apple. I mean: that really, really was really, -really cool :).

-

During these years, a lot of things have changed and many users now -rely on Radicale in production. For example, I use it to manage medical -calendars, with thousands requests per day. Many people are happy to -install Radicale on their small home servers, but are also frustrated by -performance and unsupported specifications when they're trying to use it -seriously.

-

So, now is THE FUTURE! I think that Radicale 2.0 should:

-
    -
  • rely on a few external libraries for simple critical points (dealing -with HTTP and iCal for example),
    • -
  • be thread-safe,
    • -
  • be small,
    • -
  • be documented in a different way (for example by splitting the -client part from the server part, and by adding use cases),
    • -
  • let most of the "auth" modules outside in external modules,
    • -
  • have more and more tests,
    • -
  • have reliable and faster filesystem and database storage -mechanisms,
    • -
  • get a new design :).
    • -
-

I'd also secretly love to drop the Python 2.x support.

-

These ideas are not all mine (except from the really, really, really -important "design" point :p), they have been proposed by many developers -and users. I've just tried to gather them and keep points that seem -important to me.

-

Other points have been discussed with many users and contibutors, -including:

-
    -
  • support of other clients, including Windows and BlackBerry -phones,
    • -
  • server-side meeting invitations,
    • -
  • different storage system as default (or even unique?).
    • -
-

I'm not a huge fan of these features, either because I can't do -anything about them, or because I think that they're Really Bad Ideas®™. -But I'm ready to talk about them, because, well, I may not be always -right!

-

Need to talk about this? You know how to contact us!

-
-
-
-

January 12, 2015 - Radicale 0.10

-

Radicale 0.10 is out!

-
-

0.10 - Lovely Endless Grass

-
    -
  • Support well-known URLs (by Mathieu Dupuy)
    • -
  • Fix collection discovery (by Markus Unterwaditzer)
    • -
  • Reload logger config on SIGHUP (by Élie Bouttier)
    • -
  • Remove props files when deleting a collection (by Vincent Untz)
    • -
  • Support salted SHA1 passwords (by Marc Kleine-Budde)
    • -
  • Don't spam the logs about non-SSL IMAP connections to localhost (by -Giel van Schijndel)
    • -
-

This version should bring some interesting discovery and -auto-configuration features, mostly with Apple clients.

-

Lots of love and kudos for the people who have spent hours to test -features and report issues, that was long but really useful (and some of -you have been really patient :p).

-

Issues are welcome, I'm sure that you'll find horrible, terrible, -crazy bugs faster than me. I'll release a version 0.10.1 if needed.

-

What's next? It's time to fix and improve the storage methods. A real -API for the storage modules is a good beginning, many pull requests are -already ready to be discussed and merged, and we will probably get some -good news about performance this time. Who said "databases, please"?

-
-
-
-

July 12, 2013 - Radicale 0.8

-

Radicale 0.8 is out!

-
-

0.8 - Rainbow

-
    -
  • New authentication and rights management modules (by Matthias -Jordan)
    • -
  • Experimental database storage
    • -
  • Command-line option for custom configuration file (by Mark -Adams)
    • -
  • Root URL not at the root of a domain (by Clint Adams, Fabrice -Bellet, Vincent Untz)
    • -
  • Improved support for iCal, CalDAVSync, CardDAVSync, CalDavZAP and -CardDavMATE
    • -
  • Empty PROPFIND requests handled (by Christoph Polcin)
    • -
  • Colon allowed in passwords
    • -
  • Configurable realm message
    • -
-

This version brings some of the biggest changes since Radicale's -creation, including an experimental support of database storage, clean -authentication modules, and rights management finally designed for real -users.

-

So, dear user, be careful: this version changes important -things in the configuration file, so check twice that everything is OK -when you update to 0.8, or you can have big problems.

-

More and more clients are supported, as a lot of bug fixes and -features have been added for this purpose. And before you ask: yes, 2 -web-based clients, CalDavZAP and -CardDavMATE, are now supported!

-

Even if there has been a lot of time to test these new features, I am -pretty sure that some really annoying bugs have been left in this -version. We will probably release minor versions with bugfixes during -the next weeks, and it will not take one more year to reach 0.8.1.

-

The documentation has been updated, but some parts are missing and -some may be out of date. You can report bugs or even -write -documentation directly on GitHub if you find something strange (and -you probably will).

-

If anything is not clear, or if the way rights work is a bit -complicated to understand, or if you are so happy because everything -works so well, you can share your -thoughts!

-

It has been a real pleasure to work on this version, with brilliant -ideas and interesting bug reports from the community. I'd really like to -thank all the people reporting bugs, chatting on IRC, sending mails and -proposing pull requests: you are awesome.

-
-
-
-

August 3, 2012 - Radicale 0.7.1

-

Radicale 0.7.1 is out!

-
-

0.7.1 - Waterfalls

-
    -
  • Many address books fixes
    • -
  • New IMAP ACL (by Daniel Aleksandersen)
    • -
  • PAM ACL fixed (by Daniel Aleksandersen)
    • -
  • Courier ACL fixed (by Benjamin Frank)
    • -
  • Always set display name to collections (by Oskari Timperi)
    • -
  • Various DELETE responses fixed
    • -
-

It's been a long time since the last version… As usual, many people -have contributed to this new version, that's a pleasure to get these -pull requests.

-

Most of the commits are bugfixes, especially about ACL backends and -address books. Many clients (including aCal and SyncEvolution) will be -much happier with this new version than with the previous one.

-

By the way, one main new feature has been added: a new IMAP ACL -backend, by Daniel. And about authentication, exciting features are -coming soon, stay tuned!

-

Next time, as many mails have come from angry and desperate coders, -tests will be finally added to help them to add features and -fix bugs. And after that, who knows, it may be time to release Radicale -1.0…

-
-
-
-

March 22, 2012 - Radicale 0.7

-

Radicale 0.7 is out, at least!

-
-

0.7 - Eternal Sunshine

-
    -
  • Repeating events
    • -
  • Collection deletion
    • -
  • Courier and PAM authentication methods
    • -
  • CardDAV support
    • -
  • Custom LDAP filters supported
    • -
-

A lot of people have reported bugs, proposed new -features, added useful code and tested many clients. Thank you Lynn, -Ron, Bill, Patrick, Hidde, Gerhard, Martin, Brendan, Vladimir, and -everybody I've forgotten.

-
-
-
-

January 5, 2012 - Radicale 0.6.4, News from Calypso

-

New year, new release. Radicale 0.6.4 has a really short -changelog:

-
-

0.6.4 - Tulips

-
    -
  • Fix the installation with Python 3.1
    • -
-

The bug was in fact caused by a bug in Python 3.1, -everything should be OK now.

-
-
-

Calypso

-

After a lot of changes in Radicale, Keith Packard has decided to -launch a fork called Calypso, with nice features -such as a Git storage mechanism and a CardDAV support.

-

There are lots of differences between the two projects, but the final -goal for Radicale is to provide these new features as soon as possible. -Thanks to the work of Keith and other people on GitHub, a basic CardDAV -support has been added in the carddav branch -and already works with Evolution. Korganizer also works with existing -address books, and CardDAV-Sync will be tested soon. If you want to test -other clients, please let us know!

-
-
-
-

November 3, 2011 - Radicale 0.6.3

-

Radicale version 0.6.3 has been released, with bugfixes that could be -interesting for you!

-
-

0.6.3 - Red Roses

-
    -
  • MOVE requests fixed
    • -
  • Faster REPORT answers
    • -
  • Executable script moved into the package
    • -
-
-
-

What's New Since 0.6.2?

-

The MOVE requests were suffering a little bug that is fixed now. -These requests are only sent by Apple clients, Mac users will be -happy.

-

The REPORT request were really, really slow (several minutes for -large calendars). This was caused by an awful algorithm parsing the -entire calendar for each event in the calendar. The calendar is now only -parsed three times, and the events are found in a Python list, turning -minutes into seconds! Much better, but far from perfection…

-

Finally, the executable script parsing the command line options and -starting the HTTP servers has been moved from the -radicale.py file into the radicale package. -Two executable are now present in the archive: the good old -radicale.py, and bin/radicale. The second one -is only used by setup.py, where the hack used to rename -radicale.py into radicale has therefore been -removed. As a consequence, you can now launch Radicale with the simple -python -m radicale command, without relying on an -executable.

-
-
-

Time for a Stable Release!

-

The next release may be a stable release, symbolically called 1.0. -Guess what's missing? Tests, of course!

-

A non-regression testing suite, based on the clients' requests, will -soon be added to Radicale. We're now thinking about a smart solution to -store the tests, to represent the expected answers and to launch the -requests. We've got crazy ideas, so be prepared: you'll definitely -want to write tests during the next weeks!

-

Repeating events, PAM and Courier authentication methods have already -been added in master. You'll find them in the 1.0 release!

-
-
-

What's Next?

-

Being stable is one thing, being cool is another one. If you want -some cool new features, you may be interested in:

-
    -
  • WebDAV and CardDAV support
    • -
  • Filters and rights management
    • -
  • Multiple storage backends, such as databases and git
    • -
  • Freebusy periods
    • -
  • Email alarms
    • -
-

Issues have been reported in the bug tracker, you can follow there -the latest news about these features. Your beloved text editor is -waiting for you!

-
-
-
-

September 27, 2011 - Radicale 0.6.2

-

0.6.2 is out with minor bugfixes.

-
-

0.6.2 - Seeds

-
    -
  • iPhone and iPad support fixed
    • -
  • Backslashes replaced by slashes in PROPFIND answers on Windows
    • -
  • PyPI archive set as default download URL
    • -
-
-
-
-

August 28, 2011 - Radicale 0.6.1, Changes, Future

-

As previously imagined, a new 0.6.1 version has been released, mainly -fixing obvious bugs.

-
-

0.6.1 - Growing Up

-
    -
  • Example files included in the tarball
    • -
  • htpasswd support fixed
    • -
  • Redirection loop bug fixed
    • -
  • Testing message on GET requests
    • -
-

The changelog is really small, so there should be no real new -problems since 0.6. The example files for logging, FastCGI and WSGI are -now included in the tarball, for the pleasure of our dear packagers!

-

A new branch has been created for various future bug fixes. You can -expect to get more 0.6.x versions, making this branch a kind of "stable" -branch with no big changes.

-
-
-

GitHub, Mailing List, New Website

-

A lot of small changes occurred during the last weeks.

-

If you're interested in code and new features, please note that we -moved the project from Gitorious to GitHub. Being hosted by Gitorious -was a nice experience, but the service was not that good and we were -missing some useful features such as git hooks. Moreover, GitHub is -really popular, we're sure that we'll meet a lot of kind users and -coders there.

-

We've also created a mailing-list on Librelist to keep a public trace -of the mails we're receiving. It a bit empty now, but we're sure that -you'll soon write us some kind words. For example, you can tell us what -you think of our new website!

-
-
-

Future Features

-

In the next weeks, new exciting features are coming in the master -branch! Some of them are almost ready:

-
    -
  • Henry-Nicolas has added the support for the PAM and -Courier-Authdaemon authentication mechanisms.
    • -
  • An anonymous called Keith Packard has prepared some small changes, -such as one file per event, cache and git versioning. Yes. Really.
    • -
-

As you can find in the Radicale Roadmap, tests, -rights and filters are expected for 0.7.

-
-
-
-

August 1, 2011 - Radicale 0.6 Released

-

Time for a new release with a lot of new exciting -features!

-
-

0.6 - Sapling

-
    -
  • WSGI support
    • -
  • IPv6 support
    • -
  • Smart, verbose and configurable logs
    • -
  • Apple iCal 4 and iPhone support (by Łukasz Langa)
    • -
  • CalDAV-Sync support (by Marten Gajda)
    • -
  • aCal support
    • -
  • KDE KOrganizer support
    • -
  • LDAP auth backend (by Corentin Le Bail)
    • -
  • Public and private calendars (by René Neumann)
    • -
  • PID file
    • -
  • MOVE requests management
    • -
  • Journal entries support
    • -
  • Drop Python 2.5 support
    • -
-

Well, it's been a little longer than expected, but for good reasons: -a lot of features have been added, and a lot of clients are known to -work with Radicale, thanks to kind contributors. That's definitely good -news! But…

-

Testing all the clients is really painful, moreover for the ones from -Apple (I have no Mac nor iPhone of my own). We should seriously think of -automated tests, even if it's really hard to maintain, and maybe not -that useful. If you're interested in tests, you can look at the -wonderful regression suite of DAViCal.

-

The new features, for example the WSGI support, are also poorly -documented. If you have some Apache or lighttpd configuration working -with Radicale, you can make the world a little bit better by writing a -paragraph or two in the Radicale -documentation. It's simple plain text, don't be afraid!

-

Because of all these changes, Radicale 0.6 may be a little bit buggy; -a 0.6.1 will probably be released soon, fixing small problems with -clients and features. Get ready to report bugs, I'm sure that you can -find one (and fix it)!

-
-
-
-

July 2, 2011 - Feature Freeze for 0.6

-

According to the roadmap, a -lot of features have been added since Radicale 0.5, much more than -expected. It's now time to test Radicale with your favourite client and -to report bugs before we release the next stable version!

-

Last week, the iCal and iPhone support written by Łukasz has been -fixed in order to restore the broken Lightning support. After two -afternoons of tests with Rémi, we managed to access the same calendar -with Lightning, iCal, iPhone and Evolution, and finally discovered that -CalDAV could also be a perfect instant messaging protocol between a Mac, -a PC and a phone.

-

After that, we've had the nice surprise to see events displayed -without a problem (but after some strange steps of configuration) by -aCal on Salem's Android phone.

-

It was Friday, fun fun fun fun.

-

So, that's it: Radicale supports Lightning, Evolution, Kontact, aCal -for Android, iPhone and iCal. Of course, before releasing a new -tarball:

-
    -
  • documentation -is needed for the new clients that are not documented yet (Kontact, aCal -and iPhone);
    • -
  • tests are welcome, particularly for the Apple clients that I can't -test anymore;
    • -
  • no more features will be added, they'll wait in separate branches -for the 0.7 development.
    • -
-

Please report bugs -if anything goes wrong during your tests, or just let us know by Jabber or by mail if everything is OK.

-
-
-

May 1, 2011 - Ready for WSGI

-

Here it is! Radicale is now ready to be launched behind your -favourite HTTP server (Apache, Lighttpd, Nginx or Tomcat for example). -That's really good news, because:

-
    -
  • Real HTTP servers are much more efficient and reliable than the -default Python server used in Radicale;
    • -
  • All the authentication backends available for your server will be -available for Radicale;
    • -
  • Thanks to flup, Radicale -can be interfaced with all the servers supporting CGI, AJP, FastCGI or -SCGI;
    • -
  • Radicale works very well without any additional server, without any -dependencies, without configuration, just as it was working before;
    • -
  • This one more feature removes useless code, less is definitely -more.
    • -
-

The WSGI support has only be tested as a stand-alone executable and -behind Lighttpd, you should definitely try if it works with you -favourite server too!

-

No more features will be added before (quite) a long time, because a -lot of documentation and test is waiting for us. If you want to write -tutorials for some CalDAV clients support (iCal, Android, iPhone), HTTP -servers support or logging management, feel free to fork the -documentation git repository and ask for a merge. It's plain text, I'm -sure you can do it!

-
-
-

April 30, 2011 - Apple iCal Support

-

After a long, long work, the iCal support has finally been added to -Radicale! Well, this support is only for iCal 4 and is highly -experimental, but you can test it right now with the git master branch. -Bug reports are welcome!

-

Dear MacOS users, you can thank all the gentlemen who sended a lot of -debugging iformation. Special thanks to Andrew from DAViCal, who helped -us a lot with his tips and his tests, and Rémi Hainaud who lent his -laptop for the final tests.

-

The default server address is localhost:5232/user/, -where calendars can be added. Multiple calendars and owner-less -calendars are not tested yet, but they should work quite well. More -documentation will be added during the next days. It will then be time -to release the Radicale 0.6 version, and work on the WSGI support.

-
-
-

April 25, 2011 - Two Features and One New Roadmap

-

Two features have just reached the master branch, and the roadmap has -been refreshed.

-
-

LDAP Authentication

-

Thanks to Corentin, the LDAP authentication is now included in -Radicale. The support is experimental and may suffer unstable connexions -and security problems. If you are interested in this feature (a lot of -people seem to be), you can try it and give some feedback.

-

No SSL support is included yet, but this may be quite easy to add. By -the way, serious authentication methods will rely on a "real" HTTP -server, as soon as Radicale supports WSGI.

-
-
-

Journal Entries

-

Mehmet asked for the journal entries (aka. notes or memos) support, -that's done! This also was an occasion to clean some code in the iCal -parser, and to add a much better management of multi-lines entries. -People experiencing crazy X-RADICALE-NAME entries can now -clean their files, Radicale won't pollute them again.

-
-
-

New Roadmap

-

Except from htpasswd and LDAP, most of the authentication backends -(database, SASL, PAM, user groups) are not really easy to include in -Radicale. The easiest solution to solve this problem is to give Radicale -a CGI support, to put it behind a solid server such as Apache. Of -course, CGI is not enough: a WSGI support is quite better, with the -FastCGI, AJP and SCGI backends offered by flup. Quite exciting, isn't -it?

-

That's why it was important to add new versions on the roadmap. The -0.6 version is now waiting for the Apple iCal support, and of course for -some tests to kill the last remaining bugs. The only 0.7 feature will be -WSGI, allowing many new authentication methods and a real multithread -support.

-

After that, 0.8 may add CalDAV rights and filters, while 1.0 will -draw thousands of rainbows and pink unicorns (WebDAV sync, CardDAV, -Freebusy). A lot of funky work is waiting for you, hackers!

-
-
-

Bugs

-

Many bugs have also been fixed, most of them due to the owner-less -calendars support. Radicale 0.6 may be out in a few weeks, you should -spend some time testing the master branch and filling the bug -tracker.

-
-
-
-

April 10, 2011 - New Features

-

Radicale 0.5 was released only 8 days ago, but 3 new features have -already been added to the master branch:

-
    -
  • IPv6 support, with multiple addresses/ports support
    • -
  • Logs and debug mode
    • -
  • Owner-less calendars
    • -
-

Most of the code has been written by Necoro and Corentin, and that -was not easy at all: Radicale is now multithreaded! For sure, you can -find many bugs and report them on the bug tracker. -And if you're fond of logging, you can even add a default configuration -file and more debug messages in the source.

-
-
-

April 2, 2011 - Radicale 0.5 Released

-

Radicale 0.5 is out! Here is what's new:

-
-

0.5 - Historical Artifacts

-
    -
  • Calendar depth
    • -
  • iPhone support
    • -
  • MacOS and Windows support
    • -
  • HEAD requests management
    • -
  • htpasswd user from calendar path
    • -
-

iPhone support, but no iCal support for 0.5, despite our hard work, -sorry! After 1 month with no more activity on the dedicated bug, it was -time to forget it and hack on new awesome features. Thanks for your -help, dear Apple users, I keep the hope that one day, Radicale will work -with you!

-

So, what's next? As promised, some cool git branches will soon be -merged, with LDAP support, logging, IPv6 and anonymous calendars. Sounds -pretty cool, heh? Talking about new features, more and more people are -asking for a CardDAV support in Radicale. A git branch and a feature -request are open, feel free to hack and discuss.

-
-
-
-

February 3, 2011 - Jabber Room and iPhone Support

-

After a lot of help and testing work from Andrew, Björn, Anders, -Dorian and Pete (and other ones we could have forgotten), a simple -iPhone support has been added in the git repository. If you are -interested, you can test this feature right now by downloading the latest git version (a tarball -is even available too if you don't want or know how to use git).

-

No documentation has been written yet, but using the right URL in the -configuration should be enough to synchronize your calendars. If you -have any problems, you can ask by joining our new Jabber room: radicale@room.jabber.kozea.fr.

-

Radicale 0.5 will be released as soon as the iCal support is ready. -If you have an Apple computer, Python skills and some time to spend, -we'd be glad to help you debugging Radicale.

-
-
-

October 21, 2010 - News from Radicale

-

During the last weeks, Radicale has not been idle, even if no news -have been posted since August. Thanks to Pete, Pierre-Philipp and -Andrew, we're trying to add a better support on MacOS, Windows and -mobile devices like iPhone and Android-based phones.

-

All the tests on Windows have been successful: launching Radicale and -using Lightning as client works without any problems. On Android too, -some testers have reported clients working with Radicale. These were the -good news.

-

The bad news come from Apple: both iPhone and MacOS default clients -are not working yet, despite the latest enhancements given to the -PROPFIND requests. The problems are quite hard to debug due to our lack -of Apple hardware, but Pete is helping us in this difficult quest! -Radicale 0.5 will be out as soon as these two clients are working.

-

Some cool stuff is coming next, with calendar collections and groups, -and a simple web-based CalDAV client in early development. Stay -tuned!

-
-
-

August 8, 2010 - Radicale 0.4 Released

-

Radicale 0.4 is out! Here is what's new:

-
-

0.4 - Hot Days Back

-
    -
  • Personal calendars
    • -
  • HEAD requests
    • -
  • Last-Modified HTTP header
    • -
  • no-ssl and foreground options
    • -
  • Default configuration file
    • -
-

This release has mainly been released to help our dear packagers to -include a default configuration file and to write init scripts. Big -thanks to Necoro for his work on the new Gentoo ebuild!

-
-
-
-

July 4, 2010 - Three Features Added Last Week

-

Some features have been added in the git repository during the last -weeks, thanks to Jerome and Mariusz!

-

Personal Calendars Calendars accessed through the htpasswd ACL module -can now be personal. Thanks to the personal option, a user -called bob can access calendars at /bob/* but -not to the /alice/* ones.

-

HEAD Requests Radicale can now answer HEAD requests. HTTP headers can -be retrieved thanks to this request, without getting contents given by -the GET requests.

-

Last-Modified HTTP header The Last-Modified header gives the last -time when the calendar has been modified. This is used by some clients -to cache the calendars and not retrieving them if they have not been -modified.

-
-
-

June 14, 2010 - Radicale 0.3 Released

-

Radicale 0.3 is out! Here is what’s new:

-
-

0.3 - Dancing Flowers

-
    -
  • Evolution support
    • -
  • Version management
    • -
-

The website changed a little bit too, with some small HTML5 and CSS3 -features such as articles, sections, transitions, opacity, box shadows -and rounded corners. If you’re reading this website with Internet -Explorer, you should consider using a standard-compliant browser!

-

Radicale is now included in Squeeze, the testing branch of Debian. A -Radicale ebuild -for Gentoo has been proposed too. If you want to package Radicale -for another distribution, you’re welcome!

-

Next step is 0.5, with calendar collections, and Windows and MacOS -support.

-
-
-
-

May 31, 2010 - May News

-
-

News from contributors

-

Jonas Smedegaard packaged Radicale for Debian last week. Two -packages, called radicale for the daemon and -python-radicale for the module, have been added to Sid, the -unstable branch of Debian. Thank you, Jonas!

-

Sven Guckes corrected some of the strange-English-sentences present -on this website. Thank you, Sven!

-
-
-

News from software

-

A simple VERSION has been added in the library: you can -now play with radicale.VERSION and -$radicale --version.

-

After playing with the version (should not be too long), you may -notice that the next version is called 0.3, and not 0.5 as previously -decided. The 0.3 main goal is to offer the support for Evolution as soon -as possible, without waiting for the 0.5. After more than a month of -test, we corrected all the bugs we found and everything seems to be -fine; we can imagine that a brand new tarball will be released during -the first days of June.

-
-
-
-

April 19, 2010 - Evolution Supported

-

Radicale now supports another CalDAV client: Evolution, the default mail, -addressbook and calendaring client for Gnome. This feature was quite -easy to add, as it required less than 20 new lines of code in the -requests handler.

-

If you are interested, just clone the git -repository.

-
-
-

April 13, 2010 - Radicale 0.2 Released

-

Radicale 0.2 is out! Here is what’s new:

-
-

0.2 - Snowflakes

-
    -
  • Sunbird pre-1.0 support
    • -
  • SSL connection
    • -
  • Htpasswd authentication
    • -
  • Daemon mode
    • -
  • User configuration
    • -
  • Twisted dependency removed
    • -
  • Python 3 support
    • -
  • Real URLs for PUT and DELETE
    • -
  • Concurrent modification reported to users
    • -
  • Many bugs fixed by Roger Wenham
    • -
-

First of all, we would like to thank Roger Wenham for his bugfixes -and his supercool words.

-

You may have noticed that Sunbird 1.0 has not been released, but -according to the Mozilla developers, 1.0pre is something like a final -version.

-

You may have noticed too that Radicale can be downloaded from -PyPI. Of course, it is also available on the download page.

-
-
-
-

January 21, 2010 - HTTPS and Authentication

-

HTTPS connections and authentication have been added to Radicale this -week. Command-line options and personal configuration files are also -ready for test. According to the TODO file included in the package, the -next version will finally be 0.2, when sunbird 1.0 is out. Go, Mozilla -hackers, go!

-

HTTPS connection HTTPS connections are now available using the -standard TLS mechanisms. Give Radicale a private key and a certificate, -and your data are now safe.

-

Authentication A simple authentication architecture is now available, -allowing different methods thanks to different modules. The first two -modules are fake (no authentication) and -htpasswd (authentication with an htpasswd file -created by the Apache tool). More methods such as LDAP are coming -soon!

-
-
-

January 15, 2010 - Ready for Python 3

-

Dropping Twisted dependency was the first step leading to another big -feature: Radicale now works with Python 3! The code was given a small -cleanup, with some simplifications mainly about encoding. Before the -0.1.1 release, feel free to test the git repository, all Python versions -from 2.5 should be OK.

-
-
-

January 11, 2010 - Twisted no Longer Required

-

Good news! Radicale 0.1.1 will support Sunbird 1.0, but it has -another great feature: it has no external dependency! Twisted is no -longer required for the git version, removing about 50 lines of -code.

-
-
-

December 31, 2009 - Lightning and Sunbird 1.0b2pre Support

-

Lightning/Sunbird 1.0b2pre is out, adding minor changes in CalDAV -support. A new -commit makes Radicale work with versions 0.9, 1.0b1 et 1.0b2. -Moreover, etags are now quoted according to the RFC 2616.

-
-
-

December 9, 2009 - Thunderbird 3 released

-

Thunderbird -3 is out, and Lightning/Sunbird 1.0 should be released in a few -days. The last commit -in git should make Radicale work with versions 0.9 and 1.0b1pre. -Radicale 0.1.1 will soon be released adding support for version 1.0.

-
-
-

September 1, 2009 - Radicale 0.1 Released

-

First Radicale release! Here is the changelog:

-
-

0.1 - Crazy Vegetables

-
    -
  • First release
    • -
  • Lightning/Sunbird 0.9 compatibility
    • -
  • Easy installer
    • -
-

You can download this version on the download -page.

-
-
-
-

July 28, 2009 - Radicale on Gitorious

-

Radicale code has been released on Gitorious! Take a look at the Radicale main page on -Gitorious to view and download source code.

-
-
-

July 27, 2009 - Radicale Ready to Launch

-

The Radicale Project is launched. The code has been cleaned up and -will be available soon…

-
-
-
-
- diff --git a/v3.html b/v3.html deleted file mode 100644 index e9b17692f..000000000 --- a/v3.html +++ /dev/null @@ -1,2955 +0,0 @@ - - - - - - - - - - - - - - -Radicale v3 Documentation - - - - - -
-
-

-Radicale - -v3 - - -

-

Free and Open-Source CalDAV and CardDAV Server

-
-
- -
-
-
- - -
-
-

Translations of this page

- -
-
-

Getting started

-
-

About Radicale

-

Radicale is a small but powerful CalDAV (calendars, to-do lists) and -CardDAV (contacts) server, that:

-
    -
  • Shares calendars and contact lists through CalDAV, CardDAV and -HTTP.
    • -
  • Supports events, todos, journal entries and business cards.
    • -
  • Works out-of-the-box, no complicated setup or configuration -required.
    • -
  • Offers flexible authentication options.
    • -
  • Can limit access by authorization.
    • -
  • Can secure connections with TLS.
    • -
  • Works with many CalDAV and CardDAV -clients.
    • -
  • Stores all data on the file system in a simple folder -structure.
    • -
  • Can be extended with plugins.
    • -
  • Is GPLv3-licensed free software.
    • -
-
-
-

Installation

-

Check

- -
-
-

What's New?

-

Read the Changelog -on GitHub.

-
-
-
-

Tutorials

-
-

Simple 5-minute setup

-

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!

-

The server, configured with settings from this section, only binds to -localhost (i.e. it is not reachable over the network), and you can log -in with any username 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 and desired authentication type.

-

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

-
-

Linux / *BSD

-

Hint: instead of downloading from PyPI, look for packages provided by -your distribution. They -contain also startup scripts integrated into your distributions, that -allow Radicale to run daemonized.

-

First, make sure that python 3.9 or later and -pip are installed. On most distributions it should be -enough to install the package python3-pip.

-
-
as normal user
-

Recommended only for testing - open a console and type:

-
# Run the following command to only install for the current user
-python3 -m pip install --user --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
-

If install is not working and instead -error: externally-managed-environment is displayed, create -and activate a virtual environment in advance.

-
python3 -m venv ~/venv
-source ~/venv/bin/activate
-

and try to install with

-
python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
-

Start the service manually, data is stored only for the current -user

-
# Start, data is stored for the current user only
-python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections --auth-type none
-
-
-
as system user (or as root)
-

Alternatively, you can install and run as system user or as root (not -recommended):

-
# Run the following command as root (not recommended) or non-root system user
-# (the later may require --user in case dependencies are not available system-wide and/or virtual environment)
-python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
-

Start the service manually, with data stored in a system folder under -/var/lib/radicale/collections:

-
# Start, data is stored in a system folder (requires write permissions to /var/lib/radicale/collections)
-python3 -m radicale --storage-filesystem-folder=/var/lib/radicale/collections --auth-type none
-
-
-
-

Windows

-

The first step is to install Python. Go to python.org and download the latest version -of Python 3. Then run the installer. On the first window of the -installer, check the "Add Python to PATH" box and click on "Install -now". Wait a couple of minutes, it's done!

-

Launch a command prompt and type:

-
python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
-python -m radicale --storage-filesystem-folder=~/radicale/collections --auth-type none
-
-
Common
-

Success!!! Open http://localhost:5232 in your browser! -You can log in with any username and password as no authentication is -required by example option --auth-type none. This is -INSECURE, see Configuration/Authentication for more details.

-

Just note that default configuration for security reason binds the -server to localhost (IPv4: 127.0.0.1, IPv6: -::1). See Addresses and Configuration/Server for more details.

-
-
-
-
-

Basic Configuration

-

Installation instructions can be found in the simple 5-minute setup tutorial.

-

Radicale tries to load configuration files from -/etc/radicale/config and -~/.config/radicale/config. Custom paths can be specified -with the --config /path/to/config command line argument or -the RADICALE_CONFIG environment variable. Multiple -configuration files can be separated by : (resp. -; on Windows). Paths that start with ? are -optional.

-

You should create a new configuration file at the desired location. -(If the use of a configuration file is inconvenient, all options can be -passed via command line arguments.)

-

All configuration options are described in detail in the Configuration section.

-
-

Authentication

-

In its default configuration since version 3.5.0, Radicale rejects -all authentication attempts by using config option -type = denyall (introduced with 3.2.2) as default until -explicitly configured.

-

Versions before 3.5.0 did not check usernames or passwords at all, -unless explicitly configured. If such a server is reachable over a -network, you should change this as soon as possible.

-

First a users file with all usernames and passwords must -be created. It can be stored in the same directory as the configuration -file.

-
-
The secure way
-

The users file can be created and managed with htpasswd:

-

Note: some OSes or distributions contain outdated versions of -htpasswd (< 2.4.59) without support for SHA-256 or -SHA-512 (e.g. Ubuntu LTS 22). In these cases, use -htpasswd's command line option -B for the -bcrypt hash method (recommended), or stay with the insecure -(not recommended) MD5 (default) or SHA-1 (command line option --s).

-

Note: support of SHA-256 and 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:
-Re-type new password:
-# Add another user
-$ htpasswd -5 /path/to/users user2
-New password:
-Re-type new password:
-

Authentication can be enabled with the following configuration:

-
[auth]
-type = htpasswd
-htpasswd_filename = /path/to/users
-htpasswd_encryption = autodetect
-
-
-
The simple but insecure way
-

Create the users file by hand with lines containing the -username and password separated by :. Example:

-
user1:password1
-user2:password2
-

Authentication can be enabled with the following configuration:

-
[auth]
-type = htpasswd
-htpasswd_filename = /path/to/users
-# encryption method used in the htpasswd file
-htpasswd_encryption = plain
-
-
-
-

Addresses

-

The default configuration binds the server to localhost. It cannot be -reached from other computers. This can be changed with the following -configuration options (IPv4 and IPv6):

-
[server]
-hosts = 0.0.0.0:5232, [::]:5232
-
-
-

Storage

-

Data is stored in the folder -/var/lib/radicale/collections. The path can be changed with -the following configuration:

-
[storage]
-filesystem_folder = /path/to/storage
-
-

Security: The storage folder shall not be readable -by unauthorized users. Otherwise, they can read the calendar data and -lock the storage. You can find OS dependent instructions in the Running as a service section.

-
-
-
-

Limits

-

Radicale enforces limits on the maximum number of parallel -connections, the maximum file size (important for contacts with big -photos) and the rate of incorrect authentication attempts. Connections -are terminated after a timeout. The default values should be fine for -most scenarios.

-
[server]
-max_connections = 20
-# 100 Megabyte
-max_content_length = 100000000
-# 10 Megabyte (>= 3.5.10)
-max_resource_size = 10000000
-# 30 seconds
-timeout = 30
-
-[auth]
-# Average delay after failed login attempts in seconds
-# Also used for invalid/not-existing/not-enabled share-by-token (>= 3.7.0)
-delay = 1
-
-
-
-

Running as a service

-

The method to run Radicale as a service depends on your host -operating system. Follow one of the chapters below depending on your -operating system and requirements.

-
-

Linux with systemd system-wide

-

Recommendation: check support by Linux Distribution Packages -instead of manual setup / initial configuration.

-

Create the radicale user and group for the Radicale -service by running (as root):

-
useradd --system --user-group --home-dir / --shell /sbin/nologin radicale
-

The storage folder must be made writable by the -radicale user by running (as root):

-
mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections
-

If a dedicated cache folder is configured (see option filesystem_cache_folder), it also -must be made writable by radicale. To achieve that, run -(as root):

-
mkdir -p /var/cache/radicale && chown -R radicale:radicale /var/cache/radicale
-
-

Security: The storage shall not be readable by -others. To make sure this is the case, run (as root):

-
chmod -R o= /var/lib/radicale/collections
-
-

Create the file -/etc/systemd/system/radicale.service:

-
[Unit]
-Description=A simple CalDAV (calendar) and CardDAV (contact) server
-After=network.target
-Requires=network.target
-
-[Service]
-ExecStart=/usr/bin/env python3 -m radicale
-Restart=on-failure
-User=radicale
-# Deny other users access to the calendar data
-UMask=0027
-# Optional security settings
-PrivateTmp=true
-ProtectSystem=strict
-ProtectHome=true
-PrivateDevices=true
-ProtectKernelTunables=true
-ProtectKernelModules=true
-ProtectControlGroups=true
-NoNewPrivileges=true
-ReadWritePaths=/var/lib/radicale/
-# Replace with following in case dedicated cache folder should be used
-#ReadWritePaths=/var/lib/radicale/ /var/cache/radicale/
-
-[Install]
-WantedBy=multi-user.target
-

In this system-wide implementation, Radicale will load the -configuration from the file /etc/radicale/config.

-

To enable and manage the service run:

-
# Enable the service
-$ systemctl enable radicale
-# Start the service
-$ systemctl start radicale
-# Check the status of the service
-$ systemctl status radicale
-# View all log messages
-$ journalctl --unit radicale.service
-
-
-

Linux with systemd as a user

-

Create the file -~/.config/systemd/user/radicale.service:

-
[Unit]
-Description=A simple CalDAV (calendar) and CardDAV (contact) server
-
-[Service]
-ExecStart=/usr/bin/env python3 -m radicale
-Restart=on-failure
-
-[Install]
-WantedBy=default.target
-

In this user-specific configuration, Radicale will load the -configuration from the file ~/.config/radicale/config. You -should set the configuration option filesystem_folder in -the storage section to something like -~/.var/lib/radicale/collections.

-

To enable and manage the service run:

-
# Enable the service
-$ systemctl --user enable radicale
-# Start the service
-$ systemctl --user start radicale
-# Check the status of the service
-$ systemctl --user status radicale
-# View all log messages
-$ journalctl --user --unit radicale.service
-
-
-

Windows with "NSSM - the Non-Sucking Service Manager"

-

First install NSSM and start -nssm install in a command prompt. Apply the following -configuration:

-
    -
  • Service name: Radicale
    • -
  • Application -
      -
    • Path: C:\Path\To\Python\python.exe
      • -
    • Arguments: --config C:\Path\To\Config
      • -
    • -
  • I/O redirection -
      -
    • Error: C:\Path\To\Radicale.log
      • -
    • -
-
-

Security: Be aware that the service runs in the -local system account, you might want to change this. Managing user -accounts is beyond the scope of this manual. Also, make sure that the -storage folder and log file is not readable by unauthorized users.

-
-

The log file might grow very big over time, you can configure file -rotation in NSSM to prevent this.

-

The service is configured to start automatically when the computer -starts. To start the service manually open Services in -Computer Management and start the -Radicale service.

-
-
-
-

Reverse Proxy

-

When a reverse proxy is used, and Radicale should be made available -at a path below the root (such as /radicale/), then this -path must be provided via the X-Script-Name header (without -a trailing /). The proxy must remove the location from the -URL path that is forwarded to Radicale. If Radicale should be made -available at the root of the web server (in the nginx case using -location /), then the setting of the -X-Script-Name header should be removed from the example -below.

-

Example nginx configuration extension:

-

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/nginx/

-
location /radicale/ { # The trailing / is important!
-    proxy_pass        http://localhost:5232;
-    proxy_set_header  X-Script-Name /radicale;
-    proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header  X-Forwarded-Host $host;
-    proxy_set_header  X-Forwarded-Port $server_port;
-    proxy_set_header  X-Forwarded-Proto $scheme;
-    proxy_set_header  Host $http_host;
-    proxy_pass_header Authorization;
-}
-

Example Caddy configuration extension:

-

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/caddy/

-
handle_path /radicale/* {
-    uri strip_prefix /radicale
-    reverse_proxy localhost:5232 {
-    }
-}
-

Example Apache configuration extension:

-

See also for latest examples: https://github.com/Kozea/Radicale/tree/master/contrib/apache/

-
RewriteEngine On
-RewriteRule ^/radicale$ /radicale/ [R,L]
-
-<Location "/radicale/">
-    ProxyPass        http://localhost:5232/ retry=0
-    ProxyPassReverse http://localhost:5232/
-    RequestHeader    set X-Script-Name /radicale
-    RequestHeader    set X-Forwarded-Port "%{SERVER_PORT}s"
-    RequestHeader    set X-Forwarded-Proto expr=%{REQUEST_SCHEME}
-    <IfVersion >= 2.4.40>
-    Proxy100Continue Off
-    </IfVersion>
-</Location>
-

Example Apache .htaccess configuration:

-
DirectoryIndex disabled
-RewriteEngine On
-RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]
-
-# Set to directory of .htaccess file:
-RequestHeader set X-Script-Name /radicale
-RequestHeader set X-Forwarded-Port "%{SERVER_PORT}s"
-RequestHeader unset X-Forwarded-Proto
-<If "%{HTTPS} =~ /on/">
-RequestHeader set X-Forwarded-Proto "https"
-</If>
-

Example lighttpd configuration:

-
server.modules += ( "mod_proxy" , "mod_setenv" )
-
-$HTTP["url"] =~ "^/radicale/" {
-  proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => "5232" )) )
-  setenv.add-request-header = ( "X-Script-Name" => "/radicale" )
-}
-

Be reminded that Radicale's default configuration enforces limits on -the maximum number of parallel connections, the maximum file size and -the rate of incorrect authentication attempts. Connections are -terminated after a timeout.

-
-

Manage user accounts with the reverse proxy

-

Set the configuration option type in the -auth section to http_x_remote_user. Radicale -uses the username provided in the X-Remote-User HTTP header -and disables its internal HTTP authentication.

-

Example nginx configuration:

-
location /radicale/ {
-    proxy_pass           http://localhost:5232/;
-    proxy_set_header     X-Script-Name /radicale;
-    proxy_set_header     X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header     X-Remote-User $remote_user;
-    proxy_set_header     Host $http_host;
-    auth_basic           "Radicale - Password Required";
-    auth_basic_user_file /etc/nginx/htpasswd;
-}
-

Example Caddy configuration:

-
handle_path /radicale/* {
-    uri strip_prefix /radicale
-    basicauth {
-        USER HASH
-    }
-    reverse_proxy localhost:5232 {
-        header_up X-Script-Name /radicale
-        header_up X-remote-user {http.auth.user.id}
-    }
-}
-

Example Apache configuration:

-
RewriteEngine On
-RewriteRule ^/radicale$ /radicale/ [R,L]
-
-<Location "/radicale/">
-    AuthType     Basic
-    AuthName     "Radicale - Password Required"
-    AuthUserFile "/etc/radicale/htpasswd"
-    Require      valid-user
-
-    ProxyPass        http://localhost:5232/ retry=0
-    ProxyPassReverse http://localhost:5232/
-    <IfVersion >= 2.4.40>
-    Proxy100Continue Off
-    </IfVersion>
-    RequestHeader    set X-Script-Name /radicale
-    RequestHeader    set X-Remote-User expr=%{REMOTE_USER}
-</Location>
-

Example Apache .htaccess configuration:

-
DirectoryIndex disabled
-RewriteEngine On
-RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]
-
-AuthType     Basic
-AuthName     "Radicale - Password Required"
-AuthUserFile "/etc/radicale/htpasswd"
-Require      valid-user
-
-# Set to directory of .htaccess file:
-RequestHeader set X-Script-Name /radicale
-RequestHeader set X-Remote-User expr=%{REMOTE_USER}
-
-

Security: Untrusted clients should not be able to -access the Radicale server directly. Otherwise, they can authenticate as -any user by simply setting related HTTP header. This can be prevented by -listening to the loopback interface only or local firewall rules.

-
-
-
-

Secure connection between Radicale and the reverse proxy

-

SSL certificates can be used to encrypt and authenticate the -connection between Radicale and the reverse proxy. First you need to -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, -these values do not really 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
-

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
-

If you are using the Let's Encrypt 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/;
-    ...
-    # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...).
-    proxy_ssl_certificate         /path/to/client_cert.pem;
-    proxy_ssl_certificate_key     /path/to/client_key.pem;
-}
-
-
-
-

WSGI Server

-

Radicale is compatible with the WSGI specification.

-

A configuration file can be set with the RADICALE_CONFIG -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
-

Example Gunicorn configuration:

-
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 -auth section to remote_user. This way Radicale -uses the username provided by the WSGI server and disables its internal -authentication over HTTP.

-
-
-
-

Versioning collections with Git

-

This tutorial describes how to keep track of all changes to calendars -and address books with git (or any other version -control system).

-

The repository must be initialized in the collection base directory -of the user running radicale daemon.

-
## assuming "radicale" user is starting "radicale" service
-# change to user "radicale"
-su -l -s /bin/bash radicale
-
-# change to collection base directory defined in [storage] -> filesystem_folder
-#  assumed here /var/lib/radicale/collections
-cd /var/lib/radicale/collections
-
-# initialize git repository
-git init
-
-# set user and e-mail, here minimum example
-git config user.name "$USER"
-git config user.email "$USER@$HOSTNAME"
-
-# define ignore of cache/lock/tmp files
-cat <<'END' >.gitignore
-.Radicale.cache
-.Radicale.lock
-.Radicale.tmp-*
-END
-

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

The command gets executed after every change to the storage and -commits the changes into the git repository.

-

Log of git can be investigated using

-
su -l -s /bin/bash radicale
-cd /var/lib/radicale/collections
-git log
-

In case of problems, make sure you run radicale with ---debug switch and inspect the log output. For more -information, please visit section on -logging.

-

Reason for problems can be

-
    -
  • SELinux status -> check related audit log
    • -
  • problematic file/directory permissions
    • -
  • command is not fond or cannot be executed or argument problem
    • -
-
-
-
-

Documentation

-
-

Options

-
-

General Options

-
-
--version
-

Print version

-
-
-
--verify-storage
-

Verification of local collections storage

-
-
-
--verify-item
-

(>= 3.6.0)

-

Verification of a particular item file

-
-
-
--verify-sharing
-

(>= 3.7.0)

-

Verification of local sharing database

-
-
-
-C|--config
-

Load one or more specified config file(s)

-
-
-
-D|--debug
-

Turns log level to debug

-
-
-
-

Configuration Options

-

Each supported option from config file can be provided/overridden by -command line replacing _ with - and prepending -the section followed by a -, e.g.

-
[logging]
-backtrace_on_debug = False
-

can be enabled using --logging-backtrace-on-debug=true -on command line.

-
-
-
-

Configuration

-

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.

-

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 = 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 -with the --config /path/to/config command line argument or -the RADICALE_CONFIG environment variable. Multiple -configuration files can be separated by : (resp. -; on Windows). Paths that start with ? are -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 autodetect
-

Add the argument --config "" to stop Radicale from -loading the default configuration files. Run -python3 -m radicale --help for more information.

-

You can also use command-line options in startup scripts as shown in -the following examples:

-
## simple variable containing multiple options
-RADICALE_OPTIONS="--logging-level=debug --config=/etc/radicale/config --logging-request-header-on-debug --logging-rights-rule-doesnt-match-on-debug"
-/usr/bin/radicale $RADICALE_OPTIONS
-
-## variable as array method #1
-RADICALE_OPTIONS=("--logging-level=debug" "--config=/etc/radicale/config" "--logging-request-header-on-debug" "--logging-rights-rule-doesnt-match-on-debug")
-/usr/bin/radicale ${RADICALE_OPTIONS[@]}
-
-## variable as array method #2
-RADICALE_OPTIONS=()
-RADICALE_OPTIONS+=("--logging-level=debug")
-RADICALE_OPTIONS+=("--config=/etc/radicale/config")
-/usr/bin/radicale ${RADICALE_OPTIONS[@]}
-

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

-
-
-
delay_on_error
-

(>= 3.7.0)

-

Base delay in case of error 5xx response (seconds)

-

Default: 1

-
-
-
max_content_length
-

The maximum size of the request body. (bytes)

-

Default: 100000000 (100 Mbyte)

-

In case of using a reverse proxy in front of check also there related -option.

-
-
-
max_resource_size
-

(>= 3.5.10)

-

The maximum size of a resource. (bytes)

-

Default: 10000000 (10 Mbyte)

-

Limited to 80% of max_content_length to cover plain base64 encoded -payload.

-

Announced to clients requesting "max-resource-size" via PROPFIND.

-
-
-
timeout
-

Socket timeout. (seconds)

-

Default: 30

-
-
-
ssl
-

Enable transport layer encryption.

-

Default: False

-
-
-
certificate
-

Path of the SSL certificate.

-

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)

-
-
-
-

[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 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_remote_user (>= 3.5.9) Takes the -username from the Remote-User HTTP header HTTP_REMOTE_USER -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.

    • -

  • http_x_remote_user
    -Takes the username from the X-Remote-User HTTP header -HTTP_X_REMOTE_USER 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 file.

-

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. Also -consider version of passlib(libpass): bcrypt >= 5.0.0 requires -passlib(libpass) >= 1.9.3

    • -

  • 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 or missing login attempts or -denied access.

-

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_security
-

(>= 3.5.2)

-

Use encryption on the LDAP connection.

-

One of

-
    -
  • none
    • -
  • tls
    • -
  • starttls
    • -
-

Default: none

-
-
-
ldap_ssl_verify_mode
-

(>= 3.3.0)

-

Certificate verification mode for tls and starttls.

-

One of

-
    -
  • NONE
    • -
  • OPTIONAL
    • -
  • REQUIRED.
    • -
-

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 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 search 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:

-
    -
  • AF_UNIX
    • -
  • AF_INET
    • -
  • AF_INET6
    • -
-

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:

-
    -
  • tls
    • -
  • starttls
    • -
  • none
    • -
-

Default: tls

-
-
-
oauth2_token_endpoint
-

(>= 3.5.0)

-

Endpoint URL for the OAuth2 token

-

Default: (unset)

-
-
-
oauth2_client_id
-

(>= 3.7.0)

-

Client ID used to request the Auth2 token

-

Default: radicale

-
-
-
oauth2_client_secret
-

(>= 3.7.0)

-

Client secret used to request the Auth2 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

-
-
-
-

[rights]

-
-
type
-

Authorization backend that is used to check the access rights to -collections.

-

The default and recommended backend is owner_only. If -access to calendars and address books outside the user's collection -directory (that's /username/) is granted, clients will not -detect these collections automatically and will not show them to the -users. Choosing any other authorization backend is only useful if you -access calendars and address books directly via URL.

-

Available backends are:

-
    -

  • 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
-

Name of the file containing the authorization rules for the -from_file backend. See the Rights section for details.

-

Default: /etc/radicale/rights

-
-
-
permit_delete_collection
-

(>= 3.1.9)

-

Global permission to delete complete collections.

-
    -
  • If False it can be explicitly granted per collection by -rights permissions: D
    • -
  • If True it can be explicitly forbidden per collection -by rights permissions: d
    • -
-

Default: True

-
-
-
permit_overwrite_collection
-

(>= 3.3.0)

-

Global permission to overwrite complete collections.

-
    -
  • If False it can be explicitly granted per collection by -rights permissions: O
    • -
  • If True it can be explicitly forbidden per collection -by rights permissions: o
    • -
-

Default: True

-
-
-
-

[storage]

-
-
type
-

Backend used to store data.

-

Available backends are:

-
    -

  • multifilesystem
    -Stores the data in the filesystem.

    • -

  • multifilesystem_nolock
    -The multifilesystem backend without file-based locking. -Must only be used with a single process.

    • -
-

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

-
-
-
strict_preconditions
-

(>= 3.5.8)

-

Strict preconditions check on PUT in case item already exists RFC6352#9.2

-

Default: False

-
-
-
hook
-

Command that is run after changes to storage. See 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)

-
-
-
-

[web]

-
-
type
-

The backend that provides the web interface of Radicale.

-

Available backends are:

-
    -

  • none
    -Simply shows the message "Radicale works!".

    • -

  • internal
    -Allows creation and management of address books and calendars.

    • -
-

Default: internal

-
-
-
-

[logging]

-
-
level
-

Set the logging level.

-

Available levels are:

-
    -
  • trace (>= 3.7.1)
    • -
  • debug
    • -
  • info
    • -
  • notice (>= 3.7.1)
    • -
  • warning
    • -
  • error
    • -
  • critical
    • -
  • alert (>= 3.7.1)
    • -
-

Default: warning (< 3.2.0) / -info (>= 3.2.0)

-
-
-
limit_content
-

(>= 3.7.0)

-

Limit content of wrapped text (chars)

-

Default: 3000

-
-
-
trace_on_debug
-

(> 3.5.4) && (< 3.7.1)

-

Do not filter debug messages starting with 'TRACE'

-

Default: False

-
-
-
trace_filter
-

(> 3.5.4) && (< 3.7.1)

-

Filter debug messages starting with 'TRACE/'

-

Prerequisite: trace_on_debug = True

-

(>= 3.7.1)

-

Filter trace messages starting with ''

-

Prerequisite: level = trace

-

Default: (empty)

-
-
-
mask_passwords
-

Do not include passwords in logs.

-

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 header on level = debug

-

Default: False

-
-
-
request_content_on_debug
-

(>= 3.2.2)

-

Log request content (body) on level = debug

-

Default: False

-
-
-
response_header_on_debug
-

(>= 3.5.10)

-

Log response header on level = debug

-

Default: False

-
-
-
response_content_on_debug
-

(>= 3.2.2)

-

Log response content (body) on level = debug

-

Default: False

-
-
-
rights_rule_doesnt_match_on_debug
-

(>= 3.2.3)

-

Log rights rule which doesn't match on level = debug

-

Default: False

-
-
-
storage_cache_actions_on_debug
-

(>= 3.3.2)

-

Log storage cache actions on level = debug

-

Default: False

-
-
-
profiling_per_request
-

(>= 3.5.10)

-

Log profiling data on level=info

-

Default: none

-

One of

-
    -
  • none (disabled)
    • -
  • per_request (above minimum duration)
    • -
  • per_request_method (regular interval)
    • -
-
-
-
profiling_per_request_min_duration
-

(>= 3.5.10)

-

Log profiling data per request minimum duration (seconds) before -logging, otherwise skip

-

Default: 3

-
-
-
profiling_per_request_header
-

(>= 3.5.10)

-

Log profiling request header (if passing minimum duration)

-

Default: False

-
-
-
profiling_per_request_xml
-

(>= 3.5.10)

-

Log profiling request XML (if passing minimum duration)

-

Default: False

-
-
-
profiling_per_request_method_interval
-

(>= 3.5.10)

-

Log profiling data per method interval (seconds) Triggered by -request, not active on idle systems

-

Default: 600

-
-
-
profiling_top_x_functions
-

(>= 3.5.10)

-

Log profiling top X functions (limit)

-

Default: 10

-
-
-
-

[headers]

-

This section can be used to specify additional HTTP headers that will -be sent to clients.

-

An example to relax the same-origin policy:

-
Access-Control-Allow-Origin = *
-

An example to set CSP to disallow execution of unknown -javascript:

-
Content-Security-Policy = default-src 'self'; object-src 'none'
-
-
-

[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:

-
    -
  • none
    • -
  • tls
    • -
  • starttls
    • -
-

Default: none

-
-
-
smtp_ssl_verify_mode
-

(>= 3.5.5)

-

The certificate verification mode for tls and starttls.

-

One of:

-
    -
  • NONE
    • -
  • OPTIONAL
    • -
  • REQUIRED
    • -
-

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.
-
-
-
-

[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 -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

-
-
-
-

[sharing]

-

(>= 3.7.0)

-

See also Collection -Sharing.

-
-
type
-

(>= 3.7.0)

-

Sharing database type

-

One of:

-
    -
  • none
    • -
  • csv
    • -
  • files
    • -
-

Default: none (implicit disabling the feature)

-
-
-
database_path
-

(>= 3.7.0)

-

Sharing database path

-

Default:

-
    -
  • type csv: -(filesystem_folder)/collection-db/sharing.csv
    • -
  • type files: -(filesystem_folder)/collection-db/files
    • -
-
-
-
collection_by_token
-

(>= 3.7.0)

-

Share collection by token

-

Default: false

-
-
-
collection_by_map
-

(>= 3.7.0)

-

Share collection by map

-

Default: false

-
-
-
permit_create_token
-

(>= 3.7.0)

-

Permit create of token-based sharing

-

Default: false

-
    -
  • If False it can be explicitly granted by -rights permissions: T
    • -
  • If True it can be explicitly forbidden by -rights permissions: t
    • -
-
-
-
permit_create_map
-

(>= 3.7.0)

-

Permit create of map-based sharing

-

Default: false

-
    -
  • If False it can be explicitly granted by -rights permissions: M
    • -
  • If True it can be explicitly forbidden by -rights permissions: m
    • -
-
-
-
permit_properties_overlay
-

(>= 3.7.0)

-

Permit (limited) properties overlay by user of shared collection

-

Default: false

-
    -
  • If False it can be explicitly granted by share -permissions: P
    • -
  • If True it can be explicitly forbidden by -share permissions: p
    • -
-
-
-
enforce_properties_overlay
-

(>= 3.7.0)

-

Enforce properties overlay even on write access

-

Default: true

-
    -
  • If False it can be explicitly enforced by -share permissions: E
    • -
  • If True it can be explicitly forbidden by -share permissions: e
    • -
-
-
-
default_permissions_create_token
-

Default permissions for create token-based sharing

-

Default: r

-

Supported: rwEePp

-
-
-
default_permissions_create_map
-

Default permissions for map-based sharing

-

Default: r

-

Supported: rwEePp

-
-
-
-
-
-

Supported Clients

-

Radicale has been tested with:

- -

Many clients do not support the creation of new calendars and address -books. You can use Radicale's web interface (e.g. http://localhost:5232) to create and -manage address books and calendars.

-

In some clients, it is sufficient to simply enter the URL of the -Radicale server (e.g. http://localhost:5232) and your -username. In others, you have to enter the URL of the collection -directly (e.g. http://localhost:5232/user/calendar).

-

Some clients (notably macOS's Calendar.app) may silently refuse to -include account credentials over unsecured HTTP, leading to unexpected -authentication failures. In these cases, you want to make sure the -Radicale server is accessible over HTTPS.

-
-

DAVx⁵

-

Enter the URL of the Radicale server (e.g. -http://localhost:5232) and your username. DAVx⁵ will show -all existing calendars and address books and you can create new -ones.

-
-
-

OneCalendar

-

When adding account, select CalDAV account type, then enter username, -password and the Radicale server (e.g. -https://yourdomain:5232). OneCalendar will show all -existing calendars and (FIXME: address books), you need to select which -ones you want to see. OneCalendar supports many other server types -too.

-
-
-

GNOME Calendar, Contacts

-

GNOME 46 added CalDAV and CardDAV support to GNOME Online -Accounts.

-

Open GNOME Settings, navigate to Online Accounts > -Connect an Account > Calendar, Contacts and Files. -Enter the URL (e.g. https://example.com/radicale) and your -credentials then click Sign In. In the pop-up dialog, turn off -Files. After adding Radicale in GNOME Online Accounts, -it should be available in GNOME Contacts and GNOME Calendar.

-
-
-

Evolution

-

In Evolution add a new calendar and address book -respectively with WebDAV. Enter the URL of the Radicale server (e.g. -http://localhost:5232) and your username. Clicking on the -search button will list the existing calendars and address books.

-

Adding CalDAV and CardDAV accounts in Evolution will automatically -make them available in GNOME Contacts and GNOME Calendar.

-
-
-

KDE PIM Applications

-

In Kontact add a DAV Groupware resource to -Akonadi under Settings > Configure Kontact > Calendar > -General > Calendars, select the protocol (CalDAV or CardDAV), -add the URL to the Radicale collections and enter the credentials. After -synchronization of the calendar resp. addressbook items, you can manage -them in Kontact.

-
-
-

Thunderbird

-

Add a new calendar on the network. Enter your username and the URL of -the Radicale server (e.g. http://localhost:5232). After -asking for your password, it will list the existing calendars.

-
-
Address books with CardBook add-on
-

Add a new address book on the network with CardDAV. Enter the URL of -the Radicale server (e.g. http://localhost:5232) and your -username and password. It will list your existing address books.

-
-
-
-

InfCloud, CalDavZAP and CardDavMATE

-

You can integrate InfCloud into Radicale's web interface with by -simply downloading the latest package from InfCloud -and extract the content into a folder named 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

-

This is not the recommended way of creating and managing your -calendars and address books. Use Radicale's web interface or a client -with support for it (e.g. DAVx⁵).

-

To create a new calendar run something like:

-
$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \
-'<?xml version="1.0" encoding="UTF-8" ?>
-<create xmlns="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:I="http://apple.com/ns/ical/">
-  <set>
-    <prop>
-      <resourcetype>
-        <collection />
-        <C:calendar />
-      </resourcetype>
-      <C:supported-calendar-component-set>
-        <C:comp name="VEVENT" />
-        <C:comp name="VJOURNAL" />
-        <C:comp name="VTODO" />
-      </C:supported-calendar-component-set>
-      <displayname>Calendar</displayname>
-      <C:calendar-description>Example calendar</C:calendar-description>
-      <I:calendar-color>#ff0000ff</I:calendar-color>
-    </prop>
-  </set>
-</create>'
-

To create a new address book run something like:

-
$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \
-'<?xml version="1.0" encoding="UTF-8" ?>
-<create xmlns="DAV:" xmlns:CR="urn:ietf:params:xml:ns:carddav">
-  <set>
-    <prop>
-      <resourcetype>
-        <collection />
-        <CR:addressbook />
-      </resourcetype>
-      <displayname>Address book</displayname>
-      <CR:addressbook-description>Example address book</CR:addressbook-description>
-    </prop>
-  </set>
-</create>'
-

The collection /USERNAME will be created automatically, -when the user authenticates to Radicale for the first time. Clients with -automatic discovery of collections will only show calendars and address -books that are direct children of the path /USERNAME/.

-

Delete the collections by running something like:

-
curl -u user -X DELETE 'http://localhost:5232/user/calendar'
-

Note: requires config/option -permit_delete_collection = True

-
-
-

Authorization and Rights

-

This section describes the format of the rights file for the -from_file authentication backend. The configuration option -file in the rights section must point to the -rights file.

-

The recommended rights method is owner_only. If access -is granted to calendars and address books outside the home directory of -users (that's /USERNAME/), clients will not detect these -collections automatically, and will not show them to the users. 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
-

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 -collection. Permissions from the first matching section are used. If no -section matches, access gets denied.

-

The username is empty for anonymous users. Therefore, the regex -.+ only matches authenticated users and .* -matches everyone (including anonymous users).

-

The path of the collection is separated by / and has no -leading or trailing /. Therefore, the path of the root -collection is empty.

-

In the collection regex you can use {user} -and get groups from the user regex with {0}, -{1}, etc.

-

In consequence of the parameter substitution you have to write -{{ and }} if you want to use regular curly -braces in the user and collection regexes.

-

The following permissions are recognized:

-
    -
  • R: read collections (excluding address books and -calendars)
    • -
  • r: read address book and calendar collections
    • -
  • i: subset of r that only allows -direct access via HTTP method GET (CalDAV/CardDAV is susceptible to -expensive search requests)
    • -
  • W: write collections (excluding address books and -calendars)
    • -
  • w: write address book and calendar collections
    • -
  • D: allow deleting a collection in case -permit_delete_collection=False (>= 3.3.0)
    • -
  • d: deny deleting a collection in case -permit_delete_collection=True (>= 3.3.0)
    • -
  • O: allow overwriting a collection in case -permit_overwrite_collection=False (>= -3.3.0)
    • -
  • o: deny overwriting a collection in case -permit_overwrite_collection=True (>= -3.3.0)
    • -
  • T: permit create of token-based sharing of -collection in case permit_create_token=False (>= -3.7.0)
    • -
  • t: deny create of token-based sharing of collection -in case permit_create_token=True (>= -3.7.0)
    • -
  • M: permit create of map-based sharing of collection -in case permit_create_map= False (>= -3.7.0)
    • -
  • m: deny create of map-based sharing of collection -in case permit_create_map=True (>= 3.7.0)
    • -
-
-
-

Storage

-

This document describes the layout and format of the file system -storage, the multifilesystem backend.

-

It is safe to access and manipulate the data by hand or with scripts. -Scripts can be invoked manually, periodically (e.g. using cron) -or after each change to the storage with the configuration option -hook in the storage section (e.g. Versioning collections with -Git).

-
-

Layout

-

The file system comprises the following files and folders:

-
    -
  • .Radicale.lock: The lock file for locking the -storage.
    • -
  • collection-root: This folder contains all collections -and items.
    • -
-

Each collection is represented by a folder. This folder may contain -the file .Radicale.props with all WebDAV properties of the -collection encoded as JSON.

-

Each item in a calendar or address book collection is represented by -a file containing the item's iCalendar resp. vCard data.

-

All files and folders, whose names start with a dot but not with -.Radicale. (internal files) are ignored.

-

Syntax errors in any of the files will cause all requests accessing -the faulty data to fail. The logging output should contain the names of -the culprits.

-

Caches and sync-tokens are stored in the .Radicale.cache -folder inside of collections. This folder may be created or modified, -while the storage is locked for shared access. In theory, it should be -safe to delete the folder. Caches will be recreated automatically and -clients will be told that their sync-token is not valid anymore.

-

You may encounter files or folders that start with -.Radicale.tmp-. Radicale uses them for atomic creation and -deletion of files and folders. They should be deleted after requests are -finished but it is possible that they are left behind when Radicale or -the computer crashes. You can safely delete them.

-
-
-

Locking

-

When the data is accessed by hand or by an externally invoked script, -the storage must be locked. The storage can be locked for exclusive or -shared access. It prevents Radicale from reading or writing the file -system. The storage is locked with exclusive access while the -hook runs.

-
-
Linux shell scripts
-

Use the flock -utility to acquire exclusive or shared locks for the commands you want -to run on Radicale's data.

-
# Exclusive lock for COMMAND
-$ flock --exclusive /path/to/storage/.Radicale.lock COMMAND
-# Shared lock for COMMAND
-$ flock --shared /path/to/storage/.Radicale.lock COMMAND
-
-
-
Linux and MacOS
-

Use the flock -syscall. Python provides it in the fcntl -module.

-
-
-
Windows
-

Use LockFile -for exclusive access or LockFileEx -which also supports shared access. Setting -nNumberOfBytesToLockLow to 1 and -nNumberOfBytesToLockHigh to 0 works.

-
-
-
-

Manually creating collections

-

To create a new collection, you need to create the corresponding -folder in the file system storage (e.g. -collection-root/user/calendar). To indicate to Radicale and -clients that the collection is a calendar, you have to create the file -.Radicale.props with the following content in the -folder:

-
{"tag": "VCALENDAR"}
-

The calendar is now available at the URL path (e.g. -/user/calendar). For address books -.Radicale.props must contain:

-
{"tag": "VADDRESSBOOK"}
-

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 -/USERNAME/.

-

Delete collections by deleting the corresponding folders.

-
-
-
-

Logging overview

-

Radicale logs to stderr. The verbosity of the log output -can be controlled with --debug command line argument or the -level configuration option in the logging section.

-
-
-

Architecture

-

Radicale is a small piece of software, but understanding it is not as -easy as it seems. But don't worry, reading this short section is enough -to understand what a CalDAV/CardDAV server is, and how Radicale's code -is organized.

-
-

Protocol overview

-

Here is a simple overview of the global architecture for reaching a -calendar or an address book through network:

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PartLayerProtocol or Format
ServerCalendar/Contact StorageiCal/vCard
''Calendar/Contact ServerCalDAV/CardDAV Server
TransferNetworkCalDAV/CardDAV (HTTP + TLS)
ClientCalendar/Contact ClientCalDAV/CardDAV Client
''GUITerminal, GTK, Web interface, etc.
-

Radicale is only the server part of this -architecture.

-

Please note:

-
    -
  • CalDAV and CardDAV are extension protocols of WebDAV,
    • -
  • WebDAV is an extension of the HTTP protocol.
    • -
-

Radicale being a CalDAV/CardDAV server, can also be seen as a special -WebDAV and HTTP server.

-

Radicale is not the client part of this -architecture. It means that Radicale never draws calendars, address -books, events and contacts on the screen. It only stores them and give -the possibility to share them online with other people.

-

If you want to see or edit your events and your contacts, you have to -use another software called a client, that can be a "normal" -applications with icons and buttons, a terminal or another web -application.

-
-
-

Code Architecture

-

The radicale package offers the following modules.

-
    -

  • __init__ : Contains the entry point for -WSGI.

    • -

  • __main__ : Provides the entry point for the -radicale executable and includes the command line parser. -It loads configuration files from the default (or specified) paths and -starts the internal server.

    • -

  • app : This is the core part of Radicale, with the -code for the CalDAV/CardDAV server. The code managing the different HTTP -requests according to the CalDAV/CardDAV specification can be found -here.

    • -

  • auth : Used for authenticating users based on -username and password, mapping usernames to internal users and -optionally retrieving credentials from the environment.

    • -

  • config : Contains the code for managing -configuration and loading settings from files.

    • -

  • ìtem : Internal representation of address book and -calendar entries. Based on VObject.

    • -

  • log : The logger for Radicale based on the default -Python logging module.

    • -

  • rights : This module is used by Radicale to manage -access rights to collections, address books and calendars.

    • -

  • server : The integrated HTTP server for standalone -use.

    • -

  • storage : This module contains the classes -representing collections in Radicale and the code for storing and -loading them in the filesystem.

    • -

  • web : This module contains the web -interface.

    • -

  • utils : Contains general helper functions.

    • -

  • httputils : Contains helper functions for working -with HTTP.

    • -

  • pathutils : Helper functions for working with paths -and the filesystem.

    • -

  • xmlutils : Helper functions for working with the XML -part of CalDAV/CardDAV requests and responses. It's based on the -ElementTree XML API.

    • -
-
-
-
-

Plugins

-

Radicale can be extended by plugins for authentication, rights -management and storage. Plugins are python modules.

-
-

Getting started with plugin development

-

To get started we walk through the creation of a simple -authentication plugin, that accepts login attempts with a static -password.

-

The easiest way to develop and install python -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"])
-

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

Install the python module by running the following command in the -same folder as setup.py:

-
python3 -m pip install .
-

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
-

You can uninstall the module with:

-
python3 -m pip uninstall radicale_static_password_auth
-
-
-

Authentication plugins

-

This plugin type is used to check login credentials. The module must -contain a class Auth that extends -radicale.auth.BaseAuth. Take a look at the file -radicale/auth/__init__.py in Radicale's source code for -more information.

-
-
-

Rights management plugins

-

This plugin type is used to check if a user has access to a path. The -module must contain a class Rights that extends -radicale.rights.BaseRights. Take a look at the file -radicale/rights/__init__.py in Radicale's source code for -more information.

-
-
-

Web plugins

-

This plugin type is used to provide the web interface for Radicale. -The module must contain a class Web that extends -radicale.web.BaseWeb. Take a look at the file -radicale/web/__init__.py in Radicale's source code for more -information.

-
-
-

Storage plugins

-

This plugin is used to store collections and items. The module must -contain a class Storage that extends -radicale.storage.BaseStorage. Take a look at the file -radicale/storage/__init__.py in Radicale's source code for -more information.

-
-
-
-
-

Contribute

-
-

Report Bugs

-

Found a bug? Want a new feature? Report a new issue on the Radicale -bug-tracker.

-
-
-

Hack

-

Interested in hacking? Feel free to clone the git repository on GitHub if -you want to add new features, fix bugs or update the documentation.

-
-
-

Documentation

-

To change or complement the documentation create a pull request to DOCUMENTATION.md.

-
-
-
-

Download

-
-

PyPI

-

Radicale is available on PyPI. To -install, just type as superuser:

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

You can also download the content of the repository as an archive.

-
-
-

Source Packages

-

You can find the source packages of all releases on GitHub.

-
-
-

Docker

-

Radicale is available as a Docker image for platforms -linux/amd64 and linux/arm64 on:

- -

Here are the steps to install Radicale via Docker Compose:

-
    -

  1. Create required directories

    -

    Create a directory to store the data, configuration and compose -file.

    -

    For example, assuming ./radicale:

    -
    $ mkdir radicale
-$ cd radicale
    -

    Create directories to store data and configuration.

    -

    For example, assuming data directory as ./data and -configuration directory as ./config:

    -
    $ mkdir config data
    2. -

  2. Download the compose file

    -
    $ wget https://raw.githubusercontent.com/Kozea/Radicale/refs/heads/master/compose.yaml
    -

    The compose file assumes ./config and -./data directories. Review the file and modify as -needed.

    3. -

  3. Create Radicale configuration file as necessary

    -

    Create a new configuration file or place an existing one in the -./config directory.

    -

    Note: This section demonstrates only basic steps to -setup Radicale using docker compose. For details on -configuring Radicale, including authentication, please refer to the -documentation for Basic Configuration -or detailed Configuration

    4. -

  4. Start Radicale

    -
    $ docker compose up -d
    -

    This will start the Radicale container in detached mode.

    -

    To view the logs of the running container, run:

    -
    $ docker compose logs -f
    -

    To stop the container, run this from the current directory:

    -
    $ docker compose down
    5. -
-
-
Available tags
-
    -
  • stable: Points to the latest stable release. This is -recommended for most users.
    • -
  • Major.Minor.Patch (e.g. 3.6.1): Points to a specific -release version.
    • -
  • Major.Minor (e.g. 3.6): Tracks the latest release for a -minor version.
    • -
  • Major (e.g. 3): Tracks the latest release for a major -version.
    • -
  • nightly tags (e.g. nightly-20260206): Nightly -builds.
    • -
  • latest: Points to the most recent build. In most cases, -this is nightly.
    • -
-
-
-
-

Linux Distribution Packages

-

Radicale has been packaged for:

- -

Radicale is also available -on Cloudron.

-

If you are interested in creating packages for other Linux -distributions, read the "Contribute" -section.

-
-
-
-

About

-
-

Main Goals

-

Radicale is a complete calendar and contact storing and manipulating -solution. It can store multiple calendars and multiple address -books.

-

Calendar and contact manipulation is available from both local and -distant accesses, possibly limited through authentication policies.

-

It aims to be a lightweight solution, easy to use, easy to install, -easy to configure. As a consequence, it requires few software -dependencies and is preconfigured to work out-of-the-box.

-

Radicale is written in Python. It runs on most of the UNIX-like -platforms (Linux, *BSD, macOS) and Windows. It is free and open-source -software.

-
-
-

What Radicale Will Never Be

-

Radicale is a server, not a client. No interfaces will be created to -work with the server.

-

CalDAV and CardDAV are not perfect protocols. We think that their -main problem is their complexity, that is why we decided not to -implement the whole standard but just enough to understand some of its -client-side implementations.

-

CalDAV and CardDAV are the best open standards available, and they -are quite widely used by both clients and servers. We decided to use it, -and we will not use another one.

-
-
-

Technical Choices

-

Important global development choices have been decided before writing -code. They are very useful to understand why the Radicale Project is -different from other CalDAV and CardDAV servers, and why features are -included or not in the code.

-
-
Oriented to Calendar and Contact User Agents
-

Calendar and contact servers work with calendar and contact clients, -using a defined protocol. CalDAV and CardDAV are good protocols, -covering lots of features and use cases, but it is quite hard to -implement fully.

-

Some calendar servers have been created to follow the CalDAV and -CardDAV RFCs as much as possible: Davical, Baïkal and Darwin Calendar Server, for -example, are much more respectful of CalDAV and CardDAV and can be used -with many clients. They are very good choices if you want to develop and -test new CalDAV clients, or if you have a possibly heterogeneous list of -user agents.

-

Even if it tries it best to follow the RFCs, Radicale does not and -will not blindly implement the CalDAV and CardDAV -standards. It is mainly designed to support the CalDAV and CardDAV -implementations of different clients.

-
-
-
Simple
-

Radicale is designed to be simple to install, simple to configure, -simple to use.

-

The installation is very easy, particularly with Linux: one -dependency, no superuser rights needed, no configuration required, no -database. Installing and launching the main script out-of-the-box, as a -normal user, are often the only steps to have a simple remote calendar -and contact access.

-

Contrary to other servers that are often complicated, require high -privileges or need a strong configuration, the Radicale Server can -(sometimes, if not often) be launched in a couple of minutes, if you -follow the tutorial.

-
-
-
Lazy
-

The CalDAV RFC defines what must be done, what can be done and what -cannot be done. Many violations of the protocol are totally defined and -behaviors are given in such cases.

-

Radicale often assumes that the clients are perfect and that protocol -violations do not exist. That is why most of the errors in client -requests have undetermined consequences for the lazy server that can -reply good answers, bad answers, or even no answer.

-
-
-
-

History

-

Radicale has been started as a (free topic) stupid school project -replacing another (assigned topic) even more stupid school project.

-

At the beginning, it was just a proof-of-concept. The main goal was -to write a small, dirty and simple CalDAV server working with Lightning, -using no external libraries. That's how we created a piece of code -that's (quite) easy to understand, to use and to hack.

-

The first -lines have been added to the SVN (!) repository as I was drinking -(many) beers at the very end of 2008 (Python 2.6 and 3.0 were just -released). It's now packaged for a growing number of Linux -distributions.

-

And that was fun going from here to there thanks to you!

-
-
-
-
-