SyncEvolution Usage

This page applies to 0.8.1, the latest stable version that is available on all platforms. In 0.9, several new command line options and a GTK GUI called "sync-ui" were added, but not documented here yet.

In 0.8.1, SyncEvolution comes as a simple command line tool which is configured through files. These files can be modified through command line options or a normal editor. Configuring through a graphical interface, using an Evolution plugin, would also be possible, but is not implemented yet. The general synopsis of the command line parameters is:

The <server> and the <source> strings are used to find the configuration files, which determine how synchronization is going to proceed. Each source corresponds to one local address book, calendar, task list, or set of memos and the corresponding database on the server. Depending on which parameters are given, different operations are executed.

If no arguments are given, then SyncEvolution will list all available data sources, regardless whether there is a configuration file for them or not. The output includes the identifiers, which can then be used to select those sources in a configuration file. For each source, one can set a different synchronization mode in its configuration file.

Without the optional list of sources, all sources, which are enabled in their configuration file, are synchronized.

Otherwise, only the ones mentioned on the command line are active. It is possible to configure sources without activating their synchronization. If the synchronization mode of a source is set to "none", the source will be ignored. Explicitly listing such a source will synchronize it once, in "two-way" mode.

Progress and error messages are written into a log file that is preserved for each synchronization run. Details about that are found in the "Automatic Backups and Logging" section below. Immediately before quitting, SyncEvolution will show all errors or warnings encountered and 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" option is enabled (not the default because a persistent directory must be chosen, but highly recommended if one has the space!), 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, that is, 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, for example, 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 has stored previously, which then would lead to duplication of items.

Options in the configuration can be modified using the command line. Source properties are changed for all sources, unless sources are listed explicitly. Some source properties have to be different for each source, in which case, syncevolution must be called multiple times with one source listed in each invocation.

Options can also be overridden for just the current run, without changing the configuration. To prevent accidentally running a sync session when a configuration change was intented, either --configure or --run must be given explicitly, if options are specified on the command line.

Prints what changes were made locally since the last synchronization. Depends on access to database dumps from the last run, so using the "logdir" option is recommended.

These commands print information about existing configurations. When printing a configuration, a short version, without commands, can be selected with --quiet. When sources are listed, only their configuration is show. "Sync" instead or in combination with sources lists only the main server configuration.

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.

Temporarily synchronize the active sources in that mode. Useful for a "refresh-from-server" or "refresh-from-client" sync which clears all data at one end and copies all items from the other.

Prints the names of all configured servers to stdout.

Prints the complete configuration for the selected server to stdout, including up-to-date comments for all properties. The format is the normal .ini format, with source configurations in different sections introduced with [<source>] lines. Can be combined with --sync-property and --source-property to modify the configuration on-the-fly. When one or more sources are listed after the <server> name on the command line, then only the configs of those sources are printed. "Sync" selects the main configuration, instead of source configurations. Using --quiet suppresses the comments for each property. When setting a --template, then the reference configuration for that server is printed instead of an existing configuration.

Modify the configuration files for the selected server. If no such configuration exists, then a new one is created using one of the template configurations (see --template option). When creating a new configuration, only the active sources will be set to active in the new configuration, that is "syncevolution -c scheduleworld addressbook" followed by "syncevolution scheduleworld" will only synchronize the address book. The other sources are created in a disabled state. When modifying an existing configuration and sources are specified, the source properties of only those sources are modified.

To prevent accidental sync runs, when a configuration change was intended but the "--configure" option was used, "--run" must be specified explicitly when sync or source properties are selected on the command line and they are meant to be used during a sync session triggered by the invocation.

In SyncEvolution <= 0.7, a different layout of configuration files was used. Using --migrate will automatically migrate to the new layout and rename the old directory $HOME/.sync4j/evolution/<server> into $HOME/.sync4j/evolution/<server>.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.

Overrides a configuration property in the <server>/config.ini file 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-option, but applies to the configuration of all active sources. "--sync <mode>" is a shortcut for "--source-property sync=<mode>".

When combined with "--configure", the configuration of all sources is modified. Properties cannot be specified differently for different sources, so if you want to change a source property of just one specific sync source, then use "--configure --source-property ... <server> <source>".

Can be used to select from one of the built-in default configurations for known SyncML servers. Defaults to the name, so --template only has to be specified when creating multiple different configurations for the same server. "default" is an alias for "scheduleworld" and can be used as the starting point for servers which do not have a built-in configuration. Each template contains a pseudo-random device ID. Therefore, setting the "deviceId" sync property is only necessary when manually recreating a configuration or when a more descriptive name is desired.

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.

Suppresses most of the normal output during a synchronization. The log file still contains all the information.

Prints usage information.

Prints the SyncEvolution version.

Use Cases

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:

Deactivate all sources:

Activate address book synchronization again, using the --sync shortcut:

Change the password for a configuration:

Set up another configuration for scheduleworld under a different name:

Edit all configuration properties at once:

Configuration

The configuration file of a certain <server&glt; is stored in

Each data source is configured in

The XDG_CONFIG_HOME environment variable can be used to override the default $HOME/.config directory.

The configuration of older SyncEvolution releases in the following directory is also still supported, but new configurations are no longer created there:

The format is a simple list of <property> = <value> pairs with one pair per line. Leading spaces and space around the equals character (=) and at the end of the line are skipped. In other words, values can neither start or end with spaces nor contain line breaks. Do not put quotation marks around <value>, they would be treated as part of the value itself. Lines starting with a hash (#), after optional leading spaces, are treated as comments and skipped.

All supported properties are listed in the template configurations. Those which have reasonable defaults do not have to be set and are commented out in the template configurations. Normally, at least the following configuration options need to be adapted:

See "syncevolution --sync-property ?" for options in the server configuration and "syncevolution --source-property ?" for options in each data source configuration.

Each data source corresponds to one database at the SyncML server. The local data source is determined by the type of data given in "type" and uniquely identified with the "evolutionsource" property. To get a list of available data sources, run SyncEvolution with no arguments. "evolutionsource" can be set to either the name or URL of a data source that SyncEvolution then prints.

The "uri" property is used to identify which database on the SyncML server the local data is to be synchronized with. Each server usually documents what needs to be configured here. The template configurations already have this set correctly.

One can synchronize with multiple server databases in one run, but the same server database can only be accessed once. To synchronize the same server database with multiple local data sources, one has to set up two independent configurations with different "deviceId" settings and synchronize them separately. To create such a setup, simply copy the whole configuration tree of the server, for example:

and then edit ~/.config/syncevolution/localhost_copy/config.ini to update the "deviceId" and the sources/*/config.ini files to update the "evolutionsource".

If an Evolution data source requires authentication, the "evolutionuser" and "evolutionpassword" are used as credentials. In this case, the directory that contains the source's config.txt should only be accessible by the user. Usually these fields can be left empty.

Warning: setting evolutionuser/password in cases where it is not needed, as with local calendars and addressbooks, can cause the Evolution backend to hang.

SSL encryption of the HTTP connection is supported if the underlying platform supports it. To enable it, use a syncURL with https, instead of http prefix. Not all servers support this, though. In the default configuration, servers must present a trusted certificate where the host name of the certificate matches the host name of the URL. Configuration settings can be used to relax this checking, but this makes the connection less secure and is not recommended.

If you get errors about a missing certificate file under /etc/ssl/certs, check whether the system packages, which provide that file, are installed. On Debian/Ubuntu, the package is called "ca-certificates". Alternatively, it is possible to specify a different location of a custom certificate file in the configuration.

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 imported back into Evolution, for example, .vcf for address books
• a full log file with debug information
• a dump of the data after the synchronization for automatic comparison of the before/after state with "synccompare"

If the source configuration option "logdir" is set, then a new directory will be created for each synchronization in that directory, using the format

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 oldest ones when it reaches the limit. This cleanup is only done after a successful synchronization and is limited to directories starting with the SyncEvolution-<server> prefix, so it is safe to put other files or directories into the configured log directory.

If that option is not set (as in the example configurations), then the directory will be created as

with access allowed for the user only. Files from a previous synchronization will be overwritten. This is a lot less useful because the data will usually be lost during the next reboot and each synchronization run overwrites the data of the previous one.

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.