From e69970ed568127cfe24e7060b7b515c5cf9343c3 Mon Sep 17 00:00:00 2001 From: Guillaume Ayoub Date: Sat, 27 May 2017 12:06:41 +0200 Subject: [PATCH] Minor fixes --- configuration.md | 63 ++++++++++++++++++++++++------------------------ documentation.md | 2 +- edit.md | 2 +- index.html | 4 +-- logging.md | 12 ++++----- plugins.md | 26 ++++++++++---------- proxy.md | 4 +-- rights.md | 50 +++++++++++++++++++------------------- setup.md | 44 ++++++++++++++++----------------- versioning.md | 8 +++--- 10 files changed, 108 insertions(+), 107 deletions(-) diff --git a/configuration.md b/configuration.md index ac1f2180..ae3e286a 100644 --- a/configuration.md +++ b/configuration.md @@ -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. diff --git a/documentation.md b/documentation.md index 9c570b3f..28c30273 100644 --- a/documentation.md +++ b/documentation.md @@ -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! diff --git a/edit.md b/edit.md index 4217e7e3..695d28dc 100644 --- a/edit.md +++ b/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]. diff --git a/index.html b/index.html index 51ccef4b..d1946c99 100644 --- a/index.html +++ b/index.html @@ -35,8 +35,8 @@ layout: default {{ site.title }} is really easy to install and works out-of-the-box.

- 
$ pip install radicale
-$ radicale --verbose
+    
$ python3 -m pip install --upgrade radicale
+$ python3 -m radicale --verbose
 Listening to localhost port 5232
 Radicale server ready

 
diff --git a/logging.md b/logging.md
index 0a1b62ed..f67931da 100644
--- a/logging.md
+++ b/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
diff --git a/plugins.md b/plugins.md
index 8a4b7332..ff15f04f 100644
--- a/plugins.md
+++ b/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.
diff --git a/proxy.md b/proxy.md
index 82f74815..1e329acd 100644
--- a/proxy.md
+++ b/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;
diff --git a/rights.md b/rights.md
index 2ac09539..aed141eb 100644
--- a/rights.md
+++ b/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.
diff --git a/setup.md b/setup.md
index 767b6650..fc91315c 100644
--- a/setup.md
+++ b/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``
-  * 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``
+* 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`
 
 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.
 
diff --git a/versioning.md b/versioning.md
index 66b87c59..e9571871 100644
--- a/versioning.md
+++ b/versioning.md
@@ -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)
 ```