
Full configuration manual
*************************

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 = ...

* "status_path": A directory where vdirsyncer will store some
  additional data 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.

  See A simple synchronization algorithm for what exactly is in there.


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": A list of collections to synchronize when
  "vdirsyncer sync" is executed.

  The special values ""from a"" and ""from b"", tell vdirsyncer to try
  autodiscovery on a specific storage.

  If the collection you want to sync doesn't have the same name on
  each side, you may also use a value of the form "["config_name",
  "name_a", "name_b"]". This will synchronize the collection "name_a"
  on side A with the collection "name_b" on side B. The "config_name"
  will be used for representation in CLI arguments and logging.

  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.

  * "collections = [["bar", "bar_a", "bar_b"], "foo"]" makes
    vdirsyncer synchronize "bar_a" from side A with "bar_b" from side
    B, and also synchronize "foo" on both sides with each other.

* "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
------------------


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".
        The default is preemptive Basic auth, sending credentials even
        if server didn't request them. This saves from an additional
        roundtrip per request. Consider setting "guess" if this causes
        issues with your server.

      * **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".

   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".
        The default is preemptive Basic auth, sending credentials even
        if server didn't request them. This saves from an additional
        roundtrip per request. Consider setting "guess" if this causes
        issues with your server.

      * **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".

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


Google
~~~~~~

At first run you will be asked to authorize application for google
account access.

To use this storage type, you need to install some additional
dependencies:

   pip install vdirsyncer[google]

Furthermore you need to register vdirsyncer as an application yourself
to obtain "client_id" and "client_secret", as it is against Google's
Terms of Service to hardcode those into opensource software:

1. Go to the Google API Manager and create a new project under any
   name.

2. Within that project, enable the "CalDAV" and "CardDAV" APIs
   (**not** the Calendar and Contacts APIs, those are different and
   won't work). There should be a searchbox where you can just enter
   those terms.

3. In the sidebar, select "Credentials" and create a new "OAuth
   Client ID". The application type is "Other".

   You'll be prompted to create a OAuth consent screen first. Fill out
   that form however you like.

4. Finally you should have a Client ID and a Client secret. Provide
   these in your storage config.

You can select which calendars to sync on CalDav settings page.

google_calendar

   Google calendar.

      [storage example_for_google_calendar]
      type = google_calendar
      token_file = "..."
      client_id = "..."
      client_secret = "..."
      #start_date = null
      #end_date = null
      #item_types = []

   Please refer to "caldav" regarding the "item_types" and timerange
   parameters.

   Parameters:
      * **token_file** -- A filepath where access tokens are stored.

      * **client_id/client_secret** -- OAuth credentials, obtained
        from the Google API Manager.

google_contacts

   Google contacts.

      [storage example_for_google_contacts]
      type = google_contacts
      token_file = "..."
      client_id = "..."
      client_secret = "..."

   Note: Google's CardDAV implementation is allegedly a disaster in
     terms of data safety. See this blog post for the details. Always
     back up your data.

   Parameters:
      * **token_file** -- A filepath where access tokens are stored.

      * **client_id/client_secret** -- OAuth credentials, obtained
        from the Google API Manager.


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".
        The default is preemptive Basic auth, sending credentials even
        if server didn't request them. This saves from an additional
        roundtrip per request. Consider setting "guess" if this causes
        issues with your server.

      * **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".
        The default is preemptive Basic auth, sending credentials even
        if server didn't request them. This saves from an additional
        roundtrip per request. Consider setting "guess" if this causes
        issues with your server.

      * **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. If
        collections are used, this should contain "%s" as a
        placeholder for the collection name.

      * **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
      collections = ["from a", "from b"]

      [storage my_calendar_local]
      type = singlefile
      path = ~/.calendars/%s.ics

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

   Example for syncing with "caldav" using a "null" collection:

      [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".
        The default is preemptive Basic auth, sending credentials even
        if server didn't request them. This saves from an additional
        roundtrip per request. Consider setting "guess" if this causes
        issues with your server.

      * **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
