5 ------------------------------------------------
6 synchronize personal information management data
7 ------------------------------------------------
16 List and manipulate databases:
17 syncevolution --print-databases|--create-database|--remove-database [<properties>] [<config> <store>]
19 Show information about configuration(s):
20 syncevolution --print-servers|--print-configs|--print-peers
22 Show information about a specific configuration:
23 syncevolution --print-config [--quiet] [--] <config> [main|<store> ...]
26 syncevolution --print-sessions [--quiet] [--] <config>
28 Show information about SyncEvolution:
29 syncevolution --help|-h|--version
31 Run a synchronization as configured:
32 syncevolution <config> [<store> ...]
34 Run a synchronization with properties changed just for this run:
35 syncevolution --run <options for run> [--] <config> [<store> ...]
37 Restore data from the automatic backups:
38 syncevolution --restore <session directory> --before|--after [--dry-run] [--] <config> <store> ...
40 Create, update or remove a configuration:
41 syncevolution --configure <options> [--] <config> [<store> ...]
43 syncevolution --remove|--migrate <options> [--] <config>
46 syncevolution --print-items [--] [<config> [<store>]]
49 syncevolution [--delimiter <string>] --export <dir>|<file>|- [--] [<config> [<store> [<luid> ...]]]
53 syncevolution [--delimiter <string>|none] --import <dir>|<file>|- [--] [<config> [<store>]]
57 syncevolution --update <dir> [--] <config> <store>
59 syncevolution [--delimiter <string>|none] --update <file>|- [--] <config> <store> <luid> ...
64 syncevolution --delete-items [--] <config> <store> (<luid> ... | '*')
70 This text explains the usage of the SyncEvolution command line.
72 SyncEvolution synchronizes personal information management (PIM) data
73 such as contacts, appointments, tasks and memos using the Synthesis
74 sync engine, which provides support for the SyncML synchronization
77 SyncEvolution synchronizes with SyncML servers over HTTP and with
78 SyncML capable phones locally over Bluetooth (new in 1.0). Plugins
79 provide access to the data which is to be synchronized. Binaries are
80 available for Linux desktops (synchronizing data in GNOME Evolution,
81 with KDE supported indirectly already and Akonadi support in
82 development), for MeeGo (formerly Moblin) and for Maemo 5/Nokia
83 N900. The source code can be compiled for Unix-like systems and
84 provides a framework to build custom SyncML clients or servers.
90 A peer is the entity that data is synchronized with. This can be
91 another device (like a phone), a server (like Google) or
92 even the host itself (useful for synchronizing two different
96 The device or computer that SyncEvolution runs on.
99 The smallest unit of synchronization. Examples of items include
100 calendar events and individual contacts, memos, or tasks.
103 Each peer has one or more databases that get synchronized (Google Calendar,
104 Google Contacts). Conceptually a database is a set of items where each
105 item is independent of the others.
108 Access to databases is provided by SyncEvolution backends. It does
109 not matter where that data is stored. Some backends provide access
110 to data outside of the host itself (`CalDAV and CardDAV`_, ActiveSync).
112 datastore (or just "store")
113 Used for the combination of SyncEvolution backend and database settings.
114 A datastore provides read/write access to a database, which is a prerequisite
115 for syncing the database. The datastore is independent of the peers that
116 the database might be synchronized with.
118 This used to be called "data source" or just "source", which is a
119 term still found in older documentation, some file paths and the
120 source code of SyncEvolution.
123 Synchronization always happens between a pair of databases and thus
124 has two sides. One database or side of a sync is remote (the one
125 of the peer), the other is local (SyncEvolution). For the sake of consistency (and
126 lack of better terms), these terms are used even if the peer is another
127 instance of SyncEvolution and/or all data resides on the same storage.
130 A sync configuration defines how to talk with a peer: the protocol
131 which is to be used, how to find the peer, credentials, etc.
133 Sync configs can be used to initiate a sync (like contacting a
134 SyncML server) or to handle an incoming sync request (when acting
135 as SyncML server which is contacted by the peer).
137 If the peer supports SyncML as sync protocol, a sync only uses one
138 sync config on the SyncEvolution side. If the peer supports data
139 access via some other protocols, then SyncEvolution can make that
140 data available via SyncML and run a sync where SyncML is used
141 internally. Such a sync involves two sync configs, see ``originating
142 config`` and ``target config``.
144 A sync config can use all datastores defined in the same context
145 (see below). Some properties of the datastore can be set differently
146 for each peer and thus sync config (``per-peer``). One of these, the
147 ``sync`` property, defines if and how a datastore is used during a
151 Sync and datastore configs are defined inside one or more configuration
152 contexts. There is always a ``@default`` context that gets used if nothing
155 Typically each context represents a certain set of related
156 datastores. For example, normally the ``@default`` context is used for
157 local databases. Datastores related to a certain peer can
158 be defined in a context ``@peer-name`` named after that peer.
160 configuration properties
161 SyncEvolution uses key/value pairs to store configuration options.
162 A configuration is a set of unique keys and their values that together
163 describe a certain object.
165 These sets of properties are addressed via the main config name (a
166 sync config name with or without an explicit context, or just the
167 context name) and optionally the datastore name (if the properties
168 are for a specific datastore).
170 Sync properties are set for sync configs, independently of a
171 particular datastore. Properties that cannot be set without
172 specifying they datastore that they apply to are datastore
173 properties. This includes properties that belong both to a datastore
176 The property names were chosen so that they are unique, i.e., no
177 sync property has the same name as a datastore property. For historic
178 reasons, internally these properties are treated as two different
179 sets and there are two different command line options to query the
180 list of sync resp. datastore properties.
182 Some configuration properties are shared between configurations
183 automatically. This sharing is hard-coded and cannot be configured.
184 It has the advantage that certain settings only need to be set
185 once and/or can be changed for several different configs
188 A property can be *unshared* (has separate values for each peer, therefore
189 sometimes also called *per-peer*; for example the ``sync`` property),
190 *shared* (same value for all peers; for
191 example the ``database`` property for selecting the local database) or
192 *global* (exactly one value).
194 Together with the distinction between sync and datastore properties,
195 this currently results in five different groups of properties:
197 * Sync properties (by definition, this also includes properties
198 independent of a particular sync config because they are set for
199 all sync configs at once, independently of any particular
202 * global (= ``~/.config/syncevolution/config.ini``):
203 independent of a particular context, for example ``keyring``
204 * shared (= ``~/.config/syncevolution/<context name>/config.ini``):
205 set once for each context, for example ``logdir``
206 * unshared (= ``~/.config/syncevolution/<context name>/peers/<peer name>/config.ini``):
207 set separately for each sync config, for example ``syncURL``
209 * Datastore properties:
211 * shared (= ``~/.config/syncevolution/<context name>/sources/<store name>/config.ini``):
212 the properties required for access to the data, primarily ``backend`` and ``database``
213 * unshared (= ``~/.config/syncevolution/<context name>/peers/<peer name>/sources/<store name>/config.ini``):
214 the already mentioned ``sync`` and ``uri`` properties, but also a per-peer
215 sync format properties
217 Many properties have reasonable defaults, either defined in the
218 configuration layer or chosen at runtime by the SyncEvolution
219 engine reading the configuration, and therefore do not have to
222 The configuration layer in SyncEvolution has a very limited
223 understanding of the semantic of each property. It just knows about
224 some generic types (strings, boolean, integers, ...) and where
225 properties are supposed to be stored. It is the layer above that,
226 the one which actually tries to use the configuration, that
227 determines whether the property values make sense as
228 specified. Beware that it is possible to set properties to values
229 that conflict with other property values (triggering errors when
230 using the configuration) or to set properties that are not used
231 (typically they get ignored silently, unless an explicit error check
234 configuration template
235 Templates define the settings for specific peers. Some templates
236 are packaged together with SyncEvolution, others may be added by
237 packagers or users. Settings from templates are copied once into
238 the sync config when creating it. There is no permanent link back
239 to the template, so updating a template has no effect on configs
240 created from it earlier.
242 A template only contains unshared properties. Therefore it is
243 possible to first set shared properties (for example, choosing
244 which databases to synchronize in the default context), then
245 add sync configs for different peers to that context without
246 reseting the existing settings.
248 In SyncEvolution's predefined configuration templates, the following
249 names for datastores are used. Different names can be chosen for datastores
250 that are defined manually.
252 * addressbook: a list of contacts
253 * calendar: calendar *events*
254 * memo: plain text notes
256 * calendar+todo: a virtual datastore combining one local "calendar" and
257 one "todo" datastore (required for synchronizing with some phones)
260 Traditionally, a sync config specifies SyncML as the synchronization
261 protocol via the `syncURL` property. The peer must support SyncML for
264 In a so called local sync, SyncEvolution acts as SyncML server
265 and client at the same time, connecting the two sides via internal
266 message passing. Both sides have their own set of datastores, which may
267 use CalDAV, CardDAV or ActiveSync to access the data.
269 See `Synchronization beyond SyncML`_.
272 In a local sync, the sync config used to start the sync is called
273 the originating sync config, or just originating config.
276 In addition to the originating config, a local sync also uses a target
277 config. At the configuration level, this target config is just another
278 sync config. It becomes a target config when referenced by a sync config
282 COMMAND LINE CONVENTIONS
283 ========================
285 The ``<config>`` and the ``<store>`` strings in the command line synopsis are
286 used to find the sync resp. datastore configs. Depending on which
287 other parameters are given, different operations are executed.
289 The ``<config>`` string has the format ``[<peer>][@<context>]``. When
290 the context is not specified explicitly, SyncEvolution first searches
291 for an existing sync configuration with the given ``<peer>`` name. If
292 not found, the configuration can only be created, but not read. It
293 will be created in the ``@default`` context as fallback. The empty
294 ``<config>`` string is an alias for ``@default``.
296 The ``<peer>`` part identifies a specific sync or target config inside
297 the context. It is optional and does not have to be specified when not
298 needed, for example when configuring the shared settings of datastores
299 (``--configure @default addressbook``) or accessing items inside a
300 datastore (``--print-items @work calendar``).
302 Listing datastores on the command line limits the operation to those
303 datastores (called *active datastores* below). If not given, all datastores
304 enabled for the config are active. Some operations require
305 the name of exactly one datastore.
307 Properties are set with key/value assignments and/or the
308 ``--sync/store-property`` keywords. Those keywords are only needed for
309 the hypothetical situation that a sync and datastore property share the
310 same name (which was intentionally avoided). Without them, SyncEvolution
311 automatically identifies which kind of property is meant based on the
314 A ``<property>`` assignment has the following format::
316 [<store>/]<name>[@<context>|@<peer>@<context>]=<value>
318 The optional ``<context>`` or ``<peer>@<context>`` suffix limits the scope
319 of the value to that particular configuration. This is useful when
320 running a local sync, which involves a sync and a target
321 configuration. For example, the log level can be specified separately
324 --run loglevel@default=1 loglevel@google-calendar=4 google-calendar@default
326 A string without a second @ sign inside is always interpreted as a
327 context name, so in contrast to the ``<config>`` string, ``foo`` cannot be
328 used to reference the ``foo@default`` configuration. Use the full name
329 including the context for that.
331 When no config or context is specified explicitly, a value is
332 changed in all active configs, typically the one given with
333 ``<config>``. The priority of multiple values for the same config
334 is `more specific definition wins`, so ``<peer>@<context>``
335 overrides ``@<context>``, which overrides `no suffix given`.
336 Specifying some suffix which does not apply to the current operation
337 does not trigger an error, so beware of typos.
339 Datastore properties can be specified with a ``<store>/`` prefix. This
340 allows limiting the value to the selected datastore. For example::
342 --configure "addressbook/database=My Addressbook" \
343 "calendar/database=My Calendar" \
344 @default addressbook calendar
346 Another way to achieve the same effect is to run the ``--configure``
347 operation twice, once for ``addressbook`` and once for ``calendar``::
349 --configure "database=My Addressbook" @default addressbook
350 --configure "database=My Calendar" @default calendar
352 If the same property is set both with and without a ``<store>/`` prefix,
353 then the more specific value with that prefix is used for that datastore,
354 regardless of the order on the command line. The following command
355 enables all datastores except for the addressbook::
357 --configure addressbook/sync=none \
367 syncevolution --print-databases [<properties>] [<config> <store>]
369 If no additional arguments are given, then SyncEvolution will list all
370 available backends and the databases that can be accessed through each
371 backend. This works without existing configurations. However, some
372 backends, like for example the CalDAV backend, need additional
373 information (like credentials or URL of a remote server). This
374 additional information can be provided on the command line with
375 property assignments (``username=...``) or in an existing configuration.
377 When listing all databases of all active datastores, the output starts
378 with a heading that lists the values for the ``backend`` property which
379 select the backend, followed by the databases. Each database has a
380 name and a unique ID (in brackets). Typically both can be used as
381 value of the 'database' property. One database might be marked as
382 ``default``. It will be used when ``database`` is not set explicitly.
384 When selecting an existing datastore configuration or specifying the ``backend``
385 property on the command line, only the databases for that backend
386 are listed and the initial line shows how that backend was selected
387 (<config>/<store> resp. backend value).
389 Some backends do not support listing of databases. For example, the
390 file backend synchronizes directories with one file per item and
391 always needs an explicit ``database`` property because it cannot guess
392 which directory it is meant to use. ::
394 syncevolution --create-database [<properties>] [<config> <store>]
396 Creates a new database for the selected ``backend``, using the
397 information given in the ``database`` property. As with
398 ``--print-databases``, it is possible to give the properties directly
399 without configuring a datastore first.
401 The interpretation of the ``database`` property depends on the
402 backend. Not all backends support this operation.
404 The EDS backend uses the value of the ``database`` as name of the new
405 database and assigns a unique URI automatically. ::
407 syncevolution --remove-database [<properties>] [<config> <store>]
409 Looks up the database based on the ``database`` property (depending
410 on the backend, both name and a URI are valid), then deletes the data.
411 Note that datastore configurations using the database are not removed. ::
413 syncevolution <config>
415 Without the optional list of datastores, all datastores which are enabled in
416 their configuration file are synchronized. ::
418 syncevolution <config> <store> ...
420 Otherwise only the ones mentioned on the command line are active. It
421 is possible to configure datastores without activating their
422 synchronization: if the synchronization mode of a datastore is set to
423 `disabled`, the datastore will be ignored. Explicitly listing such a
424 datastore will synchronize it in `two-way` mode once.
426 Progress and error messages are written into a log file that is
427 preserved for each synchronization run. Details about that is found in
428 the `Automatic Backups and Logging` section below. All errors and
429 warnings are printed directly to the console in addition to writing
430 them into the log file. Before quitting SyncEvolution will print a
431 summary of how the local data was modified. This is done with the
432 `synccompare` utility script described in the `Exchanging Data`_
435 When the ``logdir`` property is enabled (since v0.9 done by default for
436 new configurations), then the same comparison is also done before the
437 synchronization starts.
439 In case of a severe error the synchronization run is aborted
440 prematurely and SyncEvolution will return a non-zero value. Recovery
441 from failed synchronization is done by forcing a full synchronization
442 during the next run, i.e. by sending all items and letting the SyncML
443 server compare against the ones it already knows. This is avoided
444 whenever possible because matching items during a slow synchronization
445 can lead to duplicate entries.
447 After a successful synchronization the server's configuration file is
448 updated so that the next run can be done incrementally. If the
449 configuration file has to be recreated e.g. because it was lost, the
450 next run recovers from that by doing a full synchronization. The risk
451 associated with this is that the server might not recognize items that
452 it already has stored previously which then would lead to duplication
455 syncevolution --configure <options for configuration> <config> [<store> ...]
457 Options in the configuration can be modified via the command
458 line. The <config> and the optional <store> parameters define
459 what gets created or modified. The remaining parameters define
460 which values get set or modified.
462 To change settings of specific datastores, either invoke syncevolution
463 multiple times with exactly one <store> parameter or use the
464 ``[<store>/]`` prefix described above for property assignments. ::
466 syncevolution --remove <config>
468 Deletes the configuration. If the <config> refers to a specific
469 peer, only that peer's configuration is removed. If it refers to
470 a context, that context and all peers and datastores defined inside
473 Note that there is no confirmation question. Neither local data
474 referenced by the configuration nor the content of log dirs are
477 syncevolution --run <options for run> <config> [<store> ...]
479 Options can also be overridden for just the current run, without
480 changing the configuration. In order to prevent accidentally running a
481 sync session when a configuration change was intended, either
482 --configure or --run must be given explicitly if options are specified
483 on the command line. ::
485 syncevolution --status <config> [<store> ...]
487 Prints what changes were made locally since the last synchronization.
488 Depends on access to database dumps from the last run, so enabling the
489 ``logdir`` property is recommended. ::
491 syncevolution --print-servers|--print-configs|--print-peers
492 syncevolution --print-config [--quiet] <config> [main|<store> ...]
493 syncevolution --print-sessions [--quiet] <config>
495 These commands print information about existing configurations. When
496 printing a configuration a short version without comments can be
497 selected with --quiet. When datastores are listed, only their
498 configuration is shown. `Main` instead or in combination with datastores
499 lists only the main peer configuration. ::
501 syncevolution --restore <session directory> --before|--after
502 [--dry-run] <config> <store> ...
504 This restores local data from the backups made before or after a
505 synchronization session. The --print-sessions command can be used to
506 find these backups. The datastore(s) have to be listed explicitly. There
507 is intentionally no default, because as with --remove there is no
508 confirmation question. With --dry-run, the restore is only simulated.
510 The session directory has to be specified explicitly with its path
511 name (absolute or relative to current directory). It does not have to
512 be one of the currently active log directories, as long as it contains
513 the right database dumps for the selected datastores.
515 A restore tries to minimize the number of item changes (see section
516 `Item Changes and Data Changes`_). This means that items that are
517 identical before and after the change will not be transmitted anew to
518 the peer during the next synchronization. If the peer somehow
519 needs to get a clean copy of all local items, then use ``--sync
520 refresh-from-local`` in the next run. ::
522 syncevolution --print-items <config> <store>
523 syncevolution [--delimiter <string>] --export <dir>|<file>|- [<config> [<store> [<luid> ...]]]
524 syncevolution [--delimiter <string>|none] --import <dir>|<file>|- [<config> <store>]
525 syncevolution --update <dir> <config> <store>
526 syncevolution [--delimiter <string>|none] --update <file>|- <config> <store> <luid> ...
527 syncevolution --delete-items <config> <store> (<luid> ... | *)
529 Restore depends on the specific format of the automatic backups
530 created by SyncEvolution. Arbitrary access to item data is provided
531 with additional options. <luid> here is the unique local identifier
532 assigned to each item in the datastore, transformed so that it contains
533 only alphanumeric characters, dash and underscore. A star * in
534 --delete-items selects all items for deletion. There are two ways
535 of specifying luids: either as additional parameters after the
536 config and datastore parameters (which may be empty in this case, but
537 must be given) or after the ``--luids`` keyword.
539 <config> and <store> may be given to define the database which is to
540 be used. If not given or not refering to an existing configuration
541 (which is not an error, due to historic reasons), the desired backend
542 must be given via the ``backend`` property, like this::
544 syncevolution --print-items backend=evolution-contacts
545 syncevolution --export - backend=evolution-contacts \
546 --luids pas-id-4E33F24300000006 pas-id-4E36DD7B00000007
548 The desired backend database can be chosen via ``database=<identifier>``.
549 See ``--print-databases``.
554 Here is a full description of all <options> that can be put in front
555 of the server name. Whenever an option accepts multiple values, a
556 question mark can be used to get the corresponding help text and/or
557 a list of valid values.
560 Temporarily synchronize the active datastores in that mode. Useful
561 for a `refresh-from-local` or `refresh-from-remote` sync which
562 clears all data at one end and copies all items from the other.
564 **Warning:** `local` is the data accessed via the sync config
565 directly and `remote` is the data on the peer, regardless
566 where the data is actually stored physically.
568 --print-servers|--print-configs|--print-peers
569 Prints the names of all configured peers to stdout. There is no
570 difference between these options, the are just aliases.
572 --print-servers|--print-configs|--print-peers|-p
573 Prints the complete configuration for the selected <config>
574 to stdout, including up-to-date comments for all properties. The
575 format is the normal .ini format with datastore configurations in
576 different sections introduced with [<store>] lines. Can be combined
577 with --sync-property and --datastore-property to modify the configuration
578 on-the-fly. When one or more datastores are listed after the <config>
579 name on the command line, then only the configs of those datastores are
580 printed. `main` selects the main configuration instead of datastore
581 configurations. Using --quiet suppresses the comments for each property.
582 When setting a --template, then the reference configuration for
583 that peer is printed instead of an existing configuration.
586 Prints information about previous synchronization sessions for the
587 selected peer or context are printed. This depends on the ``logdir``
588 property. The information includes the log directory name (useful for
589 --restore) and the synchronization report. In combination with
590 --quiet, only the paths are listed.
593 Modify the configuration files for the selected peer and/or datastores.
595 If no such configuration exists, then a new one is created using one
596 of the template configurations (see --template option). Choosing a
597 template sets most of the relevant properties for the peer and the
598 default set of datastores (see above for a list of those). Anything
599 specific to the user (like username/password) still has to be set
602 When creating a new configuration and listing datastores explicitly on the
603 command line, only those datastores will be set to active in the new
604 configuration, i.e. `syncevolution -c memotoo addressbook`
605 followed by `syncevolution memotoo` will only synchronize the
606 address book. The other datastores are created in a disabled state.
607 When modifying an existing configuration and datastores are specified,
608 then the datastore properties of only those datastores are modified.
610 By default, creating a config requires a template. Datastore names on the
611 command line must match those in the template. This allows catching
612 typos in the peer and datastore names. But it also prevents some advanced
613 use cases. Therefore it is possible to disable these checks in two ways::
615 - use `--template none` or
616 - specify all required sync and datastore properties that are normally
617 in the templates on the command line (syncURL, backend, ...)
620 To prevent accidental sync runs when a configuration change was
621 intended, but the `--configure` option was not used, `--run` must be
622 specified explicitly when sync or datastore properties are selected
623 on the command line and they are meant to be used during a sync
624 session triggered by the invocation.
627 In older SyncEvolution releases a different layout of configuration files
628 was used. Using --migrate will automatically migrate to the new
629 layout and rename the <config> into <config>.old to prevent accidental use
630 of the old configuration. WARNING: old SyncEvolution releases cannot
631 use the new configuration!
633 The switch can also be used to migrate a configuration in the current
634 configuration directory: this preserves all property values, discards
635 obsolete properties and sets all comments exactly as if the configuration
636 had been created from scratch. WARNING: custom comments in the
637 configuration are not preserved.
639 --migrate implies --configure and can be combined with modifying
643 Shows all existing items using one line per item using
644 the format "<luid>[: <short description>]". Whether the description
645 is available depends on the backend and the kind of data that it
649 Writes all items in the datastore or all items whose <luid> is
650 given into a directory if the --export parameter exists and is a
651 directory. The <luid> of each item is used as file name. Otherwise it
652 creates a new file under that name and writes the selected items
653 separated by the chosen delimiter string. stdout can be selected with
656 The default delimiter (two line breaks) matches a blank line. As a special
657 case, it also matches a blank line with DOS line ending (line break,
658 carriage return, line break). This works for vCard 3.0 and iCalendar 2.0,
659 which never contain blank lines.
661 When exporting, the default delimiter will always insert two line
662 breaks regardless whether the items contain DOS line ends. As a
663 special case, the initial newline of a delimiter is skipped if the
664 item already ends in a newline.
667 Adds all items found in the directory or input file to the
668 datastore. When reading from a directory, each file is treated as one
669 item. Otherwise the input is split at the chosen delimiter. "none" as
670 delimiter disables splitting of the input.
673 Overwrites the content of existing items. When updating from a
674 directory, the name of each file is taken as its luid. When updating
675 from file or stdin, the number of luids given on the command line
676 must match with the number of items in the input.
679 Removes the specified items from the datastore. Most backends print
680 some progress information about this, but besides that, no further
681 output is produced. Trying to remove an item which does not exist
682 typically leads to an ERROR message, but is not reflected in a
683 non-zero result of the command line invocation itself because the
684 situation is not reported as an error by backends (removal of
685 non-existent items is not an error in SyncML). Use a star \* instead
686 or in addition to listing individual luids to delete all items.
688 --sync-property|-y <property>=<value>|<property>=?|?
689 Overrides a datastore-independent configuration property for the
690 current synchronization run or permanently when --configure is used
691 to update the configuration. Can be used multiple times. Specifying
692 an unused property will trigger an error message.
694 --datastore-property|--source-property|-z <property>=<value>|<property>=?|?
695 Same as --sync-property, but applies to the configuration of all active
696 datastores. `--sync <mode>` is a shortcut for `--datastore-property sync=<mode>`.
698 --template|-l <peer name>|default|?<device>
699 Can be used to select from one of the built-in default configurations
700 for known SyncML peers. Defaults to the <config> name, so --template
701 only has to be specified when creating multiple different configurations
702 for the same peer, or when using a template that is named differently
703 than the peer. `default` is an alias for `memotoo` and can be
704 used as the starting point for servers which do not have a built-in
707 A pseudo-random device ID is generated automatically. Therefore setting
708 the `deviceId` sync property is only necessary when manually recreating a
709 configuration or when a more descriptive name is desired.
711 The available templates for different known SyncML servers are listed when
712 using a single question mark instead of template name. When using the
713 `?<device>` format, a fuzzy search for a template that might be
714 suitable for talking to such a device is done. The matching works best
715 when using `<device> = <Manufacturer> <Model>`. If you don't know the
716 manufacturer, you can just keep it as empty. The output in this mode
717 gives the template name followed by a short description and a rating how well
718 the template matches the device (100% is best).
721 The changes made to local data since the last synchronization are
722 shown without starting a new one. This can be used to see in advance
723 whether the local data needs to be synchronized with the server.
726 Suppresses most of the normal output during a synchronization. The
727 log file still contains all the information.
729 --keyring[=<value>]|-k
730 A legacy option, now the same as setting the global keyring sync property.
731 When not specifying a value explicitly, "true" for "use some kind of
732 keyring" is implied. See "--sync-property keyring" for details.
735 By default, the SyncEvolution command line is executed inside the
736 syncevo-dbus-server process. This ensures that synchronization sessions
737 started by the command line do not conflict with sessions started
738 via some other means (GUI, automatically). For debugging purposes
739 or very special use cases (running a local sync against a server which
740 executes inside the daemon) it is possible to execute the operation
741 without the daemon (--daemon=no).
744 Prints usage information.
747 Prints the SyncEvolution version.
750 CONFIGURATION PROPERTIES
751 ========================
753 This section lists predefined properties. Backends can add their own
754 properties at runtime if none of the predefined properties are
755 suitable for a certain setting. Those additional properties are not
756 listed here. Use ``--sync/datastore-property ?`` to get an up-to-date
759 The predefined properties may also be interpreted slightly differently
760 by each backend and sync protocol. Sometimes this is documented in the
761 comment for each property, sometimes in the documentation of the
762 backend or sync protocol.
764 Properties are listed together with all recognized aliases (in those
765 cases where a property was renamed at some point), its default value,
766 sharing state (unshared/shared/global). Some properties must be
767 defined, which is marked with the word `required`.
771 << see "syncevolution --sync-property ?" >>
775 << see "syncevolution --datastore-property ?" >>
781 List the known configuration templates::
783 syncevolution --template ?
785 Create a new configuration, using the existing Memotoo template::
787 syncevolution --configure \
789 "password=!@#ABcd1234" \
792 Note that putting passwords into the command line, even for
793 short-lived processes as the one above, is a security risk in shared
794 environments, because the password is visible to everyone on the
795 machine. To avoid this, remove the password from the command above,
796 then add the password to the right config.ini file with a text editor.
797 This command shows the directory containing the file::
799 syncevolution --print-configs
801 Review configuration::
803 syncevolution --print-config memotoo
805 Synchronize all datastores::
807 syncevolution memotoo
809 Deactivate all datastores::
811 syncevolution --configure \
815 Activate address book synchronization again, using the --sync shortcut::
817 syncevolution --configure \
821 Change the password for a configuration::
823 syncevolution --configure \
827 Set up another configuration for under a different account, using
828 the same default databases as above::
830 syncevolution --configure \
836 Set up another configuration using the same account, but different
837 local databases (can be used to simulate synchronizing between two
838 clients, see `Exchanging Data`_::
840 syncevolution --configure \
842 password=!@#ABcd1234" \
846 syncevolution --configure \
847 database=<name of other address book> \
850 syncevolution --configure \
852 memotoo@other addressbook
854 syncevolution memotoo
855 syncevolution memotoo@other
857 Migrate a configuration from the <= 0.7 format to the current one
858 and/or updates the configuration so that it looks like configurations
859 created anew with the current syncevolution::
861 syncevolution --migrate memotoo
866 Synchronization beyond SyncML
867 =============================
869 In the simple examples above, SyncEvolution exchanges data with
870 servers via the SyncML protocol. Starting with release 1.2,
871 SyncEvolution also supports other protocols like CalDAV and
874 These protocols are implemented in backends which behave like local
875 datastores. SyncEvolution then synchronizes data between a pair of
876 backends. Because the entire sync logic (matching of items, merging)
877 is done locally by SyncEvolution, this mode of operation is called
880 Some examples of things that can be done with local sync:
882 * synchronize events with a CalDAV server and contacts with a CardDAV server
883 * mirror a local database as items in a directory, with format conversion
884 and one-way or two-way data transfer (export vs. true syncing)
886 Because local sync involves two sides, two sync configurations are
887 needed. One is called the *target config*. Traditionally, this really
888 was a configuration called ``target-config``, for example
889 ``target-config@google``. Using this particular name is no longer required.
891 The target config can hold properties which apply to all datastores
892 inside its context, like user name, password and URL for the server
893 (more on that below) and sync settings (like logging and data
894 backups). Once configured, the target config can be used to
895 list/import/export/update items via the SyncEvolution command line. It
896 cannot be used for synchronization because it does not defined what
897 the items are supposed to be synchronized with.
899 For synchronization, a second *originating config* is needed. This config has
900 the same role as the traditional SyncML sync configs and is typically
901 defined in the same implicit ``@default`` context as those
902 configs. All configs in that context use the same local data, thus turning
903 that local data into the hub through with data flows to all peers that the
904 host is configured to sync with.
906 A sync config becomes an originating config in a local sync by setting
907 the ``syncURL`` to the special URL ``local://[<target config
908 name>][@<some context name>]``. This selects the target config to
909 sync with. If the target config name is left out, the actual string
910 ``target-config`` is used as name. The context can be omitted if the
911 target config name is unique. Originating and target config can be in
912 the same context. Care must be taken to not use a datastore more than
913 once in a local sync.
915 In addition, ``peerIsClient=1`` must be set in the originating config,
916 because SyncEvolution only supports running the SyncML client on the
917 target side. It makes sense to use the local databases on
918 originating side, because that side requires more frequent access to
921 The originating config defines the database pairs, either implicitly
922 (by using the same datastore names on both sides, which is possible when
923 different contexts are used) or explicitly (via the `uri` properties
924 set for the datastores on the originating side). The originating config
925 also defines the ``sync`` mode for each pair. ``uri`` and ``sync``
926 values on the target side are ignored and do not have to be specified.
928 As a special case, datastores used in combination with the target config
929 may access the credentials and ``syncURL`` stored there as fallback when
930 nothing was specified for the datastores directly. This makes sense for
931 the WebDAV and ActiveSync backends where the credentials are typically
932 the same and (depending on the web server) the same start URL can be
933 used to find calendar and contact databases.
935 **Warning:** when setting password for the target config and using a
936 keyring, a ``syncURL`` or a unique ``remoteDeviceID`` string must be
937 set, because they are needed to identify the host in the keyring.
939 If this feature is not used, the ``syncURL`` could be left empty because
940 local sync itself does not use it. However, the command line expects
941 it to be set to ``none`` explicitly to detect typos.
943 **Warning:** because the client in the local sync starts the sync,
944 ``preventSlowSync=0`` must be set in the target config to have an effect.
950 This section explains how to use local syncing for CalDAV and
951 CardDAV. Both protocols are based on WebDAV and are provided by the
952 same backend. They share ``username/password/syncURL`` properties
953 defined in their target config.
955 The credentials must be provided if the server is password
956 protected. The ``syncURL`` is optional if the ``username`` is an email
957 address and the server supports auto-discovery of its CalDAV and/or
958 CardDAV services (using DNS SRV entries, ``.well-known`` URIs, properties
959 of the current principal, ...).
961 Alternatively, credentials can also be set in the ``databaseUser`` and
962 ``databasePassword`` properties of the datastore. The downside is that these
963 values have to be set for each datastore and cannot be shared. The advantage
964 is that, in combination with setting ``database``, such datastores can be
965 used as part of a normal SyncML server or client sync config. SyncEvolution
966 then reads and writes data directly from the server and exchanges it
967 via SyncML with the peer that is defined in the sync config.
969 The ``database`` property of each datastore can be set to the URL of a
970 specific *collection* (= database in WebDAV terminology). If not set,
971 then the WebDAV backend first locates the server based on ``username``
972 or ``syncURL`` and then scans it for the default event resp. contact
973 collection. This is done once in the initial synchronization. At the end
974 of a successful synchroniation, the automatic choice is made permanent
975 by setting the ``database`` property.
977 **Warning:** the protocols do not uniquely identify this default
978 collection. The backend tries to make an educated guess, but it might
979 pick the wrong one if the server provides more than one address book
980 or calendar. It is safer to scan for collections manually with
981 ``--print-databases`` and then use the URL of the desired collection
982 as value of ``database``.
984 To scan for collections, use::
986 syncevolution --print-databases \
987 backend=<caldav or carddav> \
988 username=<email address or user name> \
989 "password=!@#ABcd1234" \
990 syncURL=<base URL of server, if server auto-discovery is not supported>
992 Configuration templates for Google Calendar/Contacts, Yahoo Calendar and a
993 generic CalDAV/CardDAV server are included in SyncEvolution. The Yahoo
994 template also contains an entry for contact synchronization, but using
995 it is not recommended due to known server-side issues.
997 The following commands set up synchronization with a generic WebDAV
998 server that supports CalDAV, CardDAV and scanning starting at the
999 root of the server. ::
1001 # configure target config
1002 syncevolution --configure \
1004 syncURL=http://example.com \
1006 "password=!@#ABcd1234" \
1007 target-config@webdav
1009 # configure sync config
1010 syncevolution --configure \
1011 --template SyncEvolution_Client \
1012 syncURL=local://@webdav \
1016 calendar addressbook
1019 syncevolution --sync slow webdav
1022 syncevolution webdav
1024 Here are some alternative ways of configuring the target config::
1026 # A) Server supports DNS auto-discovery via domain name in the username.
1027 syncevolution --configure \
1029 username=123456@example.com \
1030 "password=!@#ABcd1234" \
1031 target-config@webdav
1033 # B) Explicitly specify collections (from server documentation or --print-databases).
1034 # The 'calendar' and 'addressbook' names are the ones expected by the sync config
1035 # above, additional datastores can also be configured and/or the names can be changed.
1036 syncevolution --configure \
1038 "password=!@#ABcd1234" \
1040 syncURL=http://example.com \
1041 addressbook/backend=carddav \
1042 addressbook/database=http://example.com/addressbooks/123456/ \
1043 calendar/backend=caldav \
1044 calendar/database=http://example.com/calendar/123456/ \
1045 target-config@webdav \
1046 calendar addressbook
1048 When creating these target configs, the command line tool tries to
1049 verify that the datastores really work and (in the case of --template
1050 webdav) will enable only datastores which really work. This involves
1051 contacting the WebDAV server.
1053 Finally, here is how the ``@webdav`` context needs to be configured so that SyncML
1054 clients or servers can be added to it::
1056 # configure datastores
1057 syncevolution --configure \
1058 databaseUser=123456 \
1059 "databasePassword=!@#ABcd1234" \
1060 addressbook/backend=carddav \
1061 addressbook/database=http://example.com/addressbooks/123456/ \
1062 calendar/backend=caldav \
1063 calendar/database=http://example.com/calendar/123456/ \
1065 calendar addressbook
1067 # configure one peer (Memotoo in this example):
1068 syncevolution --configure \
1070 password=^749@2524 \
1074 syncevolution --sync slow memotoo@webdav
1080 For Google there is no common start URL for CalDAV and CardDAV,
1081 therefore the "Google" template lists all that may be relevant and the
1082 setup is very similar to the generic ``webdav`` case, except that the
1083 syncURL does not have to be specified::
1085 # configure target config
1086 syncevolution --configure \
1088 username=john.doe@gmail.com \
1089 "password=!@#ABcd1234" \
1090 target-config@google
1092 # configure sync config
1093 syncevolution --configure \
1094 --template SyncEvolution_Client \
1095 syncURL=local://@google \
1099 calendar addressbook
1102 syncevolution --sync slow google
1105 syncevolution google
1107 If your Google account is configured to use two-factor login, then you
1108 need to create an application specific password for SyncEvolution. See
1109 https://support.google.com/mail/answer/1173270
1111 Google already announced that they will turn off support for logging
1112 into their CalDAV/CardDAV services with plain username/password
1113 credentials. SyncEvolution supports the new login method, OAuth, but
1114 it depends on additional components to implement OAuth: GNOME Online
1115 Accounts, Ubuntu Online Accounts, or gSSO.
1117 Support for GNOME Online Accounts (GOA) is compiled into
1118 syncevolution.org binaries and therefore documented here. For
1119 instructions regarding binaries shipped by distributions please
1120 consult the documentation provided by the distribution or search the
1123 For Google Calendar, GOA >= 3.8 is required. For Google Contacts, GOA
1124 3.8 may work if it was patched by the distribution (as done in Debian
1125 Jessie), otherwise a version >= 3.10 is required.
1127 Use the GNOME Control Center to create an account for Google. It is
1128 not necessary to enable any of the data categories. That would turn on
1129 access in other GNOME apps (for example, Evolution), whereas
1130 SyncEvolution's use of the account is configured separately via the
1131 SyncEvolution command line.
1133 When configuring SyncEvolution for Google, follow the instructions
1134 above with ``username=goa:<Google email address>`` and empty password.
1135 If the email address does not uniquely identify the GOA account,
1136 the SyncEvolution command line will provide a list of accounts to choose
1146 SyncEvolution transmits address book entries as vCard 2.1 or 3.0
1147 depending on the sync format chosen in the configuration. Evolution uses
1148 3.0 internally, so SyncEvolution converts between the two formats as
1149 needed. Calendar items and tasks can be sent and received in iCalendar
1150 2.0 as well as vCalendar 1.0, but vCalendar 1.0 should be avoided if
1151 possible because it cannot represent all data that Evolution stores.
1153 .. note:: The Evolution backends are mentioned as examples;
1154 the same applies to other datastores.
1156 How the server stores the items depends on its implementation and
1157 configuration. To check which data is preserved, one can use this
1158 procedure (described for contacts, but works the same way for
1159 calendars and tasks):
1161 1. synchronize the address book with the server
1162 2. create a new address book in Evolution and view it in Evolution
1163 once (the second step is necessary in at least Evolution 2.0.4
1164 to make the new address book usable in SyncEvolution)
1165 3. add a configuration for that second address book and the
1166 same URI on the SyncML server, see EXAMPLES_ above
1167 4. synchronize again, this time using the other datastore
1169 Now one can either compare the address books in Evolution or do that
1170 automatically, described here for contacts:
1172 - save the complete address books: mark all entries, save as vCard
1173 - invoke `synccompare` with two file names as arguments and it will
1174 normalize and compare them automatically
1176 Normalizing is necessary because the order of cards and their
1177 properties as well as other minor formatting aspects may be
1178 different. The output comes from a side-by-side comparison, but
1179 is augmented by the script so that the context of each change
1180 is always the complete item that was modified. Lines or items
1181 following a ">" on the right side were added, those on the
1182 left side followed by a "<" were removed, and those with
1183 a "|" between text on the left and right side were modified.
1185 The automatic unit testing (see HACKING) contains a `testItems`
1186 test which verifies the copying of special entries using the
1189 Modifying one of the address books or even both at the same time and
1190 then synchronizing back and forth can be used to verify that
1191 SyncEvolution works as expected. If you do not trust SyncEvolution or
1192 the server, then it is prudent to run these checks with a copy of the
1193 original address book. Make a backup of the .evolution/addressbook
1196 Item Changes and Data Changes
1197 -----------------------------
1199 SyncML clients and servers consider each entry in a database as one
1200 item. Items can be added, removed or updated. This is the item change
1201 information that client and server exchange during a normal,
1202 incremental synchronization.
1204 If an item is saved, removed locally, and reimported, then this is
1205 usually reported to a peer as "one item removed, one added" because
1206 the information available to SyncEvolution is not sufficient to
1207 determine that this is in fact the same item. One exception are
1208 iCalendar 2.0 items with their globally unique ID: the modification
1209 above will be reported to the server as "one item updated".
1211 That is better, but still not quite correct because the content of the
1212 item has not changed, only the meta information about it which is used
1213 to detect changes. This cannot be avoided without creating additional
1214 overhead for normal synchronizations.
1216 SyncEvolution reports *item changes* (the number of added, removed and
1217 updated items) as well as *data changes*. These data changes are
1218 calculated by comparing database dumps using the `synccompare` tool.
1219 Because this data comparison ignores information about which data
1220 belongs to which item, it is able to detect that re-adding an item
1221 that was removed earlier does not change the data, in contrast to the
1222 item changes. On the other hand, removing one item and adding a
1223 different one may look like updating just one item.
1225 Automatic Backups and Logging
1226 -----------------------------
1228 To support recovery from a synchronization which damaged the
1229 local data or modified it in an unexpected way, SyncEvolution
1230 can create the following files during a synchronization:
1232 - a dump of the data in a format which can be restored by
1233 SyncEvolution, usually a single file per item containing
1234 in a standard text format (VCARD/VCALENDAR)
1235 - a full log file with debug information
1236 - another dump of the data after the synchronization for
1237 automatic comparison of the before/after state with
1240 If the sync configuration property ``logdir`` is set, then
1241 a new directory will be created for each synchronization
1242 in that directory, using the format `<peer>-<yyyy>-<mm>-<dd>-<hh>-<mm>[-<seq>]`
1243 with the various fields filled in with the time when the
1244 synchronization started. The sequence suffix will only be
1245 used when necessary to make the name unique. By default,
1246 SyncEvolution will never delete any data in that log
1247 directory unless explicitly asked to keep only a limited
1248 number of previous log directories.
1250 This is done by setting the ``maxlogdirs`` limit to something
1251 different than the empty string and 0. If a limit is set,
1252 then SyncEvolution will only keep that many log directories
1253 and start removing the "less interesting" ones when it reaches
1254 the limit. Less interesting are those where no data changed
1255 and no error occurred.
1257 To avoid writing any additional log file or database dumps during
1258 a synchronization, the ``logdir`` can be set to ``none``. To reduce
1259 the verbosity of the log, set ``loglevel``. If not set or 0, then
1260 the verbosity is set to 3 = DEBUG when writing to a log file and
1261 2 = INFO when writing to the console directly. To debug issues
1262 involving data conversion, level 4 also dumps the content of
1268 The following environment variables control where SyncEvolution finds
1269 files and other aspects of its operations.
1272 Overrides the proxy settings temporarily. Setting it to an empty value
1273 disables the normal proxy settings.
1275 HOME/XDG_CACHE_HOME/XDG_CONFIG_HOME
1276 SyncEvolution follows the XDG_ desktop standard for its files. By default,
1277 `$HOME/.config/syncevolution` is the location for configuration files.
1278 `$HOME/.cache/syncevolution` holds session directories with log files and
1281 .. _XDG: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
1284 Setting this to any value disables the filtering of stdout and stderr
1285 that SyncEvolution employs to keep noise from system libraries out
1286 of the command line output.
1288 SYNCEVOLUTION_GNUTLS_DEBUG
1289 Enables additional debugging output when using the libsoup HTTP transport library.
1291 SYNCEVOLUTION_DATA_DIR
1292 Overrides the default path to the bluetooth device lookup table,
1293 normally `/usr/lib/syncevolution/`.
1295 SYNCEVOLUTION_BACKEND_DIR
1296 Overrides the default path to plugins, normally `/usr/lib/syncevolution/backends`.
1298 SYNCEVOLUTION_LIBEXEC_DIR
1299 Overrides the path where additional helper executables are found, normally
1302 SYNCEVOLUTION_LOCALE_DIR
1303 Overrides the path to directories with the different translations,
1304 normally `/usr/share/locale`.
1306 SYNCEVOLUTION_TEMPLATE_DIR
1307 Overrides the default path to template files, normally
1308 `/usr/share/syncevolution/templates`.
1310 SYNCEVOLUTION_XML_CONFIG_DIR
1311 Overrides the default path to the Synthesis XML configuration files, normally
1312 `/usr/share/syncevolution/xml`. These files are merged into one configuration
1313 each time the Synthesis SyncML engine is started as part of a sync session.
1315 Note that in addition to this directory, SyncEvolution also always
1316 searches for configuration files inside `$HOME/.config/syncevolution-xml`.
1317 Files with the same relative path and name as in `/usr/share/syncevolution/xml`
1318 override those files, others extend the final configuration.
1323 See `known issues`_ and the `support`_ web page for more information.
1325 .. _known issues: http://syncevolution.org/documentation/known-issues
1326 .. _support: http://syncevolution.org/support
1331 http://syncevolution.org
1337 Patrick Ohly <patrick.ohly@intel.com>, http://www.estamos.de
1339 http://syncevolution.org/about/contributors
1340 :To contact the project publicly (preferred):
1341 syncevolution@syncevolution.org
1342 :Intel-internal team mailing list (confidential):
1343 syncevolution@lists.intel.com