.\" Generated by scdoc 1.11.3 .\" Complete documentation for this program is not available as a GNU info page .ie \n(.g .ds Aq \(aq .el .ds Aq ' .nh .ad l .\" Begin generated content: .TH "pimsync.conf" "5" "2025-03-25" .PP .SH NAME .PP pimsync.\&conf - pimsync configuration file .PP .SH DESCRIPTION .PP The pimsync configuration file is divided into three main types of sections: .PP \fBglobal section\fR .RS 4 Global settings for pimsync.\& .PP .RE \fBstorage sections\fR .RS 4 Configuration for individual storages.\& .PP .RE \fBpair sections\fR .RS 4 Rules for synchronising pairs of storages.\& .PP .RE See the \fBFILES\fR section of pimsync(1) for details on the default path for the configuration file, and how to specify an alternative path.\& .PP .SH GLOBAL SECTION .PP The following setting can be set globally: .PP \fBstatus_path\fR .RS 4 Path to a directory which will contain the status database internally used by pimsync.\& .RE .PP .SH STORAGE SECTIONS .PP 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.\& .PP \fBstorage\fR \fIname\fR { … } .RS 4 Declare a storage with name \fIname\fR.\& .PP .RE Directives are declared inside the curly braces for each section, one per line.\& The following directives apply to all storage types: .PP \fBtype\fR \fItype\fR .RS 4 Type can be one of: .PP \fBvdir/icalendar\fR .RS 4 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.\& .PP .RE \fBvdir/vcard\fR .RS 4 A directory where each subdirectory represents an address book.\& Each of these subdirectories contains individual vcard files, each representing one contact.\& .PP .RE \fBcaldav\fR .RS 4 A CalDAV server, containing calendars with events, todos and/or journal entries.\& .PP .RE \fBcarddav\fR .RS 4 A CardDAV server containing address books with contacts.\& .PP .RE \fBwebcal\fR.\& .RS 4 An HTTP or HTTPS URL exposing a single iCalendar file which may contain zero or more events, todos or journal entries.\& This storage is read-only.\& .PP .RE .RE \fBinterval\fR \fIseconds\fR .RS 4 When monitoring a storage is no possible, check for changes every the specified amount of seconds.\& The default is 300 seconds.\& .PP .RE Storages of type \fBvdir\fR take the following directives: .PP .PP \fBpath\fR \fIpath\fR .RS 4 Path to a directory storing a vdir.\& A leading tilde will be expanded to match the current user'\&s home directory.\& .PP .RE \fBfileext\fR \fIext\fR .RS 4 File extension for items saved into this vdir.\& .PP .RE Storages of type \fBcaldav\fR or \fBcarddav\fR take the following directives: .PP \fBurl\fR \fIurl\fR .br \fBurl\fR { … } .RS 4 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.\& .PP URLs must specify schema \fIhttp\fR, \fIhttps\fR or \fIunix\fR.\& URLs starting in \fIunix://\fR shall be treated as a path to a unix domain socket.\& .PP .RE \fBusername\fR \fIusername\fR .br \fBusername\fR { … } .RS 4 Optional.\& Username to use for HTTP Basic Auth.\& .PP .RE \fBpassword\fR \fIpassword\fR .br \fBpassword\fR { … } .RS 4 Optional.\& Password to use for HTTP Basic Auth.\& .PP .RE .PP Storages of type \fBwebcal\fR take the following directives: .PP \fBurl\fR \fIurl\fR .br \fBurl\fR { … } .RS 4 URL of an icalendar file.\& This file may contain multiple calendar items.\& Scheme must be \fIhttp\fR or \fIhttps\fR.\& .PP .RE \fBcollection_id\fR \fIname\fR .RS 4 Name to be used when mapping this collection to another on the other storage.\& .PP .RE .PP Storages of type \fBcaldav\fR, \fBcarddav\fR or \fBwebcal\fR take the following directive: .PP \fBuser_agent\fR \fIuser-agent\fR .RS 4 Optional.\& Set a custom User-Agent header on outgoing HTTP requests.\& The default uses \fBpimsync/\fR followed by the current version number.\& E.\&g.\&: \fBpimsync/1.\&0.\&0\fR.\& .PP .RE The \fBurl\fR, \fBusername\fR and \fBpassword\fR 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 \fBcmd\fR directive.\& .PP For example, to read a password via the external command \fIsecret-store --get-caldav-password\fR, use the following syntax: .PP .nf .RS 4 password { cmd secret-store --get-caldav-password } .fi .RE .PP It is also possible to specify a shell script, which is executed via \fIsh -c\fR.\& For example: .PP .nf .RS 4 password { shell pass show communication/migadu\&.com | head -1 } .fi .RE .PP It is recommended to store credentials and other sensitive values in a secret storage service.\& .PP .SH PAIR SECTIONS .PP A pair declares how two storages shall be synchronised to each other.\& Each pair section starts with a declaration of the pair name: .PP \fBpair\fR \fIname\fR { … } .RS 4 Declare a pair with name \fIname\fR.\& .PP .RE Each pair is defined by a block of directives, one per line, enclosed in curly braces: .PP \fBstorage_a\fR \fIname\fR .RS 4 The \fIname\fR of the first storage to be synchronised with another.\& .PP .RE \fBstorage_b\fR \fIname\fR .RS 4 The \fIname\fR of the second storage to be synchronised with the other.\& .PP .RE \fBcollections all\fR .RS 4 Synchronise all collections found in both storages.\& Collections will be synchronised to others with a matching id on the other side.\& The is the recommended value if you simply want to synchronise all collections from both storages.\& .PP .RE \fBcollections from a\fR .RS 4 Synchronise all collections found in \fBstorage_a\fR.\& Each collection shall be synchronised with the collection which has the same collection id on \fBstorage_b\fR.\& .PP .RE \fBcollections from b\fR .RS 4 Synchronise all collections found in \fBstorage_b\fR.\& Each collection shall be synchronised with the collection which has the same collection id on \fBstorage_a\fR.\& .PP .RE \fBcollection\fR \fIid\fR .RS 4 Synchronise collection with id \fIid\fR.\& May be specified more than once.\& .PP .RE \fBcollection\fR { … } .RS 4 Synchronise collection defined by the given rules.\& See \fBCOLLECTION SECTIONS\fR below.\& May be specified more than once per pair.\& .PP .RE \fBon_empty skip\fR .RS 4 When a collection is completely emptied on one side, skip it.\& This is the default.\& .PP .RE \fBon_empty sync\fR .RS 4 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(1) won'\&t restore it.\& Instead, it will delete the same collection (and all of its items) on the other side.\& .PP .RE \fBon_delete sync\fR .RS 4 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 \fBon empty skip\fR.\& .PP .RE \fBon_delete skip\fR .RS 4 When a collection itself is deleted on one side, skip it.\& .PP .RE The \fBconflict_resolution\fR directive specifies which action should be taken if an item was modified on both sides: .PP \fBconflict_resolution cmd\fR \fIcommand\fR [\fIargs\fR] .RS 4 Execute \fIcommand\fR to resolve conflicts between both sides.\& \fIargs\fR 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.\& .PP .RE \fBconflict_resolution keep a\fR .RS 4 In case of conflict, keep the version for storage a.\& .PP .RE \fBconflict_resolution keep b\fR .RS 4 In case of conflict, keep the version for storage a.\& .PP .RE .SH COLLECTION SECTIONS .PP A collections block defines a mapping between two collections that are to be synchronised; one of them in \fBstorage_a\fR and the other in \fBstorage_b\fR.\& .PP These sections are only used in advanced configurations which need to map existing collections to each other without changing their location on either side.\& .PP Each block must include an alias: .PP \fBalias\fR \fIname\fR .RS 4 An alias for this pair of collections that will be used for any output.\& .PP .RE Exactly one reference to a collection in \fBstorage_a\fR must be included: .PP \fBid_a\fR \fIid\fR .RS 4 Use a collection with \fIid\fR.\& .PP .RE \fBhref_a\fR \fIhref\fR .RS 4 Use a collection with \fIhref\fR.\& .PP .RE Exactly one reference to a collection in \fBstorage_b\fR must be included: .PP \fBid_b\fR \fIid\fR .RS 4 Use a collection with \fIid\fR.\& .PP .RE \fBhref_b\fR \fIhref\fR .RS 4 Use a collection with \fIhref\fR.\& .PP .RE For example, to syncrhonise a collection with id \fIwork\fR with another at path \fI/calendars/mine/work/\fR, use: .PP .nf .RS 4 collection { alias work id_a work href_b /calendars/mine/work/ } .fi .RE .PP Specifying an id and an href for the same storage is not allowed.\& .PP .SH COLLECTION ID .PP The id of a collection is a concept specific to pimsync(1) and vdirsyncer(1).\& .PP For \fBvdir\fR storages, the id of a collection is the name of the directory that corresponds to it.\& .PP For \fBcaldav\fR or \fBcarddav\fR storages, the id of a collection is the last component of its URL.\& .PP For \fBwebcal\fR storages, the id must be specified explicitly via the \fBcollection_id\fR configuration directive.\& .PP Unless configured otherwise, collections with the same id on both storages are synchronised with each other.\& .PP .SH EXAMPLE .PP 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 \fBhiq\fR command line tool.\& .PP .PP .nf .RS 4 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 } .fi .RE .PP The following example synchronises two storages with calendar data.\& The first is local directories with icalendar files, the second is a remote caldav servers.\& .PP .nf .RS 4 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 } .fi .RE .PP 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.\& .PP 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.\& .PP The exact URL to the icalendar file exposed via http is fetched via the \fBhiq\fR tool, used to query the \fBhimitsu\fR secret store.\& .PP .nf .RS 4 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 } } .fi .RE .PP 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.\& .PP .nf .RS 4 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 } .fi .RE .PP .SH SEE ALSO .PP pimsync(1), pimsync-migration(7) .PP The configuration file follows the scfg syntax.\& .br See: https://git.\&sr.\&ht/~emersion/scfg