mirror of
https://github.com/Kozea/Radicale.git
synced 2025-06-26 16:45:52 +00:00
Minor fixes
This commit is contained in:
Guillaume Ayoub
parent
ad72c218c3
commit
e69970ed56
10 changed files with 108 additions and 107 deletions
|
|
@ -11,6 +11,7 @@ An example configuration file looks like:
|
|||
```ini
|
||||
[server]
|
||||
hosts = 0.0.0.0:5232 # Bind all addresses
|
||||
|
||||
[auth]
|
||||
type = htpasswd
|
||||
htpasswd_filename = /path/to/users
|
||||
|
|
@ -19,35 +20,35 @@ htpasswd_encryption = bcrypt
|
|||
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.
|
||||
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.
|
||||
`--config /path/to/config` command line argument.
|
||||
|
||||
The same example configuration via command line arguments looks like:
|
||||
```sh
|
||||
```shell
|
||||
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.
|
||||
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,
|
||||
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:5555``
|
||||
Default: `127.0.0.1:5555`
|
||||
|
||||
### daemon
|
||||
Daemonize the Radicale process. It does not reset the umask or double fork.
|
||||
|
||||
Default: ``False``
|
||||
Default: `False`
|
||||
|
||||
### pid
|
||||
If daemon mode is enabled, Radicale will write its PID to this file.
|
||||
|
|
@ -55,39 +56,39 @@ 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.
|
||||
The maximum number of parallel connections. Set to `0` to disable the limit.
|
||||
|
||||
Default: ``20``
|
||||
Default: `20`
|
||||
|
||||
### max_content_length
|
||||
The maximum size of the request body. (bytes)
|
||||
|
||||
Default: ``10000000``
|
||||
Default: `10000000`
|
||||
|
||||
### timeout
|
||||
Socket timeout. (seconds)
|
||||
|
||||
Default: ``10``
|
||||
Default: `10`
|
||||
|
||||
### ssl
|
||||
Enable transport layer encryption.
|
||||
|
||||
Default: ``False``
|
||||
Default: `False`
|
||||
|
||||
### certificate
|
||||
Path of the SSL certifcate.
|
||||
|
||||
Default: ``/etc/ssl/radicale.cert.pem``
|
||||
Default: `/etc/ssl/radicale.cert.pem`
|
||||
|
||||
### key
|
||||
Path to the private key for SSL. Only effective if ``ssl`` is enabled.
|
||||
Path to the private key for SSL. Only effective if `ssl` is enabled.
|
||||
|
||||
Default: ``/etc/ssl/radicale.key.pem``
|
||||
Default: `/etc/ssl/radicale.key.pem`
|
||||
|
||||
### protocol
|
||||
SSL protocol used. See python's ssl module for available values.
|
||||
|
||||
Default: ``PROTOCOL_TLSv1_2``
|
||||
Default: `PROTOCOL_TLSv1_2`
|
||||
|
||||
### ciphers
|
||||
Available ciphers for SSL. See python's ssl module for available ciphers.
|
||||
|
|
@ -97,23 +98,23 @@ Default:
|
|||
### dns_lookup
|
||||
Reverse DNS to resolve client address in logs.
|
||||
|
||||
Default: ``True``
|
||||
Default: `True`
|
||||
|
||||
### realm
|
||||
Message displayed in the client when a password is needed.
|
||||
|
||||
Default: ``Radicale - Password Required``
|
||||
Default: `Radicale - Password Required`
|
||||
|
||||
## encoding
|
||||
### request
|
||||
Encoding for responding requests.
|
||||
|
||||
Default: ``utf-8``
|
||||
Default: `utf-8`
|
||||
|
||||
### stock
|
||||
Encoding for storing local collections
|
||||
|
||||
Default: ``utf-8``
|
||||
Default: `utf-8`
|
||||
|
||||
## auth
|
||||
### type
|
||||
|
|
@ -128,7 +129,7 @@ Available backends:
|
|||
: Use an [Apache htpasswd file](https://httpd.apache.org/docs/current/programs/htpasswd.html) to store
|
||||
usernames and passwords.
|
||||
|
||||
Default: ``None``
|
||||
Default: `None`
|
||||
|
||||
### htpasswd_filename
|
||||
Path to the htpasswd file.
|
||||
|
|
@ -169,7 +170,7 @@ Available methods:
|
|||
: This uses UNIX [crypt(3)](http://man7.org/linux/man-pages/man3/crypt.3.html).
|
||||
It's insecure!
|
||||
|
||||
Default: ``bcrypt``
|
||||
Default: `bcrypt`
|
||||
|
||||
## rights
|
||||
### type
|
||||
|
|
@ -194,10 +195,10 @@ Available backends:
|
|||
`from_file`
|
||||
: Load the rules from a file.
|
||||
|
||||
Default: ``owner_only``
|
||||
Default: `owner_only`
|
||||
|
||||
### file
|
||||
File for the rights backend ``from_file``. See the
|
||||
File for the rights backend `from_file`. See the
|
||||
[Rights]({{ site.baseurl }}/logging/) page.
|
||||
|
||||
## storage
|
||||
|
|
@ -209,14 +210,14 @@ Available backends:
|
|||
`multifilesystem`
|
||||
: Stores the data in the filesystem.
|
||||
|
||||
Default: ``multifilesystem``
|
||||
Default: `multifilesystem`
|
||||
|
||||
### 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``
|
||||
Default: `True`
|
||||
|
||||
### hook
|
||||
Command that is run after changes to storage. Take a look at the
|
||||
|
|
@ -228,17 +229,17 @@ Default:
|
|||
## debug
|
||||
Set the default logging level to debug.
|
||||
|
||||
Default: ``False``
|
||||
Default: `False`
|
||||
|
||||
### full_environment
|
||||
Log all environment variables (including those set in the shell).
|
||||
|
||||
Default: ``False``
|
||||
Default: `False`
|
||||
|
||||
### mask_passwords
|
||||
Don't include passwords in logs.
|
||||
|
||||
Default: ``True``
|
||||
Default: `True`
|
||||
|
||||
### config
|
||||
Logging configuration file. See the [Logging]({{ site.baseurl }}/logging/) page.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Radicale from 1.x.x to 2.0.x, please follow
|
|||
our [migration guide]({{ site.baseurl }}/1to2/). You can find on GitHub the
|
||||
[documentation page for the 1.1.x versions](https://github.com/Kozea/Radicale/blob/website/pages/user_documentation.rst).
|
||||
|
||||
## Install and set up
|
||||
## Install and Set Up
|
||||
|
||||
You're new to Radicale and you want to know how to use it? Welcome aboard!
|
||||
|
||||
|
|
|
|||
2
edit.md
2
edit.md
|
|
@ -5,4 +5,4 @@ permalink: /edit/
|
|||
---
|
||||
|
||||
To change or complement the documentation create a pull requests to
|
||||
https://github.com/Kozea/Radicale/tree/gh-pages.
|
||||
[https://github.com/Kozea/Radicale/tree/gh-pages].
|
||||
|
|
|
|||
|
|
@ -35,8 +35,8 @@ layout: default
|
|||
{{ site.title }} is really easy to install and works out-of-the-box.
|
||||
</p>
|
||||
|
||||
<pre>$ pip install radicale
|
||||
$ radicale --verbose
|
||||
<pre>$ python3 -m pip install --upgrade radicale
|
||||
$ python3 -m radicale --verbose
|
||||
Listening to localhost port 5232
|
||||
Radicale server ready</pre>
|
||||
|
||||
|
|
|
|||
12
logging.md
12
logging.md
|
|
@ -4,9 +4,9 @@ title: Logging
|
|||
permalink: /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.
|
||||
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.
|
||||
|
|
@ -16,11 +16,11 @@ 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
|
||||
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).
|
||||
|
||||
An example configuration to write the log output to the file */var/log/radicale/log*:
|
||||
An example configuration to write the log output to the file `/var/log/radicale/log`:
|
||||
```ini
|
||||
[loggers]
|
||||
keys = root
|
||||
|
|
|
|||
26
plugins.md
26
plugins.md
|
|
@ -14,7 +14,7 @@ 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
|
||||
For a minimal setup create the file `setup.py` with the following content
|
||||
in an empty folder:
|
||||
|
||||
```python
|
||||
|
|
@ -25,10 +25,10 @@ from distutils.core import setup
|
|||
setup(packages=["silly_auth_plugin"])
|
||||
```
|
||||
|
||||
In the same folder create the sub-folder **silly_auth_plugin**. The folder
|
||||
must have the same name as specified in ``packages`` above.
|
||||
In the same folder create the sub-folder `silly_auth_plugin`. The folder
|
||||
must have the same name as specified in `packages` above.
|
||||
|
||||
Create the file **\_\_init\_\_.py** in the **silly_auth_plugin** folder with the
|
||||
Create the file `\_\_init\_\_.py` in the `silly_auth_plugin` folder with the
|
||||
following content:
|
||||
|
||||
```python
|
||||
|
|
@ -42,28 +42,28 @@ class Auth(BaseAuth):
|
|||
```
|
||||
|
||||
Install the python module by running the following command in the same folder
|
||||
as **setup.py**:
|
||||
```sh
|
||||
as `setup.py`:
|
||||
```shell
|
||||
python3 -m pip install --upgrade .
|
||||
```
|
||||
|
||||
To make use this great creation in Radicale, set the configuration option
|
||||
``type`` in the ``auth`` section to ``silly_auth_plugin``.
|
||||
`type` in the `auth` section to `silly_auth_plugin`.
|
||||
|
||||
## 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
|
||||
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.auth.BaseAuth``. Take a look at the file *radicale/rights.py* in
|
||||
The module must contain a class `Rights` that extends
|
||||
`radicale.auth.BaseAuth`. Take a look at the file `radicale/rights.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.auth.BaseStorage``. Take a look at the file *radicale/storage.py* in
|
||||
The module must contain a class `Storage` that extends
|
||||
`radicale.auth.BaseStorage`. Take a look at the file `radicale/storage.py` in
|
||||
Radicale's source code for more information.
|
||||
|
|
|
|||
4
proxy.md
4
proxy.md
|
|
@ -5,11 +5,11 @@ permalink: /proxy/
|
|||
---
|
||||
|
||||
When a everse proxy is used, the path at which Radicale is available must
|
||||
be provided via the ``X-Script-Name`` header.
|
||||
be provided via the `X-Script-Name` header.
|
||||
|
||||
|
||||
Example **nginx** configuration:
|
||||
```
|
||||
```nginx
|
||||
location /sub/folder/radicale {
|
||||
proxy_pass localhost:5232/; # The / is important!
|
||||
proxy_set_header X-Script-Name /radciale;
|
||||
|
|
|
|||
50
rights.md
50
rights.md
|
|
@ -4,12 +4,12 @@ title: Authentication and Rights
|
|||
permalink: /rights/
|
||||
---
|
||||
|
||||
This page describes the format of the rights file for the ``from_file``
|
||||
authentication backend. The configuration option ``file`` in the ``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 mehtod is ``owner_only``. If access to calendars
|
||||
and address books outside of the home directory of users (that's */USERNAME/*)
|
||||
The recommended rights mehtod 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.
|
||||
|
|
@ -18,41 +18,41 @@ An example rights file:
|
|||
```ini
|
||||
# The user "admin" can read and write any collection.
|
||||
[admin]
|
||||
user: admin
|
||||
collection: .*
|
||||
permission: rw
|
||||
user = admin
|
||||
collection = .*
|
||||
permission = rw
|
||||
|
||||
# Block access for the user "user" to everything.
|
||||
[block]
|
||||
user: user
|
||||
collection: .*
|
||||
permission:
|
||||
user = user
|
||||
collection = .*
|
||||
permission =
|
||||
|
||||
# Authenticated users can read and write their own collections.
|
||||
[owner-write]
|
||||
user: .+
|
||||
collection: %(login)s/.*
|
||||
permission: rw
|
||||
user = .+
|
||||
collection = %(login)s/.*
|
||||
permission = rw
|
||||
|
||||
# Everyone can read the root collection
|
||||
[read]
|
||||
user: .*
|
||||
collection:
|
||||
permission: r
|
||||
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
|
||||
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
|
||||
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.
|
||||
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.
|
||||
`%(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.
|
||||
|
|
|
|||
40
setup.md
40
setup.md
|
|
@ -9,9 +9,9 @@ Installation instructions can be found on the
|
|||
|
||||
## 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
|
||||
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.
|
||||
|
|
@ -26,12 +26,12 @@ All configuration options are described in detail on the
|
|||
In it's 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.
|
||||
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 file can be created and managed with
|
||||
[htpasswd](https://httpd.apache.org/docs/current/programs/htpasswd.html):
|
||||
```bash
|
||||
```shell
|
||||
# Create a new htpasswd file with the user "user1"
|
||||
$ htpasswd -B -c /path/to/users user1
|
||||
New password:
|
||||
|
|
@ -43,7 +43,7 @@ Re-type new password:
|
|||
```
|
||||
**bcrypt** is used to secure the passwords. Radicale required additional
|
||||
dependencies for this encryption method:
|
||||
```bash
|
||||
```shell
|
||||
$ python3 -m pip install --upgrade passlib
|
||||
$ python3 -m pip install --upgrade bcrypt
|
||||
```
|
||||
|
|
@ -71,7 +71,7 @@ More addresses can be added (separated by commas).
|
|||
|
||||
## Storage
|
||||
|
||||
Data is stored in the folder */var/lib/radicale/collections*. The path can
|
||||
Data is stored in the folder `/var/lib/radicale/collections`. The path can
|
||||
be changed with the foloowing configuration:
|
||||
|
||||
```ini
|
||||
|
|
@ -103,8 +103,8 @@ requirements.
|
|||
|
||||
### Linux with systemd as a user
|
||||
|
||||
Create the file *~/.config/systemd/user/radicale.service*:
|
||||
```
|
||||
Create the file `~/.config/systemd/user/radicale.service`:
|
||||
```ini
|
||||
[Unit]
|
||||
Description=A simple CalDAV (calendar) and CardDAV (contact) server
|
||||
|
||||
|
|
@ -119,7 +119,7 @@ You may have to add addition command line arguments to Radicale for the
|
|||
configuration file, etc.
|
||||
|
||||
To enable and manage the service run:
|
||||
```bash
|
||||
```shell
|
||||
# Enable the service
|
||||
$ systemctl --user enable radicale
|
||||
# Start the service
|
||||
|
|
@ -136,8 +136,8 @@ Create the **radicale** user and group for the Radicale service.
|
|||
The configuration files must be readable by this user and the storage folder
|
||||
must be writable.
|
||||
|
||||
Create the file */etc/systemd/system/radicale.service*:
|
||||
```
|
||||
Create the file `/etc/systemd/system/radicale.service`:
|
||||
```ini
|
||||
[Unit]
|
||||
Description=A simple CalDAV (calendar) and CardDAV (contact) server
|
||||
|
||||
|
|
@ -153,7 +153,7 @@ You may have to add addition command line arguments to Radicale for the
|
|||
configuration file, etc.
|
||||
|
||||
To enable and manage the service run:
|
||||
```bash
|
||||
```shell
|
||||
# Enable the service
|
||||
$ systemctl enable radicale
|
||||
# Start the service
|
||||
|
|
@ -170,8 +170,8 @@ $ journalctl --unit radicale.service
|
|||
|
||||
## 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.
|
||||
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]({{ site.baseurl }}/tutorial/).
|
||||
|
|
@ -181,15 +181,15 @@ The main process exits, after the PID file is written.
|
|||
|
||||
## Windows with "NSSM - the Non-Sucking Service Manager"
|
||||
|
||||
First install [NSSM](https://nssm.cc/) and start ``nssm install`` in a command
|
||||
First install [NSSM](https://nssm.cc/) and start `nssm install` in a command
|
||||
prompt. Apply the following configuration:
|
||||
|
||||
* Service name: ``Radicale``
|
||||
* Service name: `Radicale`
|
||||
* Application
|
||||
* Path: ``C:\Path\To\Python\python.exe``
|
||||
* Arguments: ``-m radicale --config C:\Path\To\Config``
|
||||
* Path: `C:\Path\To\Python\python.exe`
|
||||
* Arguments: `-m radicale --config C:\Path\To\Config`
|
||||
* I/O redirection
|
||||
* Error: ``C:\Path\To\Radicale.log``
|
||||
* Error: `C:\Path\To\Radicale.log`
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,18 +7,18 @@ permalink: /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
|
||||
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:
|
||||
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 configuration option `hook` in the `storage` section must be set to
|
||||
the following command:
|
||||
```sh
|
||||
```shell
|
||||
git add -A && (git diff --cached --quiet || git commit -m "Changes by "%(user)s)
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue