PIMSYNC.CONF(5)

📦
version 0.5.10 · 4 versions
, in alpine 3.24

🌸 NAME 🌸

pimsync.conf — the configuration file for pimsync(1). Yes bestie, this is the pimsync.conf(5) manual page, and it's giving “your sync setup's main character energy” 💅

✨ DESCRIPTION ✨

Okay so pimsync.conf is split into three main types of sections, and this is the vibe check:

  • “GLOBAL CONFIGURATION” — global settings for pimsync.
  • “STORAGE SECTIONS” — configuration for individual storages.
  • “PAIR SECTIONS” — rules for synchronising pairs of storages.

See pimsync(1) for the details on the default path for the configuration file, and how to specify an alternative path. iykyk 🫶

💖 GLOBAL CONFIGURATION 💖

These are the settings you can set globally, bestie:

  • status_path path — path to a directory which will contain the status database internally used by pimsync. Supports DYNAMIC PARAMETERS (see below). 🎀

🎀 STORAGE SECTIONS 🎀

A storage describes a location where calendars or contacts are stored. Each storage is declared in its own section, and each storage section starts with a declaration of the storage name. Iconic.

  • storage name {…} — declare a storage with name name.

Directives are declared inside the curly braces for each section, one per line. The following directives apply to all storage types:

  • type type — this directive must be the first directive in the storage block. Where type can be one of the following:
    • vdir/icalendar — a directory where each subdirectory represents a calendar. Each of these subdirectories contains individual icalendar files, each representing one event (or one series of recurring events), todo or journal entry.
    • vdir/vcard — a directory where each subdirectory represents an address book. Each of these subdirectories contains individual vcard files, each representing one contact.
    • caldav — a CalDAV server, containing calendars with events, todos and/or journal entries.
    • carddav — a CardDAV server containing address books with contacts.
    • webcal — an HTTP or HTTPS resource exposing a single iCalendar file which may contain zero or more events, todos or journal entries. This storage type is read-only.
    • jmap/icalendar — a JMAP server with Calendar support. This storage is experimental.
    • jmap/vcard — a JMAP server with Calendar support. This storage is experimental.
  • interval seconds — when monitoring a storage is not possible, check for changes every the specified amount of seconds. If set to zero, interval-based synchronisations are disabled. The default is 300 seconds. 🕒
  • auth basic | digest — authentication method to use. The default is basic and does not need to be specified.
  • read_only — do not perform any write operations on this storage. This directive takes no parameters. 🚫

Storages of type vdir take the following directives:

  • path path — path to a directory storing a vdir. A leading tilde will be expanded to match the current user's home directory. Supports DYNAMIC PARAMETERS (see below).
  • fileext extension — optional. File extension for items saved into this vdir. If not specified, ics is used for calendar storages and vcf is used for address book storages.

Storages of type caldav or carddav accept the following directives:

  • url url — URL of the Dav server. If this URL does not report the appropriate DAV capabilities, service discovery will be performed for this URL and its domain to find the exact location of the server and the home set collection.

URLs must specify scheme http, https. or unix. URLs starting in unix:// shall be treated as a path to a unix domain socket.

Supports DYNAMIC PARAMETERS (see below).

  • username username — optional. Username to use for HTTP Basic Auth. Supports DYNAMIC PARAMETERS (see below).
  • password password — optional. Password to use for HTTP Basic Auth. Supports DYNAMIC PARAMETERS (see below).
  • collection_id_segment last | second-last — optional. URL path segment to use as the collection id. Valid values are last (the default) or second-last. See the advanced usage documentation for details. 👑

Storages of type webcal take the following directives:

  • url url — URL of an icalendar file. This file may contain multiple calendar items. Scheme must be http or https. Supports DYNAMIC PARAMETERS (see below).
  • collection_id name — name to be used when mapping this collection to another on the other storage.

Storages of type jmap take the following directives:

  • url url — base URL of the JMAP server. Supports DYNAMIC PARAMETERS (see below).
  • username username — optional. Username to use for HTTP Basic Auth. Supports DYNAMIC PARAMETERS (see below).
  • password password — optional. Password to use for HTTP Basic Auth. Supports DYNAMIC PARAMETERS (see below).

Storages of type caldav, carddav, webcal and jmap also accept the following directives:

  • user_agent user_agent — optional. Set the User-Agent header to user_agent for outgoing HTTP requests. The default uses pimsync/ followed by the current version number. E.g.: pimsync/1.0.0.
  • tls_root path — optional. Use the certificate root store at path when checking the server's TLS certificate. Disables checking the certificate against the system certificate authorities. See tls_fingerprint below.
  • tls_fingerprint fingerprint — optional. Accept the certificate if its fingerprint matches fingerprint. If specified together with the tls_root directive, the certificate is verified with the specified root. If tls_root is not specified, the server's certificate is not validated against any root and only a fingerprint verification is performed. ⚠️
  • auth_cert certificate key — optional. Use the provided certificate and key for TLS client authentication.
  • auth_cert pem_bundle — optional. Use the certificate and key from the specified bundle for TLS client authentication.

🦋 DYNAMIC PARAMETERS 🦋

The url, username, password, and path fields may be defined in the configuration file, or may specify a block with a command to retrieve this value from an external system. When specifying an external command, instead of defining a value for the directive, specify a new block with a single cmd directive. No cap, it's that flexible. ✨

For example, to read a password via the external command secret-store --get-caldav-password, use the following syntax:

password {
        cmd secret-store --get-caldav-password
}

It is also possible to specify a shell script, which is executed via sh -c. For example:

password {
        shell pass show communication/migadu.com | head -1
}

It is recommended to store credentials and other sensitive values in a secret storage service. Please bestie, do not leave your secrets lying around like last season's fit. 🔐

🌈 PAIR SECTIONS 🌈

A pair declares how two storages shall be synchronised to each other. Each pair section starts with a declaration of the pair name:

  • pair name {…} — declare a pair with name name.

Each pair is defined by a block of directives, one per line, enclosed in curly braces:

  • storage_a name — the name of the first storage to be synchronised with another.
  • storage_b name — the name of the second storage to be synchronised with the other.
  • collections all — synchronise all collections found in both storages. Collections will be synchronised to others with a matching id on the other side. This is the recommended value if you simply want to synchronise all collections from both storages. 💯
  • collections from a — synchronise all collections found in storage_a. Each collection shall be synchronised with the collection which has the same collection id on storage_b.
  • collections from b — synchronise all collections found in storage_b. Each collection shall be synchronised with the collection which has the same collection id on storage_a.
  • collection id — synchronise collection with id id. May be specified more than once.
  • collection file ... {…} — synchronise collection defined by the given rules. See “COLLECTION SECTIONS” below. May be specified more than once.
  • on_empty skip — when a collection is completely emptied on one side, skip it. This is the default.
  • on_empty sync — when a collection is completely emptied on one side, empty its counterpart on the other side. Take care when using this option. If you completely delete a collection on one side, pimsync.conf won't restore it. Instead, it will delete the same collection (and all of its items) on the other side. 😭
  • on_delete sync — when a collection itself is deleted on one side, delete it on the other side. This only applies if the collection is already empty. This is the default. This is generally safe, especially when combined with on_empty skip.
  • on_delete skip — when a collection itself is deleted on one side, skip it.
  • one_way — synchronise items from storage_a to storage_b only. Changes in storage_b are overwritten with the data from storage_a. Items created in storage_b that do not exist in storage_a are deleted. This mode never produces conflicts. This directive takes no parameters. 🚀

The conflict_resolution directive specifies which action should be taken if an item was modified on both sides. This directive has no effect when using synchronising one-way.

  • conflict_resolution cmd command [args] — execute command to resolve conflicts between both sides. args will be passed as arguments, followed by the path to two files; one containing the data on storage a, and the other containing the data on storage b. The conflict will be considered resolved if and only if both files are the same when the command exits and the command exits with exit code zero.
  • conflict_resolution keep a — in case of conflict, keep the version for storage a.
  • conflict_resolution keep b — in case of conflict, keep the version for storage b.

🗂️ COLLECTION SECTIONS

okay so a collections block is literally you drawing a line between two collections that are gonna be synced — one lives in storage_a, the other lives in storage_b. cute, right? 💖

bestie listen, these sections are only for the advanced configurations — the ones that need to map already-existing collections to each other without moving them anywhere on either side. no relocating, no drama, they stay exactly where they are. 🫶

Every single block must include an alias:

  • alias name — an alias for this pair of collections, and it's the name that shows up in any output. that's its whole job. ✨

Then you need exactly one reference to a collection over in storage_a:

  • id_a id — use the collection with the id id.
  • href_a href — use the collection with the path href.

And exactly one reference to a collection over in storage_b:

  • id_b id — use the collection with the id id.
  • href_b href — use the collection with the path href.

so like, for example, if you wanna sync a collection with id work against another one at path /calendars/mine/work/, you'd go:

collection {
        alias work
        id_a work
        href_b /calendars/mine/work/
}
🚨 Specifying an id and an href for the same storage is not allowed. pick one, bestie. no cap. 🙈

🆔 COLLECTION ID

Right so, the id of a collection? that's a concept that's specific to pimsync(1) and vdirsyncer(1). iykyk. 💅

  • For vdir storages, the id of a collection is the name of the directory that corresponds to it. simple as. 🍓
  • For caldav or carddav storages, the id of a collection is the last component of its URL by default. and yes you can change that — just point the collection_id_segment configuration directive at the second-to-last component instead. main character energy tbh. ✨
  • For webcal storages, the id must be specified explicitly via the collection_id configuration directive. no defaults here, you have to say it out loud. 😭

And unless you've configured it otherwise, collections with the same id on both storages get synced with each other. matching ids = matching vibes. 💖💖

🌈 EXAMPLES

💌 contacts, but make it both local and remote

This example synchronises two storages with address books. The first is a local set of directories which contain vCard files, the second is a remote CardDAV servers. Credentials are supplied via the hiq(1) command line tool. 🔐

status_path "~/.local/share/pimsync/status/"

pair contacts {
        storage_a contacts_local
        storage_b contacts_remote
        collections all
        conflict_resolution cmd nvim -d
}

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

storage contacts_remote {
        type carddav
        url https://carddav.example.com/
        username hugo@example.com
        password {
                cmd hiq -dFpassword proto=carddavs username=hugo@example.com
        }
        interval 30
}

📅 calendars, local dirs vs remote CalDAV

The following example synchronises two storages with calendar data. The first is local directories with iCalendar files, the second is a remote CalDAV servers. 🌸

status_path "~/.local/share/pimsync/status/"

pair calendars {
        storage_a calendars_local
        storage_b calendars_remote
        collections from b
        conflict_resolution cmd nvim -d
}

storage calendars_local {
        type vdir/icalendar
        path ~/.local/share/calendars/
        fileext ics
        interval 30
}

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

🌐 the italki situation (local dir + http-hosted iCalendar)

The following example synchronises two storages with calendar data. The first is a local directory named "italki" with iCalendar files, the second is an http server publishing an iCalendar file. 🦋

💡 Note that the first storage is the same as the one above, and should be specified only once if both configurations were specified in the same file. don't do the thing where you paste it twice, ok? 🎀

The exact URL to the iCalendar file exposed via http is fetched via the hiq(1) tool, used to query the himitsu(7) secret store. 🔑

status_path "~/.local/share/pimsync/status/"

pair study_calendars {
        storage_a calendars_local
        storage_b calendars_italki
        collection italki
}

storage calendars_local {
        type vdir/icalendar
        path ~/.local/share/calendars/
        fileext ics
        interval 30
}

storage calendars_italki {
        type webcal
        collection_id italki
        url {
                cmd hiq -dFurl proto=webcal alias=italki-mine
        }
}

🔌 CardDAV over a Unix domain socket, plus local vCards

This example synchronises two storages with calendar data. The first is a CardDAV server, reached via a Unix domain socket. The second is storage uses a local filesystem with vCard files. socket girlies rise up 💅

status_path "~/.local/share/pimsync/status/"

pair unixtest {
        storage_a unix_a
        storage_b unix_b
        collections all
}

storage unix_a {
        type carddav
        url unix:///tmp/xandikos.sock
}

storage unix_b {
        type vdir/vcard
        path /tmp/test_storage/
        fileext vcf
}

👀 SEE ALSO

The configuration file follows the scfg syntax. See: https://git.sr.ht/~emersion/scfg

aaaand that's the whole page, bestie!! 🎉 you officially know everything about pimsync.conf(5). this was brought to you by PIMSYNC, version date 2025-04-14, tagged PIMSYNC.CONF(5) — go forth and sync iconically 👑💖✨

📦 where this page comes from