Synchronise CalDAV and CardDAV data for khal and khard with Vdirsyncer

Some of us prefer to use console (text terminal) tools for productivity and that is just fine. In this tutorial we’ll explore how to synchronise address books and calendars via the DAV protocols for the khard address book and the khal calendar.

A note in advance: If you’re using the nice Baikal software for hosting your DAV resources then you MUST switch the authentication from “digest” to “basic” because Vdirsyncer only supports basic authentication.

Setting up Vdirsyncer

First we need to setup our synchronisation. The file ~/.config/vdirsyncer/config contains the configuration needed to access our DAV server. Please check out the documentation for further details, we will concentrate on the basics here.

[general]
# A folder where vdirsyncer can store some metadata about each pair.
status_path = "~/.local/share/vdirsyncer/status/"

# CALDAV
[pair work_calendar]
a = "work_calendar_local"
b = "work_calendar_remote"
collections = ["from a", "from b"]

# Calendars also have a color property
metadata = ["displayname", "color"]

[storage work_calendar_local]
type = "filesystem"
path = "~/some/path/work-calendar"
fileext = ".ics"

[storage work_calendar_remote]
type = "caldav"
# Digest authentication as done by default by Baikal is broken in vdirsyncer.
auth = "basic"
url = "https://your.caldav.server" # e.g. https://dav.example.com/dav.php or so
username = "YOUR_USERNAME"
password.fetch = ["command", "pass", "show", "work/caldav-server"]

# CARDDAV
[pair work_addressbook]
a = "work_addressbook_local"
b = "work_addressbook_remote"
collections = ["from a", "from b"]
metadata = ["displayname"]

[storage work_addressbook_local]
type = "filesystem"
path = "~/some/path/work-addresses"
fileext = ".vcf"

[storage work_addressbook_remote]
type = "carddav"
# Digest authentication as done by default by Baikal is broken in vdirsyncer.
auth = "basic"
url = "https://your.carddav.server" # e.g. https://dav.example.com/dav.php or so
username = "YOUR_USERNAME"
password.fetch = ["command", "pass", "show", "work/carddav-server"]

As you can see we need to define a local and remote storage pair (naming doesn’t matter because they are mapped via a = ..., b = ... and collections = [ ... ]) for CardDAV and CalDAV. If you only need one (e.g. only calendar sync via CalDAV) then simply omit the other.

The auth = "basic" setting is there because others are simply not supported and I wanted to make that explicit. The username setting gets the login needed for the DAV server and you can either write the password explicitly via password = ... or use a command via password.fetch as shown in the example.

Now we need to run vdirsyncer discover and afterwards vdirsyncer sync for the first time. Once all data has been downloaded we can continue configuring khard and khal.

Addresses (khard)

We need to configure khard as our address book application. The configuration file is located at ~/.config/khal/config and our main point of interest is the [addressbooks] section.

[addressbooks]
# A private addressbook in some folder.
[[private]]
path = ~/some/path/private-addresses
# Our synchronised default addressbook from work.
[[work]]
path = ~/some/path/work-addresses/default

Please note that you’ll likely have a subfolder in the target directory for your local CardDAV sync which contains your address book. Here we picked the name “default” which is the standard with Baikal.

Calendars (khal)

The configuration for khal is done via the file ~/.config/khal/config and we also concentrate on the most basic settings here.

[calendars]

[[MyPersonalWorkCalendar]]
path = ~/some/path/work-calendar/default

[[CompanyWideCalendar]]
path = ~/some/path/work-calendar/UUID

[[SharedCalendarOfSomeColleague]]
path = ~/some/path/work-calendar/UUID
readonly = True

[default]
default_calendar = MyPersonalWorkCalendar

You can define as many calendars as you like in double brackets underneath [calendars] but their path has to map to the correct subfolders in your local CalDAV sync directory. The default calendar is named “default” in Baikal, others you created are named but shared calendars usually have a UUID as subfolder name. So some investigation might be necessary to find out the correct one. Also a calendar can explicitly be set as read only via the readonly = True setting.

Last but not least you have to define a default calendar. Please look at the documentation for more settings like locale (date and time formats) or theming.

Keeping up to date

The most easy way to keep your data up to date is to use cron (or systemd timers) to execute the vdirsyncer sync command periodically. If you do so then you should put your passwords directly into the configuration file.

Another option is to do it manually of course. ;-)