Skip to content
Get Stalwart

Overview

Calendar and contact applications on desktop and mobile platforms synchronise with a server through CalDAV and CardDAV, and file managers can mount remote storage through WebDAV. All three rest on WebDAV (RFC 4918), which extends HTTP with methods to manage collections of resources on a server, such as PROPFIND, MKCOL and LOCK.

Stalwart uses WebDAV for three services: file storage with WebDAV itself, calendars with CalDAV (RFC 4791) and contacts with CardDAV (RFC 6352). This page covers the protocol side. The collaboration section describes calendars, contacts and file storage from the user’s side.

URLs

Section titled “URLs”

The DAV services are served on every HTTP listener, under these paths:

PathContents
/dav/cal/<account>/The account’s calendars (CalDAV)
/dav/card/<account>/The account’s address books (CardDAV)
/dav/file/<account>/The account’s files (WebDAV)
/dav/pal/<account>/The account’s principal, which clients read to find its collections and access rights
/dav/itip/Calendar scheduling messages

In these paths, <account> identifies the account in one of two forms. The first is any of the account’s email addresses, aliases included, with @ encoded as %40 in the links that the server generates (/dav/cal/jane%40example.com/). The second is _ followed by the numeric account id. Other forms are not accepted: a bare user name such as jane, a sub-address and a catch-all address return 404. Access to another account’s collections requires that the account shared them.

Clients do not need to know these paths, because they find the collections from the server name. /.well-known/caldav and /.well-known/carddav redirect (HTTP 307) to /dav/cal and /dav/card. From there, the client reads the user’s principal and its home collections. Setting up clients lists the settings that clients need.

Specifications

Section titled “Specifications”

Besides WebDAV, CalDAV and CardDAV, the server implements a number of related specifications:

Clients learn which of these the server supports from the DAV header returned to OPTIONS requests, which lists the compliance classes: 1, 2, 3, access-control, extended-mkcol, calendar-access, calendar-auto-schedule, calendar-no-timezone, addressbook.

Properties that a client sets with PROPPATCH and that the server does not interpret are called dead properties. They are stored as object metadata, whose limits apply to them.

Settings

Section titled “Settings”

The WebDav singleton (found in the WebUI under Settings › Network › WebDAV) holds the protocol settings. Its size limits are described in Limits.

Shared collections raise a discovery problem, because many clients look only in the user’s own home collection. enableAssistedDiscovery, enabled unless changed, helps these clients. With it, a PROPFIND on the user’s calendar or address book home also lists the calendars and address books that other accounts have shared with the user, and the user’s principal names only the user’s own home collection. Without it, the principal names the home collection of every account that shared something with the user, and clients must look in each one. File storage is not affected.

WebDAV clients take locks before editing a file, and these locks are limited by maxLocks and maxLockTimeout, as described in WebDAV locks.

Disabling WebDAV

Section titled “Disabling WebDAV”

WebDAV can be restricted for some users or turned off for everyone. A user can use each service only with the corresponding permissions, so removing the CalDAV, CardDAV or WebDAV permissions from a role restricts the users that have it. To turn off the DAV services for all clients, add an access control rule that refuses paths under /dav.