diff --git a/3.0.html b/3.0.html index 028f2e4e..8749736d 100644 --- a/3.0.html +++ b/3.0.html @@ -228,7 +228,7 @@

Getting started

About Radicale

-

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

+

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

-

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.

+

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.

@@ -613,7 +613,7 @@ user2:password2
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.

+

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

Default:

@@ -636,11 +636,11 @@ user2:password2
type

The method to verify usernames and passwords.

Available backends:

-

None : Just allows all usernames and passwords. It also disables rights checking.

+

none : Just allows all usernames and passwords.

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

+

Default: none

htpasswd_filename
@@ -675,9 +675,8 @@ user2:password2
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.

+

The recommended backend is owner_only. If access to calendars and address books outside 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/.

@@ -829,7 +828,7 @@ user2:password2

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

+

The recommended rights method is owner_only. If access to calendars and address books outside 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:

# Allow reading root collection for authenticated users
 [root]
@@ -853,7 +852,7 @@ user2:password2
 
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.

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

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

+
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)
    • 
@@ -878,7 +877,7 @@ user2:password2
 
    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.
    
+
    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 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.
@@ -907,7 +906,7 @@ user2:password2 
{"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/.

+

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.

@@ -917,7 +916,7 @@ user2:password2

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 section is enough to understand what a CalDAV/CardDAV server is, and how Radicale's code is organized.

+

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:

@@ -973,7 +972,7 @@ user2:password2

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 represenation of address book and calendar entries. Based on VObject.

+

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

@@ -1111,14 +1110,14 @@ user2:password2

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.

+

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, as it is a really (really really) much more difficult task.

+

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.

+

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

@@ -1126,8 +1125,8 @@ user2:password2
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.

+

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
@@ -1137,7 +1136,7 @@ user2:password2
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 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.

diff --git a/master.html b/master.html index 67380624..760b1814 100644 --- a/master.html +++ b/master.html @@ -228,7 +228,7 @@

Getting started

About Radicale

-

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

+

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.
    • @@ -258,18 +258,18 @@

    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 little bit with Radicale!

    +

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

    When everything works, you can get a client and start creating calendars and address books. The server only binds to localhost (is not reachable over the network) and you can log in with any 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.5 or later (python ≥ 3.6 is recommended) and pip are installed. On most distributions it should be enough to install the package python3-pip.

    +

    First, make sure that python 3.5 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
 $ python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections
    -

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

    +

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

    Windows

    @@ -277,7 +277,7 @@

    Launch a command prompt and type:

    C:\Users\User> python -m pip install --upgrade radicale
 C:\Users\User> python -m radicale --storage-filesystem-folder=~/radicale/collections
    -

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

    +

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

    @@ -436,7 +436,7 @@ user2:password2
-

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.

+

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.

@@ -613,7 +613,7 @@ user2:password2
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.

+

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

Default:

@@ -636,11 +636,11 @@ user2:password2
type

The method to verify usernames and passwords.

Available backends:

-

None : Just allows all usernames and passwords. It also disables rights checking.

+

none : Just allows all usernames and passwords.

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

+

Default: none

htpasswd_filename
@@ -675,9 +675,8 @@ user2:password2
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.

+

The recommended backend is owner_only. If access to calendars and address books outside 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/.

@@ -829,7 +828,7 @@ user2:password2

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

+

The recommended rights method is owner_only. If access to calendars and address books outside 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:

# Allow reading root collection for authenticated users
 [root]
@@ -853,7 +852,7 @@ user2:password2
 
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.

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

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

+
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)
    • 
@@ -878,7 +877,7 @@ user2:password2
 
    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.
    
+
    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 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.
@@ -907,7 +906,7 @@ user2:password2 
{"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/.

+

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.

@@ -917,7 +916,7 @@ user2:password2

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 section is enough to understand what a CalDAV/CardDAV server is, and how Radicale's code is organized.

+

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:

@@ -973,7 +972,7 @@ user2:password2

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 represenation of address book and calendar entries. Based on VObject.

+

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

@@ -1111,14 +1110,14 @@ user2:password2

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.

+

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, as it is a really (really really) much more difficult task.

+

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.

+

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

@@ -1126,8 +1125,8 @@ user2:password2
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.

+

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
@@ -1137,7 +1136,7 @@ user2:password2
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 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.