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

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

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