Provided by: syncevolution_1.5-0ubuntu12_amd64 
NAME
SyncEvolution - synchronize personal information management data
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.
syncInterval (no default, shared)
Defines the number of days before the current date that should be use as start date
for the calendar sync. This can be set do limit the number of events imported from
the source calendar.
If unset, the limit will be set to 90 days..
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
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.
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.
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