Configuration

Vdirsyncer uses an ini-like format for storing its configuration. All values are JSON, invalid JSON will get interpreted as string:

x = "foo"  # String
x = foo  # Shorthand for same string

x = 42  # Integer

x = ["a", "b", "c"]  # List of strings

x = true  # Boolean
x = false

x = null  # Also known as None

General Section

[general]
status_path = ...
#password_command =
  • status_path: A directory where vdirsyncer will store metadata for the next sync. The data is needed to determine whether a new item means it has been added on one side or deleted on the other. Relative paths will be interpreted as relative to the configuration file’s directory.

Pair Section

[pair pair_name]
a = ...
b = ...
#collections = null
#conflict_resolution = null
  • Pair names can consist of any alphanumeric characters and the underscore.

  • a and b reference the storages to sync by their names.

  • collections: Optional, a list of collections to synchronize when vdirsyncer sync is executed. If this parameter is omitted, it is assumed the storages are already directly pointing to one collection each. Specifying a collection multiple times won’t make vdirsyncer sync that collection more than once.

    Furthermore, there are the special values "from a" and "from b", which tell vdirsyncer to try autodiscovery on a specific storage.

    Examples:

    • collections = ["from b", "foo", "bar"] makes vdirsyncer synchronize the collections from side B, and also the collections named “foo” and “bar”.
    • collections = ["from b", from a"] makes vdirsyncer synchronize all existing collections on either side.
  • conflict_resolution: Optional, define how conflicts should be handled. A conflict occurs when one item (event, task) changed on both sides since the last sync.

    Valid values are:

    • "a wins" and "b wins", where the whole item is taken from one side. Vdirsyncer will not attempt to merge the two items.
    • null, the default, where an error is shown and no changes are done.
  • metadata: Metadata keys that should be synchronized when vdirsyncer metasync is executed. Example:

       metadata = ["color", "displayname"]
    
    This synchronizes the ``color`` and the ``displayname`` properties. The
    ``conflict_resolution`` parameter applies here as well.
    

Storage Section

[storage storage_name]
type = ...
  • Storage names can consist of any alphanumeric characters and the underscore.
  • type defines which kind of storage is defined. See Supported Storages.
  • read_only defines whether the storage should be regarded as a read-only storage. The value true means synchronization will discard any changes made to the other side. The value false implies normal 2-way synchronization.
  • Any further parameters are passed on to the storage class.

Supported Storages

Read-write storages

These storages generally support reading and changing of their items. Their default value for read_only is false, but can be set to true if wished.

CalDAV and CardDAV
caldav

CalDAV.

[storage example_for_caldav]
type = caldav
#start_date = null
#end_date = null
#item_types = []
url = "..."
#username = ""
#password = ""
#verify = true
#auth = null
#useragent = "vdirsyncer"
#verify_fingerprint = null
#auth_cert = null

You can set a timerange to synchronize with the parameters start_date and end_date. Inside those parameters, you can use any Python expression to return a valid datetime.datetime object. For example, the following would synchronize the timerange from one year in the past to one year in the future:

start_date = datetime.now() - timedelta(days=365)
end_date = datetime.now() + timedelta(days=365)

Either both or none have to be specified. The default is to synchronize everything.

You can set item_types to restrict the kind of items you want to synchronize. For example, if you want to only synchronize events (but don’t download any tasks from the server), set item_types = ["VEVENT"]. If you want to synchronize events and tasks, but have some VJOURNAL items on the server you don’t want to synchronize, use item_types = ["VEVENT", "VTODO"].

Parameters:
  • start_date – Start date of timerange to show, default -inf.
  • end_date – End date of timerange to show, default +inf.
  • item_types – Kind of items to show. The default, the empty list, is to show all. This depends on particular features on the server, the results are not validated.
  • url – Base URL or an URL to a collection.
  • username – Username for authentication.
  • password – Password for authentication.
  • verify – Verify SSL certificate, default True. This can also be a local path to a self-signed SSL certificate. See SSL and certificate validation for more information.
  • verify_fingerprint – Optional. SHA1 or MD5 fingerprint of the expected server certificate. See SSL and certificate validation for more information.
  • auth – Optional. Either basic, digest or guess. Default guess. If you know yours, consider setting it explicitly for performance.
  • auth_cert – Optional. Either a path to a certificate with a client certificate and the key or a list of paths to the files with them.
  • useragent – Default vdirsyncer.
  • unsafe_href_chars – Replace the given characters when generating hrefs. Defaults to '@'.

Note

Please also see Supported servers, as some servers may not work well.

carddav

CardDAV.

[storage example_for_carddav]
type = carddav
url = "..."
#username = ""
#password = ""
#verify = true
#auth = null
#useragent = "vdirsyncer"
#verify_fingerprint = null
#auth_cert = null
Parameters:
  • url – Base URL or an URL to a collection.
  • username – Username for authentication.
  • password – Password for authentication.
  • verify – Verify SSL certificate, default True. This can also be a local path to a self-signed SSL certificate. See SSL and certificate validation for more information.
  • verify_fingerprint – Optional. SHA1 or MD5 fingerprint of the expected server certificate. See SSL and certificate validation for more information.
  • auth – Optional. Either basic, digest or guess. Default guess. If you know yours, consider setting it explicitly for performance.
  • auth_cert – Optional. Either a path to a certificate with a client certificate and the key or a list of paths to the files with them.
  • useragent – Default vdirsyncer.
  • unsafe_href_chars – Replace the given characters when generating hrefs. Defaults to '@'.

Note

Please also see Supported servers, as some servers may not work well.

remoteStorage

remoteStorage is an open per-user data storage protocol. Vdirsyncer contains highly experimental support for it.

Note

Do not use this storage if you’re not prepared for data-loss and breakage.

To use them, you need to install some optional dependencies with:

pip install vdirsyncer[remotestorage]
remotestorage_contacts

remoteStorage contacts. Uses the vdir_contacts scope.

[storage example_for_remotestorage_contacts]
type = remotestorage_contacts
account = "..."
#verify = true
#verify_fingerprint = null
#auth_cert = null
#access_token = null
Parameters:
  • account – remoteStorage account, "user@example.com".
  • username – Username for authentication.
  • password – Password for authentication.
  • verify – Verify SSL certificate, default True. This can also be a local path to a self-signed SSL certificate. See SSL and certificate validation for more information.
  • verify_fingerprint – Optional. SHA1 or MD5 fingerprint of the expected server certificate. See SSL and certificate validation for more information.
  • auth – Optional. Either basic, digest or guess. Default guess. If you know yours, consider setting it explicitly for performance.
  • auth_cert – Optional. Either a path to a certificate with a client certificate and the key or a list of paths to the files with them.
  • useragent – Default vdirsyncer.
remotestorage_calendars

remoteStorage calendars. Uses the vdir_calendars scope.

[storage example_for_remotestorage_calendars]
type = remotestorage_calendars
account = "..."
#verify = true
#verify_fingerprint = null
#auth_cert = null
#access_token = null
Parameters:
  • account – remoteStorage account, "user@example.com".
  • username – Username for authentication.
  • password – Password for authentication.
  • verify – Verify SSL certificate, default True. This can also be a local path to a self-signed SSL certificate. See SSL and certificate validation for more information.
  • verify_fingerprint – Optional. SHA1 or MD5 fingerprint of the expected server certificate. See SSL and certificate validation for more information.
  • auth – Optional. Either basic, digest or guess. Default guess. If you know yours, consider setting it explicitly for performance.
  • auth_cert – Optional. Either a path to a certificate with a client certificate and the key or a list of paths to the files with them.
  • useragent – Default vdirsyncer.
Local
filesystem

Saves each item in its own file, given a directory.

[storage example_for_filesystem]
type = filesystem
path = "..."
fileext = "..."
#encoding = "utf-8"
#post_hook = null

Can be used with khal. See The Vdir Storage Format for a more formal description of the format.

Parameters:
  • path – Absolute path to a vdir/collection. If this is used in combination with the collections parameter in a pair-section, this should point to a directory of vdirs instead.
  • fileext – The file extension to use (e.g. .txt). Contained in the href, so if you change the file extension after a sync, this will trigger a re-download of everything (but should not cause data-loss of any kind).
  • encoding – File encoding for items, both content and filename.
  • post_hook – A command to call for each item creation and modification. The command will be called with the path of the new/updated file.
singlefile

Save data in single local .vcf or .ics file.

[storage example_for_singlefile]
type = singlefile
path = "..."
#encoding = "utf-8"

The storage basically guesses how items should be joined in the file.

New in version 0.1.6.

Note

This storage is very slow, and that is unlikely to change. You should consider using filesystem if it fits your usecase.

Parameters:
  • path – The filepath to the file to be written to.
  • encoding – Which encoding the file should use. Defaults to UTF-8.

Example for syncing with caldav:

[pair my_calendar]
a = my_calendar_local
b = my_calendar_remote

[storage my_calendar_local]
type = singlefile
path = ~/my_calendar.ics

[storage my_calendar_remote]
type = caldav
url = https://caldav.example.org/username/my_calendar/
#username =
#password =

Read-only storages

These storages don’t support writing of their items, consequently read_only is set to true by default. Changing read_only to false on them leads to an error.

http

Use a simple .ics file (or similar) from the web.

[storage example_for_http]
type = http
url = "..."
#username = ""
#password = ""
#verify = true
#auth = null
#useragent = "vdirsyncer"
#verify_fingerprint = null
#auth_cert = null
Parameters:
  • url – URL to the .ics file.
  • username – Username for authentication.
  • password – Password for authentication.
  • verify – Verify SSL certificate, default True. This can also be a local path to a self-signed SSL certificate. See SSL and certificate validation for more information.
  • verify_fingerprint – Optional. SHA1 or MD5 fingerprint of the expected server certificate. See SSL and certificate validation for more information.
  • auth – Optional. Either basic, digest or guess. Default guess. If you know yours, consider setting it explicitly for performance.
  • auth_cert – Optional. Either a path to a certificate with a client certificate and the key or a list of paths to the files with them.
  • useragent – Default vdirsyncer.

A simple example:

[pair holidays]
a = holidays_local
b = holidays_remote

[storage holidays_local]
type = filesystem
path = ~/.config/vdir/calendars/holidays/
fileext = .ics

[storage holidays_remote]
type = http
url = https://example.com/holidays_from_hicksville.ics