Guides

Basic setup

The most basic setup synchronises calendar events from a remote CalDAV server to a local directory. This requires a configuration file with three sections:

• A storage section describing the details of the CalDAV server.

• A storage section describing the details of the local directory.

• A pair section describing how these two storages should be synchronise with each other.

Additionally, a status_path must be specified. This is the path to a directory where pimsync shall store a small database with the state of the events on both calendar storages. This helps resolve conflicts later: when a file changes on one storage, pimsync consults this status database to determine which side changed and which way data needs to flow to synchronise changes.

The corresponding configuration file for this example would looks something like:

# use a standard location for the status database:
status_path "~/.local/share/pimsync/status/"

storage calendars_remote {
  type caldav
  url https://caldav.example.com/
  username hugo@example.com
  password 123
}

storage calendars_local {
  type vdir/vcard
  path ~/.local/share/contacts/cards/
  fileext vcf
}

pair calendars {
  storage_a contacts_local
  storage_b contacts_fastmail
  collections all
}

The collections all directive indicates that all collections (calendars) from both sides should be synchronised. See pimsync.conf.5 for full details on the configuration file syntax and available directives.

Storing passwords in configuration files like this is considered poor security practice; one can accidentally leak them when sharing or backing up a configuration, and it’s easy for other misbehaving software to accidentally leak it. Instead, we store credentials in a secret storage service, and use some helper to retrieve credentials.

Usage with a secret storage service

In this case, I’ll be using himitsu, a secret storage manager, which I already have set up and running locally.

First I’ll store my password into the store by running hiq -a, and then providing the details for the entry, followed by ^d:

proto=caldavs username=hugo@example.com password!=123

Consult the documentation for your system’s secret storage service for specific instructions on how to persist credentials. Usually non-password fields are required in order to query the secret service and indicate which secret we want.

For the above created entry, I can use the following command to query for the password:

hiq -dFpassword proto=caldavs username=hugo@example.com

When the above command runs, the secret storage will prompt for my authorisation to disclose credentials, and then provide the password if I accept the prompt.

The storage block for the above CalDAV server now changes to:

storage calendars_remote {
  type caldav
  url https://caldav.example.com/
  username hugo@example.com
  password {
   cmd hiq -dFpassword proto=caldavs username=hugo@example.com
  }
}

Running as a deamon

The pimsync daemon command will make pimsync run continuously and keep calendars and contacts in sync. This is most suitable as a daemon that runs in the background for your user session.

It is recommended to put this daemon and other which require credentials under a non-default bundle/target/run-level, so that they don’t result in credential prompts as soon as one logs in. This target should be manually started instead.

An service script for OpenRC should look something like:

#!/sbin/openrc-run

description="Synchronise calendars and contacts"

command="/usr/bin/pimsync daemon -r 3"
ready=fd:3

supervisor=supervise-daemon
error_logger="logger -t '${RC_SVCNAME}' -p daemon.error"

An service unit for systemd should looks something like:

[Unit]
Description=Synchronise calendars and contacts
Documentation=man:pimsync

[Service]
# TODO: glue for readiness notification
ExecStart=/usr/bin/pimsync daemon
Restart=no
Slice=background.slice

[Install]
WantedBy=sync.target

Further topics

Contributions for guides for other usage scenarios are most welcome.