Debian Codegraph @

doc/html/imap/download/installation/manage-dav.html

raw
1 <!DOCTYPE html>
2 <html class="writer-html5" lang="en" data-content_root="../../../">
3 <head>
4 <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
5
6 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7 <title>HTTP modules &mdash; Cyrus IMAP 3.12.3 documentation</title>
8 <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
9 <link rel="stylesheet" type="text/css" href="../../../_static/css/theme.css?v=86f27845" />
10 <link rel="stylesheet" type="text/css" href="../../../_static/graphviz.css?v=eafc0fe6" />
11 <link rel="stylesheet" href="../../../_static/cyrus.css" type="text/css" />
12
13
14
15 <script src="../../../_static/jquery.js?v=8dae8fb0"></script>
16 <script src="../../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
17 <script src="../../../_static/documentation_options.js?v=2c828074"></script>
18 <script src="../../../_static/doctools.js?v=888ff710"></script>
19 <script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
20 <script src="../../../_static/js/theme.js"></script>
21 <link rel="index" title="Index" href="../../../genindex.html" />
22 <link rel="search" title="Search" href="../../../search.html" />
23 <link rel="next" title="CalDAV" href="http/caldav.html" />
24 <link rel="prev" title="Installing Cyrus" href="../../installing.html" />
25 </head>
26
27 <body class="wy-body-for-nav">
28 <div class="wy-grid-for-nav">
29 <nav data-toggle="wy-nav-shift" class="wy-nav-side">
30 <div class="wy-side-scroll">
31 <div class="wy-side-nav-search" >
32
33
34
35 <a href="../../../index.html" class="icon icon-home">
36 Cyrus IMAP
37 </a>
38 <div class="version">
39 3.12.3
40 </div>
41 <div role="search">
42 <form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
43 <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
44 <input type="hidden" name="check_keywords" value="yes" />
45 <input type="hidden" name="area" value="default" />
46 </form>
47 </div>
48 </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
49 <p class="caption" role="heading"><span class="caption-text">Cyrus IMAP</span></p>
50 <ul class="current">
51 <li class="toctree-l1"><a class="reference internal" href="../../../download.html">Download</a></li>
52 <li class="toctree-l1"><a class="reference internal" href="../../../quickstart.html">Quickstart Guide</a></li>
53 <li class="toctree-l1"><a class="reference internal" href="../../../overview.html">Overview</a></li>
54 <li class="toctree-l1 current"><a class="reference internal" href="../../../setup.html">Setup</a><ul class="current">
55 <li class="toctree-l2"><a class="reference internal" href="../../developer/compiling.html">Compiling</a></li>
56 <li class="toctree-l2 current"><a class="reference internal" href="../../installing.html">Installing Cyrus</a><ul class="current">
57 <li class="toctree-l3"><a class="reference internal" href="../../installing.html#install-cyrus">Install Cyrus</a></li>
58 <li class="toctree-l3 current"><a class="reference internal" href="../../installing.html#optional-components">Optional Components</a><ul class="current">
59 <li class="toctree-l4 current"><a class="current reference internal" href="#">HTTP modules</a></li>
60 <li class="toctree-l4"><a class="reference internal" href="virus.html">Virus Scanner</a></li>
61 </ul>
62 </li>
63 <li class="toctree-l3"><a class="reference internal" href="../../installing.html#setting-up-syslog">Setting up syslog</a></li>
64 <li class="toctree-l3"><a class="reference internal" href="../../installing.html#create-cyrus-environment">Create Cyrus environment</a></li>
65 <li class="toctree-l3"><a class="reference internal" href="../../installing.html#launch-cyrus">Launch Cyrus</a></li>
66 <li class="toctree-l3"><a class="reference internal" href="../../installing.html#send-a-test-email">Send a test email</a></li>
67 <li class="toctree-l3"><a class="reference internal" href="../../installing.html#checking-carddav-and-caldav">Checking CardDAV and CalDAV</a></li>
68 <li class="toctree-l3"><a class="reference internal" href="../../installing.html#troubleshooting">Troubleshooting</a></li>
69 </ul>
70 </li>
71 <li class="toctree-l2"><a class="reference internal" href="../upgrade.html">Upgrading to 3.12</a></li>
72 <li class="toctree-l2"><a class="reference internal" href="../../concepts/deployment.html">Configuration Guide</a></li>
73 </ul>
74 </li>
75 <li class="toctree-l1"><a class="reference internal" href="../../../operations.html">Operations</a></li>
76 <li class="toctree-l1"><a class="reference internal" href="../../../developers.html">Developers</a></li>
77 <li class="toctree-l1"><a class="reference internal" href="../../../support.html">Support/Community</a></li>
78 </ul>
79 <p class="caption" role="heading"><span class="caption-text">Cyrus SASL</span></p>
80 <ul>
81 <li class="toctree-l1"><a class="reference external" href="http://www.cyrusimap.org/sasl">Cyrus SASL</a></li>
82 </ul>
83
84 </div>
85 </div>
86 </nav>
87
88 <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
89 <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
90 <a href="../../../index.html">Cyrus IMAP</a>
91 </nav>
92
93 <div class="wy-nav-content">
94 <div class="rst-content">
95 <div role="navigation" aria-label="Page navigation">
96 <ul class="wy-breadcrumbs">
97 <li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
98 <li class="breadcrumb-item"><a href="../../../setup.html">Setup</a></li>
99 <li class="breadcrumb-item"><a href="../../installing.html">Installing Cyrus</a></li>
100 <li class="breadcrumb-item active">HTTP modules</li>
101 <li class="wy-breadcrumbs-aside">
102 <a href="https://github.com/cyrusimap/cyrus-imapd/blob/master/docsrc/imap/download/installation/manage-dav.rst" class="fa fa-github"> Edit on GitHub</a>
103 </li>
104 </ul>
105 <hr/>
106 </div>
107 <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
108 <div itemprop="articleBody">
109
110 <section id="http-modules">
111 <span id="manage-dav"></span><h1>HTTP modules<a class="headerlink" href="#http-modules" title="Link to this heading"></a></h1>
112 <section id="about-http-module-support">
113 <h2>About http module support<a class="headerlink" href="#about-http-module-support" title="Link to this heading"></a></h2>
114 <p>This assumes you already have the relevant modules enabled in your Cyrus
115 <a class="reference internal" href="../../../setup.html#setup"><span class="std std-ref">installation</span></a>, either via packages, or through a
116 manual installation.</p>
117 <p>CalDAV, CardDAV and WebDAV all provide their functionality through an http
118 server. Cyrus HTTP is NOT a general purpose HTTP server (such as Apache httpd).
119 Its feature set is limited to:</p>
120 <ul class="simple">
121 <li><dl class="simple">
122 <dt>Calendaring (CalDAV)</dt><dd><ul>
123 <li><p>Acts as a calendar and scheduling server by using IMAP mailboxes as calendar
124 collections and <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a> messages to store iCalendar data.</p></li>
125 <li><p>Allows non-CalDAV/remote calendar clients to query freebusy information of
126 Cyrus CalDAV users via freebusy URLs.</p></li>
127 <li><p>Allows scheduling transactions between separate calendaring and
128 scheduling systems via the iSchedule protocol (currently only
129 used within a Cyrus Murder).</p></li>
130 <li><p>Acts as a Time Zone Distribution Service by serving iCalendar
131 (VTIMEZONE) data to client systems.</p></li>
132 </ul>
133 </dd>
134 </dl>
135 </li>
136 <li><dl class="simple">
137 <dt>Contacts (CardDAV)</dt><dd><ul>
138 <li><p>Acts as a contacts server by using IMAP mailboxes as addressbook
139 collections and <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a> messages to store vCard data.</p></li>
140 </ul>
141 </dd>
142 </dl>
143 </li>
144 <li><dl class="simple">
145 <dt>File Storage (WebDAV)</dt><dd><ul>
146 <li><p>Acts as a remote storage server server by using IMAP mailboxes as
147 collections and <span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a> message to store files.</p></li>
148 </ul>
149 </dd>
150 </dl>
151 </li>
152 <li><dl class="simple">
153 <dt>JMAP support</dt><dd><ul>
154 <li><p>Allows synchronization of mail clients via the JSON Mail Access Protocol (JMAP).</p></li>
155 </ul>
156 </dd>
157 </dl>
158 </li>
159 <li><dl class="simple">
160 <dt>Other (RSS, static content)</dt><dd><ul>
161 <li><p>Serves static content (such as the RSS feed list template and the
162 CalDAV/CardDAV web GUIs).</p></li>
163 <li><p>Serves IMAP mailboxes as RSS feeds.</p></li>
164 </ul>
165 </dd>
166 </dl>
167 </li>
168 </ul>
169 </section>
170 <section id="httpd-configuration">
171 <h2>HTTPD Configuration<a class="headerlink" href="#httpd-configuration" title="Link to this heading"></a></h2>
172 <section id="general-configuration">
173 <h3>General configuration<a class="headerlink" href="#general-configuration" title="Link to this heading"></a></h3>
174 <p>The Cyrus httpd service is configured using options in <a class="reference internal" href="../../reference/manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a>.</p>
175 <aside class="sidebar">
176 <p class="sidebar-title">httpmodules</p>
177 <blockquote>
178 <div><p><code class="docutils literal notranslate"><span class="pre">httpmodules:</span></code> &lt;empty string&gt;</p>
179 <blockquote>
180 <div><p>Space-separated list of HTTP modules that will be enabled in
181 httpd(8). This option has no effect on modules that are disabled
182 at compile time due to missing dependencies (e.g. libical).</p>
183 <p>Note that &quot;domainkey&quot; depends on &quot;ischedule&quot; being enabled, and
184 that both &quot;freebusy&quot; and &quot;ischedule&quot; depend on &quot;caldav&quot; being
185 enabled.
186 Allowed values: <em>admin</em>, <em>caldav</em>, <em>carddav</em>, <em>cgi</em>, <em>domainkey</em>, <em>freebusy</em>, <em>ischedule</em>, <em>jmap</em>, <em>prometheus</em>, <em>rss</em>, <em>tzdist</em>, <em>webdav</em></p>
187 </div></blockquote>
188 </div></blockquote>
189 </aside>
190 <p>The support for RSS, CalDAV, and CardDAV is divided into separate modules which
191 run as part of the Cyrus httpd service. Selection of which module(s) are enabled
192 is done by setting the <code class="docutils literal notranslate"><span class="pre">httpmodules</span></code> option. <strong>By default, no modules
193 are enabled.</strong></p>
194 <p>Cyrus httpd also can serve static content, the location of which is set by the
195 <code class="docutils literal notranslate"><span class="pre">httpdocroot</span></code> option. Any content contained in the specified directory (including
196 sub-directories) will be served as static content only. Cyrus httpd does NOT
197 have the ability to execute any server-side scripts.</p>
198 </section>
199 <section id="authentication">
200 <h3>Authentication<a class="headerlink" href="#authentication" title="Link to this heading"></a></h3>
201 <p>As with other Cyrus services, the Cyrus httpd service uses
202 <a class="reference external" href="https://www.cyrusimap.org/sasl/index.html#sasl-index" title="(in Cyrus SASL v2.1.28)"><span class="xref std std-ref">Cyrus SASL</span></a> to perform its authentication.</p>
203 <aside class="sidebar">
204 <p class="sidebar-title">allowplaintext</p>
205 <blockquote>
206 <div><p><em>This shows the default value: change it in imapd.conf to suit your needs.</em></p>
207 </div></blockquote>
208 <blockquote>
209 <div><p><code class="docutils literal notranslate"><span class="pre">allowplaintext:</span></code> 0</p>
210 <blockquote>
211 <div><p>If enabled, allows the use of cleartext passwords on the wire.</p>
212 <p>By default, the use of cleartext passwords requires a TLS/SSL
213 encryption layer to be negotiated prior to any cleartext
214 authentication mechanisms being advertised or allowed. To require a
215 TLS/SSL encryption layer to be negotiated prior to ANY
216 authentication, see the <em>tls_required</em> option.</p>
217 </div></blockquote>
218 </div></blockquote>
219 </aside>
220 <p>Similar to plaintext login commands supported by the other Cyrus services (IMAP
221 LOGIN, POP3 USER/PASS), the Cyrus httpd service determines whether to advertise
222 the HTTP Basic authentication scheme based on the <code class="docutils literal notranslate"><span class="pre">allowplaintext</span></code> option and
223 whether the client has connected over a TLS protected connection (HTTPS). BASIC
224 authentication does not depend on a Cyrus SASL plugin.</p>
225 <p>The advertisement of the other HTTP authentication schemes is controlled by the
226 <a class="reference external" href="https://www.cyrusimap.org/sasl/sasl/options.html#options" title="(in Cyrus SASL v2.1.28)"><span class="xref std std-ref">SASL mech_list option</span></a> option. For Cyrus httpd
227 the GSS-SPNEGO, SCRAM-SHA-1, and SCRAM-SHA-256 values enable
228 support for the Negotiate (Kerberos only), SCRAM-SHA-1, and
229 SCRAM-SHA-256 authentication schemes respectively, provided that the plugins
230 are installed on the server.</p>
231 </section>
232 </section>
233 <section id="module-specific-information">
234 <h2>Module-specific information<a class="headerlink" href="#module-specific-information" title="Link to this heading"></a></h2>
235 <div class="toctree-wrapper compound">
236 <ul>
237 <li class="toctree-l1"><a class="reference internal" href="http/caldav.html">CalDAV</a><ul>
238 <li class="toctree-l2"><a class="reference internal" href="http/caldav.html#configuration">Configuration</a></li>
239 <li class="toctree-l2"><a class="reference internal" href="http/caldav.html#administration">Administration</a></li>
240 <li class="toctree-l2"><a class="reference internal" href="http/caldav.html#freebusy-url">Freebusy URL</a></li>
241 <li class="toctree-l2"><a class="reference internal" href="http/caldav.html#time-zone-distribution-service-tzdist">Time Zone Distribution Service (TZDist)</a></li>
242 <li class="toctree-l2"><a class="reference internal" href="http/caldav.html#ischedule">iSchedule</a></li>
243 </ul>
244 </li>
245 <li class="toctree-l1"><a class="reference internal" href="http/carddav.html">CardDAV</a><ul>
246 <li class="toctree-l2"><a class="reference internal" href="http/carddav.html#configuration">Configuration</a></li>
247 <li class="toctree-l2"><a class="reference internal" href="http/carddav.html#administration">Administration</a></li>
248 </ul>
249 </li>
250 <li class="toctree-l1"><a class="reference internal" href="http/webdav.html">WebDAV</a><ul>
251 <li class="toctree-l2"><a class="reference internal" href="http/webdav.html#configuration">Configuration</a></li>
252 <li class="toctree-l2"><a class="reference internal" href="http/webdav.html#administration">Administration</a></li>
253 </ul>
254 </li>
255 <li class="toctree-l1"><a class="reference internal" href="http/jmap.html">JMAP</a><ul>
256 <li class="toctree-l2"><a class="reference internal" href="http/jmap.html#about-jmap">About JMAP</a></li>
257 <li class="toctree-l2"><a class="reference internal" href="http/jmap.html#configuration">Configuration</a></li>
258 <li class="toctree-l2"><a class="reference internal" href="http/jmap.html#jmap-clients">JMAP clients</a></li>
259 <li class="toctree-l2"><a class="reference internal" href="http/jmap.html#jmap-implementation-status">JMAP implementation status</a></li>
260 </ul>
261 </li>
262 <li class="toctree-l1"><a class="reference internal" href="http/rss.html">RSS Feeds</a><ul>
263 <li class="toctree-l2"><a class="reference internal" href="http/rss.html#about-rss-feeds">About RSS Feeds</a></li>
264 <li class="toctree-l2"><a class="reference internal" href="http/rss.html#configuration">Configuration</a></li>
265 </ul>
266 </li>
267 </ul>
268 </div>
269 </section>
270 <section id="for-end-users">
271 <h2>For end users<a class="headerlink" href="#for-end-users" title="Link to this heading"></a></h2>
272 <p>Some information must be passed on to your end users so that they know how to
273 configure their clients in order to access their data on Cyrus. The list below
274 needs to be customized to your specific hostnames.</p>
275 <ul class="simple">
276 <li><dl class="simple">
277 <dt>CalDAV</dt><dd><ul>
278 <li><p>Many clients find calendars automatically if you provide the correct server, username and password.</p></li>
279 <li><p>Otherwise, use the direct URL: <code class="docutils literal notranslate"><span class="pre">https://&lt;servername&gt;/dav/calendars/user/&lt;userid&gt;/&lt;calendar&gt;/</span></code></p></li>
280 </ul>
281 </dd>
282 </dl>
283 </li>
284 <li><dl class="simple">
285 <dt>Freebusy</dt><dd><ul>
286 <li><p><code class="docutils literal notranslate"><span class="pre">https://&lt;servername&gt;/freebusy/user/&lt;userid&gt;</span></code> - considers all CalDAV collections of the user</p></li>
287 <li><p><code class="docutils literal notranslate"><span class="pre">https://&lt;servername&gt;/freebusy/user/&lt;userid&gt;/&lt;collection-name&gt;</span></code> - considers a single CalDAV collection</p></li>
288 <li><p>Query parameters can be added to the URL per Section 4 of
289 <a class="reference external" href="http://www.calconnect.org/pubdocs/CD0903%20Freebusy%20Read%20URL.pdf">Freebusy Read URL</a>.</p></li>
290 </ul>
291 </dd>
292 </dl>
293 </li>
294 <li><dl class="simple">
295 <dt>CardDAV</dt><dd><ul>
296 <li><p>Many clients find addressbooks automatically if you provide the correct server, username and password.</p></li>
297 <li><p>Otherwise, use the direct URL:<code class="docutils literal notranslate"><span class="pre">https://&lt;servername&gt;/dav/addressbooks/&lt;userid&gt;/&lt;addressbook&gt;</span></code></p></li>
298 <li><p>The address book(s) are automatically filtered based on the username and password supplied.</p></li>
299 </ul>
300 </dd>
301 </dl>
302 </li>
303 <li><dl class="simple">
304 <dt>WebDAV</dt><dd><ul>
305 <li><p><code class="docutils literal notranslate"><span class="pre">https://&lt;servername&gt;/dav/drive/user/&lt;userid&gt;</span></code></p></li>
306 </ul>
307 </dd>
308 </dl>
309 </li>
310 <li><dl class="simple">
311 <dt>RSS</dt><dd><ul>
312 <li><p><code class="docutils literal notranslate"><span class="pre">https://&lt;servername&gt;/rss/</span></code></p></li>
313 <li><p>Serves up all mailboxes (read-only) that the authenticated user has access to.</p></li>
314 </ul>
315 </dd>
316 </dl>
317 </li>
318 </ul>
319 </section>
320 </section>
321
322
323 </div>
324 </div>
325 <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
326 <a href="../../installing.html" class="btn btn-neutral float-left" title="Installing Cyrus" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
327 <a href="http/caldav.html" class="btn btn-neutral float-right" title="CalDAV" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
328 </div>
329
330 <hr/>
331
332 <div role="contentinfo">
333 <p>&#169; Copyright 1993–2026, The Cyrus Team.</p>
334 </div>
335
336 Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
337 <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
338 provided by <a href="https://readthedocs.org">Read the Docs</a>.
339
340
341 </footer>
342 </div>
343 </div>
344 </section>
345 </div>
346 <script>
347 jQuery(function () {
348 SphinxRtdTheme.Navigation.enable(true);
349 });
350 </script>
351
352
353
354
355 </body>
356 </html>