oss/Radicale
oss/Radicale
1
0
Fork 0
mirror of https://github.com/Kozea/Radicale.git synced 2025-08-10 18:40:53 +00:00
Code Wiki Activity

Generate documentation

Browse source
This commit is contained in:
Github Actions 2020-05-23 05:43:36 +00:00
parent 148ac8dba0
commit 5802267b3b
2 changed files with 44 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

45
3.0.html
View file

@ -228,7 +228,7 @@
<h2>Getting started <a class="headerlink" href="#getting-started">&para;</a></h2>
<section class="level4" id="getting-started//about-radicale">
<h4>About Radicale <a class="headerlink" href="#getting-started//about-radicale">&para;</a></h4>
<p>Radicale is a small but powerful CalDAV (calendars, todo-lists) and CardDAV (contacts) server, that:</p>
<p>Radicale is a small but powerful CalDAV (calendars, to-do lists) and CardDAV (contacts) server, that:</p>
<ul>
<li>Shares calendars and contact lists through CalDAV, CardDAV and HTTP.</li>
<li>Supports events, todos, journal entries and business cards.</li>
@ -258,18 +258,18 @@
<h2>Tutorials <a class="headerlink" href="#tutorials">&para;</a></h2>
<section class="level3" id="tutorials/simple-5-minute-setup">
<h3>Simple 5-minute setup <a class="headerlink" href="#tutorials/simple-5-minute-setup">&para;</a></h3>
<p>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!</p>
<p>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!</p>
<p>When everything works, you can get a <a href="#documentation/supported-clients">client</a> and start creating calendars and address books. The server <strong>only</strong> binds to localhost (is <strong>not</strong> 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 <a href="#tutorials/basic-configuration">some basic configuration</a>.</p>
<p>Follow one of the chapters below depending on your operating system.</p>
<section class="level4" id="tutorials/simple-5-minute-setup/linux--bsd">
<h4>Linux / *BSD <a class="headerlink" href="#tutorials/simple-5-minute-setup/linux--bsd">&para;</a></h4>
<p>First of all, make sure that <strong>python</strong> 3.5 or later (<strong>python</strong> &ge; 3.6 is recommended) and <strong>pip</strong> are installed. On most distributions it should be enough to install the package <code>python3-pip</code>.</p>
<p>First, make sure that <strong>python</strong> 3.5 or later (<strong>python</strong> &ge; 3.6 is recommended) and <strong>pip</strong> are installed. On most distributions it should be enough to install the package <code>python3-pip</code>.</p>
<p>Then open a console and type:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1"></a><span class="co"># Run the following command as root or</span></span>
<span id="cb2-2"><a href="#cb2-2"></a><span class="co"># add the --user argument to only install for the current user</span></span>
<span id="cb2-3"><a href="#cb2-3"></a>$ <span class="ex">python3</span> -m pip install --upgrade radicale</span>
<span id="cb2-4"><a href="#cb2-4"></a>$ <span class="ex">python3</span> -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections</span></code></pre></div>
<p>Victory! Open <a href="http://localhost:5232/">http://localhost:5232/</a> in your browser! You can login with any username and password.</p>
<p>Victory! Open <a href="http://localhost:5232/">http://localhost:5232/</a> in your browser! You can log in with any username and password.</p>
</section>
<section class="level4" id="tutorials/simple-5-minute-setup/windows">
<h4>Windows <a class="headerlink" href="#tutorials/simple-5-minute-setup/windows">&para;</a></h4>
@ -277,7 +277,7 @@
<p>Launch a command prompt and type:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode powershell"><code class="sourceCode powershell"><span id="cb3-1"><a href="#cb3-1"></a>C:\Users\User&gt; python -m pip install --upgrade radicale</span>
<span id="cb3-2"><a href="#cb3-2"></a>C:\Users\User&gt; python -m radicale --storage-filesystem-folder=~/radicale/collections</span></code></pre></div>
<p>Victory! Open <a href="http://localhost:5232/">http://localhost:5232/</a> in your browser! You can login with any username and password.</p>
<p>Victory! Open <a href="http://localhost:5232/">http://localhost:5232/</a> in your browser! You can log in with any username and password.</p>
</section>
</section>
<section class="level3" id="tutorials/basic-configuration">
@ -436,7 +436,7 @@ user2:password2
</ul></li>
</ul>
<blockquote>
<p><strong>Security:</strong> 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.</p>
<p><strong>Security:</strong> 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.</p>
</blockquote>
<p>The log file might grow very big over time, you can configure file rotation in <strong>NSSM</strong> to prevent this.</p>
<p>The service is configured to start automatically when the computer starts. To start the service manually open <strong>Services</strong> in <strong>Computer Management</strong> and start the <strong>Radicale</strong> service.</p>
@ -613,7 +613,7 @@ user2:password2
</section>
<section class="level5" id="documentation/configuration/server/certificate_authority">
<h5>certificate_authority <a class="headerlink" href="#documentation/configuration/server/certificate_authority">&para;</a></h5>
<p>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.</p>
<p>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.</p>
<p>Default:</p>
</section>
</section>
@ -636,11 +636,11 @@ user2:password2
<h5>type <a class="headerlink" href="#documentation/configuration/auth/type">&para;</a></h5>
<p>The method to verify usernames and passwords.</p>
<p>Available backends:</p>
<p><code>None</code> : Just allows all usernames and passwords. It also disables rights checking.</p>
<p><code>none</code> : Just allows all usernames and passwords.</p>
<p><code>htpasswd</code> : Use an <a href="https://httpd.apache.org/docs/current/programs/htpasswd.html">Apache htpasswd file</a> to store usernames and passwords.</p>
<p><code>remote_user</code> : Takes the user name from the <code>REMOTE_USER</code> environment variable and disables HTTP authentication. This can be used to provide the user name from a WSGI server.</p>
<p><code>http_x_remote_user</code> : Takes the user name from the <code>X-Remote-User</code> HTTP header and disables HTTP authentication. This can be used to provide the user name from a reverse proxy.</p>
<p>Default: <code>None</code></p>
<p>Default: <code>none</code></p>
</section>
<section class="level5" id="documentation/configuration/auth/htpasswd_filename">
<h5>htpasswd_filename <a class="headerlink" href="#documentation/configuration/auth/htpasswd_filename">&para;</a></h5>
@ -675,9 +675,8 @@ user2:password2
<section class="level5" id="documentation/configuration/rights/type">
<h5>type <a class="headerlink" href="#documentation/configuration/rights/type">&para;</a></h5>
<p>The backend that is used to check the access rights of collections.</p>
<p>The recommended backend is <code>owner_only</code>. If access to calendars and address books outside of the home directory of users (that's <code>/USERNAME/</code>) 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.</p>
<p>The recommended backend is <code>owner_only</code>. If access to calendars and address books outside the home directory of users (that's <code>/USERNAME/</code>) 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.</p>
<p>Available backends:</p>
<p><code>None</code> : Everyone can read and write everything.</p>
<p><code>authenticated</code> : Authenticated users can read and write everything.</p>
<p><code>owner_only</code> : Authenticated users can read and write their own collections under the path <em>/USERNAME/</em>.</p>
<p><code>owner_write</code> : Authenticated users can read everything and write their own collections under the path <em>/USERNAME/</em>.</p>
@ -829,7 +828,7 @@ user2:password2
<section class="level3" id="documentation/authentication-and-rights">
<h3>Authentication and Rights <a class="headerlink" href="#documentation/authentication-and-rights">&para;</a></h3>
<p>This section describes the format of the rights file for the <code>from_file</code> authentication backend. The configuration option <code>file</code> in the <code>rights</code> section must point to the rights file.</p>
<p>The recommended rights method is <code>owner_only</code>. If access to calendars and address books outside of the home directory of users (that's <code>/USERNAME/</code>) 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.</p>
<p>The recommended rights method is <code>owner_only</code>. If access to calendars and address books outside the home directory of users (that's <code>/USERNAME/</code>) 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.</p>
<p>An example rights file:</p>
<div class="sourceCode" id="cb33"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb33-1"><a href="#cb33-1"></a><span class="co"># Allow reading root collection for authenticated users</span></span>
<span id="cb33-2"><a href="#cb33-2"></a><span class="kw">[root]</span></span>
@ -853,7 +852,7 @@ user2:password2
<p>The user name is empty for anonymous users. Therefore, the regex <code>.+</code> only matches authenticated users and <code>.*</code> matches everyone (including anonymous users).</p>
<p>The path of the collection is separated by <code>/</code> and has no leading or trailing <code>/</code>. Therefore, the path of the root collection is empty.</p>
<p>In the <code>collection</code> regex you can use <code>{user}</code> and get groups from the <code>user</code> regex with <code>{0}</code>, <code>{1}</code>, etc.</p>
<p>In consequence of the parameter subsitution you have to write <code>{{</code> and <code>}}</code> if you want to use regular curly braces in the <code>user</code> and <code>collection</code> regexes.</p>
<p>In consequence of the parameter substitution you have to write <code>{{</code> and <code>}}</code> if you want to use regular curly braces in the <code>user</code> and <code>collection</code> regexes.</p>
<p>The following <code>permissions</code> are recognized:</p>
<ul>
<li><strong>R:</strong> read collections (excluding address books and calendars)</li>
@ -878,7 +877,7 @@ user2:password2
<p>An item is represented by a file containing the iCalendar data.</p>
<p>All files and folders, whose names start with a dot but not <code>.Radicale.</code> (internal files) are ignored.</p>
<p>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.</p>
<p>Future releases of Radicale 2.x.x will store caches and sync-tokens in the <code>.Radicale.cache</code> 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.</p>
<p>Caches and sync-tokens are stored in the <code>.Radicale.cache</code> 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.</p>
<p>You may encounter files or folders that start with <code>.Radicale.tmp-</code>. 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.</p>
</section>
<section class="level4" id="documentation/storage/locking">
@ -907,7 +906,7 @@ user2:password2
<div class="sourceCode" id="cb35"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb35-1"><a href="#cb35-1"></a><span class="fu">{</span><span class="dt">"tag"</span><span class="fu">:</span> <span class="st">"VCALENDAR"</span><span class="fu">}</span></span></code></pre></div>
<p>The calendar is now available at the URL path <code>/user/calendar</code>. For address books the file must contain:</p>
<div class="sourceCode" id="cb36"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb36-1"><a href="#cb36-1"></a><span class="fu">{</span><span class="dt">"tag"</span><span class="fu">:</span> <span class="st">"VADDRESSBOOK"</span><span class="fu">}</span></span></code></pre></div>
<p>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 <code>/USERNAME/</code>.</p>
<p>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 <code>/USERNAME/</code>.</p>
<p>Delete collections by deleting the corresponding folders.</p>
</section>
</section>
@ -917,7 +916,7 @@ user2:password2
</section>
<section class="level3" id="documentation/architecture">
<h3>Architecture <a class="headerlink" href="#documentation/architecture">&para;</a></h3>
<p>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.</p>
<p>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.</p>
<section class="level4" id="documentation/architecture/protocol-overview">
<h4>Protocol overview <a class="headerlink" href="#documentation/architecture/protocol-overview">&para;</a></h4>
<p>Here is a simple overview of the global architecture for reaching a calendar or an address book through network:</p>
@ -973,7 +972,7 @@ user2:password2
<p><code>app</code> : 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.</p>
<p><code>auth</code> : Used for authenticating users based on username and password, mapping usernames to internal users and optionally retrieving credentials from the environment.</p>
<p><code>config</code> : Contains the code for managing configuration and loading settings from files.</p>
<p><code>&igrave;tem</code> : Internal represenation of address book and calendar entries. Based on <a href="https://eventable.github.io/vobject/">VObject</a>.</p>
<p><code>&igrave;tem</code> : Internal representation of address book and calendar entries. Based on <a href="https://eventable.github.io/vobject/">VObject</a>.</p>
<p><code>log</code> : The logger for Radicale based on the default Python logging module.</p>
<p><code>rights</code> : This module is used by Radicale to manage access rights to collections, address books and calendars.</p>
<p><code>server</code> : The integrated HTTP server for standalone use.</p>
@ -1111,14 +1110,14 @@ user2:password2
<h4>Main Goals <a class="headerlink" href="#about//main-goals">&para;</a></h4>
<p>Radicale is a complete calendar and contact storing and manipulating solution. It can store multiple calendars and multiple address books.</p>
<p>Calendar and contact manipulation is available from both local and distant accesses, possibly limited through authentication policies.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section>
<section class="level4" id="about//what-radicale-will-never-be">
<h4>What Radicale Will Never Be <a class="headerlink" href="#about//what-radicale-will-never-be">&para;</a></h4>
<p>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.</p>
<p>Radicale is a server, not a client. No interfaces will be created to work with the server.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section>
<section class="level4" id="about//technical-choices">
<h4>Technical Choices <a class="headerlink" href="#about//technical-choices">&para;</a></h4>
@ -1126,8 +1125,8 @@ user2:password2
<section class="level5" id="about//technical-choices/oriented-to-calendar-and-contact-user-agents">
<h5>Oriented to Calendar and Contact User Agents <a class="headerlink" href="#about//technical-choices/oriented-to-calendar-and-contact-user-agents">&para;</a></h5>
<p>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.</p>
<p>Some calendar servers have been created to follow the CalDAV and CardDAV RFCs as much as possible: <a href="http://www.davical.org/">Davical</a>, <a href="http://sabre.io/baikal/">Ba&iuml;kal</a> and <a href="http://trac.calendarserver.org/">Darwin Calendar Server</a>, 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.</p>
<p>Even if it tries it best to follow the RFCs, Radicale does not and <strong>will not</strong> blindly implements the CalDAV and CardDAV standards. It is mainly designed to support the CalDAV and CardDAV implementations of different clients.</p>
<p>Some calendar servers have been created to follow the CalDAV and CardDAV RFCs as much as possible: <a href="http://www.davical.org/">Davical</a>, <a href="http://sabre.io/baikal/">Ba&iuml;kal</a> and <a href="http://trac.calendarserver.org/">Darwin Calendar Server</a>, 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.</p>
<p>Even if it tries it best to follow the RFCs, Radicale does not and <strong>will not</strong> blindly implement the CalDAV and CardDAV standards. It is mainly designed to support the CalDAV and CardDAV implementations of different clients.</p>
</section>
<section class="level5" id="about//technical-choices/simple">
<h5>Simple <a class="headerlink" href="#about//technical-choices/simple">&para;</a></h5>
@ -1137,7 +1136,7 @@ user2:password2
</section>
<section class="level5" id="about//technical-choices/lazy">
<h5>Lazy <a class="headerlink" href="#about//technical-choices/lazy">&para;</a></h5>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section>
</section>

45
master.html
View file

@ -228,7 +228,7 @@
<h2>Getting started <a class="headerlink" href="#getting-started">&para;</a></h2>
<section class="level4" id="getting-started//about-radicale">
<h4>About Radicale <a class="headerlink" href="#getting-started//about-radicale">&para;</a></h4>
<p>Radicale is a small but powerful CalDAV (calendars, todo-lists) and CardDAV (contacts) server, that:</p>
<p>Radicale is a small but powerful CalDAV (calendars, to-do lists) and CardDAV (contacts) server, that:</p>
<ul>
<li>Shares calendars and contact lists through CalDAV, CardDAV and HTTP.</li>
<li>Supports events, todos, journal entries and business cards.</li>
@ -258,18 +258,18 @@
<h2>Tutorials <a class="headerlink" href="#tutorials">&para;</a></h2>
<section class="level3" id="tutorials/simple-5-minute-setup">
<h3>Simple 5-minute setup <a class="headerlink" href="#tutorials/simple-5-minute-setup">&para;</a></h3>
<p>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!</p>
<p>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!</p>
<p>When everything works, you can get a <a href="#documentation/supported-clients">client</a> and start creating calendars and address books. The server <strong>only</strong> binds to localhost (is <strong>not</strong> 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 <a href="#tutorials/basic-configuration">some basic configuration</a>.</p>
<p>Follow one of the chapters below depending on your operating system.</p>
<section class="level4" id="tutorials/simple-5-minute-setup/linux--bsd">
<h4>Linux / *BSD <a class="headerlink" href="#tutorials/simple-5-minute-setup/linux--bsd">&para;</a></h4>
<p>First of all, make sure that <strong>python</strong> 3.5 or later (<strong>python</strong> &ge; 3.6 is recommended) and <strong>pip</strong> are installed. On most distributions it should be enough to install the package <code>python3-pip</code>.</p>
<p>First, make sure that <strong>python</strong> 3.5 or later (<strong>python</strong> &ge; 3.6 is recommended) and <strong>pip</strong> are installed. On most distributions it should be enough to install the package <code>python3-pip</code>.</p>
<p>Then open a console and type:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1"></a><span class="co"># Run the following command as root or</span></span>
<span id="cb2-2"><a href="#cb2-2"></a><span class="co"># add the --user argument to only install for the current user</span></span>
<span id="cb2-3"><a href="#cb2-3"></a>$ <span class="ex">python3</span> -m pip install --upgrade radicale</span>
<span id="cb2-4"><a href="#cb2-4"></a>$ <span class="ex">python3</span> -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections</span></code></pre></div>
<p>Victory! Open <a href="http://localhost:5232/">http://localhost:5232/</a> in your browser! You can login with any username and password.</p>
<p>Victory! Open <a href="http://localhost:5232/">http://localhost:5232/</a> in your browser! You can log in with any username and password.</p>
</section>
<section class="level4" id="tutorials/simple-5-minute-setup/windows">
<h4>Windows <a class="headerlink" href="#tutorials/simple-5-minute-setup/windows">&para;</a></h4>
@ -277,7 +277,7 @@
<p>Launch a command prompt and type:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode powershell"><code class="sourceCode powershell"><span id="cb3-1"><a href="#cb3-1"></a>C:\Users\User&gt; python -m pip install --upgrade radicale</span>
<span id="cb3-2"><a href="#cb3-2"></a>C:\Users\User&gt; python -m radicale --storage-filesystem-folder=~/radicale/collections</span></code></pre></div>
<p>Victory! Open <a href="http://localhost:5232/">http://localhost:5232/</a> in your browser! You can login with any username and password.</p>
<p>Victory! Open <a href="http://localhost:5232/">http://localhost:5232/</a> in your browser! You can log in with any username and password.</p>
</section>
</section>
<section class="level3" id="tutorials/basic-configuration">
@ -436,7 +436,7 @@ user2:password2
</ul></li>
</ul>
<blockquote>
<p><strong>Security:</strong> 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.</p>
<p><strong>Security:</strong> 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.</p>
</blockquote>
<p>The log file might grow very big over time, you can configure file rotation in <strong>NSSM</strong> to prevent this.</p>
<p>The service is configured to start automatically when the computer starts. To start the service manually open <strong>Services</strong> in <strong>Computer Management</strong> and start the <strong>Radicale</strong> service.</p>
@ -613,7 +613,7 @@ user2:password2
</section>
<section class="level5" id="documentation/configuration/server/certificate_authority">
<h5>certificate_authority <a class="headerlink" href="#documentation/configuration/server/certificate_authority">&para;</a></h5>
<p>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.</p>
<p>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.</p>
<p>Default:</p>
</section>
</section>
@ -636,11 +636,11 @@ user2:password2
<h5>type <a class="headerlink" href="#documentation/configuration/auth/type">&para;</a></h5>
<p>The method to verify usernames and passwords.</p>
<p>Available backends:</p>
<p><code>None</code> : Just allows all usernames and passwords. It also disables rights checking.</p>
<p><code>none</code> : Just allows all usernames and passwords.</p>
<p><code>htpasswd</code> : Use an <a href="https://httpd.apache.org/docs/current/programs/htpasswd.html">Apache htpasswd file</a> to store usernames and passwords.</p>
<p><code>remote_user</code> : Takes the user name from the <code>REMOTE_USER</code> environment variable and disables HTTP authentication. This can be used to provide the user name from a WSGI server.</p>
<p><code>http_x_remote_user</code> : Takes the user name from the <code>X-Remote-User</code> HTTP header and disables HTTP authentication. This can be used to provide the user name from a reverse proxy.</p>
<p>Default: <code>None</code></p>
<p>Default: <code>none</code></p>
</section>
<section class="level5" id="documentation/configuration/auth/htpasswd_filename">
<h5>htpasswd_filename <a class="headerlink" href="#documentation/configuration/auth/htpasswd_filename">&para;</a></h5>
@ -675,9 +675,8 @@ user2:password2
<section class="level5" id="documentation/configuration/rights/type">
<h5>type <a class="headerlink" href="#documentation/configuration/rights/type">&para;</a></h5>
<p>The backend that is used to check the access rights of collections.</p>
<p>The recommended backend is <code>owner_only</code>. If access to calendars and address books outside of the home directory of users (that's <code>/USERNAME/</code>) 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.</p>
<p>The recommended backend is <code>owner_only</code>. If access to calendars and address books outside the home directory of users (that's <code>/USERNAME/</code>) 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.</p>
<p>Available backends:</p>
<p><code>None</code> : Everyone can read and write everything.</p>
<p><code>authenticated</code> : Authenticated users can read and write everything.</p>
<p><code>owner_only</code> : Authenticated users can read and write their own collections under the path <em>/USERNAME/</em>.</p>
<p><code>owner_write</code> : Authenticated users can read everything and write their own collections under the path <em>/USERNAME/</em>.</p>
@ -829,7 +828,7 @@ user2:password2
<section class="level3" id="documentation/authentication-and-rights">
<h3>Authentication and Rights <a class="headerlink" href="#documentation/authentication-and-rights">&para;</a></h3>
<p>This section describes the format of the rights file for the <code>from_file</code> authentication backend. The configuration option <code>file</code> in the <code>rights</code> section must point to the rights file.</p>
<p>The recommended rights method is <code>owner_only</code>. If access to calendars and address books outside of the home directory of users (that's <code>/USERNAME/</code>) 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.</p>
<p>The recommended rights method is <code>owner_only</code>. If access to calendars and address books outside the home directory of users (that's <code>/USERNAME/</code>) 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.</p>
<p>An example rights file:</p>
<div class="sourceCode" id="cb33"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb33-1"><a href="#cb33-1"></a><span class="co"># Allow reading root collection for authenticated users</span></span>
<span id="cb33-2"><a href="#cb33-2"></a><span class="kw">[root]</span></span>
@ -853,7 +852,7 @@ user2:password2
<p>The user name is empty for anonymous users. Therefore, the regex <code>.+</code> only matches authenticated users and <code>.*</code> matches everyone (including anonymous users).</p>
<p>The path of the collection is separated by <code>/</code> and has no leading or trailing <code>/</code>. Therefore, the path of the root collection is empty.</p>
<p>In the <code>collection</code> regex you can use <code>{user}</code> and get groups from the <code>user</code> regex with <code>{0}</code>, <code>{1}</code>, etc.</p>
<p>In consequence of the parameter subsitution you have to write <code>{{</code> and <code>}}</code> if you want to use regular curly braces in the <code>user</code> and <code>collection</code> regexes.</p>
<p>In consequence of the parameter substitution you have to write <code>{{</code> and <code>}}</code> if you want to use regular curly braces in the <code>user</code> and <code>collection</code> regexes.</p>
<p>The following <code>permissions</code> are recognized:</p>
<ul>
<li><strong>R:</strong> read collections (excluding address books and calendars)</li>
@ -878,7 +877,7 @@ user2:password2
<p>An item is represented by a file containing the iCalendar data.</p>
<p>All files and folders, whose names start with a dot but not <code>.Radicale.</code> (internal files) are ignored.</p>
<p>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.</p>
<p>Future releases of Radicale 2.x.x will store caches and sync-tokens in the <code>.Radicale.cache</code> 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.</p>
<p>Caches and sync-tokens are stored in the <code>.Radicale.cache</code> 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.</p>
<p>You may encounter files or folders that start with <code>.Radicale.tmp-</code>. 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.</p>
</section>
<section class="level4" id="documentation/storage/locking">
@ -907,7 +906,7 @@ user2:password2
<div class="sourceCode" id="cb35"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb35-1"><a href="#cb35-1"></a><span class="fu">{</span><span class="dt">"tag"</span><span class="fu">:</span> <span class="st">"VCALENDAR"</span><span class="fu">}</span></span></code></pre></div>
<p>The calendar is now available at the URL path <code>/user/calendar</code>. For address books the file must contain:</p>
<div class="sourceCode" id="cb36"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb36-1"><a href="#cb36-1"></a><span class="fu">{</span><span class="dt">"tag"</span><span class="fu">:</span> <span class="st">"VADDRESSBOOK"</span><span class="fu">}</span></span></code></pre></div>
<p>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 <code>/USERNAME/</code>.</p>
<p>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 <code>/USERNAME/</code>.</p>
<p>Delete collections by deleting the corresponding folders.</p>
</section>
</section>
@ -917,7 +916,7 @@ user2:password2
</section>
<section class="level3" id="documentation/architecture">
<h3>Architecture <a class="headerlink" href="#documentation/architecture">&para;</a></h3>
<p>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.</p>
<p>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.</p>
<section class="level4" id="documentation/architecture/protocol-overview">
<h4>Protocol overview <a class="headerlink" href="#documentation/architecture/protocol-overview">&para;</a></h4>
<p>Here is a simple overview of the global architecture for reaching a calendar or an address book through network:</p>
@ -973,7 +972,7 @@ user2:password2
<p><code>app</code> : 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.</p>
<p><code>auth</code> : Used for authenticating users based on username and password, mapping usernames to internal users and optionally retrieving credentials from the environment.</p>
<p><code>config</code> : Contains the code for managing configuration and loading settings from files.</p>
<p><code>&igrave;tem</code> : Internal represenation of address book and calendar entries. Based on <a href="https://eventable.github.io/vobject/">VObject</a>.</p>
<p><code>&igrave;tem</code> : Internal representation of address book and calendar entries. Based on <a href="https://eventable.github.io/vobject/">VObject</a>.</p>
<p><code>log</code> : The logger for Radicale based on the default Python logging module.</p>
<p><code>rights</code> : This module is used by Radicale to manage access rights to collections, address books and calendars.</p>
<p><code>server</code> : The integrated HTTP server for standalone use.</p>
@ -1111,14 +1110,14 @@ user2:password2
<h4>Main Goals <a class="headerlink" href="#about//main-goals">&para;</a></h4>
<p>Radicale is a complete calendar and contact storing and manipulating solution. It can store multiple calendars and multiple address books.</p>
<p>Calendar and contact manipulation is available from both local and distant accesses, possibly limited through authentication policies.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section>
<section class="level4" id="about//what-radicale-will-never-be">
<h4>What Radicale Will Never Be <a class="headerlink" href="#about//what-radicale-will-never-be">&para;</a></h4>
<p>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.</p>
<p>Radicale is a server, not a client. No interfaces will be created to work with the server.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section>
<section class="level4" id="about//technical-choices">
<h4>Technical Choices <a class="headerlink" href="#about//technical-choices">&para;</a></h4>
@ -1126,8 +1125,8 @@ user2:password2
<section class="level5" id="about//technical-choices/oriented-to-calendar-and-contact-user-agents">
<h5>Oriented to Calendar and Contact User Agents <a class="headerlink" href="#about//technical-choices/oriented-to-calendar-and-contact-user-agents">&para;</a></h5>
<p>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.</p>
<p>Some calendar servers have been created to follow the CalDAV and CardDAV RFCs as much as possible: <a href="http://www.davical.org/">Davical</a>, <a href="http://sabre.io/baikal/">Ba&iuml;kal</a> and <a href="http://trac.calendarserver.org/">Darwin Calendar Server</a>, 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.</p>
<p>Even if it tries it best to follow the RFCs, Radicale does not and <strong>will not</strong> blindly implements the CalDAV and CardDAV standards. It is mainly designed to support the CalDAV and CardDAV implementations of different clients.</p>
<p>Some calendar servers have been created to follow the CalDAV and CardDAV RFCs as much as possible: <a href="http://www.davical.org/">Davical</a>, <a href="http://sabre.io/baikal/">Ba&iuml;kal</a> and <a href="http://trac.calendarserver.org/">Darwin Calendar Server</a>, 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.</p>
<p>Even if it tries it best to follow the RFCs, Radicale does not and <strong>will not</strong> blindly implement the CalDAV and CardDAV standards. It is mainly designed to support the CalDAV and CardDAV implementations of different clients.</p>
</section>
<section class="level5" id="about//technical-choices/simple">
<h5>Simple <a class="headerlink" href="#about//technical-choices/simple">&para;</a></h5>
@ -1137,7 +1136,7 @@ user2:password2
</section>
<section class="level5" id="about//technical-choices/lazy">
<h5>Lazy <a class="headerlink" href="#about//technical-choices/lazy">&para;</a></h5>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section>
</section>