pimsync.conf.5¶
pimsync.conf(5) | File Formats Manual | pimsync.conf(5) |
NAME
pimsync.conf - pimsync configuration file
DESCRIPTION
The pimsync configuration file is divided into three main types of sections:
global section
storage sections
pair sections
See the FILES section of pimsync(1) for details on the default path for the configuration file, and how to specify an alternative path.
GLOBAL SECTION
The following setting can be set globally:
status_path
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.
storage name { … }
Directives are declared inside the curly braces for each section, one per line. The following directives apply to all storage types:
type type
vdir/icalendar
vdir/vcard
caldav
carddav
webcal.
interval seconds
Storages of type vdir take the following directives:
path path
path { … }
fileext ext
Storages of type caldav or carddav take the following directives:
url url
url { … }
URLs must specify schema http, https or unix. URLs starting in unix:// shall be treated as a path to a unix domain socket.
username username
username { … }
password password
password { … }
Storages of type webcal take the following directives:
url url
url { … }
collection_id name
Storages of type caldav, carddav or webcal take the following directive:
user_agent user-agent
The url, username, password and path fields may be defined in the configuration file, or may specify a command to retrieve this value from an external storage. When specifying an external command, instead of defining a value for the directive, specify a new block with a single cmd directive.
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.
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 { … }
Each pair is defined by a block of directives, one per line, enclosed in curly braces:
storage_a name
storage_b name
collections all
collections from a
collections from b
collection id
collection { … }
on_empty skip
on_empty sync
on_delete sync
on_delete skip
The conflict_resolution directive specifies which action should be taken if an item was modified on both sides:
conflict_resolution cmd command [args]
conflict_resolution keep a
conflict_resolution keep b
COLLECTION SECTIONS
A collections block defines a mapping between two collections that are to be synchronised; one of them in storage_a and the other in storage_b.
These sections are only used in advanced configurations which need to map existing collections to each other without changing their location on either side.
Each block must include an alias:
alias name
Exactly one reference to a collection in storage_a must be included:
id_a id
href_a href
Exactly one reference to a collection in storage_b must be included:
id_b id
href_b href
For example, to syncrhonise a collection with id work with another at path /calendars/mine/work/, use:
collection { alias work id_a work href_b /calendars/mine/work/ }
Specifying an id and an href for the same storage is not allowed.
COLLECTION ID
The id of a collection is a concept specific to pimsync(1) and vdirsyncer(1).
For vdir storages, the id of a collection is the name of the directory that corresponds to it.
For caldav or carddav storages, the id of a collection is the last component of its URL.
For webcal storages, the id must be specified explicitly via the collection_id configuration directive.
Unless configured otherwise, collections with the same id on both storages are synchronised with each other.
EXAMPLE
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 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 }
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 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 to be merged.
The exact URL to the icalendar file exposed via http is fetched via the hiq tool, used to query the himitsu 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 } }
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.
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
pimsync(1), pimsync-migration(7)
The configuration file follows the scfg syntax.
See: https://git.sr.ht/~emersion/scfg
2025-03-31 |