1SYNCEVOLUTION(1) SYNCEVOLUTION(1)
2
6 SyncEvolution - synchronize personal information management data
7
9 List and manipulate databases:
10 syncevolution --print-databases|--create-database|--remove-data‐
11 base [<properties>] [<config> <store>]
12 Show information about configuration(s):
14 syncevolution --print-servers|--print-configs|--print-peers
15 Show information about a specific configuration:
17 syncevolution --print-config [--quiet] [--] <config>
18 [main|<store> ...]
19 List sessions:
21 syncevolution --print-sessions [--quiet] [--] <config>
22 Show information about SyncEvolution:
24 syncevolution --help|-h|--version
25 Run a synchronization as configured:
27 syncevolution <config> [<store> ...]
28 Run a synchronization with properties changed just for this run:
30 syncevolution --run <options for run> [--] <config> [<store>
31 ...]
32 Restore data from the automatic backups:
34 syncevolution --restore <session directory> --before|--after
35 [--dry-run] [--] <config> <store> ...
36 Create, update or remove a configuration:
38 syncevolution --configure <options> [--] <config> [<store> ...]
39 syncevolution --remove|--migrate <options> [--] <config>
41 List items:
43 syncevolution --print-items [--] [<config> [<store>]]
44 Export item(s):
46 syncevolution [--delimiter <string>] --export <dir>|<file>|-
48 [--] [<config> [<store> [<luid> ...]]]
49 --luids <luid> ...
50 Add item(s):
52 syncevolution [--delimiter <string>|none] --import
54 <dir>|<file>|- [--] [<config> [<store>]]
55 --luids <luid> ...
56 Update item(s):
58 syncevolution --update <dir> [--] <config> <store>
59 syncevolution [--delimiter <string>|none] --update <file>|- [--]
61 <config> <store> <luid> ...
62 --luids <luid> ...
63 Remove item(s):
65 syncevolution --delete-items [--] <config> <store> (<luid> ... |
66 '*')
67
69 This text explains the usage of the SyncEvolution command line.
70 SyncEvolution synchronizes personal information management (PIM) data
72 such as contacts, appointments, tasks and memos using the Synthesis
73 sync engine, which provides support for the SyncML synchronization pro‐
74 tocol.
75 SyncEvolution synchronizes with SyncML servers over HTTP and with
77 SyncML capable phones locally over Bluetooth (new in 1.0). Plugins pro‐
78 vide access to the data which is to be synchronized. Binaries are
79 available for Linux desktops (synchronizing data in GNOME Evolution,
80 with KDE supported indirectly already and Akonadi support in develop‐
81 ment), for MeeGo (formerly Moblin) and for Maemo 5/Nokia N900. The
82 source code can be compiled for Unix-like systems and provides a frame‐
83 work to build custom SyncML clients or servers.
84
86 peer A peer is the entity that data is synchronized with. This can be
87 another device (like a phone), a server (like Google) or even
88 the host itself (useful for synchronizing two different data‐
89 bases).
90 host The device or computer that SyncEvolution runs on.
92 item The smallest unit of synchronization. Examples of items include
94 calendar events and individual contacts, memos, or tasks.
95 database
97 Each peer has one or more databases that get synchronized
98 (Google Calendar, Google Contacts). Conceptually a database is a
99 set of items where each item is independent of the others.
100 backend
102 Access to databases is provided by SyncEvolution backends. It
103 does not matter where that data is stored. Some backends provide
104 access to data outside of the host itself (CalDAV and CardDAV,
105 ActiveSync).
106 datastore (or just store )
108 Used for the combination of SyncEvolution backend and database
109 settings. A datastore provides read/write access to a database,
110 which is a prerequisite for syncing the database. The datastore
111 is independent of the peers that the database might be synchro‐
112 nized with.
113 This used to be called "data source" or just "source", which is
115 a term still found in older documentation, some file paths and
116 the source code of SyncEvolution.
117 local/remote
119 Synchronization always happens between a pair of databases and
120 thus has two sides. One database or side of a sync is remote
121 (the one of the peer), the other is local (SyncEvolution). For
122 the sake of consistency (and lack of better terms), these terms
123 are used even if the peer is another instance of SyncEvolution
124 and/or all data resides on the same storage.
125 sync config
127 A sync configuration defines how to talk with a peer: the proto‐
128 col which is to be used, how to find the peer, credentials, etc.
129 Sync configs can be used to initiate a sync (like contacting a
131 SyncML server) or to handle an incoming sync request (when act‐
132 ing as SyncML server which is contacted by the peer).
133 If the peer supports SyncML as sync protocol, a sync only uses
135 one sync config on the SyncEvolution side. If the peer supports
136 data access via some other protocols, then SyncEvolution can
137 make that data available via SyncML and run a sync where SyncML
138 is used internally. Such a sync involves two sync configs, see
139 originating config and target config.
140 A sync config can use all datastores defined in the same context
142 (see below). Some properties of the datastore can be set differ‐
143 ently for each peer and thus sync config (per-peer). One of
144 these, the sync property, defines if and how a datastore is used
145 during a sync.
146 context
148 Sync and datastore configs are defined inside one or more con‐
149 figuration contexts. There is always a @default context that
150 gets used if nothing else is specified.
151 Typically each context represents a certain set of related data‐
153 stores. For example, normally the @default context is used for
154 local databases. Datastores related to a certain peer can be de‐
155 fined in a context @peer-name named after that peer.
156 configuration properties
158 SyncEvolution uses key/value pairs to store configuration op‐
159 tions. A configuration is a set of unique keys and their values
160 that together describe a certain object.
161 These sets of properties are addressed via the main config name
163 (a sync config name with or without an explicit context, or just
164 the context name) and optionally the datastore name (if the
165 properties are for a specific datastore).
166 Sync properties are set for sync configs, independently of a
168 particular datastore. Properties that cannot be set without
169 specifying they datastore that they apply to are datastore prop‐
170 erties. This includes properties that belong both to a datastore
171 and a sync config.
172 The property names were chosen so that they are unique, i.e., no
174 sync property has the same name as a datastore property. For
175 historic reasons, internally these properties are treated as two
176 different sets and there are two different command line options
177 to query the list of sync resp. datastore properties.
178 Some configuration properties are shared between configurations
180 automatically. This sharing is hard-coded and cannot be config‐
181 ured. It has the advantage that certain settings only need to
182 be set once and/or can be changed for several different configs
183 at once.
184 A property can be unshared (has separate values for each peer,
186 therefore sometimes also called per-peer; for example the sync
187 property), shared (same value for all peers; for example the
188 database property for selecting the local database) or global
189 (exactly one value).
190 Together with the distinction between sync and datastore proper‐
192 ties, this currently results in five different groups of proper‐
193 ties:
194 • Sync properties (by definition, this also includes properties
196 independent of a particular sync config because they are set
197 for all sync configs at once, independently of any particular
198 datastore):
199 • global (= ~/.config/syncevolution/config.ini): independent
201 of a particular context, for example keyring
202 • shared (= ~/.config/syncevolution/<context name>/con‐
204 fig.ini): set once for each context, for example logdir
205 • unshared (= ~/.config/syncevolution/<context
207 name>/peers/<peer name>/config.ini): set separately for each
208 sync config, for example syncURL
209 • Datastore properties:
211 • shared (= ~/.config/syncevolution/<context
213 name>/sources/<store name>/config.ini): the properties re‐
214 quired for access to the data, primarily backend and data‐
215 base
216 • unshared (= ~/.config/syncevolution/<context
218 name>/peers/<peer name>/sources/<store name>/config.ini):
219 the already mentioned sync and uri properties, but also a
220 per-peer sync format properties
221 Many properties have reasonable defaults, either defined in the
223 configuration layer or chosen at runtime by the SyncEvolution
224 engine reading the configuration, and therefore do not have to
225 be set.
226 The configuration layer in SyncEvolution has a very limited un‐
228 derstanding of the semantic of each property. It just knows
229 about some generic types (strings, boolean, integers, ...) and
230 where properties are supposed to be stored. It is the layer
231 above that, the one which actually tries to use the configura‐
232 tion, that determines whether the property values make sense as
233 specified. Beware that it is possible to set properties to val‐
234 ues that conflict with other property values (triggering errors
235 when using the configuration) or to set properties that are not
236 used (typically they get ignored silently, unless an explicit
237 error check was implemented).
238 configuration template
240 Templates define the settings for specific peers. Some templates
241 are packaged together with SyncEvolution, others may be added by
242 packagers or users. Settings from templates are copied once into
243 the sync config when creating it. There is no permanent link
244 back to the template, so updating a template has no effect on
245 configs created from it earlier.
246 A template only contains unshared properties. Therefore it is
248 possible to first set shared properties (for example, choosing
249 which databases to synchronize in the default context), then add
250 sync configs for different peers to that context without reset‐
251 ing the existing settings.
252 In SyncEvolution's predefined configuration templates, the fol‐
254 lowing names for datastores are used. Different names can be
255 chosen for datastores that are defined manually.
256 • addressbook: a list of contacts
258 • calendar: calendar events
260 • memo: plain text notes
262 • todo: task list
264 • calendar+todo: a virtual datastore combining one local "calen‐
266 dar" and one "todo" datastore (required for synchronizing with
267 some phones)
268 local sync
270 Traditionally, a sync config specifies SyncML as the synchro‐
271 nization protocol via the syncURL property. The peer must sup‐
272 port SyncML for this to work.
273 In a so called local sync, SyncEvolution acts as SyncML server
275 and client at the same time, connecting the two sides via inter‐
276 nal message passing. Both sides have their own set of datas‐
277 tores, which may use CalDAV, CardDAV or ActiveSync to access the
278 data.
279 See Synchronization beyond SyncML.
281 originating config
283 In a local sync, the sync config used to start the sync is
284 called the originating sync config, or just originating config.
285 target config
287 In addition to the originating config, a local sync also uses a
288 target config. At the configuration level, this target config is
289 just another sync config. It becomes a target config when refer‐
290 enced by a sync config for local syncing.
291
293 The <config> and the <store> strings in the command line synopsis are
294 used to find the sync resp. datastore configs. Depending on which other
295 parameters are given, different operations are executed.
296 The <config> string has the format [<peer>][@<context>]. When the con‐
298 text is not specified explicitly, SyncEvolution first searches for an
299 existing sync configuration with the given <peer> name. If not found,
300 the configuration can only be created, but not read. It will be created
301 in the @default context as fallback. The empty <config> string is an
302 alias for @default.
303 The <peer> part identifies a specific sync or target config inside the
305 context. It is optional and does not have to be specified when not
306 needed, for example when configuring the shared settings of datastores
307 (--configure @default addressbook) or accessing items inside a datas‐
308 tore (--print-items @work calendar).
309 Listing datastores on the command line limits the operation to those
311 datastores (called active datastores below). If not given, all datas‐
312 tores enabled for the config are active. Some operations require the
313 name of exactly one datastore.
314 Properties are set with key/value assignments and/or the
316 --sync/store-property keywords. Those keywords are only needed for the
317 hypothetical situation that a sync and datastore property share the
318 same name (which was intentionally avoided). Without them, SyncEvolu‐
319 tion automatically identifies which kind of property is meant based on
320 the name.
321 A <property> assignment has the following format:
323 [<store>/]<name>[@<context>|@<peer>@<context>]=<value>
325 The optional <context> or <peer>@<context> suffix limits the scope of
327 the value to that particular configuration. This is useful when running
328 a local sync, which involves a sync and a target configuration. For ex‐
329 ample, the log level can be specified separately for both sides:
330 --run loglevel@default=1 loglevel@google-calendar=4 google-calendar@default
332 A string without a second @ sign inside is always interpreted as a con‐
334 text name, so in contrast to the <config> string, foo cannot be used to
335 reference the foo@default configuration. Use the full name including
336 the context for that.
337 When no config or context is specified explicitly, a value is changed
339 in all active configs, typically the one given with <config>. The pri‐
340 ority of multiple values for the same config is more specific defini‐
341 tion wins, so <peer>@<context> overrides @<context>, which overrides no
342 suffix given. Specifying some suffix which does not apply to the cur‐
343 rent operation does not trigger an error, so beware of typos.
344 Datastore properties can be specified with a <store>/ prefix. This al‐
346 lows limiting the value to the selected datastore. For example:
347 --configure "addressbook/database=My Addressbook" \
349 "calendar/database=My Calendar" \
350 @default addressbook calendar
351 Another way to achieve the same effect is to run the --configure opera‐
353 tion twice, once for addressbook and once for calendar:
354 --configure "database=My Addressbook" @default addressbook
356 --configure "database=My Calendar" @default calendar
357 If the same property is set both with and without a <store>/ prefix,
359 then the more specific value with that prefix is used for that datas‐
360 tore, regardless of the order on the command line. The following com‐
361 mand enables all datastores except for the addressbook:
362 --configure addressbook/sync=none \
364 sync=two-way \
365 <sync config>
366
368 syncevolution --print-databases [<properties>] [<config> <store>]
369 If no additional arguments are given, then SyncEvolution will list all
371 available backends and the databases that can be accessed through each
372 backend. This works without existing configurations. However, some
373 backends, like for example the CalDAV backend, need additional informa‐
374 tion (like credentials or URL of a remote server). This additional in‐
375 formation can be provided on the command line with property assignments
376 (username=...) or in an existing configuration.
377 When listing all databases of all active datastores, the output starts
379 with a heading that lists the values for the backend property which se‐
380 lect the backend, followed by the databases. Each database has a name
381 and a unique ID (in brackets). Typically both can be used as value of
382 the 'database' property. One database might be marked as default. It
383 will be used when database is not set explicitly.
384 When selecting an existing datastore configuration or specifying the
386 backend property on the command line, only the databases for that back‐
387 end are listed and the initial line shows how that backend was selected
388 (<config>/<store> resp. backend value).
389 Some backends do not support listing of databases. For example, the
391 file backend synchronizes directories with one file per item and always
392 needs an explicit database property because it cannot guess which di‐
393 rectory it is meant to use.
394 syncevolution --create-database [<properties>] [<config> <store>]
396 Creates a new database for the selected backend, using the information
398 given in the database property. As with --print-databases, it is possi‐
399 ble to give the properties directly without configuring a datastore
400 first.
401 The interpretation of the database property depends on the backend. Not
403 all backends support this operation.
404 The EDS backend uses the value of the database as name of the new data‐
406 base and assigns a unique URI automatically.
407 syncevolution --remove-database [<properties>] [<config> <store>]
409 Looks up the database based on the database property (depending on the
411 backend, both name and a URI are valid), then deletes the data. Note
412 that datastore configurations using the database are not removed.
413 syncevolution <config>
415 Without the optional list of datastores, all datastores which are en‐
417 abled in their configuration file are synchronized.
418 syncevolution <config> <store> ...
420 Otherwise only the ones mentioned on the command line are active. It is
422 possible to configure datastores without activating their synchroniza‐
423 tion: if the synchronization mode of a datastore is set to disabled,
424 the datastore will be ignored. Explicitly listing such a datastore will
425 synchronize it in two-way mode once.
426 Progress and error messages are written into a log file that is pre‐
428 served for each synchronization run. Details about that is found in the
429 Automatic Backups and Logging section below. All errors and warnings
430 are printed directly to the console in addition to writing them into
431 the log file. Before quitting SyncEvolution will print a summary of how
432 the local data was modified. This is done with the synccompare utility
433 script described in the Exchanging Data section.
434 When the logdir property is enabled (since v0.9 done by default for new
436 configurations), then the same comparison is also done before the syn‐
437 chronization starts.
438 In case of a severe error the synchronization run is aborted prema‐
440 turely and SyncEvolution will return a non-zero value. Recovery from
441 failed synchronization is done by forcing a full synchronization during
442 the next run, i.e. by sending all items and letting the SyncML server
443 compare against the ones it already knows. This is avoided whenever
444 possible because matching items during a slow synchronization can lead
445 to duplicate entries.
446 After a successful synchronization the server's configuration file is
448 updated so that the next run can be done incrementally. If the config‐
449 uration file has to be recreated e.g. because it was lost, the next run
450 recovers from that by doing a full synchronization. The risk associated
451 with this is that the server might not recognize items that it already
452 has stored previously which then would lead to duplication of items.
453 syncevolution --configure <options for configuration> <config> [<store> ...]
455 Options in the configuration can be modified via the command line. The
457 <config> and the optional <store> parameters define what gets created
458 or modified. The remaining parameters define which values get set or
459 modified.
460 To change settings of specific datastores, either invoke syncevolution
462 multiple times with exactly one <store> parameter or use the [<store>/]
463 prefix described above for property assignments.
464 syncevolution --remove <config>
466 Deletes the configuration. If the <config> refers to a specific peer,
468 only that peer's configuration is removed. If it refers to a context,
469 that context and all peers and datastores defined inside it are re‐
470 moved.
471 Note that there is no confirmation question. Neither local data refer‐
473 enced by the configuration nor the content of log dirs are deleted.
474 syncevolution --run <options for run> <config> [<store> ...]
476 Options can also be overridden for just the current run, without chang‐
478 ing the configuration. In order to prevent accidentally running a sync
479 session when a configuration change was intended, either --configure or
480 --run must be given explicitly if options are specified on the command
481 line.
482 syncevolution --status <config> [<store> ...]
484 Prints what changes were made locally since the last synchronization.
486 Depends on access to database dumps from the last run, so enabling the
487 logdir property is recommended.
488 syncevolution --print-servers|--print-configs|--print-peers
490 syncevolution --print-config [--quiet] <config> [main|<store> ...]
491 syncevolution --print-sessions [--quiet] <config>
492 These commands print information about existing configurations. When
494 printing a configuration a short version without comments can be se‐
495 lected with --quiet. When datastores are listed, only their configura‐
496 tion is shown. Main instead or in combination with datastores lists
497 only the main peer configuration.
498 syncevolution --restore <session directory> --before|--after
500 [--dry-run] <config> <store> ...
501 This restores local data from the backups made before or after a syn‐
503 chronization session. The --print-sessions command can be used to find
504 these backups. The datastore(s) have to be listed explicitly. There is
505 intentionally no default, because as with --remove there is no confir‐
506 mation question. With --dry-run, the restore is only simulated.
507 The session directory has to be specified explicitly with its path name
509 (absolute or relative to current directory). It does not have to be one
510 of the currently active log directories, as long as it contains the
511 right database dumps for the selected datastores.
512 A restore tries to minimize the number of item changes (see section
514 Item Changes and Data Changes). This means that items that are identi‐
515 cal before and after the change will not be transmitted anew to the
516 peer during the next synchronization. If the peer somehow needs to get
517 a clean copy of all local items, then use --sync refresh-from-local in
518 the next run.
519 syncevolution --print-items <config> <store>
521 syncevolution [--delimiter <string>] --export <dir>|<file>|- [<config> [<store> [<luid> ...]]]
522 syncevolution [--delimiter <string>|none] --import <dir>|<file>|- [<config> <store>]
523 syncevolution --update <dir> <config> <store>
524 syncevolution [--delimiter <string>|none] --update <file>|- <config> <store> <luid> ...
525 syncevolution --delete-items <config> <store> (<luid> ... | *)
526 Restore depends on the specific format of the automatic backups created
528 by SyncEvolution. Arbitrary access to item data is provided with addi‐
529 tional options. <luid> here is the unique local identifier assigned to
530 each item in the datastore, transformed so that it contains only al‐
531 phanumeric characters, dash and underscore. A star * in --delete-items
532 selects all items for deletion. There are two ways of specifying luids:
533 either as additional parameters after the config and datastore parame‐
534 ters (which may be empty in this case, but must be given) or after the
535 --luids keyword.
536 <config> and <store> may be given to define the database which is to be
538 used. If not given or not refering to an existing configuration (which
539 is not an error, due to historic reasons), the desired backend must be
540 given via the backend property, like this:
541 syncevolution --print-items backend=evolution-contacts
543 syncevolution --export - backend=evolution-contacts \
544 --luids pas-id-4E33F24300000006 pas-id-4E36DD7B00000007
545 The desired backend database can be chosen via database=<identifier>.
547 See --print-databases.
548
550 Here is a full description of all <options> that can be put in front of
551 the server name. Whenever an option accepts multiple values, a question
552 mark can be used to get the corresponding help text and/or a list of
553 valid values.
554 --sync|-s <mode>|?
556 Temporarily synchronize the active datastores in that mode. Use‐
557 ful for a refresh-from-local or refresh-from-remote sync which
558 clears all data at one end and copies all items from the other.
559 Warning: local is the data accessed via the sync config directly
561 and remote is the data on the peer, regardless where the data is
562 actually stored physically.
563 --print-servers|--print-configs|--print-peers
565 Prints the names of all configured peers to stdout. There is no
566 difference between these options, the are just aliases.
567 --print-servers|--print-configs|--print-peers|-p
569 Prints the complete configuration for the selected <config> to
570 stdout, including up-to-date comments for all properties. The
571 format is the normal .ini format with datastore configurations
572 in different sections introduced with [<store>] lines. Can be
573 combined with --sync-property and --datastore-property to modify
574 the configuration on-the-fly. When one or more datastores are
575 listed after the <config> name on the command line, then only
576 the configs of those datastores are printed. main selects the
577 main configuration instead of datastore configurations. Using
578 --quiet suppresses the comments for each property. When setting
579 a --template, then the reference configuration for that peer is
580 printed instead of an existing configuration.
581 --print-sessions
583 Prints information about previous synchronization sessions for
584 the selected peer or context are printed. This depends on the
585 logdir property. The information includes the log directory
586 name (useful for --restore) and the synchronization report. In
587 combination with --quiet, only the paths are listed.
588 --configure|-c
590 Modify the configuration files for the selected peer and/or
591 datastores.
592 If no such configuration exists, then a new one is created using
594 one of the template configurations (see --template option).
595 Choosing a template sets most of the relevant properties for the
596 peer and the default set of datastores (see above for a list of
597 those). Anything specific to the user (like username/password)
598 still has to be set manually.
599 When creating a new configuration and listing datastores explic‐
601 itly on the command line, only those datastores will be set to
602 active in the new configuration, i.e. syncevolution -c memotoo
603 addressbook followed by syncevolution memotoo will only synchro‐
604 nize the address book. The other datastores are created in a
605 disabled state. When modifying an existing configuration and
606 datastores are specified, then the datastore properties of only
607 those datastores are modified.
608 By default, creating a config requires a template. Datastore
610 names on the command line must match those in the template. This
611 allows catching typos in the peer and datastore names. But it
612 also prevents some advanced use cases. Therefore it is possible
613 to disable these checks in two ways:
614 - 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, ...)
618 --run|-r
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 se‐
623 lected on the command line and they are meant to be used during
624 a sync session triggered by the invocation.
625 --migrate
627 In older SyncEvolution releases a different layout of configura‐
628 tion files was used. Using --migrate will automatically migrate
629 to the new layout and rename the <config> into <config>.old to
630 prevent accidental use of the old configuration. WARNING: old
631 SyncEvolution releases cannot use the new configuration!
632 The switch can also be used to migrate a configuration in the
634 current configuration directory: this preserves all property
635 values, discards obsolete properties and sets all comments ex‐
636 actly as if the configuration had been created from scratch.
637 WARNING: custom comments in the configuration are not preserved.
638 --migrate implies --configure and can be combined with modifying
640 properties.
641 --print-items
643 Shows all existing items using one line per item using the for‐
644 mat "<luid>[: <short description>]". Whether the description is
645 available depends on the backend and the kind of data that it
646 stores.
647 --export
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. Other‐
652 wise it creates a new file under that name and writes the se‐
653 lected items separated by the chosen delimiter string. stdout
654 can be selected with a dash.
655 The default delimiter (two line breaks) matches a blank line. As
657 a special case, it also matches a blank line with DOS line end‐
658 ing (line break, carriage return, line break). This works for
659 vCard 3.0 and iCalendar 2.0, which never contain blank lines.
660 When exporting, the default delimiter will always insert two
662 line breaks regardless whether the items contain DOS line ends.
663 As a special case, the initial newline of a delimiter is skipped
664 if the item already ends in a newline.
665 --import
667 Adds all items found in the directory or input file to the data‐
668 store. When reading from a directory, each file is treated as
669 one item. Otherwise the input is split at the chosen delimiter.
670 "none" as delimiter disables splitting of the input.
671 --update
673 Overwrites the content of existing items. When updating from a
674 directory, the name of each file is taken as its luid. When up‐
675 dating from file or stdin, the number of luids given on the com‐
676 mand line must match with the number of items in the input.
677 --delete-items
679 Removes the specified items from the datastore. Most backends
680 print some progress information about this, but besides that, no
681 further output is produced. Trying to remove an item which does
682 not exist typically leads to an ERROR message, but is not re‐
683 flected in a non-zero result of the command line invocation it‐
684 self because the situation is not reported as an error by back‐
685 ends (removal of non-existent items is not an error in SyncML).
686 Use a star * instead or in addition to listing individual luids
687 to delete all items.
688 --sync-property|-y <property>=<value>|<property>=?|?
690 Overrides a datastore-independent configuration property for the
691 current synchronization run or permanently when --configure is
692 used to update the configuration. Can be used multiple times.
693 Specifying an unused property will trigger an error message.
694 --datastore-property|--source-property|-z <property>=<value>|<prop‐
696 erty>=?|?
697 Same as --sync-property, but applies to the configuration of all
698 active datastores. --sync <mode> is a shortcut for --datas‐
699 tore-property sync=<mode>.
700 --template|-l <peer name>|default|?<device>
702 Can be used to select from one of the built-in default configu‐
703 rations for known SyncML peers. Defaults to the <config> name,
704 so --template only has to be specified when creating multiple
705 different configurations for the same peer, or when using a tem‐
706 plate that is named differently than the peer. default is an
707 alias for memotoo and can be used as the starting point for
708 servers which do not have a built-in template.
709 A pseudo-random device ID is generated automatically. Therefore
711 setting the deviceId sync property is only necessary when manu‐
712 ally recreating a configuration or when a more descriptive name
713 is desired.
714 The available templates for different known SyncML servers are
716 listed when using a single question mark instead of template
717 name. When using the ?<device> format, a fuzzy search for a tem‐
718 plate that might be suitable for talking to such a device is
719 done. The matching works best when using <device> = <Manufac‐
720 turer> <Model>. If you don't know the manufacturer, you can just
721 keep it as empty. The output in this mode gives the template
722 name followed by a short description and a rating how well the
723 template matches the device (100% is best).
724 --status|-t
726 The changes made to local data since the last synchronization
727 are shown without starting a new one. This can be used to see in
728 advance whether the local data needs to be synchronized with the
729 server.
730 --quiet|-q
732 Suppresses most of the normal output during a synchronization.
733 The log file still contains all the information.
734 --keyring[=<value>]|-k
736 A legacy option, now the same as setting the global keyring sync
737 property. When not specifying a value explicitly, "true" for
738 "use some kind of keyring" is implied. See "--sync-property
739 keyring" for details.
740 --daemon[=yes/no]
742 By default, the SyncEvolution command line is executed inside
743 the syncevo-dbus-server process. This ensures that synchroniza‐
744 tion sessions started by the command line do not conflict with
745 sessions started via some other means (GUI, automatically). For
746 debugging purposes or very special use cases (running a local
747 sync against a server which executes inside the daemon) it is
748 possible to execute the operation without the daemon (--dae‐
749 mon=no).
750 --help|-h
752 Prints usage information.
753 --version
755 Prints the SyncEvolution version.
756
758 This section lists predefined properties. Backends can add their own
759 properties at runtime if none of the predefined properties are suitable
760 for a certain setting. Those additional properties are not listed here.
761 Use --sync/datastore-property ? to get an up-to-date list.
762 The predefined properties may also be interpreted slightly differently
764 by each backend and sync protocol. Sometimes this is documented in the
765 comment for each property, sometimes in the documentation of the back‐
766 end or sync protocol.
767 Properties are listed together with all recognized aliases (in those
769 cases where a property was renamed at some point), its default value,
770 sharing state (unshared/shared/global). Some properties must be de‐
771 fined, which is marked with the word required.
772 Sync properties
774 syncURL (no default, unshared, required)
775 Identifies how to contact the peer, best explained with some ex‐
776 amples.
777 HTTP(S) SyncML servers:
779 http://example.com/sync
781 OBEX over Bluetooth uses the MAC address, with the channel cho‐
783 sen automatically:
784 obex-bt://00:0A:94:03:F3:7E
786 If the automatism fails, the channel can also be specified:
788 obex-bt://00:0A:94:03:F3:7E+16
790 For peers contacting us via Bluetooth, the MAC address is used
792 to identify it before the sync starts. Multiple urls can be
793 specified in one syncURL property:
794 obex-bt://00:0A:94:03:F3:7E obex-bt://00:01:02:03:04:05
796 In the future this might be used to contact the peer via one of
798 several transports; right now, only the first one is tried.
799 username (no default, unshared)
801 user name used for authorization with the SyncML server
802 password (no default, unshared)
804 password used for authorization with the peer; in addition to
805 specifying it directly as plain text, it can also be read from
806 the standard input or from an environment variable of your
807 choice:
808 plain text : password = <insert your password here>
810 ask : password = -
811 env variable: password = ${<name of environment variable>}
812 logdir (no default, shared)
814 full path to directory where automatic backups and logs are
815 stored for all synchronizations; if unset, then
816 "${XDG_CACHE_HOME}/syncevolution/<server>" (which usually ex‐
817 pands to ${HOME}/.cache/...) will be used; if "none", then no
818 backups of the databases are made and any output is printed di‐
819 rectly to the screen
820 loglevel (0, unshared)
822 level of detail for log messages: - 0 (or unset) = INFO messages
823 without log file, DEBUG with log file - 1 = only ERROR messages
824 - 2 = also INFO messages - 3 = also DEBUG messages > 3 = in‐
825 creasing amounts of debug messages for developers
826 notifyLevel (3, unshared)
828 Level of detail for desktop notifications. Currently such noti‐
829 fications are generated only for automatically started sync ses‐
830 sions.
831 0 - suppress all notifications 1 - show only errors 2 - show in‐
833 formation about changes and errors (in practice currently the
834 same as level 3) 3 - show all notifications, including starting
835 a sync
836 printChanges (TRUE, unshared)
838 enables or disables the detailed (and sometimes slow) comparison
839 of database content before and after a sync session
840 dumpData (TRUE, unshared)
842 enables or disables the automatic backup of database content be‐
843 fore and after a sync session (always enabled if printChanges is
844 enabled)
845 maxlogdirs (10, shared)
847 Controls how many session directories are kept at most in the
848 logdir. Unless set to zero, SyncEvolution will remove old di‐
849 rectories and all their content to prevent the number of log di‐
850 rectories from growing beyond the given limit. It tries to be
851 intelligent and will remove sessions in which nothing interest‐
852 ing happened (no errors, no data changes) in favor of keeping
853 sessions where something happened, even if those sessions are
854 older.
855 autoSync (0, unshared)
857 Controls automatic synchronization. Currently, automatic syn‐
858 chronization is done by running a synchronization at regular in‐
859 tervals. This may drain the battery, in particular when using
860 Bluetooth! Because a peer might be reachable via different
861 transports at some point, this option provides detailed control
862 over which transports may be used for automatic synchronization:
863 0 don't do auto sync
865 1
867 do automatic sync, using whatever transport
869 is available
870 http only via HTTP transport
872 obex-bt
874 only via Bluetooth transport
875 http,obex-bt
877 pick one of these
878 autoSyncInterval (30M, unshared)
880 This is the minimum number of seconds since the start of the
881 last synchronization that has to pass before starting an auto‐
882 matic synchronization. Can be specified using a 1h30m5s format.
883 Before reducing this interval, consider that it will increase
885 resource consumption on the local and remote side. Some SyncML
886 server operators only allow a certain number of sessions per
887 day. The value 0 has the effect of only running automatic syn‐
888 chronization when changes are detected (not implemented yet,
889 therefore it basically disables automatic synchronization).
890 autoSyncDelay (5M, unshared)
892 An automatic sync will not be started unless the peer has been
893 available for this duration, specified in seconds or 1h30m5s
894 format.
895 This prevents running a sync when network connectivity is unre‐
897 liable or was recently established for some other purpose. It is
898 also a heuristic that attempts to predict how long connectivity
899 be available in the future, because it should better be avail‐
900 able long enough to complete the synchronization.
901 preventSlowSync (TRUE, unshared)
903 During a slow sync, the SyncML server must match all items of
904 the client with its own items and detect which ones it already
905 has based on properties of the items. This is slow (client must
906 send all its data) and can lead to duplicates (when the server
907 fails to match correctly). It is therefore sometimes desirable
908 to wipe out data on one side with a refresh-from-client/server
909 sync instead of doing a slow sync. When this option is enabled,
910 slow syncs that could cause problems are not allowed to proceed.
911 Instead, the affected datastores are skipped, allowing the user
912 to choose a suitable sync mode in the next run (slow sync se‐
913 lected explicitly, refresh sync). The following situations are
914 handled:
915 • running as client with no local data => unproblematic, slow
917 sync is allowed to proceed automatically
918 • running as client with local data => client has no information
920 about server, so slow sync might be problematic and is pre‐
921 vented
922 • client has data, server asks for slow sync because all its
924 data was deleted (done by Memotoo and Mobical, because they
925 treat this as 'user wants to start from scratch') => the sync
926 would recreate all the client's data, even if the user really
927 wanted to have it deleted, therefore slow sync is prevented
928 useProxy (FALSE, unshared)
930 set to T to choose an HTTP proxy explicitly; otherwise the de‐
931 fault proxy settings of the underlying HTTP transport mechanism
932 are used; only relevant when contacting the peer via HTTP
933 proxyHost (no default, unshared)
935 proxy URL (http://<host>:<port>)
936 proxyUsername (no default, unshared)
938 authentication for proxy: username
939 proxyPassword (no default, unshared)
941 proxy password, can be specified in different ways, see SyncML
942 server password for details
943 clientAuthType (md5, unshared)
945 • empty or "md5" for secure method (recommended)
947 • "basic" for insecure method
949 This setting is only for debugging purpose and only has an ef‐
951 fect during the initial sync of a client. Later it remembers
952 the method that was supported by the server and uses that. When
953 acting as server, clients contacting us can use both basic and
954 md5 authentication.
955 RetryDuration (5M, unshared)
957 The total amount of time in seconds in which the SyncML client
958 tries to get a response from the server. During this time, the
959 client will resend messages in regular intervals (RetryInterval)
960 if no response is received or the message could not be delivered
961 due to transport problems. When this time is exceeded without a
962 response, the synchronization aborts without sending further
963 messages to the server.
964 When acting as server, this setting controls how long a client
966 is allowed to not send a message before the synchronization is
967 aborted.
968 RetryInterval (2M, unshared)
970 The number of seconds between the start of SyncML message send‐
971 ing and the start of the retransmission. If the interval has al‐
972 ready passed when a message send returns, the message is resent
973 immediately. Resending without any delay will never succeed and
974 therefore specifying 0 disables retries.
975 Servers cannot resend messages, so this setting has no effect in
977 that case.
978 The WebDAV backend also resends messages after a temporary net‐
980 work error. It uses exponential backoff to determine when the
981 server is available again. This setting is divided by 24 to ob‐
982 tain the initial delay (default: 2m => 5s), which is then dou‐
983 bled for each retry.
984 remoteIdentifier (no default, unshared)
986 the identifier sent to the remote peer for a server initiated
987 sync. if not set, deviceId will be used instead
988 PeerIsClient (FALSE, unshared)
990 Indicates whether this configuration is about a client peer or
991 server peer.
992 SyncMLVersion (no default, unshared)
994 On a client, the latest commonly supported SyncML version is
995 used when contacting a server. One of '1.0/1.1/1.2' can be used
996 to pick a specific version explicitly.
997 On a server, this option controls what kind of Server Alerted
999 Notification is sent to the client to start a synchronization.
1000 By default, first the format from 1.2 is tried, then in case of
1001 failure, the older one from 1.1. 1.2/1.1 can be set explicitly,
1002 which disables the automatism.
1003 Instead or in adddition to the version, several keywords can be
1005 set in this property (separated by spaces or commas):
1006 • NOCTCAP - avoid sending CtCap meta information
1008 • NORESTART - disable the sync mode extension that SyncEvolution
1010 client and server use to negotiate whether both sides support
1011 running multiple sync iterations in the same session
1012 • REQUESTMAXTIME=<time> - override the rate at which the SyncML
1014 server sends preliminary replies while preparing local stor‐
1015 ages in the background. This helps to avoid timeouts in the
1016 SyncML client. Depends on multithreading. This SyncEvolution
1017 binary is thread-safe and thus this feature is enabled by de‐
1018 fault for HTTP servers, with a delay of 2 minutes between mes‐
1019 sages. Other servers (Bluetooth, local sync) should not need
1020 preliminary replies and the feature is disabled, although it
1021 can be enabled by setting the time explicitly. <time> can be
1022 specified like other durations in the config, for example as
1023 REQUESTMAXTIME=2m.
1024 Setting these flags should only be necessary as workaround for
1026 broken peers.
1027 PeerName (no default, unshared)
1029 An arbitrary name for the peer referenced by this config. Might
1030 be used by a GUI. The command line tool always uses the the con‐
1031 figuration name.
1032 deviceId (no default, shared)
1034 The SyncML server gets this string and will use it to keep track
1035 of changes that still need to be synchronized with this particu‐
1036 lar client; it must be set to something unique (like the
1037 pseudo-random string created automatically for new configura‐
1038 tions) among all clients accessing the same server. myFUNAMBOL
1039 also requires that the string starts with sc-pim-
1040 remoteDeviceId (no default, unshared)
1042 SyncML ID of our peer, empty if unknown; must be set only when
1043 the peer is a SyncML client contacting us via HTTP. Clients
1044 contacting us via OBEX/Bluetooth can be identified either via
1045 this remoteDeviceId property or by their MAC address, if that
1046 was set in the syncURL property.
1047 If this property is empty and the peer synchronizes with this
1049 configuration chosen by some other means, then its ID is
1050 recorded here automatically and later used to verify that the
1051 configuration is not accidentally used by a different peer.
1052 enableWBXML (TRUE, unshared)
1054 use the more compact binary XML (WBXML) for messages between
1055 client and server; not applicable when the peer is a SyncML
1056 client, because then the client chooses the encoding
1057 enableRefreshSync (FALSE, unshared)
1059 Use the more advanced refresh-from-server sync mode to implement
1060 the refresh-from-remote operation. Some SyncML servers do not
1061 support this. Therefore the default is to delete local data be‐
1062 fore doing a slow sync, which has the same effect. However, some
1063 servers work better when they are told explicitly that the sync
1064 is a refresh sync. For example, Funambol's One Media server re‐
1065 jects too many slow syncs in a row with a 417 'retry later' er‐
1066 ror.
1067 maxMsgSize (150000, unshared), maxObjSize (4000000, unshared)
1069 The maximum size of each message can be set (maxMsgSize) and the
1070 peer can be told to never sent items larger than a certain
1071 threshold (maxObjSize). Presumably the peer has to truncate or
1072 skip larger items. Sizes are specified as number of bytes.
1073 SSLServerCertificates (/etc/ssl/certs/ca-certifi‐
1075 cates.crt:/etc/pki/tls/certs/ca-bundle.crt:/usr/share/ssl/certs/ca-bun‐
1076 dle.crt, unshared)
1077 A string specifying the location of the certificates used to au‐
1078 thenticate the server. When empty, the system's default location
1079 will be searched.
1080 SSL support when acting as HTTP server is implemented by the
1082 HTTP server frontend, not with these properties.
1083 SSLVerifyServer (TRUE, unshared)
1085 The client refuses to establish the connection unless the server
1086 presents a valid certificate. Disabling this option considerably
1087 reduces the security of SSL (man-in-the-middle attacks become
1088 possible) and is not recommended.
1089 SSLVerifyHost (TRUE, unshared)
1091 The client refuses to establish the connection unless the
1092 server's certificate matches its host name. In cases where the
1093 certificate still seems to be valid it might make sense to dis‐
1094 able this option and allow such connections.
1095 WebURL (no default, unshared)
1097 The URL of a web page with further information about the server.
1098 Used only by the GUI.
1099 IconURI (no default, unshared)
1101 The URI of an icon representing the server graphically. Should
1102 be a 48x48 pixmap or a SVG (preferred). Used only by the GUI.
1103 ConsumerReady (FALSE, unshared)
1105 Set to true in a configuration template to indicate that the
1106 server works well enough and is available for normal users. Used
1107 by the GUI to limit the choice of configurations offered to
1108 users. Has no effect in a user's server configuration.
1109 peerType (no default, unshared)
1111 Defines what a configuration is meant to be used for. Used in
1112 templates and the resulting configs to tell a GUI that special
1113 handling may be necessary. GUIs should ignore unknown types.
1114 The traditional SyncML configs use an empty value. "WebDAV" is
1115 used for the WebDAV side in a local synchronization.
1116 defaultPeer (no default, global)
1118 the peer which is used by default in some frontends, like the
1119 sync-UI
1120 keyring (yes, global)
1122 Explicitly selects a certain safe password storage. Depending
1123 on how SyncEvolution was compiled and installed the following
1124 values are possible:
1125 GNOME GNOME Keyring
1127 KDE KWallet
1129 yes/true/1
1131 pick one automatically
1132 no/false/0
1134 store passwords in SyncEvolution config files
1135 If unset, the default is to pick one automatically if support
1137 for any kind of password storage was enabled and use the config
1138 files otherwise. When choosing automatically, GNOME keyring is
1139 tried first because distinguishing between KDE and GNOME ses‐
1140 sions automatically is tricky.
1141 Note that using this option applies to all passwords in a con‐
1143 figuration and that the --keyring command line option is merely
1144 an alias for setting the global property, so setting a single
1145 password as follows sets both keyring and proxyPasswords, and
1146 also moves the other passwords into the keyring, even if they
1147 were not stored there already:
1148 --keyring --configure proxyPassword=foo
1149 When passwords were stored in a safe storage, their value is set
1151 to a single hyphen ("-") in the configuration. This means that
1152 when running a synchronization without using the storage, the
1153 password has to be entered interactively. The --print-config
1154 output always shows "-" instead of retrieving the password from
1155 the keyring.
1156 Datastore properties
1158 sync (disabled, unshared, required)
1159 Requests a certain synchronization mode when initiating a sync:
1160 two-way
1162 only send/receive changes since last sync
1163 slow exchange all items
1165 refresh-from-remote
1167 discard all local items and replace with the items on
1168 the peer
1169 refresh-from-local
1171 discard all items on the peer and replace with the lo‐
1172 cal items
1173 one-way-from-remote
1175 transmit changes from peer
1176 one-way-from-local
1178 transmit local changes
1179 local-cache-slow (server only)
1181 mirror remote data locally, transferring all data
1182 local-cache-incremental (server only)
1184 mirror remote data locally, transferring only changes;
1185 falls back to local-cache-slow automatically if neces‐
1186 sary
1187 disabled (or none)
1189 synchronization disabled
1190 refresh/one-way-from-server/client are also supported. Their use
1192 is discouraged because the direction of the data transfer de‐
1193 pends on the role of the local side (can be server or client),
1194 which is not always obvious.
1195 When accepting a sync session in a SyncML server (HTTP server),
1197 only datastores with sync != disabled are made available to the
1198 client, which chooses the final sync mode based on its own con‐
1199 figuration. When accepting a sync session in a SyncML client
1200 (local sync with the server contacting SyncEvolution on a de‐
1201 vice), the sync mode specified in the client is typically over‐
1202 riden by the server.
1203 uri (no default, unshared)
1205 this is appended to the server's URL to identify the server's
1206 database; if unset, the datastore name is used as fallback
1207 backend (select backend, shared)
1209 Specifies the SyncEvolution backend and thus the data which is
1210 synchronized by this datastore. Each backend may support multi‐
1211 ple databases (see 'database' property), different formats in‐
1212 side that database (see 'databaseFormat'), and different formats
1213 when talking to the sync peer (see 'syncFormat' and 'forceSync‐
1214 Format').
1215 A special 'virtual' backend combines several other datastores
1217 and presents them as one set of items to the peer. For example,
1218 Nokia phones typically exchange tasks and events as part of one
1219 set of calendar items.
1220 Right now such a virtual backend is limited to combining one
1222 calendar datastore with events and one task datastore. They have
1223 to be specified in the database property, typically like this:
1224 calendar,todo
1225 Different datastores combined in one virtual datastore must have
1227 a common format. As with other backends, the preferred format
1228 can be influenced via the 'syncFormat' attribute.
1229 Here's the full list of potentially supported backends, valid
1231 'backend' values for each of them, and possible formats. Note
1232 that SyncEvolution installations usually support only a subset
1233 of the backends; that's why e.g. "addressbook" is unambiguous
1234 although there are multiple address book backends.
1235 syncFormat (no default, unshared)
1237 When there are alternative formats for the same data, each side
1238 of a sync offers all that it supports and marks one as pre‐
1239 ferred. If set, this property overrides the format that would
1240 normally be marked as preferred by a backend.
1241 Valid values depend on the backend. Here are some examples:
1243 contacts - text/vcard = vCard 3.0 format
1245 text/x-vcard = legacy vCard 2.1 format
1246 calendar - text/calendar = iCalendar 2.0 format
1248 text/x-vcalendar = legacy vCalendar 1.0 format
1249 Errors while starting to sync and parsing and/or storing items
1251 on either client or server can be caused by a mismatch between
1252 the sync format and uri at the peer.
1253 forceSyncFormat (FALSE, unshared)
1255 Some peers get confused when offered multiple choices for the
1256 sync format or pick the less optimal one. In such a case, set‐
1257 ting this property enforces that the preferred format specified
1258 with 'syncFormat' is really used.
1259 database = evolutionsource (no default, shared)
1261 Picks one of the backend's databases: depending on the backend,
1262 one can set the name and/or a unique identifier.
1263 Most backends have a default database, like for example the sys‐
1265 tem address book. Not setting this property selects that de‐
1266 fault database.
1267 If the backend is a virtual data datastore, this field must con‐
1269 tain comma seperated list of sub datasources actually used to
1270 store data. If your sub datastore has a comma in name, you must
1271 prevent taht comma from being mistaken as the separator by pre‐
1272 ceding it with a backslash, like this: data‐
1273 base=Source1PartA\,PartB,Source2\\Backslash
1274 To get a full list of available databases, run syncevolution
1276 --print-databases. The name is printed in front of the colon,
1277 followed by an identifier in brackets. Usually the name is
1278 unique and can be used to reference the data datastore. The de‐
1279 fault data datastore is marked with <default> at the end of the
1280 line, if there is a default.
1281 databaseFormat (no default, shared)
1283 Defines the data format to be used by the backend for its own
1284 storage. Typically backends only support one format and ignore
1285 this property, but for example the file backend uses it. See the
1286 'backend' property for more information.
1287 databaseUser = evolutionuser (no default, shared), databasePassword =
1289 evolutionpassword (no default, shared)
1290 authentication for backend data datastore; password can be spec‐
1291 ified in multiple ways, see SyncML server password for details
1292 Warning: setting database user/password in cases where it is not
1294 needed, as for example with local Evolution calendars and ad‐
1295 dressbooks, can cause the Evolution backend to hang.
1296
1298 List the known configuration templates:
1299 syncevolution --template ?
1301 Create a new configuration, using the existing Memotoo template:
1303 syncevolution --configure \
1305 username=123456 \
1306 "password=!@#ABcd1234" \
1307 memotoo
1308 Note that putting passwords into the command line, even for short-lived
1310 processes as the one above, is a security risk in shared environments,
1311 because the password is visible to everyone on the machine. To avoid
1312 this, remove the password from the command above, then add the password
1313 to the right config.ini file with a text editor. This command shows
1314 the directory containing the file:
1315 syncevolution --print-configs
1317 Review configuration:
1319 syncevolution --print-config memotoo
1321 Synchronize all datastores:
1323 syncevolution memotoo
1325 Deactivate all datastores:
1327 syncevolution --configure \
1329 sync=none \
1330 memotoo
1331 Activate address book synchronization again, using the --sync shortcut:
1333 syncevolution --configure \
1335 --sync two-way \
1336 memotoo addressbook
1337 Change the password for a configuration:
1339 syncevolution --configure \
1341 password=foo \
1342 memotoo
1343 Set up another configuration for under a different account, using the
1345 same default databases as above:
1346 syncevolution --configure \
1348 username=joe \
1349 password=foo \
1350 --template memotoo \
1351 memotoo_joe
1352 Set up another configuration using the same account, but different lo‐
1354 cal databases (can be used to simulate synchronizing between two
1355 clients, see Exchanging Data:
1356 syncevolution --configure \
1358 username=123456 \
1359 password=!@#ABcd1234" \
1360 sync=none \
1361 memotoo@other
1362 syncevolution --configure \
1364 database=<name of other address book> \
1365 @other addressbook
1366 syncevolution --configure \
1368 sync=two-way \
1369 memotoo@other addressbook
1370 syncevolution memotoo
1372 syncevolution memotoo@other
1373 Migrate a configuration from the <= 0.7 format to the current one
1375 and/or updates the configuration so that it looks like configurations
1376 created anew with the current syncevolution:
1377 syncevolution --migrate memotoo
1379
1381 In the simple examples above, SyncEvolution exchanges data with servers
1382 via the SyncML protocol. Starting with release 1.2, SyncEvolution also
1383 supports other protocols like CalDAV and CardDAV.
1384 These protocols are implemented in backends which behave like local
1386 datastores. SyncEvolution then synchronizes data between a pair of
1387 backends. Because the entire sync logic (matching of items, merging) is
1388 done locally by SyncEvolution, this mode of operation is called local
1389 sync.
1390 Some examples of things that can be done with local sync:
1392 • synchronize events with a CalDAV server and contacts with a CardDAV
1394 server
1395 • mirror a local database as items in a directory, with format conver‐
1397 sion and one-way or two-way data transfer (export vs. true syncing)
1398 Because local sync involves two sides, two sync configurations are
1400 needed. One is called the target config. Traditionally, this really was
1401 a configuration called target-config, for example target-config@google.
1402 Using this particular name is no longer required.
1403 The target config can hold properties which apply to all datastores in‐
1405 side its context, like user name, password and URL for the server (more
1406 on that below) and sync settings (like logging and data backups). Once
1407 configured, the target config can be used to list/import/export/update
1408 items via the SyncEvolution command line. It cannot be used for syn‐
1409 chronization because it does not defined what the items are supposed to
1410 be synchronized with.
1411 For synchronization, a second originating config is needed. This config
1413 has the same role as the traditional SyncML sync configs and is typi‐
1414 cally defined in the same implicit @default context as those configs.
1415 All configs in that context use the same local data, thus turning that
1416 local data into the hub through with data flows to all peers that the
1417 host is configured to sync with.
1418 A sync config becomes an originating config in a local sync by setting
1420 the syncURL to the special URL local://[<target config name>][@<some
1421 context name>]. This selects the target config to sync with. If the
1422 target config name is left out, the actual string target-config is used
1423 as name. The context can be omitted if the target config name is
1424 unique. Originating and target config can be in the same context. Care
1425 must be taken to not use a datastore more than once in a local sync.
1426 In addition, peerIsClient=1 must be set in the originating config, be‐
1428 cause SyncEvolution only supports running the SyncML client on the tar‐
1429 get side. It makes sense to use the local databases on originating
1430 side, because that side requires more frequent access to the data.
1431 The originating config defines the database pairs, either implicitly
1433 (by using the same datastore names on both sides, which is possible
1434 when different contexts are used) or explicitly (via the uri properties
1435 set for the datastores on the originating side). The originating config
1436 also defines the sync mode for each pair. uri and sync values on the
1437 target side are ignored and do not have to be specified.
1438 As a special case, datastores used in combination with the target con‐
1440 fig may access the credentials and syncURL stored there as fallback
1441 when nothing was specified for the datastores directly. This makes
1442 sense for the WebDAV and ActiveSync backends where the credentials are
1443 typically the same and (depending on the web server) the same start URL
1444 can be used to find calendar and contact databases.
1445 Warning: when setting password for the target config and using a
1446 keyring, a syncURL or a unique remoteDeviceID string must be set,
1447 because they are needed to identify the host in the keyring.
1448 If this feature is not used, the syncURL could be left empty because
1450 local sync itself does not use it. However, the command line expects it
1451 to be set to none explicitly to detect typos.
1452 Warning: because the client in the local sync starts the sync, pre‐
1453 ventSlowSync=0 must be set in the target config to have an effect.
1454
1456 This section explains how to use local syncing for CalDAV and CardDAV.
1457 Both protocols are based on WebDAV and are provided by the same back‐
1458 end. They share username/password/syncURL properties defined in their
1459 target config.
1460 The credentials must be provided if the server is password protected.
1462 The syncURL is optional if the username is an email address and the
1463 server supports auto-discovery of its CalDAV and/or CardDAV services
1464 (using DNS SRV entries, .well-known URIs, properties of the current
1465 principal, ...).
1466 Alternatively, credentials can also be set in the databaseUser and
1468 databasePassword properties of the datastore. The downside is that
1469 these values have to be set for each datastore and cannot be shared.
1470 The advantage is that, in combination with setting database, such data‐
1471 stores can be used as part of a normal SyncML server or client sync
1472 config. SyncEvolution then reads and writes data directly from the
1473 server and exchanges it via SyncML with the peer that is defined in the
1474 sync config.
1475 The database property of each datastore can be set to the URL of a spe‐
1477 cific collection (= database in WebDAV terminology). If not set, then
1478 the WebDAV backend first locates the server based on username or syn‐
1479 cURL and then scans it for the default event resp. contact collection.
1480 This is done once in the initial synchronization. At the end of a suc‐
1481 cessful synchroniation, the automatic choice is made permanent by set‐
1482 ting the database property.
1483 Warning: the protocols do not uniquely identify this default collec‐
1484 tion. The backend tries to make an educated guess, but it might pick
1485 the wrong one if the server provides more than one address book or
1486 calendar. It is safer to scan for collections manually with
1487 --print-databases and then use the URL of the desired collection as
1488 value of database.
1489 To scan for collections, use:
1491 syncevolution --print-databases \
1493 backend=<caldav or carddav> \
1494 username=<email address or user name> \
1495 "password=!@#ABcd1234" \
1496 syncURL=<base URL of server, if server auto-discovery is not supported>
1497 Configuration templates for Google Calendar/Contacts, Yahoo Calendar
1499 and a generic CalDAV/CardDAV server are included in SyncEvolution. The
1500 Yahoo template also contains an entry for contact synchronization, but
1501 using it is not recommended due to known server-side issues.
1502 The following commands set up synchronization with a generic WebDAV
1504 server that supports CalDAV, CardDAV and scanning starting at the root
1505 of the server.
1506 # configure target config
1508 syncevolution --configure \
1509 --template webdav \
1510 syncURL=http://example.com \
1511 username=123456 \
1512 "password=!@#ABcd1234" \
1513 target-config@webdav
1514 # configure sync config
1516 syncevolution --configure \
1517 --template SyncEvolution_Client \
1518 syncURL=local://@webdav \
1519 username= \
1520 password= \
1521 webdav \
1522 calendar addressbook
1523 # initial slow sync
1525 syncevolution --sync slow webdav
1526 # incremental sync
1528 syncevolution webdav
1529 Here are some alternative ways of configuring the target config:
1531 # A) Server supports DNS auto-discovery via domain name in the username.
1533 syncevolution --configure \
1534 --template webdav \
1535 username=123456@example.com \
1536 "password=!@#ABcd1234" \
1537 target-config@webdav
1538 # B) Explicitly specify collections (from server documentation or --print-databases).
1540 # The 'calendar' and 'addressbook' names are the ones expected by the sync config
1541 # above, additional datastores can also be configured and/or the names can be changed.
1542 syncevolution --configure \
1543 username=123456 \
1544 "password=!@#ABcd1234" \
1545 --template none \
1546 syncURL=http://example.com \
1547 addressbook/backend=carddav \
1548 addressbook/database=http://example.com/addressbooks/123456/ \
1549 calendar/backend=caldav \
1550 calendar/database=http://example.com/calendar/123456/ \
1551 target-config@webdav \
1552 calendar addressbook
1553 When creating these target configs, the command line tool tries to ver‐
1555 ify that the datastores really work and (in the case of --template web‐
1556 dav) will enable only datastores which really work. This involves con‐
1557 tacting the WebDAV server.
1558 Finally, here is how the @webdav context needs to be configured so that
1560 SyncML clients or servers can be added to it:
1561 # configure datastores
1563 syncevolution --configure \
1564 databaseUser=123456 \
1565 "databasePassword=!@#ABcd1234" \
1566 addressbook/backend=carddav \
1567 addressbook/database=http://example.com/addressbooks/123456/ \
1568 calendar/backend=caldav \
1569 calendar/database=http://example.com/calendar/123456/ \
1570 @webdav \
1571 calendar addressbook
1572 # configure one peer (Memotoo in this example):
1574 syncevolution --configure \
1575 username=654321 \
1576 password=^749@2524 \
1577 memotoo@webdav
1578 # sync
1580 syncevolution --sync slow memotoo@webdav
1581 Google + OAuth
1583 For Google there is no common start URL for CalDAV and CardDAV, there‐
1584 fore the "Google" template lists all that may be relevant and the setup
1585 is very similar to the generic webdav case, except that the syncURL
1586 does not have to be specified:
1587 # configure target config
1589 syncevolution --configure \
1590 --template google \
1591 username=john.doe@gmail.com \
1592 "password=!@#ABcd1234" \
1593 target-config@google
1594 # configure sync config
1596 syncevolution --configure \
1597 --template SyncEvolution_Client \
1598 syncURL=local://@google \
1599 username= \
1600 password= \
1601 google \
1602 calendar addressbook
1603 # initial slow sync
1605 syncevolution --sync slow google
1606 # incremental sync
1608 syncevolution google
1609 If your Google account is configured to use two-factor login, then you
1611 need to create an application specific password for SyncEvolution. See
1612 https://support.google.com/mail/answer/1173270
1613 Google already announced that they will turn off support for logging
1615 into their CalDAV/CardDAV services with plain username/password creden‐
1616 tials. SyncEvolution supports the new login method, OAuth, but it de‐
1617 pends on additional components to implement OAuth: GNOME Online Ac‐
1618 counts, Ubuntu Online Accounts, or gSSO.
1619 Support for GNOME Online Accounts (GOA) is compiled into syncevolu‐
1621 tion.org binaries and therefore documented here. For instructions re‐
1622 garding binaries shipped by distributions please consult the documenta‐
1623 tion provided by the distribution or search the web.
1624 For Google Calendar, GOA >= 3.8 is required. For Google Contacts, GOA
1626 3.8 may work if it was patched by the distribution (as done in Debian
1627 Jessie), otherwise a version >= 3.10 is required.
1628 Use the GNOME Control Center to create an account for Google. It is not
1630 necessary to enable any of the data categories. That would turn on ac‐
1631 cess in other GNOME apps (for example, Evolution), whereas SyncEvolu‐
1632 tion's use of the account is configured separately via the SyncEvolu‐
1633 tion command line.
1634 When configuring SyncEvolution for Google, follow the instructions
1636 above with username=goa:<Google email address> and empty password. If
1637 the email address does not uniquely identify the GOA account, the
1638 SyncEvolution command line will provide a list of accounts to choose
1639 from.
1640
1642 Exchanging Data
1643 SyncEvolution transmits address book entries as vCard 2.1 or 3.0 de‐
1644 pending on the sync format chosen in the configuration. Evolution uses
1645 3.0 internally, so SyncEvolution converts between the two formats as
1646 needed. Calendar items and tasks can be sent and received in iCalendar
1647 2.0 as well as vCalendar 1.0, but vCalendar 1.0 should be avoided if
1648 possible because it cannot represent all data that Evolution stores.
1649 NOTE:
1651 The Evolution backends are mentioned as examples; the same applies
1652 to other datastores.
1653 How the server stores the items depends on its implementation and con‐
1655 figuration. To check which data is preserved, one can use this proce‐
1656 dure (described for contacts, but works the same way for calendars and
1657 tasks):
1658 1. synchronize the address book with the server
1660 2. create a new address book in Evolution and view it in Evolution once
1662 (the second step is necessary in at least Evolution 2.0.4 to make
1663 the new address book usable in SyncEvolution)
1664 3. add a configuration for that second address book and the same URI on
1666 the SyncML server, see EXAMPLES above
1667 4. synchronize again, this time using the other datastore
1669 Now one can either compare the address books in Evolution or do that
1671 automatically, described here for contacts:
1672 • save the complete address books: mark all entries, save as vCard
1674 • invoke synccompare with two file names as arguments and it will nor‐
1676 malize and compare them automatically
1677 Normalizing is necessary because the order of cards and their proper‐
1679 ties as well as other minor formatting aspects may be different. The
1680 output comes from a side-by-side comparison, but is augmented by the
1681 script so that the context of each change is always the complete item
1682 that was modified. Lines or items following a ">" on the right side
1683 were added, those on the left side followed by a "<" were removed, and
1684 those with a "|" between text on the left and right side were modified.
1685 The automatic unit testing (see HACKING) contains a testItems test
1687 which verifies the copying of special entries using the same method.
1688 Modifying one of the address books or even both at the same time and
1690 then synchronizing back and forth can be used to verify that SyncEvolu‐
1691 tion works as expected. If you do not trust SyncEvolution or the
1692 server, then it is prudent to run these checks with a copy of the orig‐
1693 inal address book. Make a backup of the .evolution/addressbook direc‐
1694 tory.
1695 Item Changes and Data Changes
1697 SyncML clients and servers consider each entry in a database as one
1698 item. Items can be added, removed or updated. This is the item change
1699 information that client and server exchange during a normal, incremen‐
1700 tal synchronization.
1701 If an item is saved, removed locally, and reimported, then this is usu‐
1703 ally reported to a peer as "one item removed, one added" because the
1704 information available to SyncEvolution is not sufficient to determine
1705 that this is in fact the same item. One exception are iCalendar 2.0
1706 items with their globally unique ID: the modification above will be re‐
1707 ported to the server as "one item updated".
1708 That is better, but still not quite correct because the content of the
1710 item has not changed, only the meta information about it which is used
1711 to detect changes. This cannot be avoided without creating additional
1712 overhead for normal synchronizations.
1713 SyncEvolution reports item changes (the number of added, removed and
1715 updated items) as well as data changes. These data changes are calcu‐
1716 lated by comparing database dumps using the synccompare tool. Because
1717 this data comparison ignores information about which data belongs to
1718 which item, it is able to detect that re-adding an item that was re‐
1719 moved earlier does not change the data, in contrast to the item
1720 changes. On the other hand, removing one item and adding a different
1721 one may look like updating just one item.
1722 Automatic Backups and Logging
1724 To support recovery from a synchronization which damaged the local data
1725 or modified it in an unexpected way, SyncEvolution can create the fol‐
1726 lowing files during a synchronization:
1727 • a dump of the data in a format which can be restored by SyncEvolu‐
1729 tion, usually a single file per item containing in a standard text
1730 format (VCARD/VCALENDAR)
1731 • a full log file with debug information
1733 • another dump of the data after the synchronization for automatic com‐
1735 parison of the before/after state with synccompare
1736 If the sync configuration property logdir is set, then a new directory
1738 will be created for each synchronization in that directory, using the
1739 format <peer>-<yyyy>-<mm>-<dd>-<hh>-<mm>[-<seq>] with the various
1740 fields filled in with the time when the synchronization started. The
1741 sequence suffix will only be used when necessary to make the name
1742 unique. By default, SyncEvolution will never delete any data in that
1743 log directory unless explicitly asked to keep only a limited number of
1744 previous log directories.
1745 This is done by setting the maxlogdirs limit to something different
1747 than the empty string and 0. If a limit is set, then SyncEvolution will
1748 only keep that many log directories and start removing the "less inter‐
1749 esting" ones when it reaches the limit. Less interesting are those
1750 where no data changed and no error occurred.
1751 To avoid writing any additional log file or database dumps during a
1753 synchronization, the logdir can be set to none. To reduce the verbosity
1754 of the log, set loglevel. If not set or 0, then the verbosity is set to
1755 3 = DEBUG when writing to a log file and 2 = INFO when writing to the
1756 console directly. To debug issues involving data conversion, level 4
1757 also dumps the content of items into the log.
1758
1760 The following environment variables control where SyncEvolution finds
1761 files and other aspects of its operations.
1762 http_proxy
1764 Overrides the proxy settings temporarily. Setting it to an empty
1765 value disables the normal proxy settings.
1766 HOME/XDG_CACHE_HOME/XDG_CONFIG_HOME
1768 SyncEvolution follows the XDG desktop standard for its files. By
1769 default, $HOME/.config/syncevolution is the location for config‐
1770 uration files. $HOME/.cache/syncevolution holds session direc‐
1771 tories with log files and database dumps.
1772 SYNCEVOLUTION_DEBUG
1774 Setting this to any value disables the filtering of stdout and
1775 stderr that SyncEvolution employs to keep noise from system li‐
1776 braries out of the command line output.
1777 SYNCEVOLUTION_GNUTLS_DEBUG
1779 Enables additional debugging output when using the libsoup HTTP
1780 transport library.
1781 SYNCEVOLUTION_DATA_DIR
1783 Overrides the default path to the bluetooth device lookup table,
1784 normally /usr/lib/syncevolution/.
1785 SYNCEVOLUTION_BACKEND_DIR
1787 Overrides the default path to plugins, normally
1788 /usr/lib/syncevolution/backends.
1789 SYNCEVOLUTION_LIBEXEC_DIR
1791 Overrides the path where additional helper executables are
1792 found, normally /usr/libexec.
1793 SYNCEVOLUTION_LOCALE_DIR
1795 Overrides the path to directories with the different transla‐
1796 tions, normally /usr/share/locale.
1797 SYNCEVOLUTION_TEMPLATE_DIR
1799 Overrides the default path to template files, normally
1800 /usr/share/syncevolution/templates.
1801 SYNCEVOLUTION_XML_CONFIG_DIR
1803 Overrides the default path to the Synthesis XML configuration
1804 files, normally /usr/share/syncevolution/xml. These files are
1805 merged into one configuration each time the Synthesis SyncML en‐
1806 gine is started as part of a sync session.
1807 Note that in addition to this directory, SyncEvolution also al‐
1809 ways searches for configuration files inside $HOME/.con‐
1810 fig/syncevolution-xml. Files with the same relative path and
1811 name as in /usr/share/syncevolution/xml override those files,
1812 others extend the final configuration.
1813
1815 See known issues and the support web page for more information.
1816
1818 http://syncevolution.org
1819
1821 Main developer
1822 Patrick Ohly <patrick.ohly@intel.com>, http://www.estamos.de
1823 Contributors
1825 http://syncevolution.org/about/contributors
1826 To contact the project publicly (preferred)
1828 syncevolution@syncevolution.org
1829 Intel-internal team mailing list (confidential)
1831 syncevolution@lists.intel.com
18322.0.0 2022-01-22 SYNCEVOLUTION(1)