Debian Codegraph @

doc/html/_sources/imap/download/installation/http/caldav.rst.txt

raw
1 .. _caldav:
2
3 ======
4 CalDAV
5 ======
6
7 Configuration
8 =============
9
10 .. sidebar:: calendarprefix
11
12 |change-default-config|
13
14 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
15 :start-after: startblob calendarprefix
16 :end-before: endblob calendarprefix
17
18 When enabled, the CalDAV module allows Cyrus to function as a calendar and
19 scheduling server. This module uses a subset of the mailbox hierarchy as
20 calendar collections, the toplevel of which is specified by the ``calendarprefix``
21 option. The public calendar hierarchy will reside at the toplevel of the shared
22 mailbox namespace. A user's personal calendar hierarchy will be a child of
23 their Inbox.
24
25 For example, using the default value for calendarprefix, a
26 calendar named Default for user "murch" would reside in the mailbox named
27 ``user.murch.#calendars.Default``.
28
29 .. warning::
30
31 Note that mailboxes in the calendar hierarchies (those under
32 calendarprefix) **should not** be accessed with an IMAP client as doing so will
33 leave a mailbox in a state unsuitable for CalDAV. To this end, calendar
34 mailboxes will not returned by Cyrus imapd in response to an IMAP client's
35 request for the available calendar list, but Cyrus imapd can not otherwise
36 prevent an IMAP client from accessing them.
37
38 .. sidebar:: caldav_allowscheduling
39
40 |change-default-config|
41
42 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
43 :start-after: startblob caldav_allowscheduling
44 :end-before: endblob caldav_allowscheduling
45
46 By default, the CalDAV module will automatically perform scheduling operations
47 when a scheduling object (invite or reply) is stored on or deleted from the
48 server. Support for the calendar-auto-schedule feature can be disabled with the
49 ``caldav_allowscheduling`` option.
50
51 Administration
52 ==============
53
54 The CalDAV module will *automatically* create the required calendars for a user
55 the first time that the user authenticates to the CalDAV server. Note that the
56 user MUST have an existing IMAP Inbox in order for the calendars to be created.
57
58 .. sidebar:: autocreate options
59
60 |change-default-config|
61
62 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
63 :start-after: startblob caldav_create_default
64 :end-before: endblob caldav_create_default
65 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
66 :start-after: startblob caldav_create_attach
67 :end-before: endblob caldav_create_attach
68 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
69 :start-after: startblob caldav_create_sched
70 :end-before: endblob caldav_create_sched
71
72 Autocreate of the various calendars can be disabled with the
73 "caldav_create_default/sched/attach" options, if you have an alternate
74 mechanism to create calendars.
75
76 There is also a Cyrus web GUI for managing calendar resources.
77 It allows you to:
78
79 * Create new collections, with whichever components are required
80 * Alter existing collections
81 * Subscribe or download existing collections via prepared URLs
82 * Set visibility attributes such as Public or Transparent
83 * Delete existing collections
84
85 To delete the value of a property, click on ✎ and then submit empty new value.
86
87 The Name, Description, Color, and Order properties are used only for UI
88 purposes. “None color” means, that no calendar color is communicated
89 to the calendar user agents. Transparent calendars are skipped by
90 server-side freebusy calculations. The Time Zone on calendars
91 is used to calculate the freebusy state on events with floating
92 times. Public toggles the `lrw9` rights for the `anyone` user.
93
94 The Cyrus web GUI for CalDAV Collection Management is disabled by
95 default, but can be enabled with the "caldav_allowcalendaradmin" option.
96
97 .. sidebar:: caldav_allowcalendaradmin
98
99 |change-default-config|
100
101 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
102 :start-after: startblob caldav_allowcalendaradmin
103 :end-before: endblob caldav_allowcalendaradmin
104
105 To access the Cyrus web GUI for CalDAV Collection Management, point
106 a web browser at ``https://<servername>/dav/calendars/user/<username>``
107
108 .. _calendar_ACL:
109
110 Calendar access controls
111 ------------------------
112
113 The CalDAV module uses the same access controls as the other Cyrus services. The
114 :cyrusman:`cyradm(8)` tool can be used to adjust ACLs on calendars as needed.
115 The tables below show how the access controls are used by the CalDAV module.
116
117 .. raw:: html
118
119 <table border>
120 <caption>Mapping of IMAP Rights to WebDAV Privileges & HTTP Methods</caption>
121 <tr>
122 <th>IMAP rights</th>
123 <th colspan=2>WebDAV privileges</th>
124 <th>HTTP methods</th>
125 </tr>
126 <tr>
127 <td>l - lookup
128 <br>r - read</td>
129 <td>DAV:read</td>
130 <td>DAV:read-current-user-privilege-set
131 <br>CALDAV:read-free-busy</td>
132 <td>GET/HEAD
133 <br>COPY/MOVE <small>(on source)</small>
134 <br>PROPFIND
135 <br>REPORT</td>
136 </tr>
137 <tr>
138 <td><s>s - seen</s></td>
139 <td colspan=2/>
140 <td/>
141 </tr>
142 <tr>
143 <td>w - write
144 <br>n - write shared annotation</td>
145 <td colspan=2>DAV:write-properties</td>
146 <td>PROPPATCH
147 <br>COPY/MOVE <small>(on destination)</small></td>
148 </tr>
149 <tr>
150 <td>i - insert</td>
151 <td colspan=2>DAV:write-content</td>
152 <td>PUT
153 <br>PATCH
154 <br>COPY/MOVE <small>(on destination resource)</small>
155 <br>LOCK
156 <br>UNLOCK <small>(lock owner ONLY)</small></td>
157 </tr>
158 <tr>
159 <td>p - post</td>
160 <td rowspan=2>DAV:bind</td>
161 <td>CYRUS:add-resource</td>
162 <td>POST</td>
163 </tr>
164 <tr>
165 <td>k - create mailbox</td>
166 <td>CYRUS:make-collection</td>
167 <td>MKCOL
168 <br>MKCALENDAR
169 <br>COPY/MOVE <small>(on destination collection)</small></td>
170 </tr>
171 <tr>
172 <td>x - delete mailbox</td>
173 <td rowspan=2>DAV:unbind</td>
174 <td>CYRUS:remove-collection</td>
175 <td>DELETE <small>(collection)</small>
176 <br>MOVE <small>(on source collection)</small></td>
177 </tr>
178 <tr>
179 <td>t - delete message
180 <br>e - expunge</td>
181 <td>CYRUS:remove-resource</td>
182 <td>DELETE <small>(resource)</small>
183 <br>MOVE <small>(on source resource)</small></td>
184 </tr>
185 <tr>
186 <td>a - admin</td>
187 <td>CYRUS:admin</td>
188 <td>DAV:read-acl
189 <br>DAV:write-acl
190 <br>DAV:share
191 <br>DAV:unlock</td>
192 <td>ACL
193 <br>PROPFIND <small>(DAV:acl property ONLY)</small>
194 <br>UNLOCK <small>(ANY lock)</small></td>
195 </tr>
196 <tr>
197 <td colspan=4><i>Regular Calendar Collections ONLY &#151;
198 read freebusy time?</i></td>
199 </tr>
200 <tr>
201 <td>9 - freebusy</td>
202 <td colspan=2>CALDAV:read-free-busy</td>
203 <td>REPORT <small>(CALDAV:free-busy-query ONLY)</small>
204 <br>GET/HEAD <small>(<a href="#freebusy-url">Freebusy URLs</a> ONLY)</small></td>
205 </tr>
206 <tr>
207 <td colspan=4><i>Scheduling Outbox ONLY &#151;
208 implicitly create/send iTIP message?</i></td>
209 </tr>
210 <tr>
211 <td>9 - freebusy</td>
212 <td rowspan=3>CALDAV:schedule-send</td>
213 <td>CALDAV:schedule-send-freebusy</td>
214 <td>POST
215 <br><small>(by organizer on scheduling Outbox)</small></td>
216 </tr>
217 <tr>
218 <td>8 - invite</td>
219 <td>CALDAV:schedule-send-invite</td>
220 <td>PUT/PATCH/DELETE
221 <br><small>(by organizer on calendar resource/collection)</small></td>
222 </tr>
223 <tr>
224 <td>7 - reply</td>
225 <td>CALDAV:schedule-send-reply</td>
226 <td>PUT/PATCH/DELETE
227 <br><small>(by attendee on calendar resource/collection)</small></td>
228 </tr>
229 <tr>
230 <td colspan=4><i>Scheduling Inbox ONLY &#151;
231 implicitly deliver/process incoming iTIP message?</i></td>
232 </tr>
233 <tr>
234 <td>9 - freebusy</td>
235 <td rowspan=3>CALDAV:schedule-deliver</td>
236 <td>CALDAV:schedule-query-freebusy</td>
237 <td rowspan=3/>
238 </tr>
239 <tr>
240 <td>8 - invite</td>
241 <td>CALDAV:schedule-deliver-invite</td>
242 </tr>
243 <tr>
244 <td>7 - reply</td>
245 <td>CALDAV:schedule-deliver-reply</td>
246 </tr>
247 </table>
248 <br>
249
250 <br>
251 <table border>
252 <caption>Default WebDAV Privileges by Collection</caption>
253 <tr>
254 <th>Collection</th>
255 <th>User ID</th>
256 <th>WebDAV Privileges</th>
257 <th>IMAP rights</th>
258 </tr>
259 <tr>
260 <td rowspan=2>Regular Calendar Collection</td>
261 <td>owner</td>
262 <td>DAV:all + CALDAV:read-free-busy</td>
263 <td align='right'>lrwipkxtan9</td>
264 </tr>
265 <tr>
266 <td>anyone</td>
267 <td>CALDAV:read-free-busy</td>
268 <td align='right'>9</td>
269 </tr>
270 <tr>
271 <td rowspan=2>Managed Attachments Collection</td>
272 <td>owner</td>
273 <td>DAV:all</td>
274 <td>lrwipkxtan</td>
275 </tr>
276 <tr>
277 <td>anyone</td>
278 <td>DAV:read</td>
279 <td>lr</td>
280 </tr>
281 <tr>
282 <td rowspan=2>Scheduling Inbox</td>
283 <td>owner</td>
284 <td>DAV:all + CALDAV:schedule-deliver</td>
285 <td>lrwipkxtan789</td>
286 </tr>
287 <tr>
288 <td>anyone</td>
289 <td>CALDAV:schedule-deliver</td>
290 <td align='right'>789</td>
291 </tr>
292 <tr>
293 <td>Scheduling Outbox</td>
294 <td>owner</td>
295 <td>DAV:all + CALDAV:schedule-send</td>
296 <td>lrwipkxtan789</td>
297 </tr>
298 </table>
299
300 |
301
302 Freebusy URL
303 ============
304
305 When enabled in conjunction with the CalDAV module, the Freebusy URL module
306 allows non-CalDAV and/or remote calendaring clients to query the freebusy
307 information of Cyrus CalDAV users.
308
309 Access to the freebusy information is controlled by the "freebusy" ACL (9) on a
310 user's home calendar collection. (e.g. a mailbox named
311 ``user.murch.#calendars``). To enable unauthenticated users (non-Cyrus) to
312 access freebusy information, the freebusy ACL must be given to "anyone".
313
314 Freebusy information, consolidating the data of all user's calendars, is
315 accessed via URLs of the following form:
316 ``https://<servername>/freebusy/user/<userid>``. Querying individual CalDAV
317 collections, when they have explicitly "freebusy" ACL (9) set, is done via
318 ``https://<servername>/freebusy/user/<userid>/<collection>``.
319
320
321 Query parameters can be added to the URL per Section 4 of
322 `Freebusy Read URL <http://www.calconnect.org/pubdocs/CD0903%20Freebusy%20Read%20URL.pdf>`_,
323 allowing the user to choose to set the start, end, period and format of
324 their query results.
325
326 Time Zone Distribution Service (TZDist)
327 =======================================
328
329 What is TZDist
330 --------------
331
332 The TZDist module allows Cyrus to function as a Time Zone Distribution
333 Service (:rfc:`7808` and :rfc:`7809`), providing time zone data for CalDAV
334 and calendaring clients, without having to wait for their client vendor and/or
335 OS vendor to update the timezone information. The responsibility for keeping
336 the time zone information up to date then falls upon the Cyrus administrator.
337
338 TZDist is optional: without Cyrus having TZDist enabled, calendar clients should
339 still be able to get their timezone information from their client or their OS.
340
341 TZDist strips known VTIMEZONEs from incoming iCalendar data (as
342 advertised by the ``calendar-no-timezone`` DAV option from :rfc:`7809`).
343
344 Configuration
345 -------------
346
347 .. sidebar:: zoneinfo config
348
349 |change-default-config|
350
351 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
352 :start-after: startblob zoneinfo_db_path
353 :end-before: endblob zoneinfo_db_path
354
355 |
356
357 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
358 :start-after: startblob zoneinfo_db
359 :end-before: endblob zoneinfo_db
360
361 |
362
363 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
364 :start-after: startblob zoneinfo_dir
365 :end-before: endblob zoneinfo_dir
366
367 The TZDist module requires the ``zoneinfo_dir`` setting in :cyrusman:`imapd.conf(5)`
368 to be set to the directory where your time zone data is stored.
369
370 The data is indexed by a database whose location is specified by the
371 ``zoneinfo_db_path`` option, using the format specified by the ``zoneinfo_db``
372 option.
373
374 Administration
375 --------------
376
377 The TZDist module is designed to use the IANA Time Zone Database data (a.k.a.
378 Olson Database) converted to the iCalendar format.
379
380 `vzic <https://github.com/libical/vzic>`_ does convert the IANA TZ DB to iCalendar
381 format. For each time zone it creates a separate file with its own TZID property.
382 The TZID property can have a vendor prefix, that is fixed when compiling vzic by the
383 ``TZID_PREFIX`` Makefile variable, which defaults to `/citadel.org/%D_1/`. Cyrus
384 IMAP requires that the vendor prefix is the empty string.
385
386 The `cyrus-timezones package <https://github.com/cyrusimap/cyrus-timezones>`_ provides
387 a vzic, which sets TZID_PREFIX to the emtpy string.
388
389 The steps to populate the ``zoneinfo_dir`` directory are:
390
391 1. Acquire and build your choice of ``vzic`` tool.
392
393 2. Download the latest version of the
394 `Time Zone Database data from IANA <http://www.iana.org/time-zones>`_. Note
395 you only need the **data**, not the code.
396
397 3. Expand the downloaded time zone data into a temporary directory of your choice.
398
399 4. Copy leap-seconds.list from the temporary directory to ``<zoneinfo_dir>``.
400
401 5. Populate ``zoneinfo_dir`` with iCalendar data:
402
403 *Initial Install Only*
404
405 a. Convert the raw data into iCalendar format by running vzic as follows:
406 ``vzic --pure --olson-dir <location-of-raw-data> --output-dir <zoneinfo_dir>``
407
408 This will create and install iCalendar data directly into the
409 ``<zoneinfo_dir>`` directory.
410
411 *Updating Data Only*
412
413 b. Convert the raw data into iCalendar format by running vzic as follows:
414 ``vzic --pure --olson-dir <location-of-raw-data>``
415
416 This will create a zoneinfo/ subdirectory in your current location
417
418 c. Merge new/updated iCalendar data into the ``<zoneinfo_dir>`` directory
419 by running vzic-merge.pl in your current location:
420 ``vzic-merge.pl``
421
422 6. Rebuild the Cyrus zoneinfo index by running :cyrusman:`ctl_zoneinfo(8)` as
423 follows:
424 ``ctl_zoneinfo -r <version-string>``
425
426 where <version-string> contains description of the recently downloaded time
427 zone data, colon, and the version of the data (e.g. "IANA Time Zone Database:2020a").
428
429 7. Check that the zoneinfo index database and all iCalendar data files/links
430 are readable by the cyrus user.
431
432 iSchedule
433 =========
434
435 About iSchedule
436 ---------------
437
438
439 .. note::
440
441 iSchedule support in Cyrus is a work in progress.
442
443 `iSchedule <https://tools.ietf.org/id/draft-desruisseaux-ischedule>`_
444 allows CalDAV servers to:
445
446 * query an event participant's free/busy status prior to invitation in order
447 to set up a good meeting time, which cannot be done over email.
448 * keep participant's local event current by updating the status of other
449 participants automatically. This is not done when scheduling over email as it
450 would result in too much mail traffic and extra manual overhead for the users.
451
452 .. sidebar:: caldav_allowscheduling
453
454 |change-default-config|
455
456 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
457 :start-after: startblob caldav_allowscheduling
458 :end-before: endblob caldav_allowscheduling
459
460 iSchedule is automatically enabled in Cyrus if both the CalDAV module and the
461 ``caldav_allowscheduling`` options are enabled in a
462 :ref:`Cyrus Murder <murder>`. In this instance, Cyrus uses iSchedule to move
463 scheduling messages from frontend to backend servers.
464
465 Support for scheduling with external servers is currently under development
466 as there is the burden of authorization to verify the authenticity and
467 integrity of these messages to prevent inadvertent or malicious data leaks
468 or corruption.
469
470 What mechanism to use for authorization is under discussion with the `CalConnect
471 <https://www.calconnect.org/>`_ standards body, whether this is `DKIM
472 <http://www.dkim.org/>`_ or some other type of message signature.