| Manual section: | 1 |
|---|---|
| Version: | 1.2 |
| Date: | 2011-10-13 |
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.
The <config> 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 peer. Depending on which parameters are given, different operations are executed.
Starting with SyncEvolution 1.0, <config> strings can have different meanings. Typically, a simple string like memotoo refers to the configuration for that peer, as it did in previous releases. A peer is either a SyncML server (the traditional usage of SyncEvolution) or a client (the new feature in 1.0).
Each peer configuration exists inside a specific context, typically the @default context. All peers in the same context share some parts of their configuration, for example, which local databases are to be synchronized. In that sense, a configuration context can be seen as a set of local databases plus the peer configurations that are synchronized against those databases.
The peer-independent properties of a source can be configured by giving the context name as <config> parameter ("@default addressbook"). Operations manipulating the local data also accept the context name.
When different peers are meant to synchronize different local databases, then different contexts have to be used when setting up the peers by appending a context name after the at sign, as in memotoo2@other-context. Later on, if memotoo2 is unique, the @other-context suffix becomes optional.
Sometimes it is also useful to change configuration options of a context, without modifying a specific peer. This can be done by using @default (or some other context name) without anything before the at sign. The empty string "" is the same as @default.
syncevolution
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.
syncevolution <config>
Without the optional list of sources, all sources which are enabled in their configuration file are synchronized.
syncevolution <config> <source> ...
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 disabled, the source will be ignored. Explicitly listing such a source will synchronize it in two-way mode once.
In SyncEvolution's predefined configuration templates, the following names for sources are used. Different names can be chosen for sources that are defined manually.
- addressbook: a list of contacts
- calendar: calendar events
- memo: plain text notes
- todo: task list
- calendar+todo: a virtual source combining one local "calendar" and one "todo" source (required for synchronizing with some phones)
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 option 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> [<source> ...]
Options in the configuration can be modified via 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.
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 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> [<source> ...]
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> [<source> ...]
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.
syncevolution --print-servers|--print-configs|--print-peers syncevolution --print-config [--quiet] <config> [main|<source> ...] 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 sources are listed, only their configuration is shown. Main instead or in combination with sources lists only the main peer configuration.
syncevolution --restore <session directory> --before|--after
[--dry-run] <config> <source> ...
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 source(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 sources.
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 server during the next synchronization. If the server somehow needs to get a clean copy of all items on the client then, use "--sync refresh-from-client" in the next run.
syncevolution --print-items <config> <source> syncevolution [--delimiter <string>] --export <dir>|<file>|- <config> <source> [<luid> ...] syncevolution [--delimiter <string>|none] --import <dir>|<file>|- <config> <source> syncevolution --update <dir> <config> <source> syncevolution [--delimiter <string>|none] --update <file>|- <config> <source> <luid> ... syncevolution --delete-items <config> <source> (<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 source, transformed so that it contains only alphanumeric characters, dash and underscore. A star * in --delete-items selects all items for deletion.
<config> and <source> must be given, but they do not have to refer to existing configurations. In that case, the desired backend and must be give via "--source-property type=<backend>", like this:
syncevolution --print-items --source-property type=evolution-contacts dummy-config dummy-source
The desired backend database can be chosen via "--source-property database".
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.
Warning: in local sync (CalDAV/CardDAV/ActiveSync, ...) and direct sync with a phone, the sync is started by the side which acts as server. Therefore the from-server variants (one-way-from-server, refresh-from-server) transfer data from the sync config into the target config (see "Synchronization beyond SyncML" below) resp. to a phone. The from-client variants transfer in the other direction, even if the target config happens to access data on a remote server.
Modify the configuration files for the selected peer and/or sources.
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 sources (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 sources explicitly on the command line, only those sources 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 sources are created in a disabled state. When modifying an existing configuration and sources are specified, then the source properties of only those sources are modified.
By default, creating a config requires a template. Source names on the command line must match those in the template. This allows catching typos in the peer and source 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 source properties that are normally in the templates on the command line (syncURL, backend, ...)
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.
Writes all items in the source 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.
Overrides a source-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.
The <property> has the following format: <name>[@<context>|@<peer>@<context>]
The optional <context> or <peer>@<context> suffix limits the scope of the value to that particular configuration. This is currently only useful for a local sync, which involves a source and a target configuration.
A string without a second @ sign inside is always interpreted as a context name, so in contrast to the <server> 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 <server>. 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.
When using the configuration layout introduced with 1.0, some of the sync properties are shared between peers, for example the directory where sessions are logged. Permanently changing such a shared property for one peer will automatically update the property for all other peers in the same context because the property is stored in a shared config file. When printing a config in verbose mode, a summary comment shows which properties are shared in which way.
Same as --sync-property, but applies to the configuration of all active sources. --sync <mode> is a shortcut for --source-property sync=<mode>.
The <property> has the following format: [<source>/]<name>[@<context>|@<peer>@<context>]
In it's simplest form without <source>, <context> or <config>, the name specifies one of the know properties. When combined with --configure, the configuration of all sources is modified. The value is applied to all sources unless sources are listed explicitly on the command line. So if you want to change a source property of just one specific sync source, then use --configure --source-property ... <server> <source>.
Adding the <source>/ prefix makes it possible to set the same property differently for different sources in one command:
--configure --source-property addressbook/sync=two-way \
--source-property calendar/sync=one-way-from-server \
<server>
If the same property is set both with and without a <source>/ prefix, then the more specific value with that prefix is used for that source, regardless of the order on the command line. The following command disables all sources except for the addressbook:
--configure --source-property addressbook/sync=none \
--source-property sync=two-way \
<server>
As with sync properties, some properties are shared between peers, in particular the selection of which local data to synchronize. The optional configuration suffix in <property> also has the same meaning as for sync properties. That suffix is checked first, so "sync@foo@default" overrides "addressbook/sync", even though "addressbook/sync" normally overrides "sync".
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).
Save or retrieve passwords from the GNOME keyring when modifying the configuration or running a synchronization. Note that using this option applies to all passwords in a configuration, so setting a single password as follows moves the other passwords into the keyring, if they were not stored there already:
--keyring --configure --sync-property proxyPassword=foo
When passwords were stored in the keyring, their value is set to a single hyphen ("-") in the configuration. This means that when running a synchronization without the --keyring argument, the password has to be entered interactively. The --print-config output always shows "-" instead of retrieving the password from the keyring.
The SyncEvolution daemon always uses the GNOME keyring, regardless of the --keyring command line parameter. Therefore --keyring only has an effect in combination with --daemon=no, or when SyncEvolution was compiled without daemon support (not the default).
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 sources:
syncevolution memotoo
Deactivate all sources:
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 \
--source-property 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
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 look like data sources. 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:
Because local sync involves two sides, two configurations are needed. One is called the target config. By convention it must be called target-config@<some context name>, for example target-config@google-calendar. The target config holds properties which apply to all sources inside that context, like user name, password and URL for the server. 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 sync config is needed. This config has the same role as the traditional SyncML configs and is typically defined in the same implicit @default context as those configs. All configs in that context use the same local data. The sync config defines the database pairs and the sync mode (one-way, two-way, ...).
The first step is to select a target config with syncURL=local://@<some context name>. Multiple sync configs can access the same target config. In the second step, the uri of each source in the sync config must be set to the name of the corresponding source in the target config. The sync property in the sync config defines the direction of the data flow. It can be set temporarily when starting a synchronzation with the sync config.
Warning: because the client in the local sync starts the sync, preventSlowSync=0 must be set in the target config to have an effect.
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, ...).
The database property of each source 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. A future version of SyncEvolution will support listing the available collections, but 1.2 does not yet support that.
Configuration templates for Google Calendar, 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 auto-discovery. For Google and Yahoo, replace webdav with google-calendar resp. yahoo and remove the addressbook source when setting up the sync config.
# configure target config
syncevolution --configure \
--template webdav \
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
SyncEvolution transmits address book entries as vCard 2.1 or 3.0 depending on the type 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 data sources.
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):
Now one can either compare the address books in Evolution or do that automatically, described here for contacts:
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.
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.
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:
If the server configuration option "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.
The following environment variables control where SyncEvolution finds files and other aspects of its operations.
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.
See known issues and the support web page for more information.
| 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 | |