
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.

* "password_command" specifies a command to query for server
  passwords. The command will be called with the username as the first
  argument, and the hostname as the second.

New in version 0.3.0: The "passwordeval" parameter.

Changed in version 0.4.0: The "passwordeval" parameter has been
renamed to "password_command".


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.

vdirsyncer.storage.dav.CaldavStorage

   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.

vdirsyncer.storage.dav.CarddavStorage

   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.

vdirsyncer.storage.filesystem.FilesystemStorage

   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.

vdirsyncer.storage.singlefile.SingleFileStorage

   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
     "vdirsyncer.storage.filesystem.FilesystemStorage" 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 "vdirsyncer.storage.CaldavStorage":

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

vdirsyncer.storage.http.HttpStorage

   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
