Search form

SyncEvolution Usage

This page applies to the command line interface as included in SyncEvolution >= 1.5. The same text is also available as a man page in most SyncEvolution installations starting with release 1.0. See the built-in --help output for more information, in particular about configuration options. There are also GUIs.

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):

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

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

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 not thread-safe and thus this feature
is disabled by default, although it can be enabled if absolutely
needed 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.

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.

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.

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

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):

synchronize the address book with the server

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)

add a configuration for that second address book and the
same URI on the SyncML server, see EXAMPLES above

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.

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.

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.