1865 lines
78 KiB
Plaintext
1865 lines
78 KiB
Plaintext
===============
|
|
SyncEvolution
|
|
===============
|
|
|
|
------------------------------------------------
|
|
synchronize personal information management data
|
|
------------------------------------------------
|
|
|
|
:Manual section: 1
|
|
:Version: 2.0.0
|
|
:Date: 2021-03-22
|
|
|
|
|
|
SYNOPSIS
|
|
========
|
|
|
|
List and manipulate databases:
|
|
syncevolution --print-databases|--create-database|--remove-database [<properties>] [<config> <store>]
|
|
|
|
Show information about configuration(s):
|
|
syncevolution --print-servers|--print-configs|--print-peers
|
|
|
|
Show information about a specific configuration:
|
|
syncevolution --print-config [--quiet] [--] <config> [main|<store> ...]
|
|
|
|
List sessions:
|
|
syncevolution --print-sessions [--quiet] [--] <config>
|
|
|
|
Show information about SyncEvolution:
|
|
syncevolution --help|-h|--version
|
|
|
|
Run a synchronization as configured:
|
|
syncevolution <config> [<store> ...]
|
|
|
|
Run a synchronization with properties changed just for this run:
|
|
syncevolution --run <options for run> [--] <config> [<store> ...]
|
|
|
|
Restore data from the automatic backups:
|
|
syncevolution --restore <session directory> --before|--after [--dry-run] [--] <config> <store> ...
|
|
|
|
Create, update or remove a configuration:
|
|
syncevolution --configure <options> [--] <config> [<store> ...]
|
|
|
|
syncevolution --remove|--migrate <options> [--] <config>
|
|
|
|
List items:
|
|
syncevolution --print-items [--] [<config> [<store>]]
|
|
|
|
Export item(s):
|
|
syncevolution [--delimiter <string>] --export <dir>|<file>|- [--] [<config> [<store> [<luid> ...]]]
|
|
--luids <luid> ...
|
|
|
|
Add item(s):
|
|
syncevolution [--delimiter <string>|none] --import <dir>|<file>|- [--] [<config> [<store>]]
|
|
--luids <luid> ...
|
|
|
|
Update item(s):
|
|
syncevolution --update <dir> [--] <config> <store>
|
|
|
|
syncevolution [--delimiter <string>|none] --update <file>|- [--] <config> <store> <luid> ...
|
|
--luids <luid> ...
|
|
|
|
|
|
Remove item(s):
|
|
syncevolution --delete-items [--] <config> <store> (<luid> ... | '*')
|
|
|
|
|
|
DESCRIPTION
|
|
===========
|
|
|
|
This text explains the usage of the SyncEvolution command line.
|
|
|
|
SyncEvolution synchronizes personal information management (PIM) data
|
|
such as contacts, appointments, tasks and memos using the Synthesis
|
|
sync engine, which provides support for the SyncML synchronization
|
|
protocol.
|
|
|
|
SyncEvolution synchronizes with SyncML servers over HTTP and with
|
|
SyncML capable phones locally over Bluetooth (new in 1.0). Plugins
|
|
provide access to the data which is to be synchronized. Binaries are
|
|
available for Linux desktops (synchronizing data in GNOME Evolution,
|
|
with KDE supported indirectly already and Akonadi support in
|
|
development), for MeeGo (formerly Moblin) and for Maemo 5/Nokia
|
|
N900. The source code can be compiled for Unix-like systems and
|
|
provides a framework to build custom SyncML clients or servers.
|
|
|
|
TERMINOLOGY
|
|
===========
|
|
|
|
peer
|
|
A peer is the entity that data is synchronized with. This can be
|
|
another device (like a phone), a server (like Google) or
|
|
even the host itself (useful for synchronizing two different
|
|
databases).
|
|
|
|
host
|
|
The device or computer that SyncEvolution runs on.
|
|
|
|
item
|
|
The smallest unit of synchronization. Examples of items include
|
|
calendar events and individual contacts, memos, or tasks.
|
|
|
|
database
|
|
Each peer has one or more databases that get synchronized (Google Calendar,
|
|
Google Contacts). Conceptually a database is a set of items where each
|
|
item is independent of the others.
|
|
|
|
backend
|
|
Access to databases is provided by SyncEvolution backends. It does
|
|
not matter where that data is stored. Some backends provide access
|
|
to data outside of the host itself (`CalDAV and CardDAV`_, ActiveSync).
|
|
|
|
datastore (or just "store")
|
|
Used for the combination of SyncEvolution backend and database settings.
|
|
A datastore provides read/write access to a database, which is a prerequisite
|
|
for syncing the database. The datastore is independent of the peers that
|
|
the database might be synchronized with.
|
|
|
|
This used to be called "data source" or just "source", which is a
|
|
term still found in older documentation, some file paths and the
|
|
source code of SyncEvolution.
|
|
|
|
local/remote
|
|
Synchronization always happens between a pair of databases and thus
|
|
has two sides. One database or side of a sync is remote (the one
|
|
of the peer), the other is local (SyncEvolution). For the sake of consistency (and
|
|
lack of better terms), these terms are used even if the peer is another
|
|
instance of SyncEvolution and/or all data resides on the same storage.
|
|
|
|
sync config
|
|
A sync configuration defines how to talk with a peer: the protocol
|
|
which is to be used, how to find the peer, credentials, etc.
|
|
|
|
Sync configs can be used to initiate a sync (like contacting a
|
|
SyncML server) or to handle an incoming sync request (when acting
|
|
as SyncML server which is contacted by the peer).
|
|
|
|
If the peer supports SyncML as sync protocol, a sync only uses one
|
|
sync config on the SyncEvolution side. If the peer supports data
|
|
access via some other protocols, then SyncEvolution can make that
|
|
data available via SyncML and run a sync where SyncML is used
|
|
internally. Such a sync involves two sync configs, see ``originating
|
|
config`` and ``target config``.
|
|
|
|
A sync config can use all datastores defined in the same context
|
|
(see below). Some properties of the datastore can be set differently
|
|
for each peer and thus sync config (``per-peer``). One of these, the
|
|
``sync`` property, defines if and how a datastore is used during a
|
|
sync.
|
|
|
|
context
|
|
Sync and datastore configs are defined inside one or more configuration
|
|
contexts. There is always a ``@default`` context that gets used if nothing
|
|
else is specified.
|
|
|
|
Typically each context represents a certain set of related
|
|
datastores. For example, normally the ``@default`` context is used for
|
|
local databases. Datastores related to a certain peer can
|
|
be defined in a context ``@peer-name`` named after that peer.
|
|
|
|
configuration properties
|
|
SyncEvolution uses key/value pairs to store configuration options.
|
|
A configuration is a set of unique keys and their values that together
|
|
describe a certain object.
|
|
|
|
These sets of properties are addressed via the main config name (a
|
|
sync config name with or without an explicit context, or just the
|
|
context name) and optionally the datastore name (if the properties
|
|
are for a specific datastore).
|
|
|
|
Sync properties are set for sync configs, independently of a
|
|
particular datastore. Properties that cannot be set without
|
|
specifying they datastore that they apply to are datastore
|
|
properties. This includes properties that belong both to a datastore
|
|
and a sync config.
|
|
|
|
The property names were chosen so that they are unique, i.e., no
|
|
sync property has the same name as a datastore property. For historic
|
|
reasons, internally these properties are treated as two different
|
|
sets and there are two different command line options to query the
|
|
list of sync resp. datastore properties.
|
|
|
|
Some configuration properties are shared between configurations
|
|
automatically. This sharing is hard-coded and cannot be configured.
|
|
It has the advantage that certain settings only need to be set
|
|
once and/or can be changed for several different configs
|
|
at once.
|
|
|
|
A property can be *unshared* (has separate values for each peer, therefore
|
|
sometimes also called *per-peer*; for example the ``sync`` property),
|
|
*shared* (same value for all peers; for
|
|
example the ``database`` property for selecting the local database) or
|
|
*global* (exactly one value).
|
|
|
|
Together with the distinction between sync and datastore properties,
|
|
this currently results in five different groups of properties:
|
|
|
|
* Sync properties (by definition, this also includes properties
|
|
independent of a particular sync config because they are set for
|
|
all sync configs at once, independently of any particular
|
|
datastore):
|
|
|
|
* global (= ``~/.config/syncevolution/config.ini``):
|
|
independent of a particular context, for example ``keyring``
|
|
* shared (= ``~/.config/syncevolution/<context name>/config.ini``):
|
|
set once for each context, for example ``logdir``
|
|
* unshared (= ``~/.config/syncevolution/<context name>/peers/<peer name>/config.ini``):
|
|
set separately for each sync config, for example ``syncURL``
|
|
|
|
* Datastore properties:
|
|
|
|
* shared (= ``~/.config/syncevolution/<context name>/sources/<store name>/config.ini``):
|
|
the properties required for access to the data, primarily ``backend`` and ``database``
|
|
* unshared (= ``~/.config/syncevolution/<context name>/peers/<peer name>/sources/<store name>/config.ini``):
|
|
the already mentioned ``sync`` and ``uri`` properties, but also a per-peer
|
|
sync format properties
|
|
|
|
Many properties have reasonable defaults, either defined in the
|
|
configuration layer or chosen at runtime by the SyncEvolution
|
|
engine reading the configuration, and therefore do not have to
|
|
be set.
|
|
|
|
The configuration layer in SyncEvolution has a very limited
|
|
understanding of the semantic of each property. It just knows about
|
|
some generic types (strings, boolean, integers, ...) and where
|
|
properties are supposed to be stored. It is the layer above that,
|
|
the one which actually tries to use the configuration, that
|
|
determines whether the property values make sense as
|
|
specified. Beware that it is possible to set properties to values
|
|
that conflict with other property values (triggering errors when
|
|
using the configuration) or to set properties that are not used
|
|
(typically they get ignored silently, unless an explicit error check
|
|
was implemented).
|
|
|
|
configuration template
|
|
Templates define the settings for specific peers. Some templates
|
|
are packaged together with SyncEvolution, others may be added by
|
|
packagers or users. Settings from templates are copied once into
|
|
the sync config when creating it. There is no permanent link back
|
|
to the template, so updating a template has no effect on configs
|
|
created from it earlier.
|
|
|
|
A template only contains unshared properties. Therefore it is
|
|
possible to first set shared properties (for example, choosing
|
|
which databases to synchronize in the default context), then
|
|
add sync configs for different peers to that context without
|
|
reseting the existing settings.
|
|
|
|
In SyncEvolution's predefined configuration templates, the following
|
|
names for datastores are used. Different names can be chosen for datastores
|
|
that are defined manually.
|
|
|
|
* addressbook: a list of contacts
|
|
* calendar: calendar *events*
|
|
* memo: plain text notes
|
|
* todo: task list
|
|
* calendar+todo: a virtual datastore combining one local "calendar" and
|
|
one "todo" datastore (required for synchronizing with some phones)
|
|
|
|
local sync
|
|
Traditionally, a sync config specifies SyncML as the synchronization
|
|
protocol via the `syncURL` property. The peer must support SyncML for
|
|
this to work.
|
|
|
|
In a so called local sync, SyncEvolution acts as SyncML server
|
|
and client at the same time, connecting the two sides via internal
|
|
message passing. Both sides have their own set of datastores, which may
|
|
use CalDAV, CardDAV or ActiveSync to access the data.
|
|
|
|
See `Synchronization beyond SyncML`_.
|
|
|
|
originating config
|
|
In a local sync, the sync config used to start the sync is called
|
|
the originating sync config, or just originating config.
|
|
|
|
target config
|
|
In addition to the originating config, a local sync also uses a target
|
|
config. At the configuration level, this target config is just another
|
|
sync config. It becomes a target config when referenced by a sync config
|
|
for local syncing.
|
|
|
|
|
|
COMMAND LINE CONVENTIONS
|
|
========================
|
|
|
|
The ``<config>`` and the ``<store>`` strings in the command line synopsis are
|
|
used to find the sync resp. datastore configs. Depending on which
|
|
other parameters are given, different operations are executed.
|
|
|
|
The ``<config>`` string has the format ``[<peer>][@<context>]``. When
|
|
the context is not specified explicitly, SyncEvolution first searches
|
|
for an existing sync configuration with the given ``<peer>`` name. If
|
|
not found, the configuration can only be created, but not read. It
|
|
will be created in the ``@default`` context as fallback. The empty
|
|
``<config>`` string is an alias for ``@default``.
|
|
|
|
The ``<peer>`` part identifies a specific sync or target config inside
|
|
the context. It is optional and does not have to be specified when not
|
|
needed, for example when configuring the shared settings of datastores
|
|
(``--configure @default addressbook``) or accessing items inside a
|
|
datastore (``--print-items @work calendar``).
|
|
|
|
Listing datastores on the command line limits the operation to those
|
|
datastores (called *active datastores* below). If not given, all datastores
|
|
enabled for the config are active. Some operations require
|
|
the name of exactly one datastore.
|
|
|
|
Properties are set with key/value assignments and/or the
|
|
``--sync/store-property`` keywords. Those keywords are only needed for
|
|
the hypothetical situation that a sync and datastore property share the
|
|
same name (which was intentionally avoided). Without them, SyncEvolution
|
|
automatically identifies which kind of property is meant based on the
|
|
name.
|
|
|
|
A ``<property>`` assignment has the following format::
|
|
|
|
[<store>/]<name>[@<context>|@<peer>@<context>]=<value>
|
|
|
|
The optional ``<context>`` or ``<peer>@<context>`` suffix limits the scope
|
|
of the value to that particular configuration. This is useful when
|
|
running a local sync, which involves a sync and a target
|
|
configuration. For example, the log level can be specified separately
|
|
for both sides::
|
|
|
|
--run loglevel@default=1 loglevel@google-calendar=4 google-calendar@default
|
|
|
|
A string without a second @ sign inside is always interpreted as a
|
|
context name, so in contrast to the ``<config>`` string, ``foo`` cannot be
|
|
used to reference the ``foo@default`` configuration. Use the full name
|
|
including the context for that.
|
|
|
|
When no config or context is specified explicitly, a value is
|
|
changed in all active configs, typically the one given with
|
|
``<config>``. The priority of multiple values for the same config
|
|
is `more specific definition wins`, so ``<peer>@<context>``
|
|
overrides ``@<context>``, which overrides `no suffix given`.
|
|
Specifying some suffix which does not apply to the current operation
|
|
does not trigger an error, so beware of typos.
|
|
|
|
Datastore properties can be specified with a ``<store>/`` prefix. This
|
|
allows limiting the value to the selected datastore. For example::
|
|
|
|
--configure "addressbook/database=My Addressbook" \
|
|
"calendar/database=My Calendar" \
|
|
@default addressbook calendar
|
|
|
|
Another way to achieve the same effect is to run the ``--configure``
|
|
operation twice, once for ``addressbook`` and once for ``calendar``::
|
|
|
|
--configure "database=My Addressbook" @default addressbook
|
|
--configure "database=My Calendar" @default calendar
|
|
|
|
If the same property is set both with and without a ``<store>/`` prefix,
|
|
then the more specific value with that prefix is used for that datastore,
|
|
regardless of the order on the command line. The following command
|
|
enables all datastores except for the addressbook::
|
|
|
|
--configure addressbook/sync=none \
|
|
sync=two-way \
|
|
<sync config>
|
|
|
|
|
|
USAGE
|
|
=====
|
|
|
|
::
|
|
|
|
syncevolution --print-databases [<properties>] [<config> <store>]
|
|
|
|
If no additional arguments are given, then SyncEvolution will list all
|
|
available backends and the databases that can be accessed through each
|
|
backend. This works without existing configurations. However, some
|
|
backends, like for example the CalDAV backend, need additional
|
|
information (like credentials or URL of a remote server). This
|
|
additional information can be provided on the command line with
|
|
property assignments (``username=...``) or in an existing configuration.
|
|
|
|
When listing all databases of all active datastores, the output starts
|
|
with a heading that lists the values for the ``backend`` property which
|
|
select the backend, followed by the databases. Each database has a
|
|
name and a unique ID (in brackets). Typically both can be used as
|
|
value of the 'database' property. One database might be marked as
|
|
``default``. It will be used when ``database`` is not set explicitly.
|
|
|
|
When selecting an existing datastore configuration or specifying the ``backend``
|
|
property on the command line, only the databases for that backend
|
|
are listed and the initial line shows how that backend was selected
|
|
(<config>/<store> resp. backend value).
|
|
|
|
Some backends do not support listing of databases. For example, the
|
|
file backend synchronizes directories with one file per item and
|
|
always needs an explicit ``database`` property because it cannot guess
|
|
which directory it is meant to use. ::
|
|
|
|
syncevolution --create-database [<properties>] [<config> <store>]
|
|
|
|
Creates a new database for the selected ``backend``, using the
|
|
information given in the ``database`` property. As with
|
|
``--print-databases``, it is possible to give the properties directly
|
|
without configuring a datastore first.
|
|
|
|
The interpretation of the ``database`` property depends on the
|
|
backend. Not all backends support this operation.
|
|
|
|
The EDS backend uses the value of the ``database`` as name of the new
|
|
database and assigns a unique URI automatically. ::
|
|
|
|
syncevolution --remove-database [<properties>] [<config> <store>]
|
|
|
|
Looks up the database based on the ``database`` property (depending
|
|
on the backend, both name and a URI are valid), then deletes the data.
|
|
Note that datastore configurations using the database are not removed. ::
|
|
|
|
syncevolution <config>
|
|
|
|
Without the optional list of datastores, all datastores which are enabled in
|
|
their configuration file are synchronized. ::
|
|
|
|
syncevolution <config> <store> ...
|
|
|
|
Otherwise only the ones mentioned on the command line are active. It
|
|
is possible to configure datastores without activating their
|
|
synchronization: if the synchronization mode of a datastore is set to
|
|
`disabled`, the datastore will be ignored. Explicitly listing such a
|
|
datastore will synchronize it in `two-way` mode once.
|
|
|
|
Progress and error messages are written into a log file that is
|
|
preserved for each synchronization run. Details about that is found in
|
|
the `Automatic Backups and Logging` section below. All errors and
|
|
warnings are printed directly to the console in addition to writing
|
|
them into the log file. Before quitting SyncEvolution will print a
|
|
summary of how the local data was modified. This is done with the
|
|
`synccompare` utility script described in the `Exchanging Data`_
|
|
section.
|
|
|
|
When the ``logdir`` property is enabled (since v0.9 done by default for
|
|
new configurations), then the same comparison is also done before the
|
|
synchronization starts.
|
|
|
|
In case of a severe error the synchronization run is aborted
|
|
prematurely and SyncEvolution will return a non-zero value. Recovery
|
|
from failed synchronization is done by forcing a full synchronization
|
|
during the next run, i.e. by sending all items and letting the SyncML
|
|
server compare against the ones it already knows. This is avoided
|
|
whenever possible because matching items during a slow synchronization
|
|
can lead to duplicate entries.
|
|
|
|
After a successful synchronization the server's configuration file is
|
|
updated so that the next run can be done incrementally. If the
|
|
configuration file has to be recreated e.g. because it was lost, the
|
|
next run recovers from that by doing a full synchronization. The risk
|
|
associated with this is that the server might not recognize items that
|
|
it already has stored previously which then would lead to duplication
|
|
of items. ::
|
|
|
|
syncevolution --configure <options for configuration> <config> [<store> ...]
|
|
|
|
Options in the configuration can be modified via the command
|
|
line. The <config> and the optional <store> parameters define
|
|
what gets created or modified. The remaining parameters define
|
|
which values get set or modified.
|
|
|
|
To change settings of specific datastores, either invoke syncevolution
|
|
multiple times with exactly one <store> parameter or use the
|
|
``[<store>/]`` prefix described above for property assignments. ::
|
|
|
|
syncevolution --remove <config>
|
|
|
|
Deletes the configuration. If the <config> refers to a specific
|
|
peer, only that peer's configuration is removed. If it refers to
|
|
a context, that context and all peers and datastores defined inside
|
|
it are removed.
|
|
|
|
Note that there is no confirmation question. Neither local data
|
|
referenced by the configuration nor the content of log dirs are
|
|
deleted. ::
|
|
|
|
syncevolution --run <options for run> <config> [<store> ...]
|
|
|
|
Options can also be overridden for just the current run, without
|
|
changing the configuration. In order to prevent accidentally running a
|
|
sync session when a configuration change was intended, either
|
|
--configure or --run must be given explicitly if options are specified
|
|
on the command line. ::
|
|
|
|
syncevolution --status <config> [<store> ...]
|
|
|
|
Prints what changes were made locally since the last synchronization.
|
|
Depends on access to database dumps from the last run, so enabling the
|
|
``logdir`` property is recommended. ::
|
|
|
|
syncevolution --print-servers|--print-configs|--print-peers
|
|
syncevolution --print-config [--quiet] <config> [main|<store> ...]
|
|
syncevolution --print-sessions [--quiet] <config>
|
|
|
|
These commands print information about existing configurations. When
|
|
printing a configuration a short version without comments can be
|
|
selected with --quiet. When datastores are listed, only their
|
|
configuration is shown. `Main` instead or in combination with datastores
|
|
lists only the main peer configuration. ::
|
|
|
|
syncevolution --restore <session directory> --before|--after
|
|
[--dry-run] <config> <store> ...
|
|
|
|
This restores local data from the backups made before or after a
|
|
synchronization session. The --print-sessions command can be used to
|
|
find these backups. The datastore(s) have to be listed explicitly. There
|
|
is intentionally no default, because as with --remove there is no
|
|
confirmation question. With --dry-run, the restore is only simulated.
|
|
|
|
The session directory has to be specified explicitly with its path
|
|
name (absolute or relative to current directory). It does not have to
|
|
be one of the currently active log directories, as long as it contains
|
|
the right database dumps for the selected datastores.
|
|
|
|
A restore tries to minimize the number of item changes (see section
|
|
`Item Changes and Data Changes`_). This means that items that are
|
|
identical before and after the change will not be transmitted anew to
|
|
the peer during the next synchronization. If the peer somehow
|
|
needs to get a clean copy of all local items, then use ``--sync
|
|
refresh-from-local`` in the next run. ::
|
|
|
|
syncevolution --print-items <config> <store>
|
|
syncevolution [--delimiter <string>] --export <dir>|<file>|- [<config> [<store> [<luid> ...]]]
|
|
syncevolution [--delimiter <string>|none] --import <dir>|<file>|- [<config> <store>]
|
|
syncevolution --update <dir> <config> <store>
|
|
syncevolution [--delimiter <string>|none] --update <file>|- <config> <store> <luid> ...
|
|
syncevolution --delete-items <config> <store> (<luid> ... | *)
|
|
|
|
Restore depends on the specific format of the automatic backups
|
|
created by SyncEvolution. Arbitrary access to item data is provided
|
|
with additional options. <luid> here is the unique local identifier
|
|
assigned to each item in the datastore, transformed so that it contains
|
|
only alphanumeric characters, dash and underscore. A star * in
|
|
--delete-items selects all items for deletion. There are two ways
|
|
of specifying luids: either as additional parameters after the
|
|
config and datastore parameters (which may be empty in this case, but
|
|
must be given) or after the ``--luids`` keyword.
|
|
|
|
<config> and <store> may be given to define the database which is to
|
|
be used. If not given or not refering to an existing configuration
|
|
(which is not an error, due to historic reasons), the desired backend
|
|
must be given via the ``backend`` property, like this::
|
|
|
|
syncevolution --print-items backend=evolution-contacts
|
|
syncevolution --export - backend=evolution-contacts \
|
|
--luids pas-id-4E33F24300000006 pas-id-4E36DD7B00000007
|
|
|
|
The desired backend database can be chosen via ``database=<identifier>``.
|
|
See ``--print-databases``.
|
|
|
|
OPTIONS
|
|
=======
|
|
|
|
Here is a full description of all <options> that can be put in front
|
|
of the server name. Whenever an option accepts multiple values, a
|
|
question mark can be used to get the corresponding help text and/or
|
|
a list of valid values.
|
|
|
|
--sync|-s <mode>|?
|
|
Temporarily synchronize the active datastores in that mode. Useful
|
|
for a `refresh-from-local` or `refresh-from-remote` sync which
|
|
clears all data at one end and copies all items from the other.
|
|
|
|
**Warning:** `local` is the data accessed via the sync config
|
|
directly and `remote` is the data on the peer, regardless
|
|
where the data is actually stored physically.
|
|
|
|
--print-servers|--print-configs|--print-peers
|
|
Prints the names of all configured peers to stdout. There is no
|
|
difference between these options, the are just aliases.
|
|
|
|
--print-servers|--print-configs|--print-peers|-p
|
|
Prints the complete configuration for the selected <config>
|
|
to stdout, including up-to-date comments for all properties. The
|
|
format is the normal .ini format with datastore configurations in
|
|
different sections introduced with [<store>] lines. Can be combined
|
|
with --sync-property and --datastore-property to modify the configuration
|
|
on-the-fly. When one or more datastores are listed after the <config>
|
|
name on the command line, then only the configs of those datastores are
|
|
printed. `main` selects the main configuration instead of datastore
|
|
configurations. Using --quiet suppresses the comments for each property.
|
|
When setting a --template, then the reference configuration for
|
|
that peer is printed instead of an existing configuration.
|
|
|
|
\--print-sessions
|
|
Prints information about previous synchronization sessions for the
|
|
selected peer or context are printed. This depends on the ``logdir``
|
|
property. The information includes the log directory name (useful for
|
|
--restore) and the synchronization report. In combination with
|
|
--quiet, only the paths are listed.
|
|
|
|
--configure|-c
|
|
Modify the configuration files for the selected peer and/or datastores.
|
|
|
|
If no such configuration exists, then a new one is created using one
|
|
of the template configurations (see --template option). Choosing a
|
|
template sets most of the relevant properties for the peer and the
|
|
default set of datastores (see above for a list of those). Anything
|
|
specific to the user (like username/password) still has to be set
|
|
manually.
|
|
|
|
When creating a new configuration and listing datastores explicitly on the
|
|
command line, only those datastores will be set to active in the new
|
|
configuration, i.e. `syncevolution -c memotoo addressbook`
|
|
followed by `syncevolution memotoo` will only synchronize the
|
|
address book. The other datastores are created in a disabled state.
|
|
When modifying an existing configuration and datastores are specified,
|
|
then the datastore properties of only those datastores are modified.
|
|
|
|
By default, creating a config requires a template. Datastore names on the
|
|
command line must match those in the template. This allows catching
|
|
typos in the peer and datastore names. But it also prevents some advanced
|
|
use cases. Therefore it is possible to disable these checks in two ways::
|
|
|
|
- use `--template none` or
|
|
- specify all required sync and datastore properties that are normally
|
|
in the templates on the command line (syncURL, backend, ...)
|
|
|
|
--run|-r
|
|
To prevent accidental sync runs when a configuration change was
|
|
intended, but the `--configure` option was not used, `--run` must be
|
|
specified explicitly when sync or datastore properties are selected
|
|
on the command line and they are meant to be used during a sync
|
|
session triggered by the invocation.
|
|
|
|
\--migrate
|
|
In older SyncEvolution releases a different layout of configuration files
|
|
was used. Using --migrate will automatically migrate to the new
|
|
layout and rename the <config> into <config>.old to prevent accidental use
|
|
of the old configuration. WARNING: old SyncEvolution releases cannot
|
|
use the new configuration!
|
|
|
|
The switch can also be used to migrate a configuration in the current
|
|
configuration directory: this preserves all property values, discards
|
|
obsolete properties and sets all comments exactly as if the configuration
|
|
had been created from scratch. WARNING: custom comments in the
|
|
configuration are not preserved.
|
|
|
|
--migrate implies --configure and can be combined with modifying
|
|
properties.
|
|
|
|
\--print-items
|
|
Shows all existing items using one line per item using
|
|
the format "<luid>[: <short description>]". Whether the description
|
|
is available depends on the backend and the kind of data that it
|
|
stores.
|
|
|
|
\--export
|
|
Writes all items in the datastore or all items whose <luid> is
|
|
given into a directory if the --export parameter exists and is a
|
|
directory. The <luid> of each item is used as file name. Otherwise it
|
|
creates a new file under that name and writes the selected items
|
|
separated by the chosen delimiter string. stdout can be selected with
|
|
a dash.
|
|
|
|
The default delimiter (two line breaks) matches a blank line. As a special
|
|
case, it also matches a blank line with DOS line ending (line break,
|
|
carriage return, line break). This works for vCard 3.0 and iCalendar 2.0,
|
|
which never contain blank lines.
|
|
|
|
When exporting, the default delimiter will always insert two line
|
|
breaks regardless whether the items contain DOS line ends. As a
|
|
special case, the initial newline of a delimiter is skipped if the
|
|
item already ends in a newline.
|
|
|
|
\--import
|
|
Adds all items found in the directory or input file to the
|
|
datastore. When reading from a directory, each file is treated as one
|
|
item. Otherwise the input is split at the chosen delimiter. "none" as
|
|
delimiter disables splitting of the input.
|
|
|
|
\--update
|
|
Overwrites the content of existing items. When updating from a
|
|
directory, the name of each file is taken as its luid. When updating
|
|
from file or stdin, the number of luids given on the command line
|
|
must match with the number of items in the input.
|
|
|
|
\--delete-items
|
|
Removes the specified items from the datastore. Most backends print
|
|
some progress information about this, but besides that, no further
|
|
output is produced. Trying to remove an item which does not exist
|
|
typically leads to an ERROR message, but is not reflected in a
|
|
non-zero result of the command line invocation itself because the
|
|
situation is not reported as an error by backends (removal of
|
|
non-existent items is not an error in SyncML). Use a star \* instead
|
|
or in addition to listing individual luids to delete all items.
|
|
|
|
--sync-property|-y <property>=<value>|<property>=?|?
|
|
Overrides a datastore-independent configuration property for the
|
|
current synchronization run or permanently when --configure is used
|
|
to update the configuration. Can be used multiple times. Specifying
|
|
an unused property will trigger an error message.
|
|
|
|
--datastore-property|--source-property|-z <property>=<value>|<property>=?|?
|
|
Same as --sync-property, but applies to the configuration of all active
|
|
datastores. `--sync <mode>` is a shortcut for `--datastore-property sync=<mode>`.
|
|
|
|
--template|-l <peer name>|default|?<device>
|
|
Can be used to select from one of the built-in default configurations
|
|
for known SyncML peers. Defaults to the <config> name, so --template
|
|
only has to be specified when creating multiple different configurations
|
|
for the same peer, or when using a template that is named differently
|
|
than the peer. `default` is an alias for `memotoo` and can be
|
|
used as the starting point for servers which do not have a built-in
|
|
template.
|
|
|
|
A pseudo-random device ID is generated automatically. Therefore setting
|
|
the `deviceId` sync property is only necessary when manually recreating a
|
|
configuration or when a more descriptive name is desired.
|
|
|
|
The available templates for different known SyncML servers are listed when
|
|
using a single question mark instead of template name. When using the
|
|
`?<device>` format, a fuzzy search for a template that might be
|
|
suitable for talking to such a device is done. The matching works best
|
|
when using `<device> = <Manufacturer> <Model>`. If you don't know the
|
|
manufacturer, you can just keep it as empty. The output in this mode
|
|
gives the template name followed by a short description and a rating how well
|
|
the template matches the device (100% is best).
|
|
|
|
--status|-t
|
|
The changes made to local data since the last synchronization are
|
|
shown without starting a new one. This can be used to see in advance
|
|
whether the local data needs to be synchronized with the server.
|
|
|
|
--quiet|-q
|
|
Suppresses most of the normal output during a synchronization. The
|
|
log file still contains all the information.
|
|
|
|
--keyring[=<value>]|-k
|
|
A legacy option, now the same as setting the global keyring sync property.
|
|
When not specifying a value explicitly, "true" for "use some kind of
|
|
keyring" is implied. See "--sync-property keyring" for details.
|
|
|
|
--daemon[=yes/no]
|
|
By default, the SyncEvolution command line is executed inside the
|
|
syncevo-dbus-server process. This ensures that synchronization sessions
|
|
started by the command line do not conflict with sessions started
|
|
via some other means (GUI, automatically). For debugging purposes
|
|
or very special use cases (running a local sync against a server which
|
|
executes inside the daemon) it is possible to execute the operation
|
|
without the daemon (--daemon=no).
|
|
|
|
--help|-h
|
|
Prints usage information.
|
|
|
|
\--version
|
|
Prints the SyncEvolution version.
|
|
|
|
|
|
CONFIGURATION PROPERTIES
|
|
========================
|
|
|
|
This section lists predefined properties. Backends can add their own
|
|
properties at runtime if none of the predefined properties are
|
|
suitable for a certain setting. Those additional properties are not
|
|
listed here. Use ``--sync/datastore-property ?`` to get an up-to-date
|
|
list.
|
|
|
|
The predefined properties may also be interpreted slightly differently
|
|
by each backend and sync protocol. Sometimes this is documented in the
|
|
comment for each property, sometimes in the documentation of the
|
|
backend or sync protocol.
|
|
|
|
Properties are listed together with all recognized aliases (in those
|
|
cases where a property was renamed at some point), its default value,
|
|
sharing state (unshared/shared/global). Some properties must be
|
|
defined, which is marked with the word `required`.
|
|
|
|
Sync properties
|
|
---------------
|
|
syncURL (no default, unshared, required)
|
|
Identifies how to contact the peer,
|
|
best explained with some examples.
|
|
|
|
HTTP(S) SyncML servers::
|
|
|
|
http://example.com/sync
|
|
|
|
OBEX over Bluetooth uses the MAC address, with
|
|
the channel chosen automatically::
|
|
|
|
obex-bt://00:0A:94:03:F3:7E
|
|
|
|
If the automatism fails, the channel can also be specified::
|
|
|
|
obex-bt://00:0A:94:03:F3:7E+16
|
|
|
|
For peers contacting us via Bluetooth, the MAC address is
|
|
used to identify it before the sync starts. Multiple
|
|
urls can be specified in one syncURL property::
|
|
|
|
obex-bt://00:0A:94:03:F3:7E obex-bt://00:01:02:03:04:05
|
|
|
|
In the future this might be used to contact the peer
|
|
via one of several transports; right now, only the first
|
|
one is tried.
|
|
|
|
username (no default, unshared)
|
|
user name used for authorization with the SyncML server
|
|
|
|
password (no default, unshared)
|
|
password used for authorization with the peer;
|
|
in addition to specifying it directly as plain text, it can
|
|
also be read from the standard input or from an environment
|
|
variable of your choice::
|
|
|
|
plain text : password = <insert your password here>
|
|
ask : password = -
|
|
env variable: password = ${<name of environment variable>}
|
|
|
|
logdir (no default, shared)
|
|
full path to directory where automatic backups and logs
|
|
are stored for all synchronizations; if unset, then
|
|
"${XDG_CACHE_HOME}/syncevolution/<server>" (which
|
|
usually expands to ${HOME}/.cache/...) will be used;
|
|
if "none", then no backups of the databases are made and any
|
|
output is printed directly to the screen
|
|
|
|
loglevel (0, unshared)
|
|
level of detail for log messages:
|
|
- 0 (or unset) = INFO messages without log file, DEBUG with log file
|
|
- 1 = only ERROR messages
|
|
- 2 = also INFO messages
|
|
- 3 = also DEBUG messages
|
|
> 3 = increasing amounts of debug messages for developers
|
|
|
|
notifyLevel (3, unshared)
|
|
Level of detail for desktop notifications. Currently such
|
|
notifications are generated only for automatically started
|
|
sync sessions.
|
|
|
|
0 - suppress all notifications
|
|
1 - show only errors
|
|
2 - show information about changes and errors (in practice currently the same as level 3)
|
|
3 - show all notifications, including starting a sync
|
|
|
|
printChanges (TRUE, unshared)
|
|
enables or disables the detailed (and sometimes slow) comparison
|
|
of database content before and after a sync session
|
|
|
|
dumpData (TRUE, unshared)
|
|
enables or disables the automatic backup of database content
|
|
before and after a sync session (always enabled if printChanges is enabled)
|
|
|
|
maxlogdirs (10, shared)
|
|
Controls how many session directories are kept at most in the logdir.
|
|
Unless set to zero, SyncEvolution will remove old directories and
|
|
all their content to prevent the number of log directories from
|
|
growing beyond the given limit. It tries to be intelligent and will
|
|
remove sessions in which nothing interesting happened (no errors,
|
|
no data changes) in favor of keeping sessions where something
|
|
happened, even if those sessions are older.
|
|
|
|
autoSync (0, unshared)
|
|
Controls automatic synchronization. Currently,
|
|
automatic synchronization is done by running
|
|
a synchronization at regular intervals. This
|
|
may drain the battery, in particular when
|
|
using Bluetooth!
|
|
Because a peer might be reachable via different
|
|
transports at some point, this option provides
|
|
detailed control over which transports may
|
|
be used for automatic synchronization:
|
|
|
|
0
|
|
don't do auto sync
|
|
1
|
|
do automatic sync, using whatever transport
|
|
is available
|
|
http
|
|
only via HTTP transport
|
|
obex-bt
|
|
only via Bluetooth transport
|
|
http,obex-bt
|
|
pick one of these
|
|
|
|
autoSyncInterval (30M, unshared)
|
|
This is the minimum number of seconds since the start of
|
|
the last synchronization that has to pass before starting
|
|
an automatic synchronization. Can be specified using
|
|
a 1h30m5s format.
|
|
|
|
Before reducing this interval, consider that it will
|
|
increase resource consumption on the local and remote
|
|
side. Some SyncML server operators only allow a
|
|
certain number of sessions per day.
|
|
The value 0 has the effect of only running automatic
|
|
synchronization when changes are detected (not
|
|
implemented yet, therefore it basically disables
|
|
automatic synchronization).
|
|
|
|
autoSyncDelay (5M, unshared)
|
|
An automatic sync will not be started unless the peer
|
|
has been available for this duration, specified in seconds
|
|
or 1h30m5s format.
|
|
|
|
This prevents running a sync when network connectivity
|
|
is unreliable or was recently established for some
|
|
other purpose. It is also a heuristic that attempts
|
|
to predict how long connectivity be available in the
|
|
future, because it should better be available long
|
|
enough to complete the synchronization.
|
|
|
|
preventSlowSync (TRUE, unshared)
|
|
During a slow sync, the SyncML server must match all items
|
|
of the client with its own items and detect which ones it
|
|
already has based on properties of the items. This is slow
|
|
(client must send all its data) and can lead to duplicates
|
|
(when the server fails to match correctly).
|
|
It is therefore sometimes desirable to wipe out data on one
|
|
side with a refresh-from-client/server sync instead of doing
|
|
a slow sync.
|
|
When this option is enabled, slow syncs that could cause problems
|
|
are not allowed to proceed. Instead, the affected datastores are
|
|
skipped, allowing the user to choose a suitable sync mode in
|
|
the next run (slow sync selected explicitly, refresh sync).
|
|
The following situations are handled:
|
|
|
|
- running as client with no local data => unproblematic,
|
|
slow sync is allowed to proceed automatically
|
|
- running as client with local data => client has no
|
|
information about server, so slow sync might be problematic
|
|
and is prevented
|
|
- client has data, server asks for slow sync because all its data
|
|
was deleted (done by Memotoo and Mobical, because they treat
|
|
this as 'user wants to start from scratch') => the sync would
|
|
recreate all the client's data, even if the user really wanted
|
|
to have it deleted, therefore slow sync is prevented
|
|
|
|
useProxy (FALSE, unshared)
|
|
set to T to choose an HTTP proxy explicitly; otherwise the default
|
|
proxy settings of the underlying HTTP transport mechanism are used;
|
|
only relevant when contacting the peer via HTTP
|
|
|
|
proxyHost (no default, unshared)
|
|
proxy URL (``http://<host>:<port>``)
|
|
|
|
proxyUsername (no default, unshared)
|
|
authentication for proxy: username
|
|
|
|
proxyPassword (no default, unshared)
|
|
proxy password, can be specified in different ways,
|
|
see SyncML server password for details
|
|
|
|
clientAuthType (md5, unshared)
|
|
- empty or "md5" for secure method (recommended)
|
|
- "basic" for insecure method
|
|
|
|
This setting is only for debugging purpose and only
|
|
has an effect during the initial sync of a client.
|
|
Later it remembers the method that was supported by
|
|
the server and uses that. When acting as server,
|
|
clients contacting us can use both basic and md5
|
|
authentication.
|
|
|
|
RetryDuration (5M, unshared)
|
|
The total amount of time in seconds in which the SyncML
|
|
client tries to get a response from the server.
|
|
During this time, the client will resend messages
|
|
in regular intervals (RetryInterval) if no response
|
|
is received or the message could not be delivered due
|
|
to transport problems. When this time is exceeded
|
|
without a response, the synchronization aborts without
|
|
sending further messages to the server.
|
|
|
|
When acting as server, this setting controls how long
|
|
a client is allowed to not send a message before the
|
|
synchronization is aborted.
|
|
|
|
RetryInterval (2M, unshared)
|
|
The number of seconds between the start of SyncML message sending
|
|
and the start of the retransmission. If the interval has
|
|
already passed when a message send returns, the
|
|
message is resent immediately. Resending without
|
|
any delay will never succeed and therefore specifying 0
|
|
disables retries.
|
|
|
|
Servers cannot resend messages, so this setting has no
|
|
effect in that case.
|
|
|
|
The WebDAV backend also resends messages after a temporary
|
|
network error. It uses exponential backoff to determine when
|
|
the server is available again. This setting is divided by 24
|
|
to obtain the initial delay (default: 2m => 5s), which is then
|
|
doubled for each retry.
|
|
|
|
remoteIdentifier (no default, unshared)
|
|
the identifier sent to the remote peer for a server initiated sync.
|
|
if not set, deviceId will be used instead
|
|
|
|
PeerIsClient (FALSE, unshared)
|
|
Indicates whether this configuration is about a
|
|
client peer or server peer.
|
|
|
|
SyncMLVersion (no default, unshared)
|
|
On a client, the latest commonly supported SyncML version
|
|
is used when contacting a server. One of '1.0/1.1/1.2' can
|
|
be used to pick a specific version explicitly.
|
|
|
|
On a server, this option controls what kind of Server Alerted
|
|
Notification is sent to the client to start a synchronization.
|
|
By default, first the format from 1.2 is tried, then in case
|
|
of failure, the older one from 1.1. 1.2/1.1 can be set
|
|
explicitly, which disables the automatism.
|
|
|
|
Instead or in adddition to the version, several keywords can
|
|
be set in this property (separated by spaces or commas):
|
|
|
|
- NOCTCAP - avoid sending CtCap meta information
|
|
- NORESTART - disable the sync mode extension that SyncEvolution
|
|
client and server use to negotiate whether both sides support
|
|
running multiple sync iterations in the same session
|
|
- REQUESTMAXTIME=<time> - override the rate at which the
|
|
SyncML server sends preliminary replies while preparing
|
|
local storages in the background. This helps to avoid timeouts
|
|
in the SyncML client. Depends on multithreading.
|
|
This SyncEvolution binary is thread-safe and thus this feature
|
|
is enabled by default for HTTP servers, with a delay of 2 minutes
|
|
between messages. Other servers (Bluetooth, local sync) should not
|
|
need preliminary replies and the feature is disabled, although
|
|
it can be enabled by setting the time explicitly.
|
|
<time> can be specified like other durations in the config,
|
|
for example as REQUESTMAXTIME=2m.
|
|
|
|
Setting these flags should only be necessary as workaround for
|
|
broken peers.
|
|
|
|
PeerName (no default, unshared)
|
|
An arbitrary name for the peer referenced by this config.
|
|
Might be used by a GUI. The command line tool always uses the
|
|
the configuration name.
|
|
|
|
deviceId (no default, shared)
|
|
The SyncML server gets this string and will use it to keep track of
|
|
changes that still need to be synchronized with this particular
|
|
client; it must be set to something unique (like the pseudo-random
|
|
string created automatically for new configurations) among all clients
|
|
accessing the same server.
|
|
myFUNAMBOL also requires that the string starts with sc-pim-
|
|
|
|
remoteDeviceId (no default, unshared)
|
|
SyncML ID of our peer, empty if unknown; must be set only when
|
|
the peer is a SyncML client contacting us via HTTP.
|
|
Clients contacting us via OBEX/Bluetooth can be identified
|
|
either via this remoteDeviceId property or by their MAC
|
|
address, if that was set in the syncURL property.
|
|
|
|
If this property is empty and the peer synchronizes with
|
|
this configuration chosen by some other means, then its ID
|
|
is recorded here automatically and later used to verify that
|
|
the configuration is not accidentally used by a different
|
|
peer.
|
|
|
|
enableWBXML (TRUE, unshared)
|
|
use the more compact binary XML (WBXML) for messages between client and server;
|
|
not applicable when the peer is a SyncML client, because then the client
|
|
chooses the encoding
|
|
|
|
enableRefreshSync (FALSE, unshared)
|
|
Use the more advanced refresh-from-server sync mode to
|
|
implement the refresh-from-remote operation. Some SyncML
|
|
servers do not support this. Therefore the default is to
|
|
delete local data before doing a slow sync, which has the
|
|
same effect. However, some servers work better when they
|
|
are told explicitly that the sync is a refresh sync. For
|
|
example, Funambol's One Media server rejects too many slow
|
|
syncs in a row with a 417 'retry later' error.
|
|
|
|
maxMsgSize (150000, unshared), maxObjSize (4000000, unshared)
|
|
The maximum size of each message can be set (maxMsgSize) and the
|
|
peer can be told to never sent items larger than a certain
|
|
threshold (maxObjSize). Presumably the peer has to truncate or
|
|
skip larger items. Sizes are specified as number of bytes.
|
|
|
|
SSLServerCertificates (/etc/ssl/certs/ca-certificates.crt:/etc/pki/tls/certs/ca-bundle.crt:/usr/share/ssl/certs/ca-bundle.crt, unshared)
|
|
A string specifying the location of the certificates
|
|
used to authenticate the server. When empty, the
|
|
system's default location will be searched.
|
|
|
|
SSL support when acting as HTTP server is implemented
|
|
by the HTTP server frontend, not with these properties.
|
|
|
|
SSLVerifyServer (TRUE, unshared)
|
|
The client refuses to establish the connection unless
|
|
the server presents a valid certificate. Disabling this
|
|
option considerably reduces the security of SSL
|
|
(man-in-the-middle attacks become possible) and is not
|
|
recommended.
|
|
|
|
SSLVerifyHost (TRUE, unshared)
|
|
The client refuses to establish the connection unless the
|
|
server's certificate matches its host name. In cases where
|
|
the certificate still seems to be valid it might make sense
|
|
to disable this option and allow such connections.
|
|
|
|
WebURL (no default, unshared)
|
|
The URL of a web page with further information about the server.
|
|
Used only by the GUI.
|
|
|
|
IconURI (no default, unshared)
|
|
The URI of an icon representing the server graphically.
|
|
Should be a 48x48 pixmap or a SVG (preferred).
|
|
Used only by the GUI.
|
|
|
|
ConsumerReady (FALSE, unshared)
|
|
Set to true in a configuration template to indicate
|
|
that the server works well enough and is available
|
|
for normal users. Used by the GUI to limit the choice
|
|
of configurations offered to users.
|
|
Has no effect in a user's server configuration.
|
|
|
|
peerType (no default, unshared)
|
|
Defines what a configuration is meant to be used for.
|
|
Used in templates and the resulting configs to tell a GUI
|
|
that special handling may be necessary. GUIs should ignore
|
|
unknown types.
|
|
The traditional SyncML configs use an empty value.
|
|
"WebDAV" is used for the WebDAV side in a local synchronization.
|
|
|
|
defaultPeer (no default, global)
|
|
the peer which is used by default in some frontends, like the sync-UI
|
|
|
|
keyring (yes, global)
|
|
Explicitly selects a certain safe password storage.
|
|
Depending on how SyncEvolution was compiled and installed
|
|
the following values are possible:
|
|
|
|
GNOME
|
|
GNOME Keyring
|
|
KDE
|
|
KWallet
|
|
yes/true/1
|
|
pick one automatically
|
|
no/false/0
|
|
store passwords in SyncEvolution config files
|
|
|
|
If unset, the default is to pick one automatically if support
|
|
for any kind of password storage was enabled and use the config files
|
|
otherwise. When choosing automatically, GNOME keyring is tried
|
|
first because distinguishing between KDE and GNOME sessions
|
|
automatically is tricky.
|
|
|
|
Note that using this option applies to *all* passwords in
|
|
a configuration and that the --keyring command line option
|
|
is merely an alias for setting the global property, so setting
|
|
a single password as follows sets both `keyring` and
|
|
`proxyPasswords`, and also moves the other passwords into the
|
|
keyring, even if they were not stored there already:
|
|
|
|
--keyring --configure proxyPassword=foo
|
|
|
|
When passwords were stored in a safe storage, their value is set to a single
|
|
hyphen ("-") in the configuration. This means that when running a
|
|
synchronization without using the storage, the password has to be
|
|
entered interactively. The --print-config output always shows "-" instead
|
|
of retrieving the password from the keyring.
|
|
|
|
Datastore properties
|
|
--------------------
|
|
sync (disabled, unshared, required)
|
|
Requests a certain synchronization mode when initiating a sync:
|
|
|
|
two-way
|
|
only send/receive changes since last sync
|
|
slow
|
|
exchange all items
|
|
refresh-from-remote
|
|
discard all local items and replace with
|
|
the items on the peer
|
|
refresh-from-local
|
|
discard all items on the peer and replace
|
|
with the local items
|
|
one-way-from-remote
|
|
transmit changes from peer
|
|
one-way-from-local
|
|
transmit local changes
|
|
local-cache-slow (server only)
|
|
mirror remote data locally, transferring all data
|
|
local-cache-incremental (server only)
|
|
mirror remote data locally, transferring only changes;
|
|
falls back to local-cache-slow automatically if necessary
|
|
disabled (or none)
|
|
synchronization disabled
|
|
|
|
refresh/one-way-from-server/client are also supported. Their use is
|
|
discouraged because the direction of the data transfer depends
|
|
on the role of the local side (can be server or client), which is
|
|
not always obvious.
|
|
|
|
When accepting a sync session in a SyncML server (HTTP server), only
|
|
datastores with sync != disabled are made available to the client,
|
|
which chooses the final sync mode based on its own configuration.
|
|
When accepting a sync session in a SyncML client (local sync with
|
|
the server contacting SyncEvolution on a device), the sync mode
|
|
specified in the client is typically overriden by the server.
|
|
|
|
uri (no default, unshared)
|
|
this is appended to the server's URL to identify the
|
|
server's database; if unset, the datastore name is used as
|
|
fallback
|
|
|
|
backend (select backend, shared)
|
|
Specifies the SyncEvolution backend and thus the
|
|
data which is synchronized by this datastore. Each
|
|
backend may support multiple databases (see 'database'
|
|
property), different formats inside that database (see
|
|
'databaseFormat'), and different formats when talking to
|
|
the sync peer (see 'syncFormat' and 'forceSyncFormat').
|
|
|
|
A special 'virtual' backend combines several other
|
|
datastores and presents them as one set of items
|
|
to the peer. For example, Nokia phones typically
|
|
exchange tasks and events as part of one set of
|
|
calendar items.
|
|
|
|
Right now such a virtual backend is limited to
|
|
combining one calendar datastore with events and one
|
|
task datastore. They have to be specified in the
|
|
``database`` property, typically like this:
|
|
``calendar,todo``
|
|
|
|
Different datastores combined in one virtual datastore must
|
|
have a common format. As with other backends,
|
|
the preferred format can be influenced via the 'syncFormat'
|
|
attribute.
|
|
|
|
Here's the full list of potentially supported backends,
|
|
valid 'backend' values for each of them, and possible
|
|
formats. Note that SyncEvolution installations usually
|
|
support only a subset of the backends; that's why e.g.
|
|
"addressbook" is unambiguous although there are multiple
|
|
address book backends.
|
|
|
|
syncFormat (no default, unshared)
|
|
When there are alternative formats for the same data,
|
|
each side of a sync offers all that it supports and marks one as
|
|
preferred. If set, this property overrides the format
|
|
that would normally be marked as preferred by a backend.
|
|
|
|
Valid values depend on the backend. Here are some examples:
|
|
contacts - text/vcard = vCard 3.0 format
|
|
text/x-vcard = legacy vCard 2.1 format
|
|
calendar - text/calendar = iCalendar 2.0 format
|
|
text/x-vcalendar = legacy vCalendar 1.0 format
|
|
|
|
Errors while starting to sync and parsing and/or storing
|
|
items on either client or server can be caused by a mismatch between
|
|
the sync format and uri at the peer.
|
|
|
|
forceSyncFormat (FALSE, unshared)
|
|
Some peers get confused when offered multiple choices
|
|
for the sync format or pick the less optimal one.
|
|
In such a case, setting this property enforces that the
|
|
preferred format specified with 'syncFormat' is
|
|
really used.
|
|
|
|
database = evolutionsource (no default, shared)
|
|
Picks one of the backend's databases:
|
|
depending on the backend, one can set the name
|
|
and/or a unique identifier.
|
|
|
|
Most backends have a default database,
|
|
like for example the system address book.
|
|
Not setting this property selects that default
|
|
database.
|
|
|
|
If the backend is a virtual data datastore,
|
|
this field must contain comma seperated list of
|
|
sub datasources actually used to store data.
|
|
If your sub datastore has a comma in name, you
|
|
must prevent taht comma from being mistaken as the
|
|
separator by preceding it with a backslash, like this:
|
|
``database=Source1PartA\,PartB,Source2\\Backslash``
|
|
|
|
To get a full list of available databases,
|
|
run ``syncevolution --print-databases``. The name
|
|
is printed in front of the colon, followed by
|
|
an identifier in brackets. Usually the name is unique and can be
|
|
used to reference the data datastore. The default
|
|
data datastore is marked with <default> at the end
|
|
of the line, if there is a default.
|
|
|
|
databaseFormat (no default, shared)
|
|
Defines the data format to be used by the backend for its
|
|
own storage. Typically backends only support one format
|
|
and ignore this property, but for example the file backend
|
|
uses it. See the 'backend' property for more information.
|
|
|
|
databaseUser = evolutionuser (no default, shared), databasePassword = evolutionpassword (no default, shared)
|
|
authentication for backend data datastore; password can be specified
|
|
in multiple ways, see SyncML server password for details
|
|
|
|
Warning: setting database user/password in cases where it is not
|
|
needed, as for example with local Evolution calendars and addressbooks,
|
|
can cause the Evolution backend to hang.
|
|
|
|
|
|
EXAMPLES
|
|
========
|
|
|
|
List the known configuration templates::
|
|
|
|
syncevolution --template ?
|
|
|
|
Create a new configuration, using the existing Memotoo template::
|
|
|
|
syncevolution --configure \
|
|
username=123456 \
|
|
"password=!@#ABcd1234" \
|
|
memotoo
|
|
|
|
Note that putting passwords into the command line, even for
|
|
short-lived processes as the one above, is a security risk in shared
|
|
environments, because the password is visible to everyone on the
|
|
machine. To avoid this, remove the password from the command above,
|
|
then add the password to the right config.ini file with a text editor.
|
|
This command shows the directory containing the file::
|
|
|
|
syncevolution --print-configs
|
|
|
|
Review configuration::
|
|
|
|
syncevolution --print-config memotoo
|
|
|
|
Synchronize all datastores::
|
|
|
|
syncevolution memotoo
|
|
|
|
Deactivate all datastores::
|
|
|
|
syncevolution --configure \
|
|
sync=none \
|
|
memotoo
|
|
|
|
Activate address book synchronization again, using the --sync shortcut::
|
|
|
|
syncevolution --configure \
|
|
--sync two-way \
|
|
memotoo addressbook
|
|
|
|
Change the password for a configuration::
|
|
|
|
syncevolution --configure \
|
|
password=foo \
|
|
memotoo
|
|
|
|
Set up another configuration for under a different account, using
|
|
the same default databases as above::
|
|
|
|
syncevolution --configure \
|
|
username=joe \
|
|
password=foo \
|
|
--template memotoo \
|
|
memotoo_joe
|
|
|
|
Set up another configuration using the same account, but different
|
|
local databases (can be used to simulate synchronizing between two
|
|
clients, see `Exchanging Data`_::
|
|
|
|
syncevolution --configure \
|
|
username=123456 \
|
|
password=!@#ABcd1234" \
|
|
sync=none \
|
|
memotoo@other
|
|
|
|
syncevolution --configure \
|
|
database=<name of other address book> \
|
|
@other addressbook
|
|
|
|
syncevolution --configure \
|
|
sync=two-way \
|
|
memotoo@other addressbook
|
|
|
|
syncevolution memotoo
|
|
syncevolution memotoo@other
|
|
|
|
Migrate a configuration from the <= 0.7 format to the current one
|
|
and/or updates the configuration so that it looks like configurations
|
|
created anew with the current syncevolution::
|
|
|
|
syncevolution --migrate memotoo
|
|
|
|
|
|
.. _local sync:
|
|
|
|
Synchronization beyond SyncML
|
|
=============================
|
|
|
|
In the simple examples above, SyncEvolution exchanges data with
|
|
servers via the SyncML protocol. Starting with release 1.2,
|
|
SyncEvolution also supports other protocols like CalDAV and
|
|
CardDAV.
|
|
|
|
These protocols are implemented in backends which behave like local
|
|
datastores. SyncEvolution then synchronizes data between a pair of
|
|
backends. Because the entire sync logic (matching of items, merging)
|
|
is done locally by SyncEvolution, this mode of operation is called
|
|
*local sync*.
|
|
|
|
Some examples of things that can be done with local sync:
|
|
|
|
* synchronize events with a CalDAV server and contacts with a CardDAV server
|
|
* mirror a local database as items in a directory, with format conversion
|
|
and one-way or two-way data transfer (export vs. true syncing)
|
|
|
|
Because local sync involves two sides, two sync configurations are
|
|
needed. One is called the *target config*. Traditionally, this really
|
|
was a configuration called ``target-config``, for example
|
|
``target-config@google``. Using this particular name is no longer required.
|
|
|
|
The target config can hold properties which apply to all datastores
|
|
inside its context, like user name, password and URL for the server
|
|
(more on that below) and sync settings (like logging and data
|
|
backups). Once configured, the target config can be used to
|
|
list/import/export/update items via the SyncEvolution command line. It
|
|
cannot be used for synchronization because it does not defined what
|
|
the items are supposed to be synchronized with.
|
|
|
|
For synchronization, a second *originating config* is needed. This config has
|
|
the same role as the traditional SyncML sync configs and is typically
|
|
defined in the same implicit ``@default`` context as those
|
|
configs. All configs in that context use the same local data, thus turning
|
|
that local data into the hub through with data flows to all peers that the
|
|
host is configured to sync with.
|
|
|
|
A sync config becomes an originating config in a local sync by setting
|
|
the ``syncURL`` to the special URL ``local://[<target config
|
|
name>][@<some context name>]``. This selects the target config to
|
|
sync with. If the target config name is left out, the actual string
|
|
``target-config`` is used as name. The context can be omitted if the
|
|
target config name is unique. Originating and target config can be in
|
|
the same context. Care must be taken to not use a datastore more than
|
|
once in a local sync.
|
|
|
|
In addition, ``peerIsClient=1`` must be set in the originating config,
|
|
because SyncEvolution only supports running the SyncML client on the
|
|
target side. It makes sense to use the local databases on
|
|
originating side, because that side requires more frequent access to
|
|
the data.
|
|
|
|
The originating config defines the database pairs, either implicitly
|
|
(by using the same datastore names on both sides, which is possible when
|
|
different contexts are used) or explicitly (via the `uri` properties
|
|
set for the datastores on the originating side). The originating config
|
|
also defines the ``sync`` mode for each pair. ``uri`` and ``sync``
|
|
values on the target side are ignored and do not have to be specified.
|
|
|
|
As a special case, datastores used in combination with the target config
|
|
may access the credentials and ``syncURL`` stored there as fallback when
|
|
nothing was specified for the datastores directly. This makes sense for
|
|
the WebDAV and ActiveSync backends where the credentials are typically
|
|
the same and (depending on the web server) the same start URL can be
|
|
used to find calendar and contact databases.
|
|
|
|
**Warning:** when setting password for the target config and using a
|
|
keyring, a ``syncURL`` or a unique ``remoteDeviceID`` string must be
|
|
set, because they are needed to identify the host in the keyring.
|
|
|
|
If this feature is not used, the ``syncURL`` could be left empty because
|
|
local sync itself does not use it. However, the command line expects
|
|
it to be set to ``none`` explicitly to detect typos.
|
|
|
|
**Warning:** because the client in the local sync starts the sync,
|
|
``preventSlowSync=0`` must be set in the target config to have an effect.
|
|
|
|
|
|
CalDAV and CardDAV
|
|
==================
|
|
|
|
This section explains how to use local syncing for CalDAV and
|
|
CardDAV. Both protocols are based on WebDAV and are provided by the
|
|
same backend. They share ``username/password/syncURL`` properties
|
|
defined in their target config.
|
|
|
|
The credentials must be provided if the server is password
|
|
protected. The ``syncURL`` is optional if the ``username`` is an email
|
|
address and the server supports auto-discovery of its CalDAV and/or
|
|
CardDAV services (using DNS SRV entries, ``.well-known`` URIs, properties
|
|
of the current principal, ...).
|
|
|
|
Alternatively, credentials can also be set in the ``databaseUser`` and
|
|
``databasePassword`` properties of the datastore. The downside is that these
|
|
values have to be set for each datastore and cannot be shared. The advantage
|
|
is that, in combination with setting ``database``, such datastores can be
|
|
used as part of a normal SyncML server or client sync config. SyncEvolution
|
|
then reads and writes data directly from the server and exchanges it
|
|
via SyncML with the peer that is defined in the sync config.
|
|
|
|
The ``database`` property of each datastore can be set to the URL of a
|
|
specific *collection* (= database in WebDAV terminology). If not set,
|
|
then the WebDAV backend first locates the server based on ``username``
|
|
or ``syncURL`` and then scans it for the default event resp. contact
|
|
collection. This is done once in the initial synchronization. At the end
|
|
of a successful synchroniation, the automatic choice is made permanent
|
|
by setting the ``database`` property.
|
|
|
|
**Warning:** the protocols do not uniquely identify this default
|
|
collection. The backend tries to make an educated guess, but it might
|
|
pick the wrong one if the server provides more than one address book
|
|
or calendar. It is safer to scan for collections manually with
|
|
``--print-databases`` and then use the URL of the desired collection
|
|
as value of ``database``.
|
|
|
|
To scan for collections, use::
|
|
|
|
syncevolution --print-databases \
|
|
backend=<caldav or carddav> \
|
|
username=<email address or user name> \
|
|
"password=!@#ABcd1234" \
|
|
syncURL=<base URL of server, if server auto-discovery is not supported>
|
|
|
|
Configuration templates for Google Calendar/Contacts, Yahoo Calendar and a
|
|
generic CalDAV/CardDAV server are included in SyncEvolution. The Yahoo
|
|
template also contains an entry for contact synchronization, but using
|
|
it is not recommended due to known server-side issues.
|
|
|
|
The following commands set up synchronization with a generic WebDAV
|
|
server that supports CalDAV, CardDAV and scanning starting at the
|
|
root of the server. ::
|
|
|
|
# configure target config
|
|
syncevolution --configure \
|
|
--template webdav \
|
|
syncURL=http://example.com \
|
|
username=123456 \
|
|
"password=!@#ABcd1234" \
|
|
target-config@webdav
|
|
|
|
# configure sync config
|
|
syncevolution --configure \
|
|
--template SyncEvolution_Client \
|
|
syncURL=local://@webdav \
|
|
username= \
|
|
password= \
|
|
webdav \
|
|
calendar addressbook
|
|
|
|
# initial slow sync
|
|
syncevolution --sync slow webdav
|
|
|
|
# incremental sync
|
|
syncevolution webdav
|
|
|
|
Here are some alternative ways of configuring the target config::
|
|
|
|
# A) Server supports DNS auto-discovery via domain name in the username.
|
|
syncevolution --configure \
|
|
--template webdav \
|
|
username=123456@example.com \
|
|
"password=!@#ABcd1234" \
|
|
target-config@webdav
|
|
|
|
# B) Explicitly specify collections (from server documentation or --print-databases).
|
|
# The 'calendar' and 'addressbook' names are the ones expected by the sync config
|
|
# above, additional datastores can also be configured and/or the names can be changed.
|
|
syncevolution --configure \
|
|
username=123456 \
|
|
"password=!@#ABcd1234" \
|
|
--template none \
|
|
syncURL=http://example.com \
|
|
addressbook/backend=carddav \
|
|
addressbook/database=http://example.com/addressbooks/123456/ \
|
|
calendar/backend=caldav \
|
|
calendar/database=http://example.com/calendar/123456/ \
|
|
target-config@webdav \
|
|
calendar addressbook
|
|
|
|
When creating these target configs, the command line tool tries to
|
|
verify that the datastores really work and (in the case of --template
|
|
webdav) will enable only datastores which really work. This involves
|
|
contacting the WebDAV server.
|
|
|
|
Finally, here is how the ``@webdav`` context needs to be configured so that SyncML
|
|
clients or servers can be added to it::
|
|
|
|
# configure datastores
|
|
syncevolution --configure \
|
|
databaseUser=123456 \
|
|
"databasePassword=!@#ABcd1234" \
|
|
addressbook/backend=carddav \
|
|
addressbook/database=http://example.com/addressbooks/123456/ \
|
|
calendar/backend=caldav \
|
|
calendar/database=http://example.com/calendar/123456/ \
|
|
@webdav \
|
|
calendar addressbook
|
|
|
|
# configure one peer (Memotoo in this example):
|
|
syncevolution --configure \
|
|
username=654321 \
|
|
password=^749@2524 \
|
|
memotoo@webdav
|
|
|
|
# sync
|
|
syncevolution --sync slow memotoo@webdav
|
|
|
|
|
|
Google + OAuth
|
|
--------------
|
|
|
|
For Google there is no common start URL for CalDAV and CardDAV,
|
|
therefore the "Google" template lists all that may be relevant and the
|
|
setup is very similar to the generic ``webdav`` case, except that the
|
|
syncURL does not have to be specified::
|
|
|
|
# configure target config
|
|
syncevolution --configure \
|
|
--template google \
|
|
username=john.doe@gmail.com \
|
|
"password=!@#ABcd1234" \
|
|
target-config@google
|
|
|
|
# configure sync config
|
|
syncevolution --configure \
|
|
--template SyncEvolution_Client \
|
|
syncURL=local://@google \
|
|
username= \
|
|
password= \
|
|
google \
|
|
calendar addressbook
|
|
|
|
# initial slow sync
|
|
syncevolution --sync slow google
|
|
|
|
# incremental sync
|
|
syncevolution google
|
|
|
|
If your Google account is configured to use two-factor login, then you
|
|
need to create an application specific password for SyncEvolution. See
|
|
https://support.google.com/mail/answer/1173270
|
|
|
|
Google already announced that they will turn off support for logging
|
|
into their CalDAV/CardDAV services with plain username/password
|
|
credentials. SyncEvolution supports the new login method, OAuth, but
|
|
it depends on additional components to implement OAuth: GNOME Online
|
|
Accounts, Ubuntu Online Accounts, or gSSO.
|
|
|
|
Support for GNOME Online Accounts (GOA) is compiled into
|
|
syncevolution.org binaries and therefore documented here. For
|
|
instructions regarding binaries shipped by distributions please
|
|
consult the documentation provided by the distribution or search the
|
|
web.
|
|
|
|
For Google Calendar, GOA >= 3.8 is required. For Google Contacts, GOA
|
|
3.8 may work if it was patched by the distribution (as done in Debian
|
|
Jessie), otherwise a version >= 3.10 is required.
|
|
|
|
Use the GNOME Control Center to create an account for Google. It is
|
|
not necessary to enable any of the data categories. That would turn on
|
|
access in other GNOME apps (for example, Evolution), whereas
|
|
SyncEvolution's use of the account is configured separately via the
|
|
SyncEvolution command line.
|
|
|
|
When configuring SyncEvolution for Google, follow the instructions
|
|
above with ``username=goa:<Google email address>`` and empty password.
|
|
If the email address does not uniquely identify the GOA account,
|
|
the SyncEvolution command line will provide a list of accounts to choose
|
|
from.
|
|
|
|
|
|
NOTES
|
|
=====
|
|
|
|
Exchanging Data
|
|
---------------
|
|
|
|
SyncEvolution transmits address book entries as vCard 2.1 or 3.0
|
|
depending on the sync format chosen in the configuration. Evolution uses
|
|
3.0 internally, so SyncEvolution converts between the two formats as
|
|
needed. Calendar items and tasks can be sent and received in iCalendar
|
|
2.0 as well as vCalendar 1.0, but vCalendar 1.0 should be avoided if
|
|
possible because it cannot represent all data that Evolution stores.
|
|
|
|
.. note:: The Evolution backends are mentioned as examples;
|
|
the same applies to other datastores.
|
|
|
|
How the server stores the items depends on its implementation and
|
|
configuration. To check which data is preserved, one can use this
|
|
procedure (described for contacts, but works the same way for
|
|
calendars and tasks):
|
|
|
|
1. synchronize the address book with the server
|
|
2. create a new address book in Evolution and view it in Evolution
|
|
once (the second step is necessary in at least Evolution 2.0.4
|
|
to make the new address book usable in SyncEvolution)
|
|
3. add a configuration for that second address book and the
|
|
same URI on the SyncML server, see EXAMPLES_ above
|
|
4. synchronize again, this time using the other datastore
|
|
|
|
Now one can either compare the address books in Evolution or do that
|
|
automatically, described here for contacts:
|
|
|
|
- save the complete address books: mark all entries, save as vCard
|
|
- invoke `synccompare` with two file names as arguments and it will
|
|
normalize and compare them automatically
|
|
|
|
Normalizing is necessary because the order of cards and their
|
|
properties as well as other minor formatting aspects may be
|
|
different. The output comes from a side-by-side comparison, but
|
|
is augmented by the script so that the context of each change
|
|
is always the complete item that was modified. Lines or items
|
|
following a ">" on the right side were added, those on the
|
|
left side followed by a "<" were removed, and those with
|
|
a "|" between text on the left and right side were modified.
|
|
|
|
The automatic unit testing (see HACKING) contains a `testItems`
|
|
test which verifies the copying of special entries using the
|
|
same method.
|
|
|
|
Modifying one of the address books or even both at the same time and
|
|
then synchronizing back and forth can be used to verify that
|
|
SyncEvolution works as expected. If you do not trust SyncEvolution or
|
|
the server, then it is prudent to run these checks with a copy of the
|
|
original address book. Make a backup of the .evolution/addressbook
|
|
directory.
|
|
|
|
Item Changes and Data Changes
|
|
-----------------------------
|
|
|
|
SyncML clients and servers consider each entry in a database as one
|
|
item. Items can be added, removed or updated. This is the item change
|
|
information that client and server exchange during a normal,
|
|
incremental synchronization.
|
|
|
|
If an item is saved, removed locally, and reimported, then this is
|
|
usually reported to a peer as "one item removed, one added" because
|
|
the information available to SyncEvolution is not sufficient to
|
|
determine that this is in fact the same item. One exception are
|
|
iCalendar 2.0 items with their globally unique ID: the modification
|
|
above will be reported to the server as "one item updated".
|
|
|
|
That is better, but still not quite correct because the content of the
|
|
item has not changed, only the meta information about it which is used
|
|
to detect changes. This cannot be avoided without creating additional
|
|
overhead for normal synchronizations.
|
|
|
|
SyncEvolution reports *item changes* (the number of added, removed and
|
|
updated items) as well as *data changes*. These data changes are
|
|
calculated by comparing database dumps using the `synccompare` tool.
|
|
Because this data comparison ignores information about which data
|
|
belongs to which item, it is able to detect that re-adding an item
|
|
that was removed earlier does not change the data, in contrast to the
|
|
item changes. On the other hand, removing one item and adding a
|
|
different one may look like updating just one item.
|
|
|
|
Automatic Backups and Logging
|
|
-----------------------------
|
|
|
|
To support recovery from a synchronization which damaged the
|
|
local data or modified it in an unexpected way, SyncEvolution
|
|
can create the following files during a synchronization:
|
|
|
|
- a dump of the data in a format which can be restored by
|
|
SyncEvolution, usually a single file per item containing
|
|
in a standard text format (VCARD/VCALENDAR)
|
|
- a full log file with debug information
|
|
- another dump of the data after the synchronization for
|
|
automatic comparison of the before/after state with
|
|
`synccompare`
|
|
|
|
If the sync configuration property ``logdir`` is set, then
|
|
a new directory will be created for each synchronization
|
|
in that directory, using the format `<peer>-<yyyy>-<mm>-<dd>-<hh>-<mm>[-<seq>]`
|
|
with the various fields filled in with the time when the
|
|
synchronization started. The sequence suffix will only be
|
|
used when necessary to make the name unique. By default,
|
|
SyncEvolution will never delete any data in that log
|
|
directory unless explicitly asked to keep only a limited
|
|
number of previous log directories.
|
|
|
|
This is done by setting the ``maxlogdirs`` limit to something
|
|
different than the empty string and 0. If a limit is set,
|
|
then SyncEvolution will only keep that many log directories
|
|
and start removing the "less interesting" ones when it reaches
|
|
the limit. Less interesting are those where no data changed
|
|
and no error occurred.
|
|
|
|
To avoid writing any additional log file or database dumps during
|
|
a synchronization, the ``logdir`` can be set to ``none``. To reduce
|
|
the verbosity of the log, set ``loglevel``. If not set or 0, then
|
|
the verbosity is set to 3 = DEBUG when writing to a log file and
|
|
2 = INFO when writing to the console directly. To debug issues
|
|
involving data conversion, level 4 also dumps the content of
|
|
items into the log.
|
|
|
|
ENVIRONMENT
|
|
===========
|
|
|
|
The following environment variables control where SyncEvolution finds
|
|
files and other aspects of its operations.
|
|
|
|
http_proxy
|
|
Overrides the proxy settings temporarily. Setting it to an empty value
|
|
disables the normal proxy settings.
|
|
|
|
HOME/XDG_CACHE_HOME/XDG_CONFIG_HOME
|
|
SyncEvolution follows the XDG_ desktop standard for its files. By default,
|
|
`$HOME/.config/syncevolution` is the location for configuration files.
|
|
`$HOME/.cache/syncevolution` holds session directories with log files and
|
|
database dumps.
|
|
|
|
.. _XDG: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
|
|
|
|
SYNCEVOLUTION_DEBUG
|
|
Setting this to any value disables the filtering of stdout and stderr
|
|
that SyncEvolution employs to keep noise from system libraries out
|
|
of the command line output.
|
|
|
|
SYNCEVOLUTION_GNUTLS_DEBUG
|
|
Enables additional debugging output when using the libsoup HTTP transport library.
|
|
|
|
SYNCEVOLUTION_DATA_DIR
|
|
Overrides the default path to the bluetooth device lookup table,
|
|
normally `/usr/lib/syncevolution/`.
|
|
|
|
SYNCEVOLUTION_BACKEND_DIR
|
|
Overrides the default path to plugins, normally `/usr/lib/syncevolution/backends`.
|
|
|
|
SYNCEVOLUTION_LIBEXEC_DIR
|
|
Overrides the path where additional helper executables are found, normally
|
|
`/usr/libexec`.
|
|
|
|
SYNCEVOLUTION_LOCALE_DIR
|
|
Overrides the path to directories with the different translations,
|
|
normally `/usr/share/locale`.
|
|
|
|
SYNCEVOLUTION_TEMPLATE_DIR
|
|
Overrides the default path to template files, normally
|
|
`/usr/share/syncevolution/templates`.
|
|
|
|
SYNCEVOLUTION_XML_CONFIG_DIR
|
|
Overrides the default path to the Synthesis XML configuration files, normally
|
|
`/usr/share/syncevolution/xml`. These files are merged into one configuration
|
|
each time the Synthesis SyncML engine is started as part of a sync session.
|
|
|
|
Note that in addition to this directory, SyncEvolution also always
|
|
searches for configuration files inside `$HOME/.config/syncevolution-xml`.
|
|
Files with the same relative path and name as in `/usr/share/syncevolution/xml`
|
|
override those files, others extend the final configuration.
|
|
|
|
BUGS
|
|
====
|
|
|
|
See `known issues`_ and the `support`_ web page for more information.
|
|
|
|
.. _known issues: http://syncevolution.org/documentation/known-issues
|
|
.. _support: http://syncevolution.org/support
|
|
|
|
SEE ALSO
|
|
========
|
|
|
|
http://syncevolution.org
|
|
|
|
AUTHORS
|
|
=======
|
|
|
|
:Main developer:
|
|
Patrick Ohly <patrick.ohly@intel.com>, http://www.estamos.de
|
|
:Contributors:
|
|
http://syncevolution.org/about/contributors
|
|
:To contact the project publicly (preferred):
|
|
syncevolution@syncevolution.org
|
|
:Intel-internal team mailing list (confidential):
|
|
syncevolution@lists.intel.com
|