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

Generate documentation

Browse source
This commit is contained in:
Github Actions 2021-12-14 21:31:19 +00:00
parent 79e7992f20
commit bea2582390
4 changed files with 1649 additions and 1649 deletions
Download patch file Download diff file Expand all files Collapse all files

540
master.html
View file

@ -124,104 +124,104 @@
<ul> <ul>
<li class="level2"><a href="#getting-started">Getting started</a> <li class="level2"><a href="#getting-started">Getting started</a>
<ul> <ul>
<li class="level4"><a href="#getting-started//about-radicale">About Radicale</a></li> <li class="level4"><a href="#about-radicale">About Radicale</a></li>
<li class="level4"><a href="#getting-started//installation">Installation</a></li> <li class="level4"><a href="#installation">Installation</a></li>
<li class="level4"><a href="#getting-started//whats-new">What's New?</a></li> <li class="level4"><a href="#whats-new">What's New?</a></li>
</ul></li> </ul></li>
<li class="level2"><a href="#tutorials">Tutorials</a> <li class="level2"><a href="#tutorials">Tutorials</a>
<ul> <ul>
<li class="level3"><a href="#tutorials/simple-5-minute-setup">Simple 5-minute setup</a> <li class="level3"><a href="#simple-5-minute-setup">Simple 5-minute setup</a>
<ul> <ul>
<li class="level4"><a href="#tutorials/simple-5-minute-setup/linux--bsd">Linux / *BSD</a></li> <li class="level4"><a href="#linux--bsd">Linux / *BSD</a></li>
<li class="level4"><a href="#tutorials/simple-5-minute-setup/windows">Windows</a></li> <li class="level4"><a href="#windows">Windows</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#tutorials/basic-configuration">Basic Configuration</a> <li class="level3"><a href="#basic-configuration">Basic Configuration</a>
<ul> <ul>
<li class="level4"><a href="#tutorials/basic-configuration/authentication">Authentication</a></li> <li class="level4"><a href="#authentication">Authentication</a></li>
<li class="level4"><a href="#tutorials/basic-configuration/addresses">Addresses</a></li> <li class="level4"><a href="#addresses">Addresses</a></li>
<li class="level4"><a href="#tutorials/basic-configuration/storage">Storage</a></li> <li class="level4"><a href="#storage">Storage</a></li>
<li class="level4"><a href="#tutorials/basic-configuration/limits">Limits</a></li> <li class="level4"><a href="#limits">Limits</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#tutorials/running-as-a-service">Running as a service</a> <li class="level3"><a href="#running-as-a-service">Running as a service</a>
<ul> <ul>
<li class="level4"><a href="#tutorials/running-as-a-service/linux-with-systemd-system-wide">Linux with systemd system-wide</a></li> <li class="level4"><a href="#linux-with-systemd-system-wide">Linux with systemd system-wide</a></li>
<li class="level4"><a href="#tutorials/running-as-a-service/linux-with-systemd-as-a-user">Linux with systemd as a user</a></li> <li class="level4"><a href="#linux-with-systemd-as-a-user">Linux with systemd as a user</a></li>
<li class="level4"><a href="#tutorials/running-as-a-service/windows-with-nssm---the-non-sucking-service-manager">Windows with "NSSM - the Non-Sucking Service Manager"</a></li> <li class="level4"><a href="#windows-with-nssm---the-non-sucking-service-manager">Windows with "NSSM - the Non-Sucking Service Manager"</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#tutorials/reverse-proxy">Reverse Proxy</a> <li class="level3"><a href="#reverse-proxy">Reverse Proxy</a>
<ul> <ul>
<li class="level4"><a href="#tutorials/reverse-proxy/manage-user-accounts-with-the-reverse-proxy">Manage user accounts with the reverse proxy</a></li> <li class="level4"><a href="#manage-user-accounts-with-the-reverse-proxy">Manage user accounts with the reverse proxy</a></li>
<li class="level4"><a href="#tutorials/reverse-proxy/secure-connection-between-radicale-and-the-reverse-proxy">Secure connection between Radicale and the reverse proxy</a></li> <li class="level4"><a href="#secure-connection-between-radicale-and-the-reverse-proxy">Secure connection between Radicale and the reverse proxy</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#tutorials/wsgi-server">WSGI Server</a> <li class="level3"><a href="#wsgi-server">WSGI Server</a>
<ul> <ul>
<li class="level4"><a href="#tutorials/wsgi-server/manage-user-accounts-with-the-wsgi-server">Manage user accounts with the WSGI server</a></li> <li class="level4"><a href="#manage-user-accounts-with-the-wsgi-server">Manage user accounts with the WSGI server</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#tutorials/versioning-with-git">Versioning with Git</a></li> <li class="level3"><a href="#versioning-with-git">Versioning with Git</a></li>
</ul></li> </ul></li>
<li class="level2"><a href="#documentation">Documentation</a> <li class="level2"><a href="#documentation-1">Documentation</a>
<ul> <ul>
<li class="level3"><a href="#documentation/configuration">Configuration</a> <li class="level3"><a href="#configuration">Configuration</a>
<ul> <ul>
<li class="level4"><a href="#documentation/configuration/server">server</a></li> <li class="level4"><a href="#server">server</a></li>
<li class="level4"><a href="#documentation/configuration/encoding">encoding</a></li> <li class="level4"><a href="#encoding">encoding</a></li>
<li class="level4"><a href="#documentation/configuration/auth">auth</a></li> <li class="level4"><a href="#auth">auth</a></li>
<li class="level4"><a href="#documentation/configuration/rights">rights</a></li> <li class="level4"><a href="#rights">rights</a></li>
<li class="level4"><a href="#documentation/configuration/storage">storage</a></li> <li class="level4"><a href="#storage-1">storage</a></li>
<li class="level4"><a href="#documentation/configuration/web">web</a></li> <li class="level4"><a href="#web">web</a></li>
<li class="level4"><a href="#documentation/configuration/logging">logging</a></li> <li class="level4"><a href="#logging">logging</a></li>
<li class="level4"><a href="#documentation/configuration/headers">headers</a></li> <li class="level4"><a href="#headers">headers</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#documentation/supported-clients">Supported Clients</a> <li class="level3"><a href="#supported-clients">Supported Clients</a>
<ul> <ul>
<li class="level4"><a href="#documentation/supported-clients/davx⁵">DAVx⁵</a></li> <li class="level4"><a href="#davx⁵">DAVx⁵</a></li>
<li class="level4"><a href="#documentation/supported-clients/gnome-calendar-contacts-and-evolution">GNOME Calendar, Contacts and Evolution</a></li> <li class="level4"><a href="#gnome-calendar-contacts-and-evolution">GNOME Calendar, Contacts and Evolution</a></li>
<li class="level4"><a href="#documentation/supported-clients/thunderbird">Thunderbird</a></li> <li class="level4"><a href="#thunderbird">Thunderbird</a></li>
<li class="level4"><a href="#documentation/supported-clients/infcloud-caldavzap-and-carddavmate">InfCloud, CalDavZAP and CardDavMATE</a></li> <li class="level4"><a href="#infcloud-caldavzap-and-carddavmate">InfCloud, CalDavZAP and CardDavMATE</a></li>
<li class="level4"><a href="#documentation/supported-clients/command-line">Command line</a></li> <li class="level4"><a href="#command-line">Command line</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#documentation/authentication-and-rights">Authentication and Rights</a></li> <li class="level3"><a href="#authentication-and-rights">Authentication and Rights</a></li>
<li class="level3"><a href="#documentation/storage">Storage</a> <li class="level3"><a href="#storage-2">Storage</a>
<ul> <ul>
<li class="level4"><a href="#documentation/storage/layout">Layout</a></li> <li class="level4"><a href="#layout">Layout</a></li>
<li class="level4"><a href="#documentation/storage/locking">Locking</a></li> <li class="level4"><a href="#locking">Locking</a></li>
<li class="level4"><a href="#documentation/storage/manually-creating-collections">Manually creating collections</a></li> <li class="level4"><a href="#manually-creating-collections">Manually creating collections</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#documentation/logging">Logging</a></li> <li class="level3"><a href="#logging-1">Logging</a></li>
<li class="level3"><a href="#documentation/architecture">Architecture</a> <li class="level3"><a href="#architecture">Architecture</a>
<ul> <ul>
<li class="level4"><a href="#documentation/architecture/protocol-overview">Protocol overview</a></li> <li class="level4"><a href="#protocol-overview">Protocol overview</a></li>
<li class="level4"><a href="#documentation/architecture/code-architecture">Code Architecture</a></li> <li class="level4"><a href="#code-architecture">Code Architecture</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#documentation/plugins">Plugins</a> <li class="level3"><a href="#plugins">Plugins</a>
<ul> <ul>
<li class="level4"><a href="#documentation/plugins/getting-started">Getting started</a></li> <li class="level4"><a href="#getting-started-1">Getting started</a></li>
<li class="level4"><a href="#documentation/plugins/authentication-plugins">Authentication plugins</a></li> <li class="level4"><a href="#authentication-plugins">Authentication plugins</a></li>
<li class="level4"><a href="#documentation/plugins/rights-management-plugins">Rights management plugins</a></li> <li class="level4"><a href="#rights-management-plugins">Rights management plugins</a></li>
<li class="level4"><a href="#documentation/plugins/web-plugins">Web plugins</a></li> <li class="level4"><a href="#web-plugins">Web plugins</a></li>
<li class="level4"><a href="#documentation/plugins/storage-plugins">Storage plugins</a></li> <li class="level4"><a href="#storage-plugins">Storage plugins</a></li>
</ul></li> </ul></li>
</ul></li> </ul></li>
<li class="level2"><a href="#contribute">Contribute</a> <li class="level2"><a href="#contribute">Contribute</a>
<ul> <ul>
<li class="level4"><a href="#contribute//chat-with-us-on-irc">Chat with Us on IRC</a></li> <li class="level4"><a href="#chat-with-us-on-irc">Chat with Us on IRC</a></li>
<li class="level4"><a href="#contribute//report-bugs">Report Bugs</a></li> <li class="level4"><a href="#report-bugs">Report Bugs</a></li>
<li class="level4"><a href="#contribute//hack">Hack</a></li> <li class="level4"><a href="#hack">Hack</a></li>
<li class="level4"><a href="#contribute//documentation">Documentation</a></li> <li class="level4"><a href="#documentation-2">Documentation</a></li>
</ul></li> </ul></li>
<li class="level2"><a href="#download">Download</a> <li class="level2"><a href="#download">Download</a>
<ul> <ul>
<li class="level4"><a href="#download//pypi">PyPI</a></li> <li class="level4"><a href="#pypi">PyPI</a></li>
<li class="level4"><a href="#download//git-repository">Git Repository</a></li> <li class="level4"><a href="#git-repository">Git Repository</a></li>
<li class="level4"><a href="#download//source-packages">Source Packages</a></li> <li class="level4"><a href="#source-packages">Source Packages</a></li>
<li class="level4"><a href="#download//linux-distribution-packages">Linux Distribution Packages</a></li> <li class="level4"><a href="#linux-distribution-packages">Linux Distribution Packages</a></li>
</ul></li> </ul></li>
<li class="level2"><a href="#about">About</a> <li class="level2"><a href="#about">About</a>
<ul> <ul>
<li class="level4"><a href="#about//main-goals">Main Goals</a></li> <li class="level4"><a href="#main-goals">Main Goals</a></li>
<li class="level4"><a href="#about//what-radicale-will-never-be">What Radicale Will Never Be</a></li> <li class="level4"><a href="#what-radicale-will-never-be">What Radicale Will Never Be</a></li>
<li class="level4"><a href="#about//technical-choices">Technical Choices</a></li> <li class="level4"><a href="#technical-choices">Technical Choices</a></li>
<li class="level4"><a href="#about//history">History</a></li> <li class="level4"><a href="#history">History</a></li>
</ul></li> </ul></li>
</ul> </ul>
</div> </div>
@ -229,8 +229,8 @@
<div class="documentContainer"> <div class="documentContainer">
<section class="level2" id="getting-started"> <section class="level2" id="getting-started">
<h2>Getting started <a class="headerlink" href="#getting-started">&para;</a></h2> <h2>Getting started <a class="headerlink" href="#getting-started">&para;</a></h2>
<section class="level4" id="getting-started//about-radicale"> <section class="level4" id="about-radicale">
<h4>About Radicale <a class="headerlink" href="#getting-started//about-radicale">&para;</a></h4> <h4>About Radicale <a class="headerlink" href="#about-radicale">&para;</a></h4>
<p>Radicale is a small but powerful CalDAV (calendars, to-do 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> <ul>
<li>Shares calendars and contact lists through CalDAV, CardDAV and HTTP.</li> <li>Shares calendars and contact lists through CalDAV, CardDAV and HTTP.</li>
@ -238,34 +238,34 @@
<li>Works out-of-the-box, no complicated setup or configuration required.</li> <li>Works out-of-the-box, no complicated setup or configuration required.</li>
<li>Can limit access by authentication.</li> <li>Can limit access by authentication.</li>
<li>Can secure connections with TLS.</li> <li>Can secure connections with TLS.</li>
<li>Works with many <a href="#documentation/supported-clients">CalDAV and CardDAV clients</a>.</li> <li>Works with many <a href="#supported-clients">CalDAV and CardDAV clients</a>.</li>
<li>Stores all data on the file system in a simple folder structure.</li> <li>Stores all data on the file system in a simple folder structure.</li>
<li>Can be extended with plugins.</li> <li>Can be extended with plugins.</li>
<li>Is GPLv3-licensed free software.</li> <li>Is GPLv3-licensed free software.</li>
</ul> </ul>
</section> </section>
<section class="level4" id="getting-started//installation"> <section class="level4" id="installation">
<h4>Installation <a class="headerlink" href="#getting-started//installation">&para;</a></h4> <h4>Installation <a class="headerlink" href="#installation">&para;</a></h4>
<p>Radicale is really easy to install and works out-of-the-box.</p> <p>Radicale is really easy to install and works out-of-the-box.</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a aria-hidden="true" href="#cb1-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> pip install <span class="at">--upgrade</span> https://github.com/Kozea/Radicale/archive/master.tar.gz</span> <div class="sourceCode" id="cb1"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a aria-hidden="true" href="#cb1-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> pip install <span class="at">--upgrade</span> https://github.com/Kozea/Radicale/archive/master.tar.gz</span>
<span id="cb1-2"><a aria-hidden="true" href="#cb1-2" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> radicale <span class="at">--storage-filesystem-folder</span><span class="op">=</span>~/.var/lib/radicale/collections</span></code></pre></div> <span id="cb1-2"><a aria-hidden="true" href="#cb1-2" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> radicale <span class="at">--storage-filesystem-folder</span><span class="op">=</span>~/.var/lib/radicale/collections</span></code></pre></div>
<p>When the server is launched, open <a href="http://localhost:5232">http://localhost:5232</a> in your browser! You can login with any username and password.</p> <p>When the server is launched, open <a href="http://localhost:5232">http://localhost:5232</a> in your browser! You can login with any username and password.</p>
<p>Want more? Check the <a href="#tutorials">tutorials</a> and the <a href="#documentation">documentation</a>.</p> <p>Want more? Check the <a href="#tutorials">tutorials</a> and the <a href="#documentation-1">documentation</a>.</p>
</section> </section>
<section class="level4" id="getting-started//whats-new"> <section class="level4" id="whats-new">
<h4>What's New? <a class="headerlink" href="#getting-started//whats-new">&para;</a></h4> <h4>What's New? <a class="headerlink" href="#whats-new">&para;</a></h4>
<p>Read the <a href="https://github.com/Kozea/Radicale/blob/master/NEWS.md">changelog on GitHub.</a></p> <p>Read the <a href="https://github.com/Kozea/Radicale/blob/master/NEWS.md">changelog on GitHub.</a></p>
</section> </section>
</section> </section>
<section class="level2" id="tutorials"> <section class="level2" id="tutorials">
<h2>Tutorials <a class="headerlink" href="#tutorials">&para;</a></h2> <h2>Tutorials <a class="headerlink" href="#tutorials">&para;</a></h2>
<section class="level3" id="tutorials/simple-5-minute-setup"> <section class="level3" id="simple-5-minute-setup">
<h3>Simple 5-minute setup <a class="headerlink" href="#tutorials/simple-5-minute-setup">&para;</a></h3> <h3>Simple 5-minute setup <a class="headerlink" href="#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 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>When everything works, you can get a <a href="#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="#basic-configuration">some basic configuration</a>.</p>
<p>Follow one of the chapters below depending on your operating system.</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"> <section class="level4" id="linux--bsd">
<h4>Linux / *BSD <a class="headerlink" href="#tutorials/simple-5-minute-setup/linux--bsd">&para;</a></h4> <h4>Linux / *BSD <a class="headerlink" href="#linux--bsd">&para;</a></h4>
<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>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> <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 aria-hidden="true" href="#cb2-1" tabindex="-1"></a><span class="co"># Run the following command as root or</span></span> <div class="sourceCode" id="cb2"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb2-1"><a aria-hidden="true" href="#cb2-1" tabindex="-1"></a><span class="co"># Run the following command as root or</span></span>
@ -274,8 +274,8 @@
<span id="cb2-4"><a aria-hidden="true" href="#cb2-4" tabindex="-1"></a><span class="ex">$</span> python3 <span class="at">-m</span> radicale <span class="at">--storage-filesystem-folder</span><span class="op">=</span>~/.var/lib/radicale/collections</span></code></pre></div> <span id="cb2-4"><a aria-hidden="true" href="#cb2-4" tabindex="-1"></a><span class="ex">$</span> python3 <span class="at">-m</span> radicale <span class="at">--storage-filesystem-folder</span><span class="op">=</span>~/.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 log in 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="level4" id="tutorials/simple-5-minute-setup/windows"> <section class="level4" id="windows">
<h4>Windows <a class="headerlink" href="#tutorials/simple-5-minute-setup/windows">&para;</a></h4> <h4>Windows <a class="headerlink" href="#windows">&para;</a></h4>
<p>The first step is to install Python. Go to <a href="https://python.org">python.org</a> and download the latest version of Python 3. Then run the installer. On the first window of the installer, check the "Add Python to PATH" box and click on "Install now". Wait a couple of minutes, it's done!</p> <p>The first step is to install Python. Go to <a href="https://python.org">python.org</a> and download the latest version of Python 3. Then run the installer. On the first window of the installer, check the "Add Python to PATH" box and click on "Install now". Wait a couple of minutes, it's done!</p>
<p>Launch a command prompt and type:</p> <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 aria-hidden="true" href="#cb3-1" tabindex="-1"></a>C<span class="op">:</span>\Users\User<span class="op">&gt;</span> python <span class="op">-</span>m pip install <span class="op">--</span>upgrade https<span class="op">://</span>github<span class="op">.</span><span class="fu">com</span><span class="op">/</span>Kozea<span class="op">/</span>Radicale<span class="op">/</span>archive<span class="op">/</span>master<span class="op">.</span><span class="fu">tar</span><span class="op">.</span><span class="fu">gz</span></span> <div class="sourceCode" id="cb3"><pre class="sourceCode powershell"><code class="sourceCode powershell"><span id="cb3-1"><a aria-hidden="true" href="#cb3-1" tabindex="-1"></a>C<span class="op">:</span>\Users\User<span class="op">&gt;</span> python <span class="op">-</span>m pip install <span class="op">--</span>upgrade https<span class="op">://</span>github<span class="op">.</span><span class="fu">com</span><span class="op">/</span>Kozea<span class="op">/</span>Radicale<span class="op">/</span>archive<span class="op">/</span>master<span class="op">.</span><span class="fu">tar</span><span class="op">.</span><span class="fu">gz</span></span>
@ -283,18 +283,18 @@
<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> <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> </section>
<section class="level3" id="tutorials/basic-configuration"> <section class="level3" id="basic-configuration">
<h3>Basic Configuration <a class="headerlink" href="#tutorials/basic-configuration">&para;</a></h3> <h3>Basic Configuration <a class="headerlink" href="#basic-configuration">&para;</a></h3>
<p>Installation instructions can be found in the <a href="#tutorials/simple-5-minute-setup">simple 5-minute setup</a> tutorial.</p> <p>Installation instructions can be found in the <a href="#simple-5-minute-setup">simple 5-minute setup</a> tutorial.</p>
<p>Radicale tries to load configuration files from <code>/etc/radicale/config</code> and <code>~/.config/radicale/config</code>. Custom paths can be specified with the <code>--config /path/to/config</code> command line argument or the <code>RADICALE_CONFIG</code> environment variable. Multiple configuration files can be separated by <code>:</code> (resp. <code>;</code> on Windows). Paths that start with <code>?</code> are optional.</p> <p>Radicale tries to load configuration files from <code>/etc/radicale/config</code> and <code>~/.config/radicale/config</code>. Custom paths can be specified with the <code>--config /path/to/config</code> command line argument or the <code>RADICALE_CONFIG</code> environment variable. Multiple configuration files can be separated by <code>:</code> (resp. <code>;</code> on Windows). Paths that start with <code>?</code> are optional.</p>
<p>You should create a new configuration file at the desired location. (If the use of a configuration file is inconvenient, all options can be passed via command line arguments.)</p> <p>You should create a new configuration file at the desired location. (If the use of a configuration file is inconvenient, all options can be passed via command line arguments.)</p>
<p>All configuration options are described in detail in the <a href="#documentation/configuration">Configuration</a> section.</p> <p>All configuration options are described in detail in the <a href="#configuration">Configuration</a> section.</p>
<section class="level4" id="tutorials/basic-configuration/authentication"> <section class="level4" id="authentication">
<h4>Authentication <a class="headerlink" href="#tutorials/basic-configuration/authentication">&para;</a></h4> <h4>Authentication <a class="headerlink" href="#authentication">&para;</a></h4>
<p>In its default configuration Radicale doesn't check user names or passwords. If the server is reachable over a network, you should change this.</p> <p>In its default configuration Radicale doesn't check user names or passwords. If the server is reachable over a network, you should change this.</p>
<p>First a <code>users</code> file with all user names and passwords must be created. It can be stored in the same directory as the configuration file.</p> <p>First a <code>users</code> file with all user names and passwords must be created. It can be stored in the same directory as the configuration file.</p>
<section class="level5" id="tutorials/basic-configuration/authentication/the-secure-way"> <section class="level5" id="the-secure-way">
<h5>The secure way <a class="headerlink" href="#tutorials/basic-configuration/authentication/the-secure-way">&para;</a></h5> <h5>The secure way <a class="headerlink" href="#the-secure-way">&para;</a></h5>
<p>The <code>users</code> file can be created and managed with <a href="https://httpd.apache.org/docs/current/programs/htpasswd.html">htpasswd</a>:</p> <p>The <code>users</code> file can be created and managed with <a href="https://httpd.apache.org/docs/current/programs/htpasswd.html">htpasswd</a>:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a aria-hidden="true" href="#cb4-1" tabindex="-1"></a><span class="co"># Create a new htpasswd file with the user "user1"</span></span> <div class="sourceCode" id="cb4"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a aria-hidden="true" href="#cb4-1" tabindex="-1"></a><span class="co"># Create a new htpasswd file with the user "user1"</span></span>
<span id="cb4-2"><a aria-hidden="true" href="#cb4-2" tabindex="-1"></a><span class="ex">$</span> htpasswd <span class="at">-c</span> /path/to/users user1</span> <span id="cb4-2"><a aria-hidden="true" href="#cb4-2" tabindex="-1"></a><span class="ex">$</span> htpasswd <span class="at">-c</span> /path/to/users user1</span>
@ -311,8 +311,8 @@
<span id="cb5-4"><a aria-hidden="true" href="#cb5-4" tabindex="-1"></a><span class="co"># encryption method used in the htpasswd file</span></span> <span id="cb5-4"><a aria-hidden="true" href="#cb5-4" tabindex="-1"></a><span class="co"># encryption method used in the htpasswd file</span></span>
<span id="cb5-5"><a aria-hidden="true" href="#cb5-5" tabindex="-1"></a><span class="dt">htpasswd_encryption </span><span class="ot">=</span><span class="st"> md5</span></span></code></pre></div> <span id="cb5-5"><a aria-hidden="true" href="#cb5-5" tabindex="-1"></a><span class="dt">htpasswd_encryption </span><span class="ot">=</span><span class="st"> md5</span></span></code></pre></div>
</section> </section>
<section class="level5" id="tutorials/basic-configuration/authentication/the-simple-but-insecure-way"> <section class="level5" id="the-simple-but-insecure-way">
<h5>The simple but insecure way <a class="headerlink" href="#tutorials/basic-configuration/authentication/the-simple-but-insecure-way">&para;</a></h5> <h5>The simple but insecure way <a class="headerlink" href="#the-simple-but-insecure-way">&para;</a></h5>
<p>Create the <code>users</code> file by hand with lines containing the user name and password separated by <code>:</code>. Example:</p> <p>Create the <code>users</code> file by hand with lines containing the user name and password separated by <code>:</code>. Example:</p>
<pre class="htpasswd"><code>user1:password1 <pre class="htpasswd"><code>user1:password1
user2:password2</code></pre> user2:password2</code></pre>
@ -324,23 +324,23 @@ user2:password2</code></pre>
<span id="cb7-5"><a aria-hidden="true" href="#cb7-5" tabindex="-1"></a><span class="dt">htpasswd_encryption </span><span class="ot">=</span><span class="st"> plain</span></span></code></pre></div> <span id="cb7-5"><a aria-hidden="true" href="#cb7-5" tabindex="-1"></a><span class="dt">htpasswd_encryption </span><span class="ot">=</span><span class="st"> plain</span></span></code></pre></div>
</section> </section>
</section> </section>
<section class="level4" id="tutorials/basic-configuration/addresses"> <section class="level4" id="addresses">
<h4>Addresses <a class="headerlink" href="#tutorials/basic-configuration/addresses">&para;</a></h4> <h4>Addresses <a class="headerlink" href="#addresses">&para;</a></h4>
<p>The default configuration binds the server to localhost. It can't be reached from other computers. This can be changed with the following configuration options (IPv4 and IPv6):</p> <p>The default configuration binds the server to localhost. It can't be reached from other computers. This can be changed with the following configuration options (IPv4 and IPv6):</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb8-1"><a aria-hidden="true" href="#cb8-1" tabindex="-1"></a><span class="kw">[server]</span></span> <div class="sourceCode" id="cb8"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb8-1"><a aria-hidden="true" href="#cb8-1" tabindex="-1"></a><span class="kw">[server]</span></span>
<span id="cb8-2"><a aria-hidden="true" href="#cb8-2" tabindex="-1"></a><span class="dt">hosts </span><span class="ot">=</span><span class="st"> 0.0.0.0:5232, [::]:5232</span></span></code></pre></div> <span id="cb8-2"><a aria-hidden="true" href="#cb8-2" tabindex="-1"></a><span class="dt">hosts </span><span class="ot">=</span><span class="st"> 0.0.0.0:5232, [::]:5232</span></span></code></pre></div>
</section> </section>
<section class="level4" id="tutorials/basic-configuration/storage"> <section class="level4" id="storage">
<h4>Storage <a class="headerlink" href="#tutorials/basic-configuration/storage">&para;</a></h4> <h4>Storage <a class="headerlink" href="#storage">&para;</a></h4>
<p>Data is stored in the folder <code>/var/lib/radicale/collections</code>. The path can be changed with the following configuration:</p> <p>Data is stored in the folder <code>/var/lib/radicale/collections</code>. The path can be changed with the following configuration:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb9-1"><a aria-hidden="true" href="#cb9-1" tabindex="-1"></a><span class="kw">[storage]</span></span> <div class="sourceCode" id="cb9"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb9-1"><a aria-hidden="true" href="#cb9-1" tabindex="-1"></a><span class="kw">[storage]</span></span>
<span id="cb9-2"><a aria-hidden="true" href="#cb9-2" tabindex="-1"></a><span class="dt">filesystem_folder </span><span class="ot">=</span><span class="st"> /path/to/storage</span></span></code></pre></div> <span id="cb9-2"><a aria-hidden="true" href="#cb9-2" tabindex="-1"></a><span class="dt">filesystem_folder </span><span class="ot">=</span><span class="st"> /path/to/storage</span></span></code></pre></div>
<blockquote> <blockquote>
<p><strong>Security:</strong> The storage folder should not be readable by unauthorized users. Otherwise, they can read the calendar data and lock the storage. You can find OS dependent instructions in the <a href="#tutorials/running-as-a-service">Running as a service</a> section.</p> <p><strong>Security:</strong> The storage folder should not be readable by unauthorized users. Otherwise, they can read the calendar data and lock the storage. You can find OS dependent instructions in the <a href="#running-as-a-service">Running as a service</a> section.</p>
</blockquote> </blockquote>
</section> </section>
<section class="level4" id="tutorials/basic-configuration/limits"> <section class="level4" id="limits">
<h4>Limits <a class="headerlink" href="#tutorials/basic-configuration/limits">&para;</a></h4> <h4>Limits <a class="headerlink" href="#limits">&para;</a></h4>
<p>Radicale enforces limits on the maximum number of parallel connections, the maximum file size (important for contacts with big photos) and the rate of incorrect authentication attempts. Connections are terminated after a timeout. The default values should be fine for most scenarios.</p> <p>Radicale enforces limits on the maximum number of parallel connections, the maximum file size (important for contacts with big photos) and the rate of incorrect authentication attempts. Connections are terminated after a timeout. The default values should be fine for most scenarios.</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb10-1"><a aria-hidden="true" href="#cb10-1" tabindex="-1"></a><span class="kw">[server]</span></span> <div class="sourceCode" id="cb10"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb10-1"><a aria-hidden="true" href="#cb10-1" tabindex="-1"></a><span class="kw">[server]</span></span>
<span id="cb10-2"><a aria-hidden="true" href="#cb10-2" tabindex="-1"></a><span class="dt">max_connections </span><span class="ot">=</span><span class="st"> </span><span class="dv">20</span></span> <span id="cb10-2"><a aria-hidden="true" href="#cb10-2" tabindex="-1"></a><span class="dt">max_connections </span><span class="ot">=</span><span class="st"> </span><span class="dv">20</span></span>
@ -354,11 +354,11 @@ user2:password2</code></pre>
<span id="cb10-10"><a aria-hidden="true" href="#cb10-10" tabindex="-1"></a><span class="dt">delay </span><span class="ot">=</span><span class="st"> </span><span class="dv">1</span></span></code></pre></div> <span id="cb10-10"><a aria-hidden="true" href="#cb10-10" tabindex="-1"></a><span class="dt">delay </span><span class="ot">=</span><span class="st"> </span><span class="dv">1</span></span></code></pre></div>
</section> </section>
</section> </section>
<section class="level3" id="tutorials/running-as-a-service"> <section class="level3" id="running-as-a-service">
<h3>Running as a service <a class="headerlink" href="#tutorials/running-as-a-service">&para;</a></h3> <h3>Running as a service <a class="headerlink" href="#running-as-a-service">&para;</a></h3>
<p>The method to run Radicale as a service depends on your host operating system. Follow one of the chapters below depending on your operating system and requirements.</p> <p>The method to run Radicale as a service depends on your host operating system. Follow one of the chapters below depending on your operating system and requirements.</p>
<section class="level4" id="tutorials/running-as-a-service/linux-with-systemd-system-wide"> <section class="level4" id="linux-with-systemd-system-wide">
<h4>Linux with systemd system-wide <a class="headerlink" href="#tutorials/running-as-a-service/linux-with-systemd-system-wide">&para;</a></h4> <h4>Linux with systemd system-wide <a class="headerlink" href="#linux-with-systemd-system-wide">&para;</a></h4>
<p>Create the <strong>radicale</strong> user and group for the Radicale service. (Run <code>useradd --system --user-group --home-dir / --shell /sbin/nologin radicale</code> as root.) The storage folder must be writable by <strong>radicale</strong>. (Run <code>mkdir -p /var/lib/radicale/collections &amp;&amp; chown -R radicale:radicale /var/lib/radicale/collections</code> as root.)</p> <p>Create the <strong>radicale</strong> user and group for the Radicale service. (Run <code>useradd --system --user-group --home-dir / --shell /sbin/nologin radicale</code> as root.) The storage folder must be writable by <strong>radicale</strong>. (Run <code>mkdir -p /var/lib/radicale/collections &amp;&amp; chown -R radicale:radicale /var/lib/radicale/collections</code> as root.)</p>
<blockquote> <blockquote>
<p><strong>Security:</strong> The storage should not be readable by others. (Run <code>chmod -R o= /var/lib/radicale/collections</code> as root.)</p> <p><strong>Security:</strong> The storage should not be readable by others. (Run <code>chmod -R o= /var/lib/radicale/collections</code> as root.)</p>
@ -399,8 +399,8 @@ user2:password2</code></pre>
<span id="cb12-7"><a aria-hidden="true" href="#cb12-7" tabindex="-1"></a><span class="co"># View all log messages</span></span> <span id="cb12-7"><a aria-hidden="true" href="#cb12-7" tabindex="-1"></a><span class="co"># View all log messages</span></span>
<span id="cb12-8"><a aria-hidden="true" href="#cb12-8" tabindex="-1"></a><span class="ex">$</span> journalctl <span class="at">--unit</span> radicale.service</span></code></pre></div> <span id="cb12-8"><a aria-hidden="true" href="#cb12-8" tabindex="-1"></a><span class="ex">$</span> journalctl <span class="at">--unit</span> radicale.service</span></code></pre></div>
</section> </section>
<section class="level4" id="tutorials/running-as-a-service/linux-with-systemd-as-a-user"> <section class="level4" id="linux-with-systemd-as-a-user">
<h4>Linux with systemd as a user <a class="headerlink" href="#tutorials/running-as-a-service/linux-with-systemd-as-a-user">&para;</a></h4> <h4>Linux with systemd as a user <a class="headerlink" href="#linux-with-systemd-as-a-user">&para;</a></h4>
<p>Create the file <code>~/.config/systemd/user/radicale.service</code>:</p> <p>Create the file <code>~/.config/systemd/user/radicale.service</code>:</p>
<div class="sourceCode" id="cb13"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb13-1"><a aria-hidden="true" href="#cb13-1" tabindex="-1"></a><span class="kw">[Unit]</span></span> <div class="sourceCode" id="cb13"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb13-1"><a aria-hidden="true" href="#cb13-1" tabindex="-1"></a><span class="kw">[Unit]</span></span>
<span id="cb13-2"><a aria-hidden="true" href="#cb13-2" tabindex="-1"></a><span class="dt">Description</span><span class="ot">=</span><span class="st">A simple CalDAV (calendar) and CardDAV (contact) server</span></span> <span id="cb13-2"><a aria-hidden="true" href="#cb13-2" tabindex="-1"></a><span class="dt">Description</span><span class="ot">=</span><span class="st">A simple CalDAV (calendar) and CardDAV (contact) server</span></span>
@ -422,8 +422,8 @@ user2:password2</code></pre>
<span id="cb14-7"><a aria-hidden="true" href="#cb14-7" tabindex="-1"></a><span class="co"># View all log messages</span></span> <span id="cb14-7"><a aria-hidden="true" href="#cb14-7" tabindex="-1"></a><span class="co"># View all log messages</span></span>
<span id="cb14-8"><a aria-hidden="true" href="#cb14-8" tabindex="-1"></a><span class="ex">$</span> journalctl <span class="at">--user</span> <span class="at">--unit</span> radicale.service</span></code></pre></div> <span id="cb14-8"><a aria-hidden="true" href="#cb14-8" tabindex="-1"></a><span class="ex">$</span> journalctl <span class="at">--user</span> <span class="at">--unit</span> radicale.service</span></code></pre></div>
</section> </section>
<section class="level4" id="tutorials/running-as-a-service/windows-with-nssm---the-non-sucking-service-manager"> <section class="level4" id="windows-with-nssm---the-non-sucking-service-manager">
<h4>Windows with "NSSM - the Non-Sucking Service Manager" <a class="headerlink" href="#tutorials/running-as-a-service/windows-with-nssm---the-non-sucking-service-manager">&para;</a></h4> <h4>Windows with "NSSM - the Non-Sucking Service Manager" <a class="headerlink" href="#windows-with-nssm---the-non-sucking-service-manager">&para;</a></h4>
<p>First install <a href="https://nssm.cc/">NSSM</a> and start <code>nssm install</code> in a command prompt. Apply the following configuration:</p> <p>First install <a href="https://nssm.cc/">NSSM</a> and start <code>nssm install</code> in a command prompt. Apply the following configuration:</p>
<ul> <ul>
<li>Service name: <code>Radicale</code></li> <li>Service name: <code>Radicale</code></li>
@ -444,8 +444,8 @@ user2:password2</code></pre>
<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> <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>
</section> </section>
</section> </section>
<section class="level3" id="tutorials/reverse-proxy"> <section class="level3" id="reverse-proxy">
<h3>Reverse Proxy <a class="headerlink" href="#tutorials/reverse-proxy">&para;</a></h3> <h3>Reverse Proxy <a class="headerlink" href="#reverse-proxy">&para;</a></h3>
<p>When a reverse proxy is used, the path at which Radicale is available must be provided via the <code>X-Script-Name</code> header. The proxy must remove the location from the URL path that is forwarded to Radicale.</p> <p>When a reverse proxy is used, the path at which Radicale is available must be provided via the <code>X-Script-Name</code> header. The proxy must remove the location from the URL path that is forwarded to Radicale.</p>
<p>Example <strong>nginx</strong> configuration:</p> <p>Example <strong>nginx</strong> configuration:</p>
<pre class="nginx"><code>location /radicale/ { # The trailing / is important! <pre class="nginx"><code>location /radicale/ { # The trailing / is important!
@ -472,8 +472,8 @@ user2:password2</code></pre>
<span id="cb17-5"><a aria-hidden="true" href="#cb17-5" tabindex="-1"></a><span class="co"># Set to directory of .htaccess file:</span></span> <span id="cb17-5"><a aria-hidden="true" href="#cb17-5" tabindex="-1"></a><span class="co"># Set to directory of .htaccess file:</span></span>
<span id="cb17-6"><a aria-hidden="true" href="#cb17-6" tabindex="-1"></a>RequestHeader<span class="st"> set X-Script-Name /radicale</span></span></code></pre></div> <span id="cb17-6"><a aria-hidden="true" href="#cb17-6" tabindex="-1"></a>RequestHeader<span class="st"> set X-Script-Name /radicale</span></span></code></pre></div>
<p>Be reminded that Radicale's default configuration enforces limits on the maximum number of parallel connections, the maximum file size and the rate of incorrect authentication attempts. Connections are terminated after a timeout.</p> <p>Be reminded that Radicale's default configuration enforces limits on the maximum number of parallel connections, the maximum file size and the rate of incorrect authentication attempts. Connections are terminated after a timeout.</p>
<section class="level4" id="tutorials/reverse-proxy/manage-user-accounts-with-the-reverse-proxy"> <section class="level4" id="manage-user-accounts-with-the-reverse-proxy">
<h4>Manage user accounts with the reverse proxy <a class="headerlink" href="#tutorials/reverse-proxy/manage-user-accounts-with-the-reverse-proxy">&para;</a></h4> <h4>Manage user accounts with the reverse proxy <a class="headerlink" href="#manage-user-accounts-with-the-reverse-proxy">&para;</a></h4>
<p>Set the configuration option <code>type</code> in the <code>auth</code> section to <code>http_x_remote_user</code>. Radicale uses the user name provided in the <code>X-Remote-User</code> HTTP header and disables HTTP authentication.</p> <p>Set the configuration option <code>type</code> in the <code>auth</code> section to <code>http_x_remote_user</code>. Radicale uses the user name provided in the <code>X-Remote-User</code> HTTP header and disables HTTP authentication.</p>
<p>Example <strong>nginx</strong> configuration:</p> <p>Example <strong>nginx</strong> configuration:</p>
<pre class="nginx"><code>location /radicale/ { <pre class="nginx"><code>location /radicale/ {
@ -517,8 +517,8 @@ user2:password2</code></pre>
<p><strong>Security:</strong> Untrusted clients should not be able to access the Radicale server directly. Otherwise, they can authenticate as any user.</p> <p><strong>Security:</strong> Untrusted clients should not be able to access the Radicale server directly. Otherwise, they can authenticate as any user.</p>
</blockquote> </blockquote>
</section> </section>
<section class="level4" id="tutorials/reverse-proxy/secure-connection-between-radicale-and-the-reverse-proxy"> <section class="level4" id="secure-connection-between-radicale-and-the-reverse-proxy">
<h4>Secure connection between Radicale and the reverse proxy <a class="headerlink" href="#tutorials/reverse-proxy/secure-connection-between-radicale-and-the-reverse-proxy">&para;</a></h4> <h4>Secure connection between Radicale and the reverse proxy <a class="headerlink" href="#secure-connection-between-radicale-and-the-reverse-proxy">&para;</a></h4>
<p>SSL certificates can be used to encrypt and authenticate the connection between Radicale and the reverse proxy. First you have to generate a certificate for Radicale and a certificate for the reverse proxy. The following commands generate self-signed certificates. You will be asked to enter additional information about the certificate, the values don't matter and you can keep the defaults.</p> <p>SSL certificates can be used to encrypt and authenticate the connection between Radicale and the reverse proxy. First you have to generate a certificate for Radicale and a certificate for the reverse proxy. The following commands generate self-signed certificates. You will be asked to enter additional information about the certificate, the values don't matter and you can keep the defaults.</p>
<div class="sourceCode" id="cb21"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb21-1"><a aria-hidden="true" href="#cb21-1" tabindex="-1"></a><span class="ex">openssl</span> req <span class="at">-x509</span> <span class="at">-newkey</span> rsa:4096 <span class="at">-keyout</span> server_key.pem <span class="at">-out</span> server_cert.pem <span class="dt">\</span></span> <div class="sourceCode" id="cb21"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb21-1"><a aria-hidden="true" href="#cb21-1" tabindex="-1"></a><span class="ex">openssl</span> req <span class="at">-x509</span> <span class="at">-newkey</span> rsa:4096 <span class="at">-keyout</span> server_key.pem <span class="at">-out</span> server_cert.pem <span class="dt">\</span></span>
<span id="cb21-2"><a aria-hidden="true" href="#cb21-2" tabindex="-1"></a> <span class="at">-nodes</span> <span class="at">-days</span> 9999</span> <span id="cb21-2"><a aria-hidden="true" href="#cb21-2" tabindex="-1"></a> <span class="at">-nodes</span> <span class="at">-days</span> 9999</span>
@ -541,8 +541,8 @@ user2:password2</code></pre>
}</code></pre> }</code></pre>
</section> </section>
</section> </section>
<section class="level3" id="tutorials/wsgi-server"> <section class="level3" id="wsgi-server">
<h3>WSGI Server <a class="headerlink" href="#tutorials/wsgi-server">&para;</a></h3> <h3>WSGI Server <a class="headerlink" href="#wsgi-server">&para;</a></h3>
<p>Radicale is compatible with the WSGI specification.</p> <p>Radicale is compatible with the WSGI specification.</p>
<p>A configuration file can be set with the <code>RADICALE_CONFIG</code> environment variable, otherwise no configuration file is loaded and the default configuration is used.</p> <p>A configuration file can be set with the <code>RADICALE_CONFIG</code> environment variable, otherwise no configuration file is loaded and the default configuration is used.</p>
<p>Example <strong>uWSGI</strong> configuration:</p> <p>Example <strong>uWSGI</strong> configuration:</p>
@ -555,13 +555,13 @@ user2:password2</code></pre>
<p>Example <strong>Gunicorn</strong> configuration:</p> <p>Example <strong>Gunicorn</strong> configuration:</p>
<div class="sourceCode" id="cb25"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb25-1"><a aria-hidden="true" href="#cb25-1" tabindex="-1"></a><span class="ex">gunicorn</span> <span class="at">--bind</span> <span class="st">'127.0.0.1:5232'</span> <span class="at">--env</span> <span class="st">'RADICALE_CONFIG=/etc/radicale/config'</span> <span class="dt">\</span></span> <div class="sourceCode" id="cb25"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb25-1"><a aria-hidden="true" href="#cb25-1" tabindex="-1"></a><span class="ex">gunicorn</span> <span class="at">--bind</span> <span class="st">'127.0.0.1:5232'</span> <span class="at">--env</span> <span class="st">'RADICALE_CONFIG=/etc/radicale/config'</span> <span class="dt">\</span></span>
<span id="cb25-2"><a aria-hidden="true" href="#cb25-2" tabindex="-1"></a> <span class="at">--workers</span> 8 radicale</span></code></pre></div> <span id="cb25-2"><a aria-hidden="true" href="#cb25-2" tabindex="-1"></a> <span class="at">--workers</span> 8 radicale</span></code></pre></div>
<section class="level4" id="tutorials/wsgi-server/manage-user-accounts-with-the-wsgi-server"> <section class="level4" id="manage-user-accounts-with-the-wsgi-server">
<h4>Manage user accounts with the WSGI server <a class="headerlink" href="#tutorials/wsgi-server/manage-user-accounts-with-the-wsgi-server">&para;</a></h4> <h4>Manage user accounts with the WSGI server <a class="headerlink" href="#manage-user-accounts-with-the-wsgi-server">&para;</a></h4>
<p>Set the configuration option <code>type</code> in the <code>auth</code> section to <code>remote_user</code>. Radicale uses the user name provided by the WSGI server and disables authentication over HTTP.</p> <p>Set the configuration option <code>type</code> in the <code>auth</code> section to <code>remote_user</code>. Radicale uses the user name provided by the WSGI server and disables authentication over HTTP.</p>
</section> </section>
</section> </section>
<section class="level3" id="tutorials/versioning-with-git"> <section class="level3" id="versioning-with-git">
<h3>Versioning with Git <a class="headerlink" href="#tutorials/versioning-with-git">&para;</a></h3> <h3>Versioning with Git <a class="headerlink" href="#versioning-with-git">&para;</a></h3>
<p>This tutorial describes how to keep track of all changes to calendars and address books with <strong>git</strong> (or any other version control system).</p> <p>This tutorial describes how to keep track of all changes to calendars and address books with <strong>git</strong> (or any other version control system).</p>
<p>The repository must be initialized by running <code>git init</code> in the file system folder. Internal files of Radicale can be excluded by creating the file <code>.gitignore</code> with the following content:</p> <p>The repository must be initialized by running <code>git init</code> in the file system folder. Internal files of Radicale can be excluded by creating the file <code>.gitignore</code> with the following content:</p>
<pre class="gitignore"><code>.Radicale.cache <pre class="gitignore"><code>.Radicale.cache
@ -572,10 +572,10 @@ user2:password2</code></pre>
<p>The command gets executed after every change to the storage and commits the changes into the <strong>git</strong> repository.</p> <p>The command gets executed after every change to the storage and commits the changes into the <strong>git</strong> repository.</p>
</section> </section>
</section> </section>
<section class="level2" id="documentation"> <section class="level2" id="documentation-1">
<h2>Documentation <a class="headerlink" href="#documentation">&para;</a></h2> <h2>Documentation <a class="headerlink" href="#documentation-1">&para;</a></h2>
<section class="level3" id="documentation/configuration"> <section class="level3" id="configuration">
<h3>Configuration <a class="headerlink" href="#documentation/configuration">&para;</a></h3> <h3>Configuration <a class="headerlink" href="#configuration">&para;</a></h3>
<p>Radicale can be configured with a configuration file or with command line arguments.</p> <p>Radicale can be configured with a configuration file or with command line arguments.</p>
<p>An example configuration file looks like:</p> <p>An example configuration file looks like:</p>
<div class="sourceCode" id="cb28"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb28-1"><a aria-hidden="true" href="#cb28-1" tabindex="-1"></a><span class="kw">[server]</span></span> <div class="sourceCode" id="cb28"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb28-1"><a aria-hidden="true" href="#cb28-1" tabindex="-1"></a><span class="kw">[server]</span></span>
@ -596,67 +596,67 @@ user2:password2</code></pre>
<span id="cb29-3"><a aria-hidden="true" href="#cb29-3" tabindex="-1"></a> <span class="at">--auth-htpasswd-encryption</span> md5</span></code></pre></div> <span id="cb29-3"><a aria-hidden="true" href="#cb29-3" tabindex="-1"></a> <span class="at">--auth-htpasswd-encryption</span> md5</span></code></pre></div>
<p>Add the argument <code>--config ""</code> to stop Radicale from loading the default configuration files. Run <code>python3 -m radicale --help</code> for more information.</p> <p>Add the argument <code>--config ""</code> to stop Radicale from loading the default configuration files. Run <code>python3 -m radicale --help</code> for more information.</p>
<p>In the following, all configuration categories and options are described.</p> <p>In the following, all configuration categories and options are described.</p>
<section class="level4" id="documentation/configuration/server"> <section class="level4" id="server">
<h4>server <a class="headerlink" href="#documentation/configuration/server">&para;</a></h4> <h4>server <a class="headerlink" href="#server">&para;</a></h4>
<p>The configuration options in this category are only relevant in standalone mode. All options are ignored, when Radicale runs via WSGI.</p> <p>The configuration options in this category are only relevant in standalone mode. All options are ignored, when Radicale runs via WSGI.</p>
<section class="level5" id="documentation/configuration/server/hosts"> <section class="level5" id="hosts">
<h5>hosts <a class="headerlink" href="#documentation/configuration/server/hosts">&para;</a></h5> <h5>hosts <a class="headerlink" href="#hosts">&para;</a></h5>
<p>A comma separated list of addresses that the server will bind to.</p> <p>A comma separated list of addresses that the server will bind to.</p>
<p>Default: <code>localhost:5232</code></p> <p>Default: <code>localhost:5232</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/max_connections"> <section class="level5" id="max_connections">
<h5>max_connections <a class="headerlink" href="#documentation/configuration/server/max_connections">&para;</a></h5> <h5>max_connections <a class="headerlink" href="#max_connections">&para;</a></h5>
<p>The maximum number of parallel connections. Set to <code>0</code> to disable the limit.</p> <p>The maximum number of parallel connections. Set to <code>0</code> to disable the limit.</p>
<p>Default: <code>8</code></p> <p>Default: <code>8</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/max_content_length"> <section class="level5" id="max_content_length">
<h5>max_content_length <a class="headerlink" href="#documentation/configuration/server/max_content_length">&para;</a></h5> <h5>max_content_length <a class="headerlink" href="#max_content_length">&para;</a></h5>
<p>The maximum size of the request body. (bytes)</p> <p>The maximum size of the request body. (bytes)</p>
<p>Default: <code>100000000</code></p> <p>Default: <code>100000000</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/timeout"> <section class="level5" id="timeout">
<h5>timeout <a class="headerlink" href="#documentation/configuration/server/timeout">&para;</a></h5> <h5>timeout <a class="headerlink" href="#timeout">&para;</a></h5>
<p>Socket timeout. (seconds)</p> <p>Socket timeout. (seconds)</p>
<p>Default: <code>30</code></p> <p>Default: <code>30</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/ssl"> <section class="level5" id="ssl">
<h5>ssl <a class="headerlink" href="#documentation/configuration/server/ssl">&para;</a></h5> <h5>ssl <a class="headerlink" href="#ssl">&para;</a></h5>
<p>Enable transport layer encryption.</p> <p>Enable transport layer encryption.</p>
<p>Default: <code>False</code></p> <p>Default: <code>False</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/certificate"> <section class="level5" id="certificate">
<h5>certificate <a class="headerlink" href="#documentation/configuration/server/certificate">&para;</a></h5> <h5>certificate <a class="headerlink" href="#certificate">&para;</a></h5>
<p>Path of the SSL certifcate.</p> <p>Path of the SSL certifcate.</p>
<p>Default: <code>/etc/ssl/radicale.cert.pem</code></p> <p>Default: <code>/etc/ssl/radicale.cert.pem</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/key"> <section class="level5" id="key">
<h5>key <a class="headerlink" href="#documentation/configuration/server/key">&para;</a></h5> <h5>key <a class="headerlink" href="#key">&para;</a></h5>
<p>Path to the private key for SSL. Only effective if <code>ssl</code> is enabled.</p> <p>Path to the private key for SSL. Only effective if <code>ssl</code> is enabled.</p>
<p>Default: <code>/etc/ssl/radicale.key.pem</code></p> <p>Default: <code>/etc/ssl/radicale.key.pem</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/certificate_authority"> <section class="level5" id="certificate_authority">
<h5>certificate_authority <a class="headerlink" href="#documentation/configuration/server/certificate_authority">&para;</a></h5> <h5>certificate_authority <a class="headerlink" href="#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 certificate.</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> <p>Default:</p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/encoding"> <section class="level4" id="encoding">
<h4>encoding <a class="headerlink" href="#documentation/configuration/encoding">&para;</a></h4> <h4>encoding <a class="headerlink" href="#encoding">&para;</a></h4>
<section class="level5" id="documentation/configuration/encoding/request"> <section class="level5" id="request">
<h5>request <a class="headerlink" href="#documentation/configuration/encoding/request">&para;</a></h5> <h5>request <a class="headerlink" href="#request">&para;</a></h5>
<p>Encoding for responding requests.</p> <p>Encoding for responding requests.</p>
<p>Default: <code>utf-8</code></p> <p>Default: <code>utf-8</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/encoding/stock"> <section class="level5" id="stock">
<h5>stock <a class="headerlink" href="#documentation/configuration/encoding/stock">&para;</a></h5> <h5>stock <a class="headerlink" href="#stock">&para;</a></h5>
<p>Encoding for storing local collections</p> <p>Encoding for storing local collections</p>
<p>Default: <code>utf-8</code></p> <p>Default: <code>utf-8</code></p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/auth"> <section class="level4" id="auth">
<h4>auth <a class="headerlink" href="#documentation/configuration/auth">&para;</a></h4> <h4>auth <a class="headerlink" href="#auth">&para;</a></h4>
<section class="level5" id="documentation/configuration/auth/type"> <section class="level5" id="type">
<h5>type <a class="headerlink" href="#documentation/configuration/auth/type">&para;</a></h5> <h5>type <a class="headerlink" href="#type">&para;</a></h5>
<p>The method to verify usernames and passwords.</p> <p>The method to verify usernames and passwords.</p>
<p>Available backends:</p> <p>Available backends:</p>
<p><code>none</code> : Just allows all usernames and passwords.</p> <p><code>none</code> : Just allows all usernames and passwords.</p>
@ -665,13 +665,13 @@ user2:password2</code></pre>
<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><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>
<section class="level5" id="documentation/configuration/auth/htpasswd_filename"> <section class="level5" id="htpasswd_filename">
<h5>htpasswd_filename <a class="headerlink" href="#documentation/configuration/auth/htpasswd_filename">&para;</a></h5> <h5>htpasswd_filename <a class="headerlink" href="#htpasswd_filename">&para;</a></h5>
<p>Path to the htpasswd file.</p> <p>Path to the htpasswd file.</p>
<p>Default:</p> <p>Default:</p>
</section> </section>
<section class="level5" id="documentation/configuration/auth/htpasswd_encryption"> <section class="level5" id="htpasswd_encryption">
<h5>htpasswd_encryption <a class="headerlink" href="#documentation/configuration/auth/htpasswd_encryption">&para;</a></h5> <h5>htpasswd_encryption <a class="headerlink" href="#htpasswd_encryption">&para;</a></h5>
<p>The encryption method that is used in the htpasswd file. Use the <a href="https://httpd.apache.org/docs/current/programs/htpasswd.html">htpasswd</a> or similar to generate this files.</p> <p>The encryption method that is used in the htpasswd file. Use the <a href="https://httpd.apache.org/docs/current/programs/htpasswd.html">htpasswd</a> or similar to generate this files.</p>
<p>Available methods:</p> <p>Available methods:</p>
<p><code>plain</code> : Passwords are stored in plaintext. This is obviously not secure! The htpasswd file for this can be created by hand and looks like:</p> <p><code>plain</code> : Passwords are stored in plaintext. This is obviously not secure! The htpasswd file for this can be created by hand and looks like:</p>
@ -681,21 +681,21 @@ user2:password2</code></pre>
<p><code>md5</code> : This uses an iterated md5 digest of the password with a salt.</p> <p><code>md5</code> : This uses an iterated md5 digest of the password with a salt.</p>
<p>Default: <code>md5</code></p> <p>Default: <code>md5</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/auth/delay"> <section class="level5" id="delay">
<h5>delay <a class="headerlink" href="#documentation/configuration/auth/delay">&para;</a></h5> <h5>delay <a class="headerlink" href="#delay">&para;</a></h5>
<p>Average delay after failed login attempts in seconds.</p> <p>Average delay after failed login attempts in seconds.</p>
<p>Default: <code>1</code></p> <p>Default: <code>1</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/auth/realm"> <section class="level5" id="realm">
<h5>realm <a class="headerlink" href="#documentation/configuration/auth/realm">&para;</a></h5> <h5>realm <a class="headerlink" href="#realm">&para;</a></h5>
<p>Message displayed in the client when a password is needed.</p> <p>Message displayed in the client when a password is needed.</p>
<p>Default: <code>Radicale - Password Required</code></p> <p>Default: <code>Radicale - Password Required</code></p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/rights"> <section class="level4" id="rights">
<h4>rights <a class="headerlink" href="#documentation/configuration/rights">&para;</a></h4> <h4>rights <a class="headerlink" href="#rights">&para;</a></h4>
<section class="level5" id="documentation/configuration/rights/type"> <section class="level5" id="type-1">
<h5>type <a class="headerlink" href="#documentation/configuration/rights/type">&para;</a></h5> <h5>type <a class="headerlink" href="#type-1">&para;</a></h5>
<p>The backend that is used to check the access rights of collections.</p> <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 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>Available backends:</p>
@ -705,41 +705,41 @@ user2:password2</code></pre>
<p><code>from_file</code> : Load the rules from a file.</p> <p><code>from_file</code> : Load the rules from a file.</p>
<p>Default: <code>owner_only</code></p> <p>Default: <code>owner_only</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/rights/file"> <section class="level5" id="file">
<h5>file <a class="headerlink" href="#documentation/configuration/rights/file">&para;</a></h5> <h5>file <a class="headerlink" href="#file">&para;</a></h5>
<p>File for the rights backend <code>from_file</code>. See the <a href="#documentation/authentication-and-rights">Rights</a> section.</p> <p>File for the rights backend <code>from_file</code>. See the <a href="#authentication-and-rights">Rights</a> section.</p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/storage"> <section class="level4" id="storage-1">
<h4>storage <a class="headerlink" href="#documentation/configuration/storage">&para;</a></h4> <h4>storage <a class="headerlink" href="#storage-1">&para;</a></h4>
<section class="level5" id="documentation/configuration/storage/type"> <section class="level5" id="type-2">
<h5>type <a class="headerlink" href="#documentation/configuration/storage/type">&para;</a></h5> <h5>type <a class="headerlink" href="#type-2">&para;</a></h5>
<p>The backend that is used to store data.</p> <p>The backend that is used to store data.</p>
<p>Available backends:</p> <p>Available backends:</p>
<p><code>multifilesystem</code> : Stores the data in the filesystem.</p> <p><code>multifilesystem</code> : Stores the data in the filesystem.</p>
<p><code>multifilesystem_nolock</code> : The <code>multifilesystem</code> backend without file-based locking. Must only be used with a single process.</p> <p><code>multifilesystem_nolock</code> : The <code>multifilesystem</code> backend without file-based locking. Must only be used with a single process.</p>
<p>Default: <code>multifilesystem</code></p> <p>Default: <code>multifilesystem</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/storage/filesystem_folder"> <section class="level5" id="filesystem_folder">
<h5>filesystem_folder <a class="headerlink" href="#documentation/configuration/storage/filesystem_folder">&para;</a></h5> <h5>filesystem_folder <a class="headerlink" href="#filesystem_folder">&para;</a></h5>
<p>Folder for storing local collections, created if not present.</p> <p>Folder for storing local collections, created if not present.</p>
<p>Default: <code>/var/lib/radicale/collections</code></p> <p>Default: <code>/var/lib/radicale/collections</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/storage/max_sync_token_age"> <section class="level5" id="max_sync_token_age">
<h5>max_sync_token_age <a class="headerlink" href="#documentation/configuration/storage/max_sync_token_age">&para;</a></h5> <h5>max_sync_token_age <a class="headerlink" href="#max_sync_token_age">&para;</a></h5>
<p>Delete sync-token that are older than the specified time. (seconds)</p> <p>Delete sync-token that are older than the specified time. (seconds)</p>
<p>Default: <code>2592000</code></p> <p>Default: <code>2592000</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/storage/hook"> <section class="level5" id="hook">
<h5>hook <a class="headerlink" href="#documentation/configuration/storage/hook">&para;</a></h5> <h5>hook <a class="headerlink" href="#hook">&para;</a></h5>
<p>Command that is run after changes to storage. Take a look at the <a href="#tutorials/versioning-with-git">Versioning with Git</a> tutorial for an example.</p> <p>Command that is run after changes to storage. Take a look at the <a href="#versioning-with-git">Versioning with Git</a> tutorial for an example.</p>
<p>Default:</p> <p>Default:</p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/web"> <section class="level4" id="web">
<h4>web <a class="headerlink" href="#documentation/configuration/web">&para;</a></h4> <h4>web <a class="headerlink" href="#web">&para;</a></h4>
<section class="level5" id="documentation/configuration/web/type"> <section class="level5" id="type-3">
<h5>type <a class="headerlink" href="#documentation/configuration/web/type">&para;</a></h5> <h5>type <a class="headerlink" href="#type-3">&para;</a></h5>
<p>The backend that provides the web interface of Radicale.</p> <p>The backend that provides the web interface of Radicale.</p>
<p>Available backends:</p> <p>Available backends:</p>
<p><code>none</code> : Just shows the message "Radicale works!".</p> <p><code>none</code> : Just shows the message "Radicale works!".</p>
@ -747,29 +747,29 @@ user2:password2</code></pre>
<p>Default: <code>internal</code></p> <p>Default: <code>internal</code></p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/logging"> <section class="level4" id="logging">
<h4>logging <a class="headerlink" href="#documentation/configuration/logging">&para;</a></h4> <h4>logging <a class="headerlink" href="#logging">&para;</a></h4>
<section class="level5" id="documentation/configuration/logging/level"> <section class="level5" id="level">
<h5>level <a class="headerlink" href="#documentation/configuration/logging/level">&para;</a></h5> <h5>level <a class="headerlink" href="#level">&para;</a></h5>
<p>Set the logging level.</p> <p>Set the logging level.</p>
<p>Available levels: <strong>debug</strong>, <strong>info</strong>, <strong>warning</strong>, <strong>error</strong>, <strong>critical</strong></p> <p>Available levels: <strong>debug</strong>, <strong>info</strong>, <strong>warning</strong>, <strong>error</strong>, <strong>critical</strong></p>
<p>Default: <code>warning</code></p> <p>Default: <code>warning</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/logging/mask_passwords"> <section class="level5" id="mask_passwords">
<h5>mask_passwords <a class="headerlink" href="#documentation/configuration/logging/mask_passwords">&para;</a></h5> <h5>mask_passwords <a class="headerlink" href="#mask_passwords">&para;</a></h5>
<p>Don't include passwords in logs.</p> <p>Don't include passwords in logs.</p>
<p>Default: <code>True</code></p> <p>Default: <code>True</code></p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/headers"> <section class="level4" id="headers">
<h4>headers <a class="headerlink" href="#documentation/configuration/headers">&para;</a></h4> <h4>headers <a class="headerlink" href="#headers">&para;</a></h4>
<p>In this section additional HTTP headers that are sent to clients can be specified.</p> <p>In this section additional HTTP headers that are sent to clients can be specified.</p>
<p>An example to relax the same-origin policy:</p> <p>An example to relax the same-origin policy:</p>
<div class="sourceCode" id="cb31"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb31-1"><a aria-hidden="true" href="#cb31-1" tabindex="-1"></a><span class="dt">Access-Control-Allow-Origin </span><span class="ot">=</span><span class="st"> *</span></span></code></pre></div> <div class="sourceCode" id="cb31"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb31-1"><a aria-hidden="true" href="#cb31-1" tabindex="-1"></a><span class="dt">Access-Control-Allow-Origin </span><span class="ot">=</span><span class="st"> *</span></span></code></pre></div>
</section> </section>
</section> </section>
<section class="level3" id="documentation/supported-clients"> <section class="level3" id="supported-clients">
<h3>Supported Clients <a class="headerlink" href="#documentation/supported-clients">&para;</a></h3> <h3>Supported Clients <a class="headerlink" href="#supported-clients">&para;</a></h3>
<p>Radicale has been tested with:</p> <p>Radicale has been tested with:</p>
<ul> <ul>
<li><a href="https://android.com/">Android</a> with <a href="https://www.davx5.com/">DAVx⁵</a> (formerly DAVdroid)</li> <li><a href="https://android.com/">Android</a> with <a href="https://www.davx5.com/">DAVx⁵</a> (formerly DAVdroid)</li>
@ -779,33 +779,33 @@ user2:password2</code></pre>
</ul> </ul>
<p>Many clients do not support the creation of new calendars and address books. You can use Radicale's web interface (e.g. <a href="http://localhost:5232">http://localhost:5232</a>) to create and manage address books and calendars.</p> <p>Many clients do not support the creation of new calendars and address books. You can use Radicale's web interface (e.g. <a href="http://localhost:5232">http://localhost:5232</a>) to create and manage address books and calendars.</p>
<p>In some clients you can just enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. In others, you have to enter the URL of the collection directly (e.g. <code>http://localhost:5232/user/calendar</code>).</p> <p>In some clients you can just enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. In others, you have to enter the URL of the collection directly (e.g. <code>http://localhost:5232/user/calendar</code>).</p>
<section class="level4" id="documentation/supported-clients/davx⁵"> <section class="level4" id="davx⁵">
<h4>DAVx⁵ <a class="headerlink" href="#documentation/supported-clients/davx⁵">&para;</a></h4> <h4>DAVx⁵ <a class="headerlink" href="#davx⁵">&para;</a></h4>
<p>Enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. DAVx⁵ will show all existing calendars and address books and you can create new.</p> <p>Enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. DAVx⁵ will show all existing calendars and address books and you can create new.</p>
</section> </section>
<section class="level4" id="documentation/supported-clients/gnome-calendar-contacts-and-evolution"> <section class="level4" id="gnome-calendar-contacts-and-evolution">
<h4>GNOME Calendar, Contacts and Evolution <a class="headerlink" href="#documentation/supported-clients/gnome-calendar-contacts-and-evolution">&para;</a></h4> <h4>GNOME Calendar, Contacts and Evolution <a class="headerlink" href="#gnome-calendar-contacts-and-evolution">&para;</a></h4>
<p><strong>GNOME Calendar</strong> and <strong>Contacts</strong> do not support adding WebDAV calendars and address books directly, but you can add them in <strong>Evolution</strong>.</p> <p><strong>GNOME Calendar</strong> and <strong>Contacts</strong> do not support adding WebDAV calendars and address books directly, but you can add them in <strong>Evolution</strong>.</p>
<p>In <strong>Evolution</strong> add a new calendar and address book respectively with WebDAV. Enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. Clicking on the search button will list the existing calendars and address books.</p> <p>In <strong>Evolution</strong> add a new calendar and address book respectively with WebDAV. Enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. Clicking on the search button will list the existing calendars and address books.</p>
</section> </section>
<section class="level4" id="documentation/supported-clients/thunderbird"> <section class="level4" id="thunderbird">
<h4>Thunderbird <a class="headerlink" href="#documentation/supported-clients/thunderbird">&para;</a></h4> <h4>Thunderbird <a class="headerlink" href="#thunderbird">&para;</a></h4>
<section class="level5" id="documentation/supported-clients/thunderbird/cardbook"> <section class="level5" id="cardbook">
<h5>CardBook <a class="headerlink" href="#documentation/supported-clients/thunderbird/cardbook">&para;</a></h5> <h5>CardBook <a class="headerlink" href="#cardbook">&para;</a></h5>
<p>Add a new address book on the network with CardDAV. You have to enter the full URL of the collection (e.g. <code>http://localhost:5232/user/addressbook</code>) and your user name.</p> <p>Add a new address book on the network with CardDAV. You have to enter the full URL of the collection (e.g. <code>http://localhost:5232/user/addressbook</code>) and your user name.</p>
</section> </section>
<section class="level5" id="documentation/supported-clients/thunderbird/lightning"> <section class="level5" id="lightning">
<h5>Lightning <a class="headerlink" href="#documentation/supported-clients/thunderbird/lightning">&para;</a></h5> <h5>Lightning <a class="headerlink" href="#lightning">&para;</a></h5>
<p>Add a new calendar on the network with <code>CalDAV</code>. (Don't use <code>iCalendar (ICS)</code>!) You have to enter the full URL of the collection (e.g. <code>http://localhost:5232/user/calendar</code>). If you want to add calendars from different users on the same server, you can specify the user name in the URL (e.g. <code>http://user@localhost...</code>)</p> <p>Add a new calendar on the network with <code>CalDAV</code>. (Don't use <code>iCalendar (ICS)</code>!) You have to enter the full URL of the collection (e.g. <code>http://localhost:5232/user/calendar</code>). If you want to add calendars from different users on the same server, you can specify the user name in the URL (e.g. <code>http://user@localhost...</code>)</p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/supported-clients/infcloud-caldavzap-and-carddavmate"> <section class="level4" id="infcloud-caldavzap-and-carddavmate">
<h4>InfCloud, CalDavZAP and CardDavMATE <a class="headerlink" href="#documentation/supported-clients/infcloud-caldavzap-and-carddavmate">&para;</a></h4> <h4>InfCloud, CalDavZAP and CardDavMATE <a class="headerlink" href="#infcloud-caldavzap-and-carddavmate">&para;</a></h4>
<p>You can integrate InfCloud into Radicale's web interface with <a href="https://github.com/Unrud/RadicaleInfCloud">RadicaleInfCloud</a>. No additional configuration is required.</p> <p>You can integrate InfCloud into Radicale's web interface with <a href="https://github.com/Unrud/RadicaleInfCloud">RadicaleInfCloud</a>. No additional configuration is required.</p>
<p>Set the URL of the Radicale server in <code>config.js</code>. If <strong>InfCloud</strong> is not hosted on the same server and port as Radicale, the browser will deny access to the Radicale server, because of the <a href="https://en.wikipedia.org/wiki/Same-origin_policy">same-origin policy</a>. You have to add additional HTTP header in the <code>headers</code> section of Radicale's configuration. The documentation of <strong>InfCloud</strong> has more details on this.</p> <p>Set the URL of the Radicale server in <code>config.js</code>. If <strong>InfCloud</strong> is not hosted on the same server and port as Radicale, the browser will deny access to the Radicale server, because of the <a href="https://en.wikipedia.org/wiki/Same-origin_policy">same-origin policy</a>. You have to add additional HTTP header in the <code>headers</code> section of Radicale's configuration. The documentation of <strong>InfCloud</strong> has more details on this.</p>
</section> </section>
<section class="level4" id="documentation/supported-clients/command-line"> <section class="level4" id="command-line">
<h4>Command line <a class="headerlink" href="#documentation/supported-clients/command-line">&para;</a></h4> <h4>Command line <a class="headerlink" href="#command-line">&para;</a></h4>
<p>This is not the recommended way of creating and managing your calendars and address books. Use Radicale's web interface or a client with support for it (e.g. <strong>DAVx⁵</strong>).</p> <p>This is not the recommended way of creating and managing your calendars and address books. Use Radicale's web interface or a client with support for it (e.g. <strong>DAVx⁵</strong>).</p>
<p>To create a new calendar run something like:</p> <p>To create a new calendar run something like:</p>
<div class="sourceCode" id="cb32"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb32-1"><a aria-hidden="true" href="#cb32-1" tabindex="-1"></a><span class="ex">$</span> curl <span class="at">-u</span> user <span class="at">-X</span> MKCOL <span class="st">'http://localhost:5232/user/calendar'</span> <span class="at">--data</span> <span class="dt">\</span></span> <div class="sourceCode" id="cb32"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb32-1"><a aria-hidden="true" href="#cb32-1" tabindex="-1"></a><span class="ex">$</span> curl <span class="at">-u</span> user <span class="at">-X</span> MKCOL <span class="st">'http://localhost:5232/user/calendar'</span> <span class="at">--data</span> <span class="dt">\</span></span>
@ -848,8 +848,8 @@ user2:password2</code></pre>
<div class="sourceCode" id="cb34"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb34-1"><a aria-hidden="true" href="#cb34-1" tabindex="-1"></a><span class="ex">curl</span> <span class="at">-u</span> user <span class="at">-X</span> DELETE <span class="st">'http://localhost:5232/user/calendar'</span></span></code></pre></div> <div class="sourceCode" id="cb34"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb34-1"><a aria-hidden="true" href="#cb34-1" tabindex="-1"></a><span class="ex">curl</span> <span class="at">-u</span> user <span class="at">-X</span> DELETE <span class="st">'http://localhost:5232/user/calendar'</span></span></code></pre></div>
</section> </section>
</section> </section>
<section class="level3" id="documentation/authentication-and-rights"> <section class="level3" id="authentication-and-rights">
<h3>Authentication and Rights <a class="headerlink" href="#documentation/authentication-and-rights">&para;</a></h3> <h3>Authentication and Rights <a class="headerlink" href="#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>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 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> <p>An example rights file:</p>
@ -885,12 +885,12 @@ user2:password2</code></pre>
<li><strong>w:</strong> write address book and calendar collections</li> <li><strong>w:</strong> write address book and calendar collections</li>
</ul> </ul>
</section> </section>
<section class="level3" id="documentation/storage"> <section class="level3" id="storage-2">
<h3>Storage <a class="headerlink" href="#documentation/storage">&para;</a></h3> <h3>Storage <a class="headerlink" href="#storage-2">&para;</a></h3>
<p>This document describes the layout and format of the file system storage (<code>multifilesystem</code> backend).</p> <p>This document describes the layout and format of the file system storage (<code>multifilesystem</code> backend).</p>
<p>It's safe to access and manipulate the data by hand or with scripts. Scripts can be invoked manually, periodically (e.g. with <a href="https://manpages.debian.org/unstable/cron/cron.8.en.html">cron</a>) or after each change to the storage with the configuration option <code>hook</code> in the <code>storage</code> section (e.g. <a href="#tutorials/versioning-with-git">Versioning with Git</a>).</p> <p>It's safe to access and manipulate the data by hand or with scripts. Scripts can be invoked manually, periodically (e.g. with <a href="https://manpages.debian.org/unstable/cron/cron.8.en.html">cron</a>) or after each change to the storage with the configuration option <code>hook</code> in the <code>storage</code> section (e.g. <a href="#versioning-with-git">Versioning with Git</a>).</p>
<section class="level4" id="documentation/storage/layout"> <section class="level4" id="layout">
<h4>Layout <a class="headerlink" href="#documentation/storage/layout">&para;</a></h4> <h4>Layout <a class="headerlink" href="#layout">&para;</a></h4>
<p>The file system contains the following files and folders:</p> <p>The file system contains the following files and folders:</p>
<ul> <ul>
<li><code>.Radicale.lock</code>: The lock file for locking the storage.</li> <li><code>.Radicale.lock</code>: The lock file for locking the storage.</li>
@ -903,28 +903,28 @@ user2:password2</code></pre>
<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>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> <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>
<section class="level4" id="documentation/storage/locking"> <section class="level4" id="locking">
<h4>Locking <a class="headerlink" href="#documentation/storage/locking">&para;</a></h4> <h4>Locking <a class="headerlink" href="#locking">&para;</a></h4>
<p>When the data is accessed by hand or by an externally invoked script, the storage must be locked. The storage can be locked for exclusive or shared access. It prevents Radicale from reading or writing the file system. The storage is locked with exclusive access while the <code>hook</code> runs.</p> <p>When the data is accessed by hand or by an externally invoked script, the storage must be locked. The storage can be locked for exclusive or shared access. It prevents Radicale from reading or writing the file system. The storage is locked with exclusive access while the <code>hook</code> runs.</p>
<section class="level5" id="documentation/storage/locking/linux-shell-scripts"> <section class="level5" id="linux-shell-scripts">
<h5>Linux shell scripts <a class="headerlink" href="#documentation/storage/locking/linux-shell-scripts">&para;</a></h5> <h5>Linux shell scripts <a class="headerlink" href="#linux-shell-scripts">&para;</a></h5>
<p>Use the <a href="https://manpages.debian.org/unstable/util-linux/flock.1.en.html">flock</a> utility.</p> <p>Use the <a href="https://manpages.debian.org/unstable/util-linux/flock.1.en.html">flock</a> utility.</p>
<div class="sourceCode" id="cb36"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb36-1"><a aria-hidden="true" href="#cb36-1" tabindex="-1"></a><span class="co"># Exclusive</span></span> <div class="sourceCode" id="cb36"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb36-1"><a aria-hidden="true" href="#cb36-1" tabindex="-1"></a><span class="co"># Exclusive</span></span>
<span id="cb36-2"><a aria-hidden="true" href="#cb36-2" tabindex="-1"></a><span class="ex">$</span> flock <span class="at">--exclusive</span> /path/to/storage/.Radicale.lock COMMAND</span> <span id="cb36-2"><a aria-hidden="true" href="#cb36-2" tabindex="-1"></a><span class="ex">$</span> flock <span class="at">--exclusive</span> /path/to/storage/.Radicale.lock COMMAND</span>
<span id="cb36-3"><a aria-hidden="true" href="#cb36-3" tabindex="-1"></a><span class="co"># Shared</span></span> <span id="cb36-3"><a aria-hidden="true" href="#cb36-3" tabindex="-1"></a><span class="co"># Shared</span></span>
<span id="cb36-4"><a aria-hidden="true" href="#cb36-4" tabindex="-1"></a><span class="ex">$</span> flock <span class="at">--shared</span> /path/to/storage/.Radicale.lock COMMAND</span></code></pre></div> <span id="cb36-4"><a aria-hidden="true" href="#cb36-4" tabindex="-1"></a><span class="ex">$</span> flock <span class="at">--shared</span> /path/to/storage/.Radicale.lock COMMAND</span></code></pre></div>
</section> </section>
<section class="level5" id="documentation/storage/locking/linux-and-macos"> <section class="level5" id="linux-and-macos">
<h5>Linux and MacOS <a class="headerlink" href="#documentation/storage/locking/linux-and-macos">&para;</a></h5> <h5>Linux and MacOS <a class="headerlink" href="#linux-and-macos">&para;</a></h5>
<p>Use the <a href="https://manpages.debian.org/unstable/manpages-dev/flock.2.en.html">flock</a> syscall. Python provides it in the <a href="https://docs.python.org/3/library/fcntl.html#fcntl.flock">fcntl</a> module.</p> <p>Use the <a href="https://manpages.debian.org/unstable/manpages-dev/flock.2.en.html">flock</a> syscall. Python provides it in the <a href="https://docs.python.org/3/library/fcntl.html#fcntl.flock">fcntl</a> module.</p>
</section> </section>
<section class="level5" id="documentation/storage/locking/windows"> <section class="level5" id="windows-1">
<h5>Windows <a class="headerlink" href="#documentation/storage/locking/windows">&para;</a></h5> <h5>Windows <a class="headerlink" href="#windows-1">&para;</a></h5>
<p>Use <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365202%28v=vs.85%29.aspx">LockFile</a> for exclusive access or <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365203%28v=vs.85%29.aspx">LockFileEx</a> which also supports shared access. Setting <code>nNumberOfBytesToLockLow</code> to <code>1</code> and <code>nNumberOfBytesToLockHigh</code> to <code>0</code> works.</p> <p>Use <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365202%28v=vs.85%29.aspx">LockFile</a> for exclusive access or <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365203%28v=vs.85%29.aspx">LockFileEx</a> which also supports shared access. Setting <code>nNumberOfBytesToLockLow</code> to <code>1</code> and <code>nNumberOfBytesToLockHigh</code> to <code>0</code> works.</p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/storage/manually-creating-collections"> <section class="level4" id="manually-creating-collections">
<h4>Manually creating collections <a class="headerlink" href="#documentation/storage/manually-creating-collections">&para;</a></h4> <h4>Manually creating collections <a class="headerlink" href="#manually-creating-collections">&para;</a></h4>
<p>To create a new collection, you have to create the corresponding folder in the file system storage (e.g. <code>collection-root/user/calendar</code>). To tell Radicale and clients that the collection is a calendar, you have to create the file <code>.Radicale.props</code> with the following content in the folder:</p> <p>To create a new collection, you have to create the corresponding folder in the file system storage (e.g. <code>collection-root/user/calendar</code>). To tell Radicale and clients that the collection is a calendar, you have to create the file <code>.Radicale.props</code> with the following content in the folder:</p>
<div class="sourceCode" id="cb37"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb37-1"><a aria-hidden="true" href="#cb37-1" tabindex="-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> <div class="sourceCode" id="cb37"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb37-1"><a aria-hidden="true" href="#cb37-1" tabindex="-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> <p>The calendar is now available at the URL path <code>/user/calendar</code>. For address books the file must contain:</p>
@ -933,15 +933,15 @@ user2:password2</code></pre>
<p>Delete collections by deleting the corresponding folders.</p> <p>Delete collections by deleting the corresponding folders.</p>
</section> </section>
</section> </section>
<section class="level3" id="documentation/logging"> <section class="level3" id="logging-1">
<h3>Logging <a class="headerlink" href="#documentation/logging">&para;</a></h3> <h3>Logging <a class="headerlink" href="#logging-1">&para;</a></h3>
<p>Radicale logs to <code>stderr</code>. The verbosity of the log output can be controlled with <code>--debug</code> command line argument or the <code>level</code> configuration option in the <code>logging</code> section.</p> <p>Radicale logs to <code>stderr</code>. The verbosity of the log output can be controlled with <code>--debug</code> command line argument or the <code>level</code> configuration option in the <code>logging</code> section.</p>
</section> </section>
<section class="level3" id="documentation/architecture"> <section class="level3" id="architecture">
<h3>Architecture <a class="headerlink" href="#documentation/architecture">&para;</a></h3> <h3>Architecture <a class="headerlink" href="#architecture">&para;</a></h3>
<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> <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"> <section class="level4" id="protocol-overview">
<h4>Protocol overview <a class="headerlink" href="#documentation/architecture/protocol-overview">&para;</a></h4> <h4>Protocol overview <a class="headerlink" href="#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> <p>Here is a simple overview of the global architecture for reaching a calendar or an address book through network:</p>
<div class="tableContainer"><table> <div class="tableContainer"><table>
<thead> <thead>
@ -989,8 +989,8 @@ user2:password2</code></pre>
<p>Radicale is <strong>not the client part</strong> of this architecture. It means that Radicale never draws calendars, address books, events and contacts on the screen. It only stores them and give the possibility to share them online with other people.</p> <p>Radicale is <strong>not the client part</strong> of this architecture. It means that Radicale never draws calendars, address books, events and contacts on the screen. It only stores them and give the possibility to share them online with other people.</p>
<p>If you want to see or edit your events and your contacts, you have to use another software called a client, that can be a "normal" applications with icons and buttons, a terminal or another web application.</p> <p>If you want to see or edit your events and your contacts, you have to use another software called a client, that can be a "normal" applications with icons and buttons, a terminal or another web application.</p>
</section> </section>
<section class="level4" id="documentation/architecture/code-architecture"> <section class="level4" id="code-architecture">
<h4>Code Architecture <a class="headerlink" href="#documentation/architecture/code-architecture">&para;</a></h4> <h4>Code Architecture <a class="headerlink" href="#code-architecture">&para;</a></h4>
<p>The <code>radicale</code> package offers the following modules.</p> <p>The <code>radicale</code> package offers the following modules.</p>
<p><code>__init__</code> : Contains the entry point for WSGI.</p> <p><code>__init__</code> : Contains the entry point for WSGI.</p>
<p><code>__main__</code> : Provides the entry point for the <code>radicale</code> executable and includes the command line parser. It loads configuration files from the default (or specified) paths and starts the internal server.</p> <p><code>__main__</code> : Provides the entry point for the <code>radicale</code> executable and includes the command line parser. It loads configuration files from the default (or specified) paths and starts the internal server.</p>
@ -1009,11 +1009,11 @@ user2:password2</code></pre>
<p><code>xmlutils</code> : Helper functions for working with the XML part of CalDAV/CardDAV requests and responses. It's based on the ElementTree XML API.</p> <p><code>xmlutils</code> : Helper functions for working with the XML part of CalDAV/CardDAV requests and responses. It's based on the ElementTree XML API.</p>
</section> </section>
</section> </section>
<section class="level3" id="documentation/plugins"> <section class="level3" id="plugins">
<h3>Plugins <a class="headerlink" href="#documentation/plugins">&para;</a></h3> <h3>Plugins <a class="headerlink" href="#plugins">&para;</a></h3>
<p>Radicale can be extended by plugins for authentication, rights management and storage. Plugins are <strong>python</strong> modules.</p> <p>Radicale can be extended by plugins for authentication, rights management and storage. Plugins are <strong>python</strong> modules.</p>
<section class="level4" id="documentation/plugins/getting-started"> <section class="level4" id="getting-started-1">
<h4>Getting started <a class="headerlink" href="#documentation/plugins/getting-started">&para;</a></h4> <h4>Getting started <a class="headerlink" href="#getting-started-1">&para;</a></h4>
<p>To get started we walk through the creation of a simple authentication plugin, that accepts login attempts with a static password.</p> <p>To get started we walk through the creation of a simple authentication plugin, that accepts login attempts with a static password.</p>
<p>The easiest way to develop and install <strong>python</strong> modules is <a href="https://docs.python.org/3/distutils/setupscript.html">Distutils</a>. For a minimal setup create the file <code>setup.py</code> with the following content in an empty folder:</p> <p>The easiest way to develop and install <strong>python</strong> modules is <a href="https://docs.python.org/3/distutils/setupscript.html">Distutils</a>. For a minimal setup create the file <code>setup.py</code> with the following content in an empty folder:</p>
<div class="sourceCode" id="cb39"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb39-1"><a aria-hidden="true" href="#cb39-1" tabindex="-1"></a><span class="co">#!/usr/bin/env python3</span></span> <div class="sourceCode" id="cb39"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb39-1"><a aria-hidden="true" href="#cb39-1" tabindex="-1"></a><span class="co">#!/usr/bin/env python3</span></span>
@ -1053,62 +1053,62 @@ user2:password2</code></pre>
<p>You can uninstall the module with:</p> <p>You can uninstall the module with:</p>
<div class="sourceCode" id="cb43"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb43-1"><a aria-hidden="true" href="#cb43-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> pip uninstall radicale_static_password_auth</span></code></pre></div> <div class="sourceCode" id="cb43"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb43-1"><a aria-hidden="true" href="#cb43-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> pip uninstall radicale_static_password_auth</span></code></pre></div>
</section> </section>
<section class="level4" id="documentation/plugins/authentication-plugins"> <section class="level4" id="authentication-plugins">
<h4>Authentication plugins <a class="headerlink" href="#documentation/plugins/authentication-plugins">&para;</a></h4> <h4>Authentication plugins <a class="headerlink" href="#authentication-plugins">&para;</a></h4>
<p>This plugin type is used to check login credentials. The module must contain a class <code>Auth</code> that extends <code>radicale.auth.BaseAuth</code>. Take a look at the file <code>radicale/auth/__init__.py</code> in Radicale's source code for more information.</p> <p>This plugin type is used to check login credentials. The module must contain a class <code>Auth</code> that extends <code>radicale.auth.BaseAuth</code>. Take a look at the file <code>radicale/auth/__init__.py</code> in Radicale's source code for more information.</p>
</section> </section>
<section class="level4" id="documentation/plugins/rights-management-plugins"> <section class="level4" id="rights-management-plugins">
<h4>Rights management plugins <a class="headerlink" href="#documentation/plugins/rights-management-plugins">&para;</a></h4> <h4>Rights management plugins <a class="headerlink" href="#rights-management-plugins">&para;</a></h4>
<p>This plugin type is used to check if a user has access to a path. The module must contain a class <code>Rights</code> that extends <code>radicale.rights.BaseRights</code>. Take a look at the file <code>radicale/rights/__init__.py</code> in Radicale's source code for more information.</p> <p>This plugin type is used to check if a user has access to a path. The module must contain a class <code>Rights</code> that extends <code>radicale.rights.BaseRights</code>. Take a look at the file <code>radicale/rights/__init__.py</code> in Radicale's source code for more information.</p>
</section> </section>
<section class="level4" id="documentation/plugins/web-plugins"> <section class="level4" id="web-plugins">
<h4>Web plugins <a class="headerlink" href="#documentation/plugins/web-plugins">&para;</a></h4> <h4>Web plugins <a class="headerlink" href="#web-plugins">&para;</a></h4>
<p>This plugin type is used to provide the web interface for Radicale. The module must contain a class <code>Web</code> that extends <code>radicale.web.BaseWeb</code>. Take a look at the file <code>radicale/web/__init__.py</code> in Radicale's source code for more information.</p> <p>This plugin type is used to provide the web interface for Radicale. The module must contain a class <code>Web</code> that extends <code>radicale.web.BaseWeb</code>. Take a look at the file <code>radicale/web/__init__.py</code> in Radicale's source code for more information.</p>
</section> </section>
<section class="level4" id="documentation/plugins/storage-plugins"> <section class="level4" id="storage-plugins">
<h4>Storage plugins <a class="headerlink" href="#documentation/plugins/storage-plugins">&para;</a></h4> <h4>Storage plugins <a class="headerlink" href="#storage-plugins">&para;</a></h4>
<p>This plugin is used to store collections and items. The module must contain a class <code>Storage</code> that extends <code>radicale.storage.BaseStorage</code>. Take a look at the file <code>radicale/storage/__init__.py</code> in Radicale's source code for more information.</p> <p>This plugin is used to store collections and items. The module must contain a class <code>Storage</code> that extends <code>radicale.storage.BaseStorage</code>. Take a look at the file <code>radicale/storage/__init__.py</code> in Radicale's source code for more information.</p>
</section> </section>
</section> </section>
</section> </section>
<section class="level2" id="contribute"> <section class="level2" id="contribute">
<h2>Contribute <a class="headerlink" href="#contribute">&para;</a></h2> <h2>Contribute <a class="headerlink" href="#contribute">&para;</a></h2>
<section class="level4" id="contribute//chat-with-us-on-irc"> <section class="level4" id="chat-with-us-on-irc">
<h4>Chat with Us on IRC <a class="headerlink" href="#contribute//chat-with-us-on-irc">&para;</a></h4> <h4>Chat with Us on IRC <a class="headerlink" href="#chat-with-us-on-irc">&para;</a></h4>
<p>Want to say something? Join our IRC room: <code>##kozea</code> on Freenode.</p> <p>Want to say something? Join our IRC room: <code>##kozea</code> on Freenode.</p>
</section> </section>
<section class="level4" id="contribute//report-bugs"> <section class="level4" id="report-bugs">
<h4>Report Bugs <a class="headerlink" href="#contribute//report-bugs">&para;</a></h4> <h4>Report Bugs <a class="headerlink" href="#report-bugs">&para;</a></h4>
<p>Found a bug? Want a new feature? Report a new issue on the <a href="https://github.com/Kozea/Radicale/issues">Radicale bug-tracker</a>.</p> <p>Found a bug? Want a new feature? Report a new issue on the <a href="https://github.com/Kozea/Radicale/issues">Radicale bug-tracker</a>.</p>
</section> </section>
<section class="level4" id="contribute//hack"> <section class="level4" id="hack">
<h4>Hack <a class="headerlink" href="#contribute//hack">&para;</a></h4> <h4>Hack <a class="headerlink" href="#hack">&para;</a></h4>
<p>Interested in hacking? Feel free to clone the <a href="https://github.com/Kozea/Radicale">git repository on GitHub</a> if you want to add new features, fix bugs or update the documentation.</p> <p>Interested in hacking? Feel free to clone the <a href="https://github.com/Kozea/Radicale">git repository on GitHub</a> if you want to add new features, fix bugs or update the documentation.</p>
</section> </section>
<section class="level4" id="contribute//documentation"> <section class="level4" id="documentation-2">
<h4>Documentation <a class="headerlink" href="#contribute//documentation">&para;</a></h4> <h4>Documentation <a class="headerlink" href="#documentation-2">&para;</a></h4>
<p>To change or complement the documentation create a pull request to <a href="https://github.com/Kozea/Radicale/blob/master/DOCUMENTATION.md">DOCUMENTATION.md</a>.</p> <p>To change or complement the documentation create a pull request to <a href="https://github.com/Kozea/Radicale/blob/master/DOCUMENTATION.md">DOCUMENTATION.md</a>.</p>
</section> </section>
</section> </section>
<section class="level2" id="download"> <section class="level2" id="download">
<h2>Download <a class="headerlink" href="#download">&para;</a></h2> <h2>Download <a class="headerlink" href="#download">&para;</a></h2>
<section class="level4" id="download//pypi"> <section class="level4" id="pypi">
<h4>PyPI <a class="headerlink" href="#download//pypi">&para;</a></h4> <h4>PyPI <a class="headerlink" href="#pypi">&para;</a></h4>
<p>Radicale is <a href="https://pypi.python.org/pypi/Radicale/">available on PyPI</a>. To install, just type as superuser:</p> <p>Radicale is <a href="https://pypi.python.org/pypi/Radicale/">available on PyPI</a>. To install, just type as superuser:</p>
<div class="sourceCode" id="cb44"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb44-1"><a aria-hidden="true" href="#cb44-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> pip install <span class="at">--upgrade</span> radicale</span></code></pre></div> <div class="sourceCode" id="cb44"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb44-1"><a aria-hidden="true" href="#cb44-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> pip install <span class="at">--upgrade</span> radicale</span></code></pre></div>
</section> </section>
<section class="level4" id="download//git-repository"> <section class="level4" id="git-repository">
<h4>Git Repository <a class="headerlink" href="#download//git-repository">&para;</a></h4> <h4>Git Repository <a class="headerlink" href="#git-repository">&para;</a></h4>
<p>If you want the development version of Radicale, take a look at the <a href="https://github.com/Kozea/Radicale/">git repository on GitHub</a>, or install it directly with:</p> <p>If you want the development version of Radicale, take a look at the <a href="https://github.com/Kozea/Radicale/">git repository on GitHub</a>, or install it directly with:</p>
<div class="sourceCode" id="cb45"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb45-1"><a aria-hidden="true" href="#cb45-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> pip install <span class="at">--upgrade</span> https://github.com/Kozea/Radicale/archive/master.tar.gz</span></code></pre></div> <div class="sourceCode" id="cb45"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb45-1"><a aria-hidden="true" href="#cb45-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> pip install <span class="at">--upgrade</span> https://github.com/Kozea/Radicale/archive/master.tar.gz</span></code></pre></div>
<p>You can also download the content of the repository as an <a href="https://github.com/Kozea/Radicale/tarball/master">archive</a>.</p> <p>You can also download the content of the repository as an <a href="https://github.com/Kozea/Radicale/tarball/master">archive</a>.</p>
</section> </section>
<section class="level4" id="download//source-packages"> <section class="level4" id="source-packages">
<h4>Source Packages <a class="headerlink" href="#download//source-packages">&para;</a></h4> <h4>Source Packages <a class="headerlink" href="#source-packages">&para;</a></h4>
<p>You can find the source packages of all releases on <a href="https://github.com/Kozea/Radicale/releases">GitHub</a>.</p> <p>You can find the source packages of all releases on <a href="https://github.com/Kozea/Radicale/releases">GitHub</a>.</p>
</section> </section>
<section class="level4" id="download//linux-distribution-packages"> <section class="level4" id="linux-distribution-packages">
<h4>Linux Distribution Packages <a class="headerlink" href="#download//linux-distribution-packages">&para;</a></h4> <h4>Linux Distribution Packages <a class="headerlink" href="#linux-distribution-packages">&para;</a></h4>
<p>Radicale has been packaged for:</p> <p>Radicale has been packaged for:</p>
<ul> <ul>
<li><a href="https://www.archlinux.org/packages/community/any/radicale/">ArchLinux</a> by David Runge</li> <li><a href="https://www.archlinux.org/packages/community/any/radicale/">ArchLinux</a> by David Runge</li>
@ -1129,42 +1129,42 @@ user2:password2</code></pre>
</section> </section>
<section class="level2" id="about"> <section class="level2" id="about">
<h2>About <a class="headerlink" href="#about">&para;</a></h2> <h2>About <a class="headerlink" href="#about">&para;</a></h2>
<section class="level4" id="about//main-goals"> <section class="level4" id="main-goals">
<h4>Main Goals <a class="headerlink" href="#about//main-goals">&para;</a></h4> <h4>Main Goals <a class="headerlink" href="#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>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>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 preconfigured 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> <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>
<section class="level4" id="about//what-radicale-will-never-be"> <section class="level4" id="what-radicale-will-never-be">
<h4>What Radicale Will Never Be <a class="headerlink" href="#about//what-radicale-will-never-be">&para;</a></h4> <h4>What Radicale Will Never Be <a class="headerlink" href="#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.</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 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>
<section class="level4" id="about//technical-choices"> <section class="level4" id="technical-choices">
<h4>Technical Choices <a class="headerlink" href="#about//technical-choices">&para;</a></h4> <h4>Technical Choices <a class="headerlink" href="#technical-choices">&para;</a></h4>
<p>Important global development choices have been decided before writing code. They are very useful to understand why the Radicale Project is different from other CalDAV and CardDAV servers, and why features are included or not in the code.</p> <p>Important global development choices have been decided before writing code. They are very useful to understand why the Radicale Project is different from other CalDAV and CardDAV servers, and why features are included or not in the code.</p>
<section class="level5" id="about//technical-choices/oriented-to-calendar-and-contact-user-agents"> <section class="level5" id="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> <h5>Oriented to Calendar and Contact User Agents <a class="headerlink" href="#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>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 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>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> <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>
<section class="level5" id="about//technical-choices/simple"> <section class="level5" id="simple">
<h5>Simple <a class="headerlink" href="#about//technical-choices/simple">&para;</a></h5> <h5>Simple <a class="headerlink" href="#simple">&para;</a></h5>
<p>Radicale is designed to be simple to install, simple to configure, simple to use.</p> <p>Radicale is designed to be simple to install, simple to configure, simple to use.</p>
<p>The installation is very easy, particularly with Linux: one dependency, no superuser rights needed, no configuration required, no database. Installing and launching the main script out-of-the-box, as a normal user, are often the only steps to have a simple remote calendar and contact access.</p> <p>The installation is very easy, particularly with Linux: one dependency, no superuser rights needed, no configuration required, no database. Installing and launching the main script out-of-the-box, as a normal user, are often the only steps to have a simple remote calendar and contact access.</p>
<p>Contrary to other servers that are often complicated, require high privileges or need a strong configuration, the Radicale Server can (sometimes, if not often) be launched in a couple of minutes, if you follow the <a href="#tutorials/simple-5-minute-setup">tutorial</a>.</p> <p>Contrary to other servers that are often complicated, require high privileges or need a strong configuration, the Radicale Server can (sometimes, if not often) be launched in a couple of minutes, if you follow the <a href="#simple-5-minute-setup">tutorial</a>.</p>
</section> </section>
<section class="level5" id="about//technical-choices/lazy"> <section class="level5" id="lazy">
<h5>Lazy <a class="headerlink" href="#about//technical-choices/lazy">&para;</a></h5> <h5>Lazy <a class="headerlink" href="#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 behaviors 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> <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>
</section> </section>
<section class="level4 last" id="about//history"> <section class="level4 last" id="history">
<h4>History <a class="headerlink" href="#about//history">&para;</a></h4> <h4>History <a class="headerlink" href="#history">&para;</a></h4>
<p>Radicale has been started as a (free topic) stupid school project replacing another (assigned topic) even more stupid school project.</p> <p>Radicale has been started as a (free topic) stupid school project replacing another (assigned topic) even more stupid school project.</p>
<p>At the beginning, it was just a proof-of-concept. The main goal was to write a small, dirty and simple CalDAV server working with Lightning, using no external libraries. That's how we created a piece of code that's (quite) easy to understand, to use and to hack.</p> <p>At the beginning, it was just a proof-of-concept. The main goal was to write a small, dirty and simple CalDAV server working with Lightning, using no external libraries. That's how we created a piece of code that's (quite) easy to understand, to use and to hack.</p>
<p>The <a href="https://github.com/Kozea/Radicale/commit/b1591aea">first lines</a> have been added to the SVN (!) repository as I was drinking (many) beers at the very end of 2008 (Python 2.6 and 3.0 were just released). It's now packaged for a growing number of Linux distributions.</p> <p>The <a href="https://github.com/Kozea/Radicale/commit/b1591aea">first lines</a> have been added to the SVN (!) repository as I was drinking (many) beers at the very end of 2008 (Python 2.6 and 3.0 were just released). It's now packaged for a growing number of Linux distributions.</p>

922
v1.html
View file

File diff suppressed because it is too large Load diff

1296
v2.html
View file

File diff suppressed because it is too large Load diff

540
v3.html
View file

@ -124,104 +124,104 @@
<ul> <ul>
<li class="level2"><a href="#getting-started">Getting started</a> <li class="level2"><a href="#getting-started">Getting started</a>
<ul> <ul>
<li class="level4"><a href="#getting-started//about-radicale">About Radicale</a></li> <li class="level4"><a href="#about-radicale">About Radicale</a></li>
<li class="level4"><a href="#getting-started//installation">Installation</a></li> <li class="level4"><a href="#installation">Installation</a></li>
<li class="level4"><a href="#getting-started//whats-new">What's New?</a></li> <li class="level4"><a href="#whats-new">What's New?</a></li>
</ul></li> </ul></li>
<li class="level2"><a href="#tutorials">Tutorials</a> <li class="level2"><a href="#tutorials">Tutorials</a>
<ul> <ul>
<li class="level3"><a href="#tutorials/simple-5-minute-setup">Simple 5-minute setup</a> <li class="level3"><a href="#simple-5-minute-setup">Simple 5-minute setup</a>
<ul> <ul>
<li class="level4"><a href="#tutorials/simple-5-minute-setup/linux--bsd">Linux / *BSD</a></li> <li class="level4"><a href="#linux--bsd">Linux / *BSD</a></li>
<li class="level4"><a href="#tutorials/simple-5-minute-setup/windows">Windows</a></li> <li class="level4"><a href="#windows">Windows</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#tutorials/basic-configuration">Basic Configuration</a> <li class="level3"><a href="#basic-configuration">Basic Configuration</a>
<ul> <ul>
<li class="level4"><a href="#tutorials/basic-configuration/authentication">Authentication</a></li> <li class="level4"><a href="#authentication">Authentication</a></li>
<li class="level4"><a href="#tutorials/basic-configuration/addresses">Addresses</a></li> <li class="level4"><a href="#addresses">Addresses</a></li>
<li class="level4"><a href="#tutorials/basic-configuration/storage">Storage</a></li> <li class="level4"><a href="#storage">Storage</a></li>
<li class="level4"><a href="#tutorials/basic-configuration/limits">Limits</a></li> <li class="level4"><a href="#limits">Limits</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#tutorials/running-as-a-service">Running as a service</a> <li class="level3"><a href="#running-as-a-service">Running as a service</a>
<ul> <ul>
<li class="level4"><a href="#tutorials/running-as-a-service/linux-with-systemd-system-wide">Linux with systemd system-wide</a></li> <li class="level4"><a href="#linux-with-systemd-system-wide">Linux with systemd system-wide</a></li>
<li class="level4"><a href="#tutorials/running-as-a-service/linux-with-systemd-as-a-user">Linux with systemd as a user</a></li> <li class="level4"><a href="#linux-with-systemd-as-a-user">Linux with systemd as a user</a></li>
<li class="level4"><a href="#tutorials/running-as-a-service/windows-with-nssm---the-non-sucking-service-manager">Windows with "NSSM - the Non-Sucking Service Manager"</a></li> <li class="level4"><a href="#windows-with-nssm---the-non-sucking-service-manager">Windows with "NSSM - the Non-Sucking Service Manager"</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#tutorials/reverse-proxy">Reverse Proxy</a> <li class="level3"><a href="#reverse-proxy">Reverse Proxy</a>
<ul> <ul>
<li class="level4"><a href="#tutorials/reverse-proxy/manage-user-accounts-with-the-reverse-proxy">Manage user accounts with the reverse proxy</a></li> <li class="level4"><a href="#manage-user-accounts-with-the-reverse-proxy">Manage user accounts with the reverse proxy</a></li>
<li class="level4"><a href="#tutorials/reverse-proxy/secure-connection-between-radicale-and-the-reverse-proxy">Secure connection between Radicale and the reverse proxy</a></li> <li class="level4"><a href="#secure-connection-between-radicale-and-the-reverse-proxy">Secure connection between Radicale and the reverse proxy</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#tutorials/wsgi-server">WSGI Server</a> <li class="level3"><a href="#wsgi-server">WSGI Server</a>
<ul> <ul>
<li class="level4"><a href="#tutorials/wsgi-server/manage-user-accounts-with-the-wsgi-server">Manage user accounts with the WSGI server</a></li> <li class="level4"><a href="#manage-user-accounts-with-the-wsgi-server">Manage user accounts with the WSGI server</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#tutorials/versioning-with-git">Versioning with Git</a></li> <li class="level3"><a href="#versioning-with-git">Versioning with Git</a></li>
</ul></li> </ul></li>
<li class="level2"><a href="#documentation">Documentation</a> <li class="level2"><a href="#documentation-1">Documentation</a>
<ul> <ul>
<li class="level3"><a href="#documentation/configuration">Configuration</a> <li class="level3"><a href="#configuration">Configuration</a>
<ul> <ul>
<li class="level4"><a href="#documentation/configuration/server">server</a></li> <li class="level4"><a href="#server">server</a></li>
<li class="level4"><a href="#documentation/configuration/encoding">encoding</a></li> <li class="level4"><a href="#encoding">encoding</a></li>
<li class="level4"><a href="#documentation/configuration/auth">auth</a></li> <li class="level4"><a href="#auth">auth</a></li>
<li class="level4"><a href="#documentation/configuration/rights">rights</a></li> <li class="level4"><a href="#rights">rights</a></li>
<li class="level4"><a href="#documentation/configuration/storage">storage</a></li> <li class="level4"><a href="#storage-1">storage</a></li>
<li class="level4"><a href="#documentation/configuration/web">web</a></li> <li class="level4"><a href="#web">web</a></li>
<li class="level4"><a href="#documentation/configuration/logging">logging</a></li> <li class="level4"><a href="#logging">logging</a></li>
<li class="level4"><a href="#documentation/configuration/headers">headers</a></li> <li class="level4"><a href="#headers">headers</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#documentation/supported-clients">Supported Clients</a> <li class="level3"><a href="#supported-clients">Supported Clients</a>
<ul> <ul>
<li class="level4"><a href="#documentation/supported-clients/davx⁵">DAVx⁵</a></li> <li class="level4"><a href="#davx⁵">DAVx⁵</a></li>
<li class="level4"><a href="#documentation/supported-clients/gnome-calendar-contacts-and-evolution">GNOME Calendar, Contacts and Evolution</a></li> <li class="level4"><a href="#gnome-calendar-contacts-and-evolution">GNOME Calendar, Contacts and Evolution</a></li>
<li class="level4"><a href="#documentation/supported-clients/thunderbird">Thunderbird</a></li> <li class="level4"><a href="#thunderbird">Thunderbird</a></li>
<li class="level4"><a href="#documentation/supported-clients/infcloud-caldavzap-and-carddavmate">InfCloud, CalDavZAP and CardDavMATE</a></li> <li class="level4"><a href="#infcloud-caldavzap-and-carddavmate">InfCloud, CalDavZAP and CardDavMATE</a></li>
<li class="level4"><a href="#documentation/supported-clients/command-line">Command line</a></li> <li class="level4"><a href="#command-line">Command line</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#documentation/authentication-and-rights">Authentication and Rights</a></li> <li class="level3"><a href="#authentication-and-rights">Authentication and Rights</a></li>
<li class="level3"><a href="#documentation/storage">Storage</a> <li class="level3"><a href="#storage-2">Storage</a>
<ul> <ul>
<li class="level4"><a href="#documentation/storage/layout">Layout</a></li> <li class="level4"><a href="#layout">Layout</a></li>
<li class="level4"><a href="#documentation/storage/locking">Locking</a></li> <li class="level4"><a href="#locking">Locking</a></li>
<li class="level4"><a href="#documentation/storage/manually-creating-collections">Manually creating collections</a></li> <li class="level4"><a href="#manually-creating-collections">Manually creating collections</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#documentation/logging">Logging</a></li> <li class="level3"><a href="#logging-1">Logging</a></li>
<li class="level3"><a href="#documentation/architecture">Architecture</a> <li class="level3"><a href="#architecture">Architecture</a>
<ul> <ul>
<li class="level4"><a href="#documentation/architecture/protocol-overview">Protocol overview</a></li> <li class="level4"><a href="#protocol-overview">Protocol overview</a></li>
<li class="level4"><a href="#documentation/architecture/code-architecture">Code Architecture</a></li> <li class="level4"><a href="#code-architecture">Code Architecture</a></li>
</ul></li> </ul></li>
<li class="level3"><a href="#documentation/plugins">Plugins</a> <li class="level3"><a href="#plugins">Plugins</a>
<ul> <ul>
<li class="level4"><a href="#documentation/plugins/getting-started">Getting started</a></li> <li class="level4"><a href="#getting-started-1">Getting started</a></li>
<li class="level4"><a href="#documentation/plugins/authentication-plugins">Authentication plugins</a></li> <li class="level4"><a href="#authentication-plugins">Authentication plugins</a></li>
<li class="level4"><a href="#documentation/plugins/rights-management-plugins">Rights management plugins</a></li> <li class="level4"><a href="#rights-management-plugins">Rights management plugins</a></li>
<li class="level4"><a href="#documentation/plugins/web-plugins">Web plugins</a></li> <li class="level4"><a href="#web-plugins">Web plugins</a></li>
<li class="level4"><a href="#documentation/plugins/storage-plugins">Storage plugins</a></li> <li class="level4"><a href="#storage-plugins">Storage plugins</a></li>
</ul></li> </ul></li>
</ul></li> </ul></li>
<li class="level2"><a href="#contribute">Contribute</a> <li class="level2"><a href="#contribute">Contribute</a>
<ul> <ul>
<li class="level4"><a href="#contribute//chat-with-us-on-irc">Chat with Us on IRC</a></li> <li class="level4"><a href="#chat-with-us-on-irc">Chat with Us on IRC</a></li>
<li class="level4"><a href="#contribute//report-bugs">Report Bugs</a></li> <li class="level4"><a href="#report-bugs">Report Bugs</a></li>
<li class="level4"><a href="#contribute//hack">Hack</a></li> <li class="level4"><a href="#hack">Hack</a></li>
<li class="level4"><a href="#contribute//documentation">Documentation</a></li> <li class="level4"><a href="#documentation-2">Documentation</a></li>
</ul></li> </ul></li>
<li class="level2"><a href="#download">Download</a> <li class="level2"><a href="#download">Download</a>
<ul> <ul>
<li class="level4"><a href="#download//pypi">PyPI</a></li> <li class="level4"><a href="#pypi">PyPI</a></li>
<li class="level4"><a href="#download//git-repository">Git Repository</a></li> <li class="level4"><a href="#git-repository">Git Repository</a></li>
<li class="level4"><a href="#download//source-packages">Source Packages</a></li> <li class="level4"><a href="#source-packages">Source Packages</a></li>
<li class="level4"><a href="#download//linux-distribution-packages">Linux Distribution Packages</a></li> <li class="level4"><a href="#linux-distribution-packages">Linux Distribution Packages</a></li>
</ul></li> </ul></li>
<li class="level2"><a href="#about">About</a> <li class="level2"><a href="#about">About</a>
<ul> <ul>
<li class="level4"><a href="#about//main-goals">Main Goals</a></li> <li class="level4"><a href="#main-goals">Main Goals</a></li>
<li class="level4"><a href="#about//what-radicale-will-never-be">What Radicale Will Never Be</a></li> <li class="level4"><a href="#what-radicale-will-never-be">What Radicale Will Never Be</a></li>
<li class="level4"><a href="#about//technical-choices">Technical Choices</a></li> <li class="level4"><a href="#technical-choices">Technical Choices</a></li>
<li class="level4"><a href="#about//history">History</a></li> <li class="level4"><a href="#history">History</a></li>
</ul></li> </ul></li>
</ul> </ul>
</div> </div>
@ -229,8 +229,8 @@
<div class="documentContainer"> <div class="documentContainer">
<section class="level2" id="getting-started"> <section class="level2" id="getting-started">
<h2>Getting started <a class="headerlink" href="#getting-started">&para;</a></h2> <h2>Getting started <a class="headerlink" href="#getting-started">&para;</a></h2>
<section class="level4" id="getting-started//about-radicale"> <section class="level4" id="about-radicale">
<h4>About Radicale <a class="headerlink" href="#getting-started//about-radicale">&para;</a></h4> <h4>About Radicale <a class="headerlink" href="#about-radicale">&para;</a></h4>
<p>Radicale is a small but powerful CalDAV (calendars, to-do 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> <ul>
<li>Shares calendars and contact lists through CalDAV, CardDAV and HTTP.</li> <li>Shares calendars and contact lists through CalDAV, CardDAV and HTTP.</li>
@ -238,34 +238,34 @@
<li>Works out-of-the-box, no complicated setup or configuration required.</li> <li>Works out-of-the-box, no complicated setup or configuration required.</li>
<li>Can limit access by authentication.</li> <li>Can limit access by authentication.</li>
<li>Can secure connections with TLS.</li> <li>Can secure connections with TLS.</li>
<li>Works with many <a href="#documentation/supported-clients">CalDAV and CardDAV clients</a>.</li> <li>Works with many <a href="#supported-clients">CalDAV and CardDAV clients</a>.</li>
<li>Stores all data on the file system in a simple folder structure.</li> <li>Stores all data on the file system in a simple folder structure.</li>
<li>Can be extended with plugins.</li> <li>Can be extended with plugins.</li>
<li>Is GPLv3-licensed free software.</li> <li>Is GPLv3-licensed free software.</li>
</ul> </ul>
</section> </section>
<section class="level4" id="getting-started//installation"> <section class="level4" id="installation">
<h4>Installation <a class="headerlink" href="#getting-started//installation">&para;</a></h4> <h4>Installation <a class="headerlink" href="#installation">&para;</a></h4>
<p>Radicale is really easy to install and works out-of-the-box.</p> <p>Radicale is really easy to install and works out-of-the-box.</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a aria-hidden="true" href="#cb1-1" tabindex="-1"></a><span class="ex">$</span> python3 <span class="at">-m</span> pip install <span class="at">--upgrade</span> radicale</span> <div class="sourceCode" id="cb1"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a aria-hidden="true" href="#cb1-1" tabindex="-1"></a><span class="ex">$</span> python3 <span class="at">-m</span> pip install <span class="at">--upgrade</span> radicale</span>
<span id="cb1-2"><a aria-hidden="true" href="#cb1-2" tabindex="-1"></a><span class="ex">$</span> python3 <span class="at">-m</span> radicale <span class="at">--storage-filesystem-folder</span><span class="op">=</span>~/.var/lib/radicale/collections</span></code></pre></div> <span id="cb1-2"><a aria-hidden="true" href="#cb1-2" tabindex="-1"></a><span class="ex">$</span> python3 <span class="at">-m</span> radicale <span class="at">--storage-filesystem-folder</span><span class="op">=</span>~/.var/lib/radicale/collections</span></code></pre></div>
<p>When the server is launched, open http://localhost:5232/ in your browser! You can login with any username and password.</p> <p>When the server is launched, open http://localhost:5232/ in your browser! You can login with any username and password.</p>
<p>Want more? Check the <a href="#tutorials">tutorials</a> and the <a href="#documentation">documentation</a>.</p> <p>Want more? Check the <a href="#tutorials">tutorials</a> and the <a href="#documentation-1">documentation</a>.</p>
</section> </section>
<section class="level4" id="getting-started//whats-new"> <section class="level4" id="whats-new">
<h4>What's New? <a class="headerlink" href="#getting-started//whats-new">&para;</a></h4> <h4>What's New? <a class="headerlink" href="#whats-new">&para;</a></h4>
<p>Read the <a href="https://github.com/Kozea/Radicale/blob/3.0.x/NEWS.md">changelog on GitHub.</a></p> <p>Read the <a href="https://github.com/Kozea/Radicale/blob/3.0.x/NEWS.md">changelog on GitHub.</a></p>
</section> </section>
</section> </section>
<section class="level2" id="tutorials"> <section class="level2" id="tutorials">
<h2>Tutorials <a class="headerlink" href="#tutorials">&para;</a></h2> <h2>Tutorials <a class="headerlink" href="#tutorials">&para;</a></h2>
<section class="level3" id="tutorials/simple-5-minute-setup"> <section class="level3" id="simple-5-minute-setup">
<h3>Simple 5-minute setup <a class="headerlink" href="#tutorials/simple-5-minute-setup">&para;</a></h3> <h3>Simple 5-minute setup <a class="headerlink" href="#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 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>When everything works, you can get a <a href="#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="#basic-configuration">some basic configuration</a>.</p>
<p>Follow one of the chapters below depending on your operating system.</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"> <section class="level4" id="linux--bsd">
<h4>Linux / *BSD <a class="headerlink" href="#tutorials/simple-5-minute-setup/linux--bsd">&para;</a></h4> <h4>Linux / *BSD <a class="headerlink" href="#linux--bsd">&para;</a></h4>
<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>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> <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 aria-hidden="true" href="#cb2-1" tabindex="-1"></a><span class="co"># Run the following command as root or</span></span> <div class="sourceCode" id="cb2"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb2-1"><a aria-hidden="true" href="#cb2-1" tabindex="-1"></a><span class="co"># Run the following command as root or</span></span>
@ -274,8 +274,8 @@
<span id="cb2-4"><a aria-hidden="true" href="#cb2-4" tabindex="-1"></a><span class="ex">$</span> python3 <span class="at">-m</span> radicale <span class="at">--storage-filesystem-folder</span><span class="op">=</span>~/.var/lib/radicale/collections</span></code></pre></div> <span id="cb2-4"><a aria-hidden="true" href="#cb2-4" tabindex="-1"></a><span class="ex">$</span> python3 <span class="at">-m</span> radicale <span class="at">--storage-filesystem-folder</span><span class="op">=</span>~/.var/lib/radicale/collections</span></code></pre></div>
<p>Victory! Open http://localhost:5232/ in your browser! You can log in with any username and password.</p> <p>Victory! Open http://localhost:5232/ in your browser! You can log in with any username and password.</p>
</section> </section>
<section class="level4" id="tutorials/simple-5-minute-setup/windows"> <section class="level4" id="windows">
<h4>Windows <a class="headerlink" href="#tutorials/simple-5-minute-setup/windows">&para;</a></h4> <h4>Windows <a class="headerlink" href="#windows">&para;</a></h4>
<p>The first step is to install Python. Go to <a href="https://python.org">python.org</a> and download the latest version of Python 3. Then run the installer. On the first window of the installer, check the "Add Python to PATH" box and click on "Install now". Wait a couple of minutes, it's done!</p> <p>The first step is to install Python. Go to <a href="https://python.org">python.org</a> and download the latest version of Python 3. Then run the installer. On the first window of the installer, check the "Add Python to PATH" box and click on "Install now". Wait a couple of minutes, it's done!</p>
<p>Launch a command prompt and type:</p> <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 aria-hidden="true" href="#cb3-1" tabindex="-1"></a>C<span class="op">:</span>\Users\User<span class="op">&gt;</span> python <span class="op">-</span>m pip install <span class="op">--</span>upgrade radicale</span> <div class="sourceCode" id="cb3"><pre class="sourceCode powershell"><code class="sourceCode powershell"><span id="cb3-1"><a aria-hidden="true" href="#cb3-1" tabindex="-1"></a>C<span class="op">:</span>\Users\User<span class="op">&gt;</span> python <span class="op">-</span>m pip install <span class="op">--</span>upgrade radicale</span>
@ -283,18 +283,18 @@
<p>Victory! Open http://localhost:5232/ in your browser! You can log in with any username and password.</p> <p>Victory! Open http://localhost:5232/ in your browser! You can log in with any username and password.</p>
</section> </section>
</section> </section>
<section class="level3" id="tutorials/basic-configuration"> <section class="level3" id="basic-configuration">
<h3>Basic Configuration <a class="headerlink" href="#tutorials/basic-configuration">&para;</a></h3> <h3>Basic Configuration <a class="headerlink" href="#basic-configuration">&para;</a></h3>
<p>Installation instructions can be found in the <a href="#tutorials/simple-5-minute-setup">simple 5-minute setup</a> tutorial.</p> <p>Installation instructions can be found in the <a href="#simple-5-minute-setup">simple 5-minute setup</a> tutorial.</p>
<p>Radicale tries to load configuration files from <code>/etc/radicale/config</code> and <code>~/.config/radicale/config</code>. Custom paths can be specified with the <code>--config /path/to/config</code> command line argument or the <code>RADICALE_CONFIG</code> environment variable. Multiple configuration files can be separated by <code>:</code> (resp. <code>;</code> on Windows). Paths that start with <code>?</code> are optional.</p> <p>Radicale tries to load configuration files from <code>/etc/radicale/config</code> and <code>~/.config/radicale/config</code>. Custom paths can be specified with the <code>--config /path/to/config</code> command line argument or the <code>RADICALE_CONFIG</code> environment variable. Multiple configuration files can be separated by <code>:</code> (resp. <code>;</code> on Windows). Paths that start with <code>?</code> are optional.</p>
<p>You should create a new configuration file at the desired location. (If the use of a configuration file is inconvenient, all options can be passed via command line arguments.)</p> <p>You should create a new configuration file at the desired location. (If the use of a configuration file is inconvenient, all options can be passed via command line arguments.)</p>
<p>All configuration options are described in detail in the <a href="#documentation/configuration">Configuration</a> section.</p> <p>All configuration options are described in detail in the <a href="#configuration">Configuration</a> section.</p>
<section class="level4" id="tutorials/basic-configuration/authentication"> <section class="level4" id="authentication">
<h4>Authentication <a class="headerlink" href="#tutorials/basic-configuration/authentication">&para;</a></h4> <h4>Authentication <a class="headerlink" href="#authentication">&para;</a></h4>
<p>In its default configuration Radicale doesn't check user names or passwords. If the server is reachable over a network, you should change this.</p> <p>In its default configuration Radicale doesn't check user names or passwords. If the server is reachable over a network, you should change this.</p>
<p>First a <code>users</code> file with all user names and passwords must be created. It can be stored in the same directory as the configuration file.</p> <p>First a <code>users</code> file with all user names and passwords must be created. It can be stored in the same directory as the configuration file.</p>
<section class="level5" id="tutorials/basic-configuration/authentication/the-secure-way"> <section class="level5" id="the-secure-way">
<h5>The secure way <a class="headerlink" href="#tutorials/basic-configuration/authentication/the-secure-way">&para;</a></h5> <h5>The secure way <a class="headerlink" href="#the-secure-way">&para;</a></h5>
<p>The <code>users</code> file can be created and managed with <a href="https://httpd.apache.org/docs/current/programs/htpasswd.html">htpasswd</a>:</p> <p>The <code>users</code> file can be created and managed with <a href="https://httpd.apache.org/docs/current/programs/htpasswd.html">htpasswd</a>:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a aria-hidden="true" href="#cb4-1" tabindex="-1"></a><span class="co"># Create a new htpasswd file with the user "user1"</span></span> <div class="sourceCode" id="cb4"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a aria-hidden="true" href="#cb4-1" tabindex="-1"></a><span class="co"># Create a new htpasswd file with the user "user1"</span></span>
<span id="cb4-2"><a aria-hidden="true" href="#cb4-2" tabindex="-1"></a><span class="ex">$</span> htpasswd <span class="at">-c</span> /path/to/users user1</span> <span id="cb4-2"><a aria-hidden="true" href="#cb4-2" tabindex="-1"></a><span class="ex">$</span> htpasswd <span class="at">-c</span> /path/to/users user1</span>
@ -311,8 +311,8 @@
<span id="cb5-4"><a aria-hidden="true" href="#cb5-4" tabindex="-1"></a><span class="co"># encryption method used in the htpasswd file</span></span> <span id="cb5-4"><a aria-hidden="true" href="#cb5-4" tabindex="-1"></a><span class="co"># encryption method used in the htpasswd file</span></span>
<span id="cb5-5"><a aria-hidden="true" href="#cb5-5" tabindex="-1"></a><span class="dt">htpasswd_encryption </span><span class="ot">=</span><span class="st"> md5</span></span></code></pre></div> <span id="cb5-5"><a aria-hidden="true" href="#cb5-5" tabindex="-1"></a><span class="dt">htpasswd_encryption </span><span class="ot">=</span><span class="st"> md5</span></span></code></pre></div>
</section> </section>
<section class="level5" id="tutorials/basic-configuration/authentication/the-simple-but-insecure-way"> <section class="level5" id="the-simple-but-insecure-way">
<h5>The simple but insecure way <a class="headerlink" href="#tutorials/basic-configuration/authentication/the-simple-but-insecure-way">&para;</a></h5> <h5>The simple but insecure way <a class="headerlink" href="#the-simple-but-insecure-way">&para;</a></h5>
<p>Create the <code>users</code> file by hand with lines containing the user name and password separated by <code>:</code>. Example:</p> <p>Create the <code>users</code> file by hand with lines containing the user name and password separated by <code>:</code>. Example:</p>
<pre class="htpasswd"><code>user1:password1 <pre class="htpasswd"><code>user1:password1
user2:password2</code></pre> user2:password2</code></pre>
@ -324,23 +324,23 @@ user2:password2</code></pre>
<span id="cb7-5"><a aria-hidden="true" href="#cb7-5" tabindex="-1"></a><span class="dt">htpasswd_encryption </span><span class="ot">=</span><span class="st"> plain</span></span></code></pre></div> <span id="cb7-5"><a aria-hidden="true" href="#cb7-5" tabindex="-1"></a><span class="dt">htpasswd_encryption </span><span class="ot">=</span><span class="st"> plain</span></span></code></pre></div>
</section> </section>
</section> </section>
<section class="level4" id="tutorials/basic-configuration/addresses"> <section class="level4" id="addresses">
<h4>Addresses <a class="headerlink" href="#tutorials/basic-configuration/addresses">&para;</a></h4> <h4>Addresses <a class="headerlink" href="#addresses">&para;</a></h4>
<p>The default configuration binds the server to localhost. It can't be reached from other computers. This can be changed with the following configuration options (IPv4 and IPv6):</p> <p>The default configuration binds the server to localhost. It can't be reached from other computers. This can be changed with the following configuration options (IPv4 and IPv6):</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb8-1"><a aria-hidden="true" href="#cb8-1" tabindex="-1"></a><span class="kw">[server]</span></span> <div class="sourceCode" id="cb8"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb8-1"><a aria-hidden="true" href="#cb8-1" tabindex="-1"></a><span class="kw">[server]</span></span>
<span id="cb8-2"><a aria-hidden="true" href="#cb8-2" tabindex="-1"></a><span class="dt">hosts </span><span class="ot">=</span><span class="st"> 0.0.0.0:5232, [::]:5232</span></span></code></pre></div> <span id="cb8-2"><a aria-hidden="true" href="#cb8-2" tabindex="-1"></a><span class="dt">hosts </span><span class="ot">=</span><span class="st"> 0.0.0.0:5232, [::]:5232</span></span></code></pre></div>
</section> </section>
<section class="level4" id="tutorials/basic-configuration/storage"> <section class="level4" id="storage">
<h4>Storage <a class="headerlink" href="#tutorials/basic-configuration/storage">&para;</a></h4> <h4>Storage <a class="headerlink" href="#storage">&para;</a></h4>
<p>Data is stored in the folder <code>/var/lib/radicale/collections</code>. The path can be changed with the following configuration:</p> <p>Data is stored in the folder <code>/var/lib/radicale/collections</code>. The path can be changed with the following configuration:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb9-1"><a aria-hidden="true" href="#cb9-1" tabindex="-1"></a><span class="kw">[storage]</span></span> <div class="sourceCode" id="cb9"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb9-1"><a aria-hidden="true" href="#cb9-1" tabindex="-1"></a><span class="kw">[storage]</span></span>
<span id="cb9-2"><a aria-hidden="true" href="#cb9-2" tabindex="-1"></a><span class="dt">filesystem_folder </span><span class="ot">=</span><span class="st"> /path/to/storage</span></span></code></pre></div> <span id="cb9-2"><a aria-hidden="true" href="#cb9-2" tabindex="-1"></a><span class="dt">filesystem_folder </span><span class="ot">=</span><span class="st"> /path/to/storage</span></span></code></pre></div>
<blockquote> <blockquote>
<p><strong>Security:</strong> The storage folder should not be readable by unauthorized users. Otherwise, they can read the calendar data and lock the storage. You can find OS dependent instructions in the <a href="#tutorials/running-as-a-service">Running as a service</a> section.</p> <p><strong>Security:</strong> The storage folder should not be readable by unauthorized users. Otherwise, they can read the calendar data and lock the storage. You can find OS dependent instructions in the <a href="#running-as-a-service">Running as a service</a> section.</p>
</blockquote> </blockquote>
</section> </section>
<section class="level4" id="tutorials/basic-configuration/limits"> <section class="level4" id="limits">
<h4>Limits <a class="headerlink" href="#tutorials/basic-configuration/limits">&para;</a></h4> <h4>Limits <a class="headerlink" href="#limits">&para;</a></h4>
<p>Radicale enforces limits on the maximum number of parallel connections, the maximum file size (important for contacts with big photos) and the rate of incorrect authentication attempts. Connections are terminated after a timeout. The default values should be fine for most scenarios.</p> <p>Radicale enforces limits on the maximum number of parallel connections, the maximum file size (important for contacts with big photos) and the rate of incorrect authentication attempts. Connections are terminated after a timeout. The default values should be fine for most scenarios.</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb10-1"><a aria-hidden="true" href="#cb10-1" tabindex="-1"></a><span class="kw">[server]</span></span> <div class="sourceCode" id="cb10"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb10-1"><a aria-hidden="true" href="#cb10-1" tabindex="-1"></a><span class="kw">[server]</span></span>
<span id="cb10-2"><a aria-hidden="true" href="#cb10-2" tabindex="-1"></a><span class="dt">max_connections </span><span class="ot">=</span><span class="st"> </span><span class="dv">20</span></span> <span id="cb10-2"><a aria-hidden="true" href="#cb10-2" tabindex="-1"></a><span class="dt">max_connections </span><span class="ot">=</span><span class="st"> </span><span class="dv">20</span></span>
@ -354,11 +354,11 @@ user2:password2</code></pre>
<span id="cb10-10"><a aria-hidden="true" href="#cb10-10" tabindex="-1"></a><span class="dt">delay </span><span class="ot">=</span><span class="st"> </span><span class="dv">1</span></span></code></pre></div> <span id="cb10-10"><a aria-hidden="true" href="#cb10-10" tabindex="-1"></a><span class="dt">delay </span><span class="ot">=</span><span class="st"> </span><span class="dv">1</span></span></code></pre></div>
</section> </section>
</section> </section>
<section class="level3" id="tutorials/running-as-a-service"> <section class="level3" id="running-as-a-service">
<h3>Running as a service <a class="headerlink" href="#tutorials/running-as-a-service">&para;</a></h3> <h3>Running as a service <a class="headerlink" href="#running-as-a-service">&para;</a></h3>
<p>The method to run Radicale as a service depends on your host operating system. Follow one of the chapters below depending on your operating system and requirements.</p> <p>The method to run Radicale as a service depends on your host operating system. Follow one of the chapters below depending on your operating system and requirements.</p>
<section class="level4" id="tutorials/running-as-a-service/linux-with-systemd-system-wide"> <section class="level4" id="linux-with-systemd-system-wide">
<h4>Linux with systemd system-wide <a class="headerlink" href="#tutorials/running-as-a-service/linux-with-systemd-system-wide">&para;</a></h4> <h4>Linux with systemd system-wide <a class="headerlink" href="#linux-with-systemd-system-wide">&para;</a></h4>
<p>Create the <strong>radicale</strong> user and group for the Radicale service. (Run <code>useradd --system --user-group --home-dir / --shell /sbin/nologin radicale</code> as root.) The storage folder must be writable by <strong>radicale</strong>. (Run <code>mkdir -p /var/lib/radicale/collections &amp;&amp; chown -R radicale:radicale /var/lib/radicale/collections</code> as root.)</p> <p>Create the <strong>radicale</strong> user and group for the Radicale service. (Run <code>useradd --system --user-group --home-dir / --shell /sbin/nologin radicale</code> as root.) The storage folder must be writable by <strong>radicale</strong>. (Run <code>mkdir -p /var/lib/radicale/collections &amp;&amp; chown -R radicale:radicale /var/lib/radicale/collections</code> as root.)</p>
<blockquote> <blockquote>
<p><strong>Security:</strong> The storage should not be readable by others. (Run <code>chmod -R o= /var/lib/radicale/collections</code> as root.)</p> <p><strong>Security:</strong> The storage should not be readable by others. (Run <code>chmod -R o= /var/lib/radicale/collections</code> as root.)</p>
@ -399,8 +399,8 @@ user2:password2</code></pre>
<span id="cb12-7"><a aria-hidden="true" href="#cb12-7" tabindex="-1"></a><span class="co"># View all log messages</span></span> <span id="cb12-7"><a aria-hidden="true" href="#cb12-7" tabindex="-1"></a><span class="co"># View all log messages</span></span>
<span id="cb12-8"><a aria-hidden="true" href="#cb12-8" tabindex="-1"></a><span class="ex">$</span> journalctl <span class="at">--unit</span> radicale.service</span></code></pre></div> <span id="cb12-8"><a aria-hidden="true" href="#cb12-8" tabindex="-1"></a><span class="ex">$</span> journalctl <span class="at">--unit</span> radicale.service</span></code></pre></div>
</section> </section>
<section class="level4" id="tutorials/running-as-a-service/linux-with-systemd-as-a-user"> <section class="level4" id="linux-with-systemd-as-a-user">
<h4>Linux with systemd as a user <a class="headerlink" href="#tutorials/running-as-a-service/linux-with-systemd-as-a-user">&para;</a></h4> <h4>Linux with systemd as a user <a class="headerlink" href="#linux-with-systemd-as-a-user">&para;</a></h4>
<p>Create the file <code>~/.config/systemd/user/radicale.service</code>:</p> <p>Create the file <code>~/.config/systemd/user/radicale.service</code>:</p>
<div class="sourceCode" id="cb13"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb13-1"><a aria-hidden="true" href="#cb13-1" tabindex="-1"></a><span class="kw">[Unit]</span></span> <div class="sourceCode" id="cb13"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb13-1"><a aria-hidden="true" href="#cb13-1" tabindex="-1"></a><span class="kw">[Unit]</span></span>
<span id="cb13-2"><a aria-hidden="true" href="#cb13-2" tabindex="-1"></a><span class="dt">Description</span><span class="ot">=</span><span class="st">A simple CalDAV (calendar) and CardDAV (contact) server</span></span> <span id="cb13-2"><a aria-hidden="true" href="#cb13-2" tabindex="-1"></a><span class="dt">Description</span><span class="ot">=</span><span class="st">A simple CalDAV (calendar) and CardDAV (contact) server</span></span>
@ -422,8 +422,8 @@ user2:password2</code></pre>
<span id="cb14-7"><a aria-hidden="true" href="#cb14-7" tabindex="-1"></a><span class="co"># View all log messages</span></span> <span id="cb14-7"><a aria-hidden="true" href="#cb14-7" tabindex="-1"></a><span class="co"># View all log messages</span></span>
<span id="cb14-8"><a aria-hidden="true" href="#cb14-8" tabindex="-1"></a><span class="ex">$</span> journalctl <span class="at">--user</span> <span class="at">--unit</span> radicale.service</span></code></pre></div> <span id="cb14-8"><a aria-hidden="true" href="#cb14-8" tabindex="-1"></a><span class="ex">$</span> journalctl <span class="at">--user</span> <span class="at">--unit</span> radicale.service</span></code></pre></div>
</section> </section>
<section class="level4" id="tutorials/running-as-a-service/windows-with-nssm---the-non-sucking-service-manager"> <section class="level4" id="windows-with-nssm---the-non-sucking-service-manager">
<h4>Windows with "NSSM - the Non-Sucking Service Manager" <a class="headerlink" href="#tutorials/running-as-a-service/windows-with-nssm---the-non-sucking-service-manager">&para;</a></h4> <h4>Windows with "NSSM - the Non-Sucking Service Manager" <a class="headerlink" href="#windows-with-nssm---the-non-sucking-service-manager">&para;</a></h4>
<p>First install <a href="https://nssm.cc/">NSSM</a> and start <code>nssm install</code> in a command prompt. Apply the following configuration:</p> <p>First install <a href="https://nssm.cc/">NSSM</a> and start <code>nssm install</code> in a command prompt. Apply the following configuration:</p>
<ul> <ul>
<li>Service name: <code>Radicale</code></li> <li>Service name: <code>Radicale</code></li>
@ -444,8 +444,8 @@ user2:password2</code></pre>
<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> <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>
</section> </section>
</section> </section>
<section class="level3" id="tutorials/reverse-proxy"> <section class="level3" id="reverse-proxy">
<h3>Reverse Proxy <a class="headerlink" href="#tutorials/reverse-proxy">&para;</a></h3> <h3>Reverse Proxy <a class="headerlink" href="#reverse-proxy">&para;</a></h3>
<p>When a reverse proxy is used, the path at which Radicale is available must be provided via the <code>X-Script-Name</code> header. The proxy must remove the location from the URL path that is forwarded to Radicale.</p> <p>When a reverse proxy is used, the path at which Radicale is available must be provided via the <code>X-Script-Name</code> header. The proxy must remove the location from the URL path that is forwarded to Radicale.</p>
<p>Example <strong>nginx</strong> configuration:</p> <p>Example <strong>nginx</strong> configuration:</p>
<pre class="nginx"><code>location /radicale/ { # The trailing / is important! <pre class="nginx"><code>location /radicale/ { # The trailing / is important!
@ -472,8 +472,8 @@ user2:password2</code></pre>
<span id="cb17-5"><a aria-hidden="true" href="#cb17-5" tabindex="-1"></a><span class="co"># Set to directory of .htaccess file:</span></span> <span id="cb17-5"><a aria-hidden="true" href="#cb17-5" tabindex="-1"></a><span class="co"># Set to directory of .htaccess file:</span></span>
<span id="cb17-6"><a aria-hidden="true" href="#cb17-6" tabindex="-1"></a>RequestHeader<span class="st"> set X-Script-Name /radicale</span></span></code></pre></div> <span id="cb17-6"><a aria-hidden="true" href="#cb17-6" tabindex="-1"></a>RequestHeader<span class="st"> set X-Script-Name /radicale</span></span></code></pre></div>
<p>Be reminded that Radicale's default configuration enforces limits on the maximum number of parallel connections, the maximum file size and the rate of incorrect authentication attempts. Connections are terminated after a timeout.</p> <p>Be reminded that Radicale's default configuration enforces limits on the maximum number of parallel connections, the maximum file size and the rate of incorrect authentication attempts. Connections are terminated after a timeout.</p>
<section class="level4" id="tutorials/reverse-proxy/manage-user-accounts-with-the-reverse-proxy"> <section class="level4" id="manage-user-accounts-with-the-reverse-proxy">
<h4>Manage user accounts with the reverse proxy <a class="headerlink" href="#tutorials/reverse-proxy/manage-user-accounts-with-the-reverse-proxy">&para;</a></h4> <h4>Manage user accounts with the reverse proxy <a class="headerlink" href="#manage-user-accounts-with-the-reverse-proxy">&para;</a></h4>
<p>Set the configuration option <code>type</code> in the <code>auth</code> section to <code>http_x_remote_user</code>. Radicale uses the user name provided in the <code>X-Remote-User</code> HTTP header and disables HTTP authentication.</p> <p>Set the configuration option <code>type</code> in the <code>auth</code> section to <code>http_x_remote_user</code>. Radicale uses the user name provided in the <code>X-Remote-User</code> HTTP header and disables HTTP authentication.</p>
<p>Example <strong>nginx</strong> configuration:</p> <p>Example <strong>nginx</strong> configuration:</p>
<pre class="nginx"><code>location /radicale/ { <pre class="nginx"><code>location /radicale/ {
@ -517,8 +517,8 @@ user2:password2</code></pre>
<p><strong>Security:</strong> Untrusted clients should not be able to access the Radicale server directly. Otherwise, they can authenticate as any user.</p> <p><strong>Security:</strong> Untrusted clients should not be able to access the Radicale server directly. Otherwise, they can authenticate as any user.</p>
</blockquote> </blockquote>
</section> </section>
<section class="level4" id="tutorials/reverse-proxy/secure-connection-between-radicale-and-the-reverse-proxy"> <section class="level4" id="secure-connection-between-radicale-and-the-reverse-proxy">
<h4>Secure connection between Radicale and the reverse proxy <a class="headerlink" href="#tutorials/reverse-proxy/secure-connection-between-radicale-and-the-reverse-proxy">&para;</a></h4> <h4>Secure connection between Radicale and the reverse proxy <a class="headerlink" href="#secure-connection-between-radicale-and-the-reverse-proxy">&para;</a></h4>
<p>SSL certificates can be used to encrypt and authenticate the connection between Radicale and the reverse proxy. First you have to generate a certificate for Radicale and a certificate for the reverse proxy. The following commands generate self-signed certificates. You will be asked to enter additional information about the certificate, the values don't matter and you can keep the defaults.</p> <p>SSL certificates can be used to encrypt and authenticate the connection between Radicale and the reverse proxy. First you have to generate a certificate for Radicale and a certificate for the reverse proxy. The following commands generate self-signed certificates. You will be asked to enter additional information about the certificate, the values don't matter and you can keep the defaults.</p>
<div class="sourceCode" id="cb21"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb21-1"><a aria-hidden="true" href="#cb21-1" tabindex="-1"></a><span class="ex">$</span> openssl req <span class="at">-x509</span> <span class="at">-newkey</span> rsa:4096 <span class="at">-keyout</span> server_key.pem <span class="at">-out</span> server_cert.pem <span class="at">-nodes</span> <span class="at">-days</span> 9999</span> <div class="sourceCode" id="cb21"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb21-1"><a aria-hidden="true" href="#cb21-1" tabindex="-1"></a><span class="ex">$</span> openssl req <span class="at">-x509</span> <span class="at">-newkey</span> rsa:4096 <span class="at">-keyout</span> server_key.pem <span class="at">-out</span> server_cert.pem <span class="at">-nodes</span> <span class="at">-days</span> 9999</span>
<span id="cb21-2"><a aria-hidden="true" href="#cb21-2" tabindex="-1"></a><span class="ex">$</span> openssl req <span class="at">-x509</span> <span class="at">-newkey</span> rsa:4096 <span class="at">-keyout</span> client_key.pem <span class="at">-out</span> client_cert.pem <span class="at">-nodes</span> <span class="at">-days</span> 9999</span></code></pre></div> <span id="cb21-2"><a aria-hidden="true" href="#cb21-2" tabindex="-1"></a><span class="ex">$</span> openssl req <span class="at">-x509</span> <span class="at">-newkey</span> rsa:4096 <span class="at">-keyout</span> client_key.pem <span class="at">-out</span> client_cert.pem <span class="at">-nodes</span> <span class="at">-days</span> 9999</span></code></pre></div>
@ -539,8 +539,8 @@ user2:password2</code></pre>
}</code></pre> }</code></pre>
</section> </section>
</section> </section>
<section class="level3" id="tutorials/wsgi-server"> <section class="level3" id="wsgi-server">
<h3>WSGI Server <a class="headerlink" href="#tutorials/wsgi-server">&para;</a></h3> <h3>WSGI Server <a class="headerlink" href="#wsgi-server">&para;</a></h3>
<p>Radicale is compatible with the WSGI specification.</p> <p>Radicale is compatible with the WSGI specification.</p>
<p>A configuration file can be set with the <code>RADICALE_CONFIG</code> environment variable, otherwise no configuration file is loaded and the default configuration is used.</p> <p>A configuration file can be set with the <code>RADICALE_CONFIG</code> environment variable, otherwise no configuration file is loaded and the default configuration is used.</p>
<p>Example <strong>uWSGI</strong> configuration:</p> <p>Example <strong>uWSGI</strong> configuration:</p>
@ -552,13 +552,13 @@ user2:password2</code></pre>
<span id="cb24-6"><a aria-hidden="true" href="#cb24-6" tabindex="-1"></a><span class="dt">env </span><span class="ot">=</span><span class="st"> RADICALE_CONFIG=/etc/radicale/config</span></span></code></pre></div> <span id="cb24-6"><a aria-hidden="true" href="#cb24-6" tabindex="-1"></a><span class="dt">env </span><span class="ot">=</span><span class="st"> RADICALE_CONFIG=/etc/radicale/config</span></span></code></pre></div>
<p>Example <strong>Gunicorn</strong> configuration:</p> <p>Example <strong>Gunicorn</strong> configuration:</p>
<div class="sourceCode" id="cb25"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb25-1"><a aria-hidden="true" href="#cb25-1" tabindex="-1"></a><span class="ex">gunicorn</span> <span class="at">--bind</span> <span class="st">'127.0.0.1:5232'</span> <span class="at">--workers</span> 8 <span class="at">--env</span> <span class="st">'RADICALE_CONFIG=/etc/radicale/config'</span> radicale</span></code></pre></div> <div class="sourceCode" id="cb25"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb25-1"><a aria-hidden="true" href="#cb25-1" tabindex="-1"></a><span class="ex">gunicorn</span> <span class="at">--bind</span> <span class="st">'127.0.0.1:5232'</span> <span class="at">--workers</span> 8 <span class="at">--env</span> <span class="st">'RADICALE_CONFIG=/etc/radicale/config'</span> radicale</span></code></pre></div>
<section class="level4" id="tutorials/wsgi-server/manage-user-accounts-with-the-wsgi-server"> <section class="level4" id="manage-user-accounts-with-the-wsgi-server">
<h4>Manage user accounts with the WSGI server <a class="headerlink" href="#tutorials/wsgi-server/manage-user-accounts-with-the-wsgi-server">&para;</a></h4> <h4>Manage user accounts with the WSGI server <a class="headerlink" href="#manage-user-accounts-with-the-wsgi-server">&para;</a></h4>
<p>Set the configuration option <code>type</code> in the <code>auth</code> section to <code>remote_user</code>. Radicale uses the user name provided by the WSGI server and disables authentication over HTTP.</p> <p>Set the configuration option <code>type</code> in the <code>auth</code> section to <code>remote_user</code>. Radicale uses the user name provided by the WSGI server and disables authentication over HTTP.</p>
</section> </section>
</section> </section>
<section class="level3" id="tutorials/versioning-with-git"> <section class="level3" id="versioning-with-git">
<h3>Versioning with Git <a class="headerlink" href="#tutorials/versioning-with-git">&para;</a></h3> <h3>Versioning with Git <a class="headerlink" href="#versioning-with-git">&para;</a></h3>
<p>This tutorial describes how to keep track of all changes to calendars and address books with <strong>git</strong> (or any other version control system).</p> <p>This tutorial describes how to keep track of all changes to calendars and address books with <strong>git</strong> (or any other version control system).</p>
<p>The repository must be initialized by running <code>git init</code> in the file system folder. Internal files of Radicale can be excluded by creating the file <code>.gitignore</code> with the following content:</p> <p>The repository must be initialized by running <code>git init</code> in the file system folder. Internal files of Radicale can be excluded by creating the file <code>.gitignore</code> with the following content:</p>
<pre><code>.Radicale.cache <pre><code>.Radicale.cache
@ -569,10 +569,10 @@ user2:password2</code></pre>
<p>The command gets executed after every change to the storage and commits the changes into the <strong>git</strong> repository.</p> <p>The command gets executed after every change to the storage and commits the changes into the <strong>git</strong> repository.</p>
</section> </section>
</section> </section>
<section class="level2" id="documentation"> <section class="level2" id="documentation-1">
<h2>Documentation <a class="headerlink" href="#documentation">&para;</a></h2> <h2>Documentation <a class="headerlink" href="#documentation-1">&para;</a></h2>
<section class="level3" id="documentation/configuration"> <section class="level3" id="configuration">
<h3>Configuration <a class="headerlink" href="#documentation/configuration">&para;</a></h3> <h3>Configuration <a class="headerlink" href="#configuration">&para;</a></h3>
<p>Radicale can be configured with a configuration file or with command line arguments.</p> <p>Radicale can be configured with a configuration file or with command line arguments.</p>
<p>An example configuration file looks like:</p> <p>An example configuration file looks like:</p>
<div class="sourceCode" id="cb28"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb28-1"><a aria-hidden="true" href="#cb28-1" tabindex="-1"></a><span class="kw">[server]</span></span> <div class="sourceCode" id="cb28"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb28-1"><a aria-hidden="true" href="#cb28-1" tabindex="-1"></a><span class="kw">[server]</span></span>
@ -591,67 +591,67 @@ user2:password2</code></pre>
<div class="sourceCode" id="cb29"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb29-1"><a aria-hidden="true" href="#cb29-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> radicale <span class="at">--server-hosts</span> 0.0.0.0:5232,[::]:5232 <span class="at">--auth-type</span> htpasswd <span class="at">--htpasswd-filename</span> ~/.config/radicale/users <span class="at">--htpasswd-encryption</span> md5</span></code></pre></div> <div class="sourceCode" id="cb29"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb29-1"><a aria-hidden="true" href="#cb29-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> radicale <span class="at">--server-hosts</span> 0.0.0.0:5232,[::]:5232 <span class="at">--auth-type</span> htpasswd <span class="at">--htpasswd-filename</span> ~/.config/radicale/users <span class="at">--htpasswd-encryption</span> md5</span></code></pre></div>
<p>Add the argument <code>--config ""</code> to stop Radicale from loading the default configuration files. Run <code>python3 -m radicale --help</code> for more information.</p> <p>Add the argument <code>--config ""</code> to stop Radicale from loading the default configuration files. Run <code>python3 -m radicale --help</code> for more information.</p>
<p>In the following, all configuration categories and options are described.</p> <p>In the following, all configuration categories and options are described.</p>
<section class="level4" id="documentation/configuration/server"> <section class="level4" id="server">
<h4>server <a class="headerlink" href="#documentation/configuration/server">&para;</a></h4> <h4>server <a class="headerlink" href="#server">&para;</a></h4>
<p>The configuration options in this category are only relevant in standalone mode. All options are ignored, when Radicale runs via WSGI.</p> <p>The configuration options in this category are only relevant in standalone mode. All options are ignored, when Radicale runs via WSGI.</p>
<section class="level5" id="documentation/configuration/server/hosts"> <section class="level5" id="hosts">
<h5>hosts <a class="headerlink" href="#documentation/configuration/server/hosts">&para;</a></h5> <h5>hosts <a class="headerlink" href="#hosts">&para;</a></h5>
<p>A comma separated list of addresses that the server will bind to.</p> <p>A comma separated list of addresses that the server will bind to.</p>
<p>Default: <code>localhost:5232</code></p> <p>Default: <code>localhost:5232</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/max_connections"> <section class="level5" id="max_connections">
<h5>max_connections <a class="headerlink" href="#documentation/configuration/server/max_connections">&para;</a></h5> <h5>max_connections <a class="headerlink" href="#max_connections">&para;</a></h5>
<p>The maximum number of parallel connections. Set to <code>0</code> to disable the limit.</p> <p>The maximum number of parallel connections. Set to <code>0</code> to disable the limit.</p>
<p>Default: <code>8</code></p> <p>Default: <code>8</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/max_content_length"> <section class="level5" id="max_content_length">
<h5>max_content_length <a class="headerlink" href="#documentation/configuration/server/max_content_length">&para;</a></h5> <h5>max_content_length <a class="headerlink" href="#max_content_length">&para;</a></h5>
<p>The maximum size of the request body. (bytes)</p> <p>The maximum size of the request body. (bytes)</p>
<p>Default: <code>100000000</code></p> <p>Default: <code>100000000</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/timeout"> <section class="level5" id="timeout">
<h5>timeout <a class="headerlink" href="#documentation/configuration/server/timeout">&para;</a></h5> <h5>timeout <a class="headerlink" href="#timeout">&para;</a></h5>
<p>Socket timeout. (seconds)</p> <p>Socket timeout. (seconds)</p>
<p>Default: <code>30</code></p> <p>Default: <code>30</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/ssl"> <section class="level5" id="ssl">
<h5>ssl <a class="headerlink" href="#documentation/configuration/server/ssl">&para;</a></h5> <h5>ssl <a class="headerlink" href="#ssl">&para;</a></h5>
<p>Enable transport layer encryption.</p> <p>Enable transport layer encryption.</p>
<p>Default: <code>False</code></p> <p>Default: <code>False</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/certificate"> <section class="level5" id="certificate">
<h5>certificate <a class="headerlink" href="#documentation/configuration/server/certificate">&para;</a></h5> <h5>certificate <a class="headerlink" href="#certificate">&para;</a></h5>
<p>Path of the SSL certifcate.</p> <p>Path of the SSL certifcate.</p>
<p>Default: <code>/etc/ssl/radicale.cert.pem</code></p> <p>Default: <code>/etc/ssl/radicale.cert.pem</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/key"> <section class="level5" id="key">
<h5>key <a class="headerlink" href="#documentation/configuration/server/key">&para;</a></h5> <h5>key <a class="headerlink" href="#key">&para;</a></h5>
<p>Path to the private key for SSL. Only effective if <code>ssl</code> is enabled.</p> <p>Path to the private key for SSL. Only effective if <code>ssl</code> is enabled.</p>
<p>Default: <code>/etc/ssl/radicale.key.pem</code></p> <p>Default: <code>/etc/ssl/radicale.key.pem</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/server/certificate_authority"> <section class="level5" id="certificate_authority">
<h5>certificate_authority <a class="headerlink" href="#documentation/configuration/server/certificate_authority">&para;</a></h5> <h5>certificate_authority <a class="headerlink" href="#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 certificate.</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> <p>Default:</p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/encoding"> <section class="level4" id="encoding">
<h4>encoding <a class="headerlink" href="#documentation/configuration/encoding">&para;</a></h4> <h4>encoding <a class="headerlink" href="#encoding">&para;</a></h4>
<section class="level5" id="documentation/configuration/encoding/request"> <section class="level5" id="request">
<h5>request <a class="headerlink" href="#documentation/configuration/encoding/request">&para;</a></h5> <h5>request <a class="headerlink" href="#request">&para;</a></h5>
<p>Encoding for responding requests.</p> <p>Encoding for responding requests.</p>
<p>Default: <code>utf-8</code></p> <p>Default: <code>utf-8</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/encoding/stock"> <section class="level5" id="stock">
<h5>stock <a class="headerlink" href="#documentation/configuration/encoding/stock">&para;</a></h5> <h5>stock <a class="headerlink" href="#stock">&para;</a></h5>
<p>Encoding for storing local collections</p> <p>Encoding for storing local collections</p>
<p>Default: <code>utf-8</code></p> <p>Default: <code>utf-8</code></p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/auth"> <section class="level4" id="auth">
<h4>auth <a class="headerlink" href="#documentation/configuration/auth">&para;</a></h4> <h4>auth <a class="headerlink" href="#auth">&para;</a></h4>
<section class="level5" id="documentation/configuration/auth/type"> <section class="level5" id="type">
<h5>type <a class="headerlink" href="#documentation/configuration/auth/type">&para;</a></h5> <h5>type <a class="headerlink" href="#type">&para;</a></h5>
<p>The method to verify usernames and passwords.</p> <p>The method to verify usernames and passwords.</p>
<p>Available backends:</p> <p>Available backends:</p>
<p><code>none</code> : Just allows all usernames and passwords.</p> <p><code>none</code> : Just allows all usernames and passwords.</p>
@ -660,13 +660,13 @@ user2:password2</code></pre>
<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><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>
<section class="level5" id="documentation/configuration/auth/htpasswd_filename"> <section class="level5" id="htpasswd_filename">
<h5>htpasswd_filename <a class="headerlink" href="#documentation/configuration/auth/htpasswd_filename">&para;</a></h5> <h5>htpasswd_filename <a class="headerlink" href="#htpasswd_filename">&para;</a></h5>
<p>Path to the htpasswd file.</p> <p>Path to the htpasswd file.</p>
<p>Default:</p> <p>Default:</p>
</section> </section>
<section class="level5" id="documentation/configuration/auth/htpasswd_encryption"> <section class="level5" id="htpasswd_encryption">
<h5>htpasswd_encryption <a class="headerlink" href="#documentation/configuration/auth/htpasswd_encryption">&para;</a></h5> <h5>htpasswd_encryption <a class="headerlink" href="#htpasswd_encryption">&para;</a></h5>
<p>The encryption method that is used in the htpasswd file. Use the <a href="https://httpd.apache.org/docs/current/programs/htpasswd.html">htpasswd</a> or similar to generate this files.</p> <p>The encryption method that is used in the htpasswd file. Use the <a href="https://httpd.apache.org/docs/current/programs/htpasswd.html">htpasswd</a> or similar to generate this files.</p>
<p>Available methods:</p> <p>Available methods:</p>
<p><code>plain</code> : Passwords are stored in plaintext. This is obviously not secure! The htpasswd file for this can be created by hand and looks like:</p> <p><code>plain</code> : Passwords are stored in plaintext. This is obviously not secure! The htpasswd file for this can be created by hand and looks like:</p>
@ -676,21 +676,21 @@ user2:password2</code></pre>
<p><code>md5</code> : This uses an iterated md5 digest of the password with a salt.</p> <p><code>md5</code> : This uses an iterated md5 digest of the password with a salt.</p>
<p>Default: <code>md5</code></p> <p>Default: <code>md5</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/auth/delay"> <section class="level5" id="delay">
<h5>delay <a class="headerlink" href="#documentation/configuration/auth/delay">&para;</a></h5> <h5>delay <a class="headerlink" href="#delay">&para;</a></h5>
<p>Average delay after failed login attempts in seconds.</p> <p>Average delay after failed login attempts in seconds.</p>
<p>Default: <code>1</code></p> <p>Default: <code>1</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/auth/realm"> <section class="level5" id="realm">
<h5>realm <a class="headerlink" href="#documentation/configuration/auth/realm">&para;</a></h5> <h5>realm <a class="headerlink" href="#realm">&para;</a></h5>
<p>Message displayed in the client when a password is needed.</p> <p>Message displayed in the client when a password is needed.</p>
<p>Default: <code>Radicale - Password Required</code></p> <p>Default: <code>Radicale - Password Required</code></p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/rights"> <section class="level4" id="rights">
<h4>rights <a class="headerlink" href="#documentation/configuration/rights">&para;</a></h4> <h4>rights <a class="headerlink" href="#rights">&para;</a></h4>
<section class="level5" id="documentation/configuration/rights/type"> <section class="level5" id="type-1">
<h5>type <a class="headerlink" href="#documentation/configuration/rights/type">&para;</a></h5> <h5>type <a class="headerlink" href="#type-1">&para;</a></h5>
<p>The backend that is used to check the access rights of collections.</p> <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 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>Available backends:</p>
@ -700,40 +700,40 @@ user2:password2</code></pre>
<p><code>from_file</code> : Load the rules from a file.</p> <p><code>from_file</code> : Load the rules from a file.</p>
<p>Default: <code>owner_only</code></p> <p>Default: <code>owner_only</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/rights/file"> <section class="level5" id="file">
<h5>file <a class="headerlink" href="#documentation/configuration/rights/file">&para;</a></h5> <h5>file <a class="headerlink" href="#file">&para;</a></h5>
<p>File for the rights backend <code>from_file</code>. See the <a href="#documentation/authentication-and-rights">Rights</a> section.</p> <p>File for the rights backend <code>from_file</code>. See the <a href="#authentication-and-rights">Rights</a> section.</p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/storage"> <section class="level4" id="storage-1">
<h4>storage <a class="headerlink" href="#documentation/configuration/storage">&para;</a></h4> <h4>storage <a class="headerlink" href="#storage-1">&para;</a></h4>
<section class="level5" id="documentation/configuration/storage/type"> <section class="level5" id="type-2">
<h5>type <a class="headerlink" href="#documentation/configuration/storage/type">&para;</a></h5> <h5>type <a class="headerlink" href="#type-2">&para;</a></h5>
<p>The backend that is used to store data.</p> <p>The backend that is used to store data.</p>
<p>Available backends:</p> <p>Available backends:</p>
<p><code>multifilesystem</code> : Stores the data in the filesystem.</p> <p><code>multifilesystem</code> : Stores the data in the filesystem.</p>
<p>Default: <code>multifilesystem</code></p> <p>Default: <code>multifilesystem</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/storage/filesystem_folder"> <section class="level5" id="filesystem_folder">
<h5>filesystem_folder <a class="headerlink" href="#documentation/configuration/storage/filesystem_folder">&para;</a></h5> <h5>filesystem_folder <a class="headerlink" href="#filesystem_folder">&para;</a></h5>
<p>Folder for storing local collections, created if not present.</p> <p>Folder for storing local collections, created if not present.</p>
<p>Default: <code>/var/lib/radicale/collections</code></p> <p>Default: <code>/var/lib/radicale/collections</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/storage/max_sync_token_age"> <section class="level5" id="max_sync_token_age">
<h5>max_sync_token_age <a class="headerlink" href="#documentation/configuration/storage/max_sync_token_age">&para;</a></h5> <h5>max_sync_token_age <a class="headerlink" href="#max_sync_token_age">&para;</a></h5>
<p>Delete sync-token that are older than the specified time. (seconds)</p> <p>Delete sync-token that are older than the specified time. (seconds)</p>
<p>Default: <code>2592000</code></p> <p>Default: <code>2592000</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/storage/hook"> <section class="level5" id="hook">
<h5>hook <a class="headerlink" href="#documentation/configuration/storage/hook">&para;</a></h5> <h5>hook <a class="headerlink" href="#hook">&para;</a></h5>
<p>Command that is run after changes to storage. Take a look at the <a href="#tutorials/versioning-with-git">Versioning with Git</a> tutorial for an example.</p> <p>Command that is run after changes to storage. Take a look at the <a href="#versioning-with-git">Versioning with Git</a> tutorial for an example.</p>
<p>Default:</p> <p>Default:</p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/web"> <section class="level4" id="web">
<h4>web <a class="headerlink" href="#documentation/configuration/web">&para;</a></h4> <h4>web <a class="headerlink" href="#web">&para;</a></h4>
<section class="level5" id="documentation/configuration/web/type"> <section class="level5" id="type-3">
<h5>type <a class="headerlink" href="#documentation/configuration/web/type">&para;</a></h5> <h5>type <a class="headerlink" href="#type-3">&para;</a></h5>
<p>The backend that provides the web interface of Radicale.</p> <p>The backend that provides the web interface of Radicale.</p>
<p>Available backends:</p> <p>Available backends:</p>
<p><code>none</code> : Just shows the message "Radicale works!".</p> <p><code>none</code> : Just shows the message "Radicale works!".</p>
@ -741,29 +741,29 @@ user2:password2</code></pre>
<p>Default: <code>internal</code></p> <p>Default: <code>internal</code></p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/logging"> <section class="level4" id="logging">
<h4>logging <a class="headerlink" href="#documentation/configuration/logging">&para;</a></h4> <h4>logging <a class="headerlink" href="#logging">&para;</a></h4>
<section class="level5" id="documentation/configuration/logging/level"> <section class="level5" id="level">
<h5>level <a class="headerlink" href="#documentation/configuration/logging/level">&para;</a></h5> <h5>level <a class="headerlink" href="#level">&para;</a></h5>
<p>Set the logging level.</p> <p>Set the logging level.</p>
<p>Available levels: <strong>debug</strong>, <strong>info</strong>, <strong>warning</strong>, <strong>error</strong>, <strong>critical</strong></p> <p>Available levels: <strong>debug</strong>, <strong>info</strong>, <strong>warning</strong>, <strong>error</strong>, <strong>critical</strong></p>
<p>Default: <code>warning</code></p> <p>Default: <code>warning</code></p>
</section> </section>
<section class="level5" id="documentation/configuration/logging/mask_passwords"> <section class="level5" id="mask_passwords">
<h5>mask_passwords <a class="headerlink" href="#documentation/configuration/logging/mask_passwords">&para;</a></h5> <h5>mask_passwords <a class="headerlink" href="#mask_passwords">&para;</a></h5>
<p>Don't include passwords in logs.</p> <p>Don't include passwords in logs.</p>
<p>Default: <code>True</code></p> <p>Default: <code>True</code></p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/configuration/headers"> <section class="level4" id="headers">
<h4>headers <a class="headerlink" href="#documentation/configuration/headers">&para;</a></h4> <h4>headers <a class="headerlink" href="#headers">&para;</a></h4>
<p>In this section additional HTTP headers that are sent to clients can be specified.</p> <p>In this section additional HTTP headers that are sent to clients can be specified.</p>
<p>An example to relax the same-origin policy:</p> <p>An example to relax the same-origin policy:</p>
<div class="sourceCode" id="cb31"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb31-1"><a aria-hidden="true" href="#cb31-1" tabindex="-1"></a><span class="dt">Access-Control-Allow-Origin </span><span class="ot">=</span><span class="st"> *</span></span></code></pre></div> <div class="sourceCode" id="cb31"><pre class="sourceCode ini"><code class="sourceCode ini"><span id="cb31-1"><a aria-hidden="true" href="#cb31-1" tabindex="-1"></a><span class="dt">Access-Control-Allow-Origin </span><span class="ot">=</span><span class="st"> *</span></span></code></pre></div>
</section> </section>
</section> </section>
<section class="level3" id="documentation/supported-clients"> <section class="level3" id="supported-clients">
<h3>Supported Clients <a class="headerlink" href="#documentation/supported-clients">&para;</a></h3> <h3>Supported Clients <a class="headerlink" href="#supported-clients">&para;</a></h3>
<p>Radicale has been tested with:</p> <p>Radicale has been tested with:</p>
<ul> <ul>
<li><a href="https://android.com/">Android</a> with <a href="https://www.davx5.com/">DAVx⁵</a> (formerly DAVdroid)</li> <li><a href="https://android.com/">Android</a> with <a href="https://www.davx5.com/">DAVx⁵</a> (formerly DAVdroid)</li>
@ -773,33 +773,33 @@ user2:password2</code></pre>
</ul> </ul>
<p>Many clients do not support the creation of new calendars and address books. You can use Radicale's web interface (e.g. http://localhost:5232) to create and manage address books and calendars.</p> <p>Many clients do not support the creation of new calendars and address books. You can use Radicale's web interface (e.g. http://localhost:5232) to create and manage address books and calendars.</p>
<p>In some clients you can just enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. In others, you have to enter the URL of the collection directly (e.g. <code>http://localhost:5232/user/calendar</code>).</p> <p>In some clients you can just enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. In others, you have to enter the URL of the collection directly (e.g. <code>http://localhost:5232/user/calendar</code>).</p>
<section class="level4" id="documentation/supported-clients/davx⁵"> <section class="level4" id="davx⁵">
<h4>DAVx⁵ <a class="headerlink" href="#documentation/supported-clients/davx⁵">&para;</a></h4> <h4>DAVx⁵ <a class="headerlink" href="#davx⁵">&para;</a></h4>
<p>Enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. DAVx⁵ will show all existing calendars and address books and you can create new.</p> <p>Enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. DAVx⁵ will show all existing calendars and address books and you can create new.</p>
</section> </section>
<section class="level4" id="documentation/supported-clients/gnome-calendar-contacts-and-evolution"> <section class="level4" id="gnome-calendar-contacts-and-evolution">
<h4>GNOME Calendar, Contacts and Evolution <a class="headerlink" href="#documentation/supported-clients/gnome-calendar-contacts-and-evolution">&para;</a></h4> <h4>GNOME Calendar, Contacts and Evolution <a class="headerlink" href="#gnome-calendar-contacts-and-evolution">&para;</a></h4>
<p><strong>GNOME Calendar</strong> and <strong>Contacts</strong> do not support adding WebDAV calendars and address books directly, but you can add them in <strong>Evolution</strong>.</p> <p><strong>GNOME Calendar</strong> and <strong>Contacts</strong> do not support adding WebDAV calendars and address books directly, but you can add them in <strong>Evolution</strong>.</p>
<p>In <strong>Evolution</strong> add a new calendar and address book respectively with WebDAV. Enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. Clicking on the search button will list the existing calendars and address books.</p> <p>In <strong>Evolution</strong> add a new calendar and address book respectively with WebDAV. Enter the URL of the Radicale server (e.g. <code>http://localhost:5232</code>) and your user name. Clicking on the search button will list the existing calendars and address books.</p>
</section> </section>
<section class="level4" id="documentation/supported-clients/thunderbird"> <section class="level4" id="thunderbird">
<h4>Thunderbird <a class="headerlink" href="#documentation/supported-clients/thunderbird">&para;</a></h4> <h4>Thunderbird <a class="headerlink" href="#thunderbird">&para;</a></h4>
<section class="level5" id="documentation/supported-clients/thunderbird/cardbook"> <section class="level5" id="cardbook">
<h5>CardBook <a class="headerlink" href="#documentation/supported-clients/thunderbird/cardbook">&para;</a></h5> <h5>CardBook <a class="headerlink" href="#cardbook">&para;</a></h5>
<p>Add a new address book on the network with CardDAV. You have to enter the full URL of the collection (e.g. <code>http://localhost:5232/user/addressbook</code>) and your user name.</p> <p>Add a new address book on the network with CardDAV. You have to enter the full URL of the collection (e.g. <code>http://localhost:5232/user/addressbook</code>) and your user name.</p>
</section> </section>
<section class="level5" id="documentation/supported-clients/thunderbird/lightning"> <section class="level5" id="lightning">
<h5>Lightning <a class="headerlink" href="#documentation/supported-clients/thunderbird/lightning">&para;</a></h5> <h5>Lightning <a class="headerlink" href="#lightning">&para;</a></h5>
<p>Add a new calendar on the network with <code>CalDAV</code>. (Don't use <code>iCalendar (ICS)</code>!) You have to enter the full URL of the collection (e.g. <code>http://localhost:5232/user/calendar</code>). If you want to add calendars from different users on the same server, you can specify the user name in the URL (e.g. <code>http://user@localhost...</code>)</p> <p>Add a new calendar on the network with <code>CalDAV</code>. (Don't use <code>iCalendar (ICS)</code>!) You have to enter the full URL of the collection (e.g. <code>http://localhost:5232/user/calendar</code>). If you want to add calendars from different users on the same server, you can specify the user name in the URL (e.g. <code>http://user@localhost...</code>)</p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/supported-clients/infcloud-caldavzap-and-carddavmate"> <section class="level4" id="infcloud-caldavzap-and-carddavmate">
<h4>InfCloud, CalDavZAP and CardDavMATE <a class="headerlink" href="#documentation/supported-clients/infcloud-caldavzap-and-carddavmate">&para;</a></h4> <h4>InfCloud, CalDavZAP and CardDavMATE <a class="headerlink" href="#infcloud-caldavzap-and-carddavmate">&para;</a></h4>
<p>You can integrate InfCloud into Radicale's web interface with <a href="https://github.com/Unrud/RadicaleInfCloud">RadicaleInfCloud</a>. No additional configuration is required.</p> <p>You can integrate InfCloud into Radicale's web interface with <a href="https://github.com/Unrud/RadicaleInfCloud">RadicaleInfCloud</a>. No additional configuration is required.</p>
<p>Set the URL of the Radicale server in <code>config.js</code>. If <strong>InfCloud</strong> is not hosted on the same server and port as Radicale, the browser will deny access to the Radicale server, because of the <a href="https://en.wikipedia.org/wiki/Same-origin_policy">same-origin policy</a>. You have to add additional HTTP header in the <code>headers</code> section of Radicale's configuration. The documentation of <strong>InfCloud</strong> has more details on this.</p> <p>Set the URL of the Radicale server in <code>config.js</code>. If <strong>InfCloud</strong> is not hosted on the same server and port as Radicale, the browser will deny access to the Radicale server, because of the <a href="https://en.wikipedia.org/wiki/Same-origin_policy">same-origin policy</a>. You have to add additional HTTP header in the <code>headers</code> section of Radicale's configuration. The documentation of <strong>InfCloud</strong> has more details on this.</p>
</section> </section>
<section class="level4" id="documentation/supported-clients/command-line"> <section class="level4" id="command-line">
<h4>Command line <a class="headerlink" href="#documentation/supported-clients/command-line">&para;</a></h4> <h4>Command line <a class="headerlink" href="#command-line">&para;</a></h4>
<p>This is not the recommended way of creating and managing your calendars and address books. Use Radicale's web interface or a client with support for it (e.g. <strong>DAVx⁵</strong>).</p> <p>This is not the recommended way of creating and managing your calendars and address books. Use Radicale's web interface or a client with support for it (e.g. <strong>DAVx⁵</strong>).</p>
<p>To create a new calendar run something like:</p> <p>To create a new calendar run something like:</p>
<div class="sourceCode" id="cb32"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb32-1"><a aria-hidden="true" href="#cb32-1" tabindex="-1"></a><span class="ex">$</span> curl <span class="at">-u</span> user <span class="at">-X</span> MKCOL <span class="st">'http://localhost:5232/user/calendar'</span> <span class="at">--data</span> <span class="dt">\</span></span> <div class="sourceCode" id="cb32"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb32-1"><a aria-hidden="true" href="#cb32-1" tabindex="-1"></a><span class="ex">$</span> curl <span class="at">-u</span> user <span class="at">-X</span> MKCOL <span class="st">'http://localhost:5232/user/calendar'</span> <span class="at">--data</span> <span class="dt">\</span></span>
@ -842,8 +842,8 @@ user2:password2</code></pre>
<div class="sourceCode" id="cb34"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb34-1"><a aria-hidden="true" href="#cb34-1" tabindex="-1"></a><span class="ex">$</span> curl <span class="at">-u</span> user <span class="at">-X</span> DELETE <span class="st">'http://localhost:5232/user/calendar'</span></span></code></pre></div> <div class="sourceCode" id="cb34"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb34-1"><a aria-hidden="true" href="#cb34-1" tabindex="-1"></a><span class="ex">$</span> curl <span class="at">-u</span> user <span class="at">-X</span> DELETE <span class="st">'http://localhost:5232/user/calendar'</span></span></code></pre></div>
</section> </section>
</section> </section>
<section class="level3" id="documentation/authentication-and-rights"> <section class="level3" id="authentication-and-rights">
<h3>Authentication and Rights <a class="headerlink" href="#documentation/authentication-and-rights">&para;</a></h3> <h3>Authentication and Rights <a class="headerlink" href="#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>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 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> <p>An example rights file:</p>
@ -879,12 +879,12 @@ user2:password2</code></pre>
<li><strong>w:</strong> write address book and calendar collections</li> <li><strong>w:</strong> write address book and calendar collections</li>
</ul> </ul>
</section> </section>
<section class="level3" id="documentation/storage"> <section class="level3" id="storage-2">
<h3>Storage <a class="headerlink" href="#documentation/storage">&para;</a></h3> <h3>Storage <a class="headerlink" href="#storage-2">&para;</a></h3>
<p>This document describes the layout and format of the file system storage (<code>multifilesystem</code> backend).</p> <p>This document describes the layout and format of the file system storage (<code>multifilesystem</code> backend).</p>
<p>It's safe to access and manipulate the data by hand or with scripts. Scripts can be invoked manually, periodically (e.g. with <a href="https://manpages.debian.org/unstable/cron/cron.8.en.html">cron</a>) or after each change to the storage with the configuration option <code>hook</code> in the <code>storage</code> section (e.g. <a href="#tutorials/versioning-with-git">Versioning with Git</a>).</p> <p>It's safe to access and manipulate the data by hand or with scripts. Scripts can be invoked manually, periodically (e.g. with <a href="https://manpages.debian.org/unstable/cron/cron.8.en.html">cron</a>) or after each change to the storage with the configuration option <code>hook</code> in the <code>storage</code> section (e.g. <a href="#versioning-with-git">Versioning with Git</a>).</p>
<section class="level4" id="documentation/storage/layout"> <section class="level4" id="layout">
<h4>Layout <a class="headerlink" href="#documentation/storage/layout">&para;</a></h4> <h4>Layout <a class="headerlink" href="#layout">&para;</a></h4>
<p>The file system contains the following files and folders:</p> <p>The file system contains the following files and folders:</p>
<ul> <ul>
<li><code>.Radicale.lock</code>: The lock file for locking the storage.</li> <li><code>.Radicale.lock</code>: The lock file for locking the storage.</li>
@ -897,28 +897,28 @@ user2:password2</code></pre>
<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>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> <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>
<section class="level4" id="documentation/storage/locking"> <section class="level4" id="locking">
<h4>Locking <a class="headerlink" href="#documentation/storage/locking">&para;</a></h4> <h4>Locking <a class="headerlink" href="#locking">&para;</a></h4>
<p>When the data is accessed by hand or by an externally invoked script, the storage must be locked. The storage can be locked for exclusive or shared access. It prevents Radicale from reading or writing the file system. The storage is locked with exclusive access while the <code>hook</code> runs.</p> <p>When the data is accessed by hand or by an externally invoked script, the storage must be locked. The storage can be locked for exclusive or shared access. It prevents Radicale from reading or writing the file system. The storage is locked with exclusive access while the <code>hook</code> runs.</p>
<section class="level5" id="documentation/storage/locking/linux-shell-scripts"> <section class="level5" id="linux-shell-scripts">
<h5>Linux shell scripts <a class="headerlink" href="#documentation/storage/locking/linux-shell-scripts">&para;</a></h5> <h5>Linux shell scripts <a class="headerlink" href="#linux-shell-scripts">&para;</a></h5>
<p>Use the <a href="https://manpages.debian.org/unstable/util-linux/flock.1.en.html">flock</a> utility.</p> <p>Use the <a href="https://manpages.debian.org/unstable/util-linux/flock.1.en.html">flock</a> utility.</p>
<div class="sourceCode" id="cb36"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb36-1"><a aria-hidden="true" href="#cb36-1" tabindex="-1"></a><span class="co"># Exclusive</span></span> <div class="sourceCode" id="cb36"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb36-1"><a aria-hidden="true" href="#cb36-1" tabindex="-1"></a><span class="co"># Exclusive</span></span>
<span id="cb36-2"><a aria-hidden="true" href="#cb36-2" tabindex="-1"></a><span class="ex">$</span> flock <span class="at">--exclusive</span> /path/to/storage/.Radicale.lock COMMAND</span> <span id="cb36-2"><a aria-hidden="true" href="#cb36-2" tabindex="-1"></a><span class="ex">$</span> flock <span class="at">--exclusive</span> /path/to/storage/.Radicale.lock COMMAND</span>
<span id="cb36-3"><a aria-hidden="true" href="#cb36-3" tabindex="-1"></a><span class="co"># Shared</span></span> <span id="cb36-3"><a aria-hidden="true" href="#cb36-3" tabindex="-1"></a><span class="co"># Shared</span></span>
<span id="cb36-4"><a aria-hidden="true" href="#cb36-4" tabindex="-1"></a><span class="ex">$</span> flock <span class="at">--shared</span> /path/to/storage/.Radicale.lock COMMAND</span></code></pre></div> <span id="cb36-4"><a aria-hidden="true" href="#cb36-4" tabindex="-1"></a><span class="ex">$</span> flock <span class="at">--shared</span> /path/to/storage/.Radicale.lock COMMAND</span></code></pre></div>
</section> </section>
<section class="level5" id="documentation/storage/locking/linux-and-macos"> <section class="level5" id="linux-and-macos">
<h5>Linux and MacOS <a class="headerlink" href="#documentation/storage/locking/linux-and-macos">&para;</a></h5> <h5>Linux and MacOS <a class="headerlink" href="#linux-and-macos">&para;</a></h5>
<p>Use the <a href="https://manpages.debian.org/unstable/manpages-dev/flock.2.en.html">flock</a> syscall. Python provides it in the <a href="https://docs.python.org/3/library/fcntl.html#fcntl.flock">fcntl</a> module.</p> <p>Use the <a href="https://manpages.debian.org/unstable/manpages-dev/flock.2.en.html">flock</a> syscall. Python provides it in the <a href="https://docs.python.org/3/library/fcntl.html#fcntl.flock">fcntl</a> module.</p>
</section> </section>
<section class="level5" id="documentation/storage/locking/windows"> <section class="level5" id="windows-1">
<h5>Windows <a class="headerlink" href="#documentation/storage/locking/windows">&para;</a></h5> <h5>Windows <a class="headerlink" href="#windows-1">&para;</a></h5>
<p>Use <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365202%28v=vs.85%29.aspx">LockFile</a> for exclusive access or <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365203%28v=vs.85%29.aspx">LockFileEx</a> which also supports shared access. Setting <code>nNumberOfBytesToLockLow</code> to <code>1</code> and <code>nNumberOfBytesToLockHigh</code> to <code>0</code> works.</p> <p>Use <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365202%28v=vs.85%29.aspx">LockFile</a> for exclusive access or <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365203%28v=vs.85%29.aspx">LockFileEx</a> which also supports shared access. Setting <code>nNumberOfBytesToLockLow</code> to <code>1</code> and <code>nNumberOfBytesToLockHigh</code> to <code>0</code> works.</p>
</section> </section>
</section> </section>
<section class="level4" id="documentation/storage/manually-creating-collections"> <section class="level4" id="manually-creating-collections">
<h4>Manually creating collections <a class="headerlink" href="#documentation/storage/manually-creating-collections">&para;</a></h4> <h4>Manually creating collections <a class="headerlink" href="#manually-creating-collections">&para;</a></h4>
<p>To create a new collection, you have to create the corresponding folder in the file system storage (e.g. <code>collection-root/user/calendar</code>). To tell Radicale and clients that the collection is a calendar, you have to create the file <code>.Radicale.props</code> with the following content in the folder:</p> <p>To create a new collection, you have to create the corresponding folder in the file system storage (e.g. <code>collection-root/user/calendar</code>). To tell Radicale and clients that the collection is a calendar, you have to create the file <code>.Radicale.props</code> with the following content in the folder:</p>
<div class="sourceCode" id="cb37"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb37-1"><a aria-hidden="true" href="#cb37-1" tabindex="-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> <div class="sourceCode" id="cb37"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb37-1"><a aria-hidden="true" href="#cb37-1" tabindex="-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> <p>The calendar is now available at the URL path <code>/user/calendar</code>. For address books the file must contain:</p>
@ -927,15 +927,15 @@ user2:password2</code></pre>
<p>Delete collections by deleting the corresponding folders.</p> <p>Delete collections by deleting the corresponding folders.</p>
</section> </section>
</section> </section>
<section class="level3" id="documentation/logging"> <section class="level3" id="logging-1">
<h3>Logging <a class="headerlink" href="#documentation/logging">&para;</a></h3> <h3>Logging <a class="headerlink" href="#logging-1">&para;</a></h3>
<p>Radicale logs to <code>stderr</code>. The verbosity of the log output can be controlled with <code>--debug</code> command line argument or the <code>level</code> configuration option in the <code>logging</code> section.</p> <p>Radicale logs to <code>stderr</code>. The verbosity of the log output can be controlled with <code>--debug</code> command line argument or the <code>level</code> configuration option in the <code>logging</code> section.</p>
</section> </section>
<section class="level3" id="documentation/architecture"> <section class="level3" id="architecture">
<h3>Architecture <a class="headerlink" href="#documentation/architecture">&para;</a></h3> <h3>Architecture <a class="headerlink" href="#architecture">&para;</a></h3>
<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> <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"> <section class="level4" id="protocol-overview">
<h4>Protocol overview <a class="headerlink" href="#documentation/architecture/protocol-overview">&para;</a></h4> <h4>Protocol overview <a class="headerlink" href="#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> <p>Here is a simple overview of the global architecture for reaching a calendar or an address book through network:</p>
<div class="tableContainer"><table> <div class="tableContainer"><table>
<thead> <thead>
@ -981,8 +981,8 @@ user2:password2</code></pre>
<p>Radicale is <strong>not the client part</strong> of this architecture. It means that Radicale never draws calendars, address books, events and contacts on the screen. It only stores them and give the possibility to share them online with other people.</p> <p>Radicale is <strong>not the client part</strong> of this architecture. It means that Radicale never draws calendars, address books, events and contacts on the screen. It only stores them and give the possibility to share them online with other people.</p>
<p>If you want to see or edit your events and your contacts, you have to use another software called a client, that can be a "normal" applications with icons and buttons, a terminal or another web application.</p> <p>If you want to see or edit your events and your contacts, you have to use another software called a client, that can be a "normal" applications with icons and buttons, a terminal or another web application.</p>
</section> </section>
<section class="level4" id="documentation/architecture/code-architecture"> <section class="level4" id="code-architecture">
<h4>Code Architecture <a class="headerlink" href="#documentation/architecture/code-architecture">&para;</a></h4> <h4>Code Architecture <a class="headerlink" href="#code-architecture">&para;</a></h4>
<p>The <code>radicale</code> package offers the following modules.</p> <p>The <code>radicale</code> package offers the following modules.</p>
<p><code>__init__</code> : Contains the entry point for WSGI.</p> <p><code>__init__</code> : Contains the entry point for WSGI.</p>
<p><code>__main__</code> : Provides the entry point for the <code>radicale</code> executable and includes the command line parser. It loads configuration files from the default (or specified) paths and starts the internal server.</p> <p><code>__main__</code> : Provides the entry point for the <code>radicale</code> executable and includes the command line parser. It loads configuration files from the default (or specified) paths and starts the internal server.</p>
@ -1001,11 +1001,11 @@ user2:password2</code></pre>
<p><code>xmlutils</code> : Helper functions for working with the XML part of CalDAV/CardDAV requests and responses. It's based on the ElementTree XML API.</p> <p><code>xmlutils</code> : Helper functions for working with the XML part of CalDAV/CardDAV requests and responses. It's based on the ElementTree XML API.</p>
</section> </section>
</section> </section>
<section class="level3" id="documentation/plugins"> <section class="level3" id="plugins">
<h3>Plugins <a class="headerlink" href="#documentation/plugins">&para;</a></h3> <h3>Plugins <a class="headerlink" href="#plugins">&para;</a></h3>
<p>Radicale can be extended by plugins for authentication, rights management and storage. Plugins are <strong>python</strong> modules.</p> <p>Radicale can be extended by plugins for authentication, rights management and storage. Plugins are <strong>python</strong> modules.</p>
<section class="level4" id="documentation/plugins/getting-started"> <section class="level4" id="getting-started-1">
<h4>Getting started <a class="headerlink" href="#documentation/plugins/getting-started">&para;</a></h4> <h4>Getting started <a class="headerlink" href="#getting-started-1">&para;</a></h4>
<p>To get started we walk through the creation of a simple authentication plugin, that accepts login attempts with a static password.</p> <p>To get started we walk through the creation of a simple authentication plugin, that accepts login attempts with a static password.</p>
<p>The easiest way to develop and install <strong>python</strong> modules is <a href="https://docs.python.org/3/distutils/setupscript.html">Distutils</a>. For a minimal setup create the file <code>setup.py</code> with the following content in an empty folder:</p> <p>The easiest way to develop and install <strong>python</strong> modules is <a href="https://docs.python.org/3/distutils/setupscript.html">Distutils</a>. For a minimal setup create the file <code>setup.py</code> with the following content in an empty folder:</p>
<div class="sourceCode" id="cb39"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb39-1"><a aria-hidden="true" href="#cb39-1" tabindex="-1"></a><span class="co">#!/usr/bin/env python3</span></span> <div class="sourceCode" id="cb39"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb39-1"><a aria-hidden="true" href="#cb39-1" tabindex="-1"></a><span class="co">#!/usr/bin/env python3</span></span>
@ -1045,62 +1045,62 @@ user2:password2</code></pre>
<p>You can uninstall the module with:</p> <p>You can uninstall the module with:</p>
<div class="sourceCode" id="cb43"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb43-1"><a aria-hidden="true" href="#cb43-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> pip uninstall radicale_static_password_auth</span></code></pre></div> <div class="sourceCode" id="cb43"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb43-1"><a aria-hidden="true" href="#cb43-1" tabindex="-1"></a><span class="ex">python3</span> <span class="at">-m</span> pip uninstall radicale_static_password_auth</span></code></pre></div>
</section> </section>
<section class="level4" id="documentation/plugins/authentication-plugins"> <section class="level4" id="authentication-plugins">
<h4>Authentication plugins <a class="headerlink" href="#documentation/plugins/authentication-plugins">&para;</a></h4> <h4>Authentication plugins <a class="headerlink" href="#authentication-plugins">&para;</a></h4>
<p>This plugin type is used to check login credentials. The module must contain a class <code>Auth</code> that extends <code>radicale.auth.BaseAuth</code>. Take a look at the file <code>radicale/auth/__init__.py</code> in Radicale's source code for more information.</p> <p>This plugin type is used to check login credentials. The module must contain a class <code>Auth</code> that extends <code>radicale.auth.BaseAuth</code>. Take a look at the file <code>radicale/auth/__init__.py</code> in Radicale's source code for more information.</p>
</section> </section>
<section class="level4" id="documentation/plugins/rights-management-plugins"> <section class="level4" id="rights-management-plugins">
<h4>Rights management plugins <a class="headerlink" href="#documentation/plugins/rights-management-plugins">&para;</a></h4> <h4>Rights management plugins <a class="headerlink" href="#rights-management-plugins">&para;</a></h4>
<p>This plugin type is used to check if a user has access to a path. The module must contain a class <code>Rights</code> that extends <code>radicale.rights.BaseRights</code>. Take a look at the file <code>radicale/rights/__init__.py</code> in Radicale's source code for more information.</p> <p>This plugin type is used to check if a user has access to a path. The module must contain a class <code>Rights</code> that extends <code>radicale.rights.BaseRights</code>. Take a look at the file <code>radicale/rights/__init__.py</code> in Radicale's source code for more information.</p>
</section> </section>
<section class="level4" id="documentation/plugins/web-plugins"> <section class="level4" id="web-plugins">
<h4>Web plugins <a class="headerlink" href="#documentation/plugins/web-plugins">&para;</a></h4> <h4>Web plugins <a class="headerlink" href="#web-plugins">&para;</a></h4>
<p>This plugin type is used to provide the web interface for Radicale. The module must contain a class <code>Web</code> that extends <code>radicale.web.BaseWeb</code>. Take a look at the file <code>radicale/web/__init__.py</code> in Radicale's source code for more information.</p> <p>This plugin type is used to provide the web interface for Radicale. The module must contain a class <code>Web</code> that extends <code>radicale.web.BaseWeb</code>. Take a look at the file <code>radicale/web/__init__.py</code> in Radicale's source code for more information.</p>
</section> </section>
<section class="level4" id="documentation/plugins/storage-plugins"> <section class="level4" id="storage-plugins">
<h4>Storage plugins <a class="headerlink" href="#documentation/plugins/storage-plugins">&para;</a></h4> <h4>Storage plugins <a class="headerlink" href="#storage-plugins">&para;</a></h4>
<p>This plugin is used to store collections and items. The module must contain a class <code>Storage</code> that extends <code>radicale.storage.BaseStorage</code>. Take a look at the file <code>radicale/storage/__init__.py</code> in Radicale's source code for more information.</p> <p>This plugin is used to store collections and items. The module must contain a class <code>Storage</code> that extends <code>radicale.storage.BaseStorage</code>. Take a look at the file <code>radicale/storage/__init__.py</code> in Radicale's source code for more information.</p>
</section> </section>
</section> </section>
</section> </section>
<section class="level2" id="contribute"> <section class="level2" id="contribute">
<h2>Contribute <a class="headerlink" href="#contribute">&para;</a></h2> <h2>Contribute <a class="headerlink" href="#contribute">&para;</a></h2>
<section class="level4" id="contribute//chat-with-us-on-irc"> <section class="level4" id="chat-with-us-on-irc">
<h4>Chat with Us on IRC <a class="headerlink" href="#contribute//chat-with-us-on-irc">&para;</a></h4> <h4>Chat with Us on IRC <a class="headerlink" href="#chat-with-us-on-irc">&para;</a></h4>
<p>Want to say something? Join our IRC room: <code>##kozea</code> on Freenode.</p> <p>Want to say something? Join our IRC room: <code>##kozea</code> on Freenode.</p>
</section> </section>
<section class="level4" id="contribute//report-bugs"> <section class="level4" id="report-bugs">
<h4>Report Bugs <a class="headerlink" href="#contribute//report-bugs">&para;</a></h4> <h4>Report Bugs <a class="headerlink" href="#report-bugs">&para;</a></h4>
<p>Found a bug? Want a new feature? Report a new issue on the <a href="https://github.com/Kozea/Radicale/issues">Radicale bug-tracker</a>.</p> <p>Found a bug? Want a new feature? Report a new issue on the <a href="https://github.com/Kozea/Radicale/issues">Radicale bug-tracker</a>.</p>
</section> </section>
<section class="level4" id="contribute//hack"> <section class="level4" id="hack">
<h4>Hack <a class="headerlink" href="#contribute//hack">&para;</a></h4> <h4>Hack <a class="headerlink" href="#hack">&para;</a></h4>
<p>Interested in hacking? Feel free to clone the <a href="https://github.com/Kozea/Radicale">git repository on GitHub</a> if you want to add new features, fix bugs or update the documentation.</p> <p>Interested in hacking? Feel free to clone the <a href="https://github.com/Kozea/Radicale">git repository on GitHub</a> if you want to add new features, fix bugs or update the documentation.</p>
</section> </section>
<section class="level4" id="contribute//documentation"> <section class="level4" id="documentation-2">
<h4>Documentation <a class="headerlink" href="#contribute//documentation">&para;</a></h4> <h4>Documentation <a class="headerlink" href="#documentation-2">&para;</a></h4>
<p>To change or complement the documentation create a pull request to <a href="https://github.com/Kozea/Radicale/blob/3.0.x/DOCUMENTATION.md">DOCUMENTATION.md</a>.</p> <p>To change or complement the documentation create a pull request to <a href="https://github.com/Kozea/Radicale/blob/3.0.x/DOCUMENTATION.md">DOCUMENTATION.md</a>.</p>
</section> </section>
</section> </section>
<section class="level2" id="download"> <section class="level2" id="download">
<h2>Download <a class="headerlink" href="#download">&para;</a></h2> <h2>Download <a class="headerlink" href="#download">&para;</a></h2>
<section class="level4" id="download//pypi"> <section class="level4" id="pypi">
<h4>PyPI <a class="headerlink" href="#download//pypi">&para;</a></h4> <h4>PyPI <a class="headerlink" href="#pypi">&para;</a></h4>
<p>Radicale is <a href="https://pypi.python.org/pypi/Radicale/">available on PyPI</a>. To install, just type as superuser:</p> <p>Radicale is <a href="https://pypi.python.org/pypi/Radicale/">available on PyPI</a>. To install, just type as superuser:</p>
<pre><code>$ python3 -m pip install --upgrade radicale</code></pre> <pre><code>$ python3 -m pip install --upgrade radicale</code></pre>
</section> </section>
<section class="level4" id="download//git-repository"> <section class="level4" id="git-repository">
<h4>Git Repository <a class="headerlink" href="#download//git-repository">&para;</a></h4> <h4>Git Repository <a class="headerlink" href="#git-repository">&para;</a></h4>
<p>If you want the development version of Radicale, take a look at the <a href="https://github.com/Kozea/Radicale/">git repository on GitHub</a>, or install it directly with:</p> <p>If you want the development version of Radicale, take a look at the <a href="https://github.com/Kozea/Radicale/">git repository on GitHub</a>, or install it directly with:</p>
<pre><code>$ python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz</code></pre> <pre><code>$ python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz</code></pre>
<p>You can also download the content of the repository as an <a href="https://github.com/Kozea/Radicale/tarball/master">archive</a>.</p> <p>You can also download the content of the repository as an <a href="https://github.com/Kozea/Radicale/tarball/master">archive</a>.</p>
</section> </section>
<section class="level4" id="download//source-packages"> <section class="level4" id="source-packages">
<h4>Source Packages <a class="headerlink" href="#download//source-packages">&para;</a></h4> <h4>Source Packages <a class="headerlink" href="#source-packages">&para;</a></h4>
<p>You can find the source packages of all releases on <a href="https://github.com/Kozea/Radicale/releases">GitHub</a>.</p> <p>You can find the source packages of all releases on <a href="https://github.com/Kozea/Radicale/releases">GitHub</a>.</p>
</section> </section>
<section class="level4" id="download//linux-distribution-packages"> <section class="level4" id="linux-distribution-packages">
<h4>Linux Distribution Packages <a class="headerlink" href="#download//linux-distribution-packages">&para;</a></h4> <h4>Linux Distribution Packages <a class="headerlink" href="#linux-distribution-packages">&para;</a></h4>
<p>Radicale has been packaged for:</p> <p>Radicale has been packaged for:</p>
<ul> <ul>
<li><a href="https://www.archlinux.org/packages/community/any/radicale/">ArchLinux</a> by David Runge</li> <li><a href="https://www.archlinux.org/packages/community/any/radicale/">ArchLinux</a> by David Runge</li>
@ -1121,42 +1121,42 @@ user2:password2</code></pre>
</section> </section>
<section class="level2" id="about"> <section class="level2" id="about">
<h2>About <a class="headerlink" href="#about">&para;</a></h2> <h2>About <a class="headerlink" href="#about">&para;</a></h2>
<section class="level4" id="about//main-goals"> <section class="level4" id="main-goals">
<h4>Main Goals <a class="headerlink" href="#about//main-goals">&para;</a></h4> <h4>Main Goals <a class="headerlink" href="#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>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>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 preconfigured 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> <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>
<section class="level4" id="about//what-radicale-will-never-be"> <section class="level4" id="what-radicale-will-never-be">
<h4>What Radicale Will Never Be <a class="headerlink" href="#about//what-radicale-will-never-be">&para;</a></h4> <h4>What Radicale Will Never Be <a class="headerlink" href="#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.</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 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>
<section class="level4" id="about//technical-choices"> <section class="level4" id="technical-choices">
<h4>Technical Choices <a class="headerlink" href="#about//technical-choices">&para;</a></h4> <h4>Technical Choices <a class="headerlink" href="#technical-choices">&para;</a></h4>
<p>Important global development choices have been decided before writing code. They are very useful to understand why the Radicale Project is different from other CalDAV and CardDAV servers, and why features are included or not in the code.</p> <p>Important global development choices have been decided before writing code. They are very useful to understand why the Radicale Project is different from other CalDAV and CardDAV servers, and why features are included or not in the code.</p>
<section class="level5" id="about//technical-choices/oriented-to-calendar-and-contact-user-agents"> <section class="level5" id="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> <h5>Oriented to Calendar and Contact User Agents <a class="headerlink" href="#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>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 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>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> <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>
<section class="level5" id="about//technical-choices/simple"> <section class="level5" id="simple">
<h5>Simple <a class="headerlink" href="#about//technical-choices/simple">&para;</a></h5> <h5>Simple <a class="headerlink" href="#simple">&para;</a></h5>
<p>Radicale is designed to be simple to install, simple to configure, simple to use.</p> <p>Radicale is designed to be simple to install, simple to configure, simple to use.</p>
<p>The installation is very easy, particularly with Linux: one dependency, no superuser rights needed, no configuration required, no database. Installing and launching the main script out-of-the-box, as a normal user, are often the only steps to have a simple remote calendar and contact access.</p> <p>The installation is very easy, particularly with Linux: one dependency, no superuser rights needed, no configuration required, no database. Installing and launching the main script out-of-the-box, as a normal user, are often the only steps to have a simple remote calendar and contact access.</p>
<p>Contrary to other servers that are often complicated, require high privileges or need a strong configuration, the Radicale Server can (sometimes, if not often) be launched in a couple of minutes, if you follow the <a href="#tutorials/simple-5-minute-setup">tutorial</a>.</p> <p>Contrary to other servers that are often complicated, require high privileges or need a strong configuration, the Radicale Server can (sometimes, if not often) be launched in a couple of minutes, if you follow the <a href="#simple-5-minute-setup">tutorial</a>.</p>
</section> </section>
<section class="level5" id="about//technical-choices/lazy"> <section class="level5" id="lazy">
<h5>Lazy <a class="headerlink" href="#about//technical-choices/lazy">&para;</a></h5> <h5>Lazy <a class="headerlink" href="#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 behaviors 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> <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>
</section> </section>
<section class="level4 last" id="about//history"> <section class="level4 last" id="history">
<h4>History <a class="headerlink" href="#about//history">&para;</a></h4> <h4>History <a class="headerlink" href="#history">&para;</a></h4>
<p>Radicale has been started as a (free topic) stupid school project replacing another (assigned topic) even more stupid school project.</p> <p>Radicale has been started as a (free topic) stupid school project replacing another (assigned topic) even more stupid school project.</p>
<p>At the beginning, it was just a proof-of-concept. The main goal was to write a small, dirty and simple CalDAV server working with Lightning, using no external libraries. That's how we created a piece of code that's (quite) easy to understand, to use and to hack.</p> <p>At the beginning, it was just a proof-of-concept. The main goal was to write a small, dirty and simple CalDAV server working with Lightning, using no external libraries. That's how we created a piece of code that's (quite) easy to understand, to use and to hack.</p>
<p>The <a href="https://github.com/Kozea/Radicale/commit/b1591aea">first lines</a> have been added to the SVN (!) repository as I was drinking (many) beers at the very end of 2008 (Python 2.6 and 3.0 were just released). It's now packaged for a growing number of Linux distributions.</p> <p>The <a href="https://github.com/Kozea/Radicale/commit/b1591aea">first lines</a> have been added to the SVN (!) repository as I was drinking (many) beers at the very end of 2008 (Python 2.6 and 3.0 were just released). It's now packaged for a growing number of Linux distributions.</p>