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 (no default, unshared)
1075 A string specifying the location of the certificates used to au‐
1076 thenticate the server. When empty, the system's default location
1077 will be searched.
1078 SSL support when acting as HTTP server is implemented by the
1080 HTTP server frontend, not with these properties.
1081 SSLVerifyServer (TRUE, unshared)
1083 The client refuses to establish the connection unless the server
1084 presents a valid certificate. Disabling this option considerably
1085 reduces the security of SSL (man-in-the-middle attacks become
1086 possible) and is not recommended.
1087 SSLVerifyHost (TRUE, unshared)
1089 The client refuses to establish the connection unless the
1090 server's certificate matches its host name. In cases where the
1091 certificate still seems to be valid it might make sense to dis‐
1092 able this option and allow such connections.
1093 WebURL (no default, unshared)
1095 The URL of a web page with further information about the server.
1096 Used only by the GUI.
1097 IconURI (no default, unshared)
1099 The URI of an icon representing the server graphically. Should
1100 be a 48x48 pixmap or a SVG (preferred). Used only by the GUI.
1101 ConsumerReady (FALSE, unshared)
1103 Set to true in a configuration template to indicate that the
1104 server works well enough and is available for normal users. Used
1105 by the GUI to limit the choice of configurations offered to
1106 users. Has no effect in a user's server configuration.
1107 peerType (no default, unshared)
1109 Defines what a configuration is meant to be used for. Used in
1110 templates and the resulting configs to tell a GUI that special
1111 handling may be necessary. GUIs should ignore unknown types.
1112 The traditional SyncML configs use an empty value. "WebDAV" is
1113 used for the WebDAV side in a local synchronization.
1114 defaultPeer (no default, global)
1116 the peer which is used by default in some frontends, like the
1117 sync-UI
1118 keyring (yes, global)
1120 Explicitly selects a certain safe password storage. Depending
1121 on how SyncEvolution was compiled and installed the following
1122 values are possible:
1123 GNOME GNOME Keyring
1125 KDE KWallet
1127 yes/true/1
1129 pick one automatically
1130 no/false/0
1132 store passwords in SyncEvolution config files
1133 If unset, the default is to pick one automatically if support
1135 for any kind of password storage was enabled and use the config
1136 files otherwise. When choosing automatically, GNOME keyring is
1137 tried first because distinguishing between KDE and GNOME ses‐
1138 sions automatically is tricky.
1139 Note that using this option applies to all passwords in a con‐
1141 figuration and that the --keyring command line option is merely
1142 an alias for setting the global property, so setting a single
1143 password as follows sets both keyring and proxyPasswords, and
1144 also moves the other passwords into the keyring, even if they
1145 were not stored there already:
1146 --keyring --configure proxyPassword=foo
1147 When passwords were stored in a safe storage, their value is set
1149 to a single hyphen ("-") in the configuration. This means that
1150 when running a synchronization without using the storage, the
1151 password has to be entered interactively. The --print-config
1152 output always shows "-" instead of retrieving the password from
1153 the keyring.
1154 Datastore properties
1156 sync (disabled, unshared, required)
1157 Requests a certain synchronization mode when initiating a sync:
1158 two-way
1160 only send/receive changes since last sync
1161 slow exchange all items
1163 refresh-from-remote
1165 discard all local items and replace with the items on
1166 the peer
1167 refresh-from-local
1169 discard all items on the peer and replace with the lo‐
1170 cal items
1171 one-way-from-remote
1173 transmit changes from peer
1174 one-way-from-local
1176 transmit local changes
1177 local-cache-slow (server only)
1179 mirror remote data locally, transferring all data
1180 local-cache-incremental (server only)
1182 mirror remote data locally, transferring only changes;
1183 falls back to local-cache-slow automatically if neces‐
1184 sary
1185 disabled (or none)
1187 synchronization disabled
1188 refresh/one-way-from-server/client are also supported. Their use
1190 is discouraged because the direction of the data transfer de‐
1191 pends on the role of the local side (can be server or client),
1192 which is not always obvious.
1193 When accepting a sync session in a SyncML server (HTTP server),
1195 only datastores with sync != disabled are made available to the
1196 client, which chooses the final sync mode based on its own con‐
1197 figuration. When accepting a sync session in a SyncML client
1198 (local sync with the server contacting SyncEvolution on a de‐
1199 vice), the sync mode specified in the client is typically over‐
1200 riden by the server.
1201 uri (no default, unshared)
1203 this is appended to the server's URL to identify the server's
1204 database; if unset, the datastore name is used as fallback
1205 backend (select backend, shared)
1207 Specifies the SyncEvolution backend and thus the data which is
1208 synchronized by this datastore. Each backend may support multi‐
1209 ple databases (see 'database' property), different formats in‐
1210 side that database (see 'databaseFormat'), and different formats
1211 when talking to the sync peer (see 'syncFormat' and 'forceSync‐
1212 Format').
1213 A special 'virtual' backend combines several other datastores
1215 and presents them as one set of items to the peer. For example,
1216 Nokia phones typically exchange tasks and events as part of one
1217 set of calendar items.
1218 Right now such a virtual backend is limited to combining one
1220 calendar datastore with events and one task datastore. They have
1221 to be specified in the database property, typically like this:
1222 calendar,todo
1223 Different datastores combined in one virtual datastore must have
1225 a common format. As with other backends, the preferred format
1226 can be influenced via the 'syncFormat' attribute.
1227 Here's the full list of potentially supported backends, valid
1229 'backend' values for each of them, and possible formats. Note
1230 that SyncEvolution installations usually support only a subset
1231 of the backends; that's why e.g. "addressbook" is unambiguous
1232 although there are multiple address book backends.
1233 syncFormat (no default, unshared)
1235 When there are alternative formats for the same data, each side
1236 of a sync offers all that it supports and marks one as pre‐
1237 ferred. If set, this property overrides the format that would
1238 normally be marked as preferred by a backend.
1239 Valid values depend on the backend. Here are some examples:
1241 contacts - text/vcard = vCard 3.0 format
1243 text/x-vcard = legacy vCard 2.1 format
1244 calendar - text/calendar = iCalendar 2.0 format
1246 text/x-vcalendar = legacy vCalendar 1.0 format
1247 Errors while starting to sync and parsing and/or storing items
1249 on either client or server can be caused by a mismatch between
1250 the sync format and uri at the peer.
1251 forceSyncFormat (FALSE, unshared)
1253 Some peers get confused when offered multiple choices for the
1254 sync format or pick the less optimal one. In such a case, set‐
1255 ting this property enforces that the preferred format specified
1256 with 'syncFormat' is really used.
1257 database = evolutionsource (no default, shared)
1259 Picks one of the backend's databases: depending on the backend,
1260 one can set the name and/or a unique identifier.
1261 Most backends have a default database, like for example the sys‐
1263 tem address book. Not setting this property selects that de‐
1264 fault database.
1265 If the backend is a virtual data datastore, this field must con‐
1267 tain comma seperated list of sub datasources actually used to
1268 store data. If your sub datastore has a comma in name, you must
1269 prevent taht comma from being mistaken as the separator by pre‐
1270 ceding it with a backslash, like this: data‐
1271 base=Source1PartA\,PartB,Source2\\Backslash
1272 To get a full list of available databases, run syncevolution
1274 --print-databases. The name is printed in front of the colon,
1275 followed by an identifier in brackets. Usually the name is
1276 unique and can be used to reference the data datastore. The de‐
1277 fault data datastore is marked with <default> at the end of the
1278 line, if there is a default.
1279 databaseFormat (no default, shared)
1281 Defines the data format to be used by the backend for its own
1282 storage. Typically backends only support one format and ignore
1283 this property, but for example the file backend uses it. See the
1284 'backend' property for more information.
1285 databaseUser = evolutionuser (no default, shared), databasePassword =
1287 evolutionpassword (no default, shared)
1288 authentication for backend data datastore; password can be spec‐
1289 ified in multiple ways, see SyncML server password for details
1290 Warning: setting database user/password in cases where it is not
1292 needed, as for example with local Evolution calendars and ad‐
1293 dressbooks, can cause the Evolution backend to hang.
1294
1296 List the known configuration templates:
1297 syncevolution --template ?
1299 Create a new configuration, using the existing Memotoo template:
1301 syncevolution --configure \
1303 username=123456 \
1304 "password=!@#ABcd1234" \
1305 memotoo
1306 Note that putting passwords into the command line, even for short-lived
1308 processes as the one above, is a security risk in shared environments,
1309 because the password is visible to everyone on the machine. To avoid
1310 this, remove the password from the command above, then add the password
1311 to the right config.ini file with a text editor. This command shows
1312 the directory containing the file:
1313 syncevolution --print-configs
1315 Review configuration:
1317 syncevolution --print-config memotoo
1319 Synchronize all datastores:
1321 syncevolution memotoo
1323 Deactivate all datastores:
1325 syncevolution --configure \
1327 sync=none \
1328 memotoo
1329 Activate address book synchronization again, using the --sync shortcut:
1331 syncevolution --configure \
1333 --sync two-way \
1334 memotoo addressbook
1335 Change the password for a configuration:
1337 syncevolution --configure \
1339 password=foo \
1340 memotoo
1341 Set up another configuration for under a different account, using the
1343 same default databases as above:
1344 syncevolution --configure \
1346 username=joe \
1347 password=foo \
1348 --template memotoo \
1349 memotoo_joe
1350 Set up another configuration using the same account, but different lo‐
1352 cal databases (can be used to simulate synchronizing between two
1353 clients, see Exchanging Data:
1354 syncevolution --configure \
1356 username=123456 \
1357 password=!@#ABcd1234" \
1358 sync=none \
1359 memotoo@other
1360 syncevolution --configure \
1362 database=<name of other address book> \
1363 @other addressbook
1364 syncevolution --configure \
1366 sync=two-way \
1367 memotoo@other addressbook
1368 syncevolution memotoo
1370 syncevolution memotoo@other
1371 Migrate a configuration from the <= 0.7 format to the current one
1373 and/or updates the configuration so that it looks like configurations
1374 created anew with the current syncevolution:
1375 syncevolution --migrate memotoo
1377
1379 In the simple examples above, SyncEvolution exchanges data with servers
1380 via the SyncML protocol. Starting with release 1.2, SyncEvolution also
1381 supports other protocols like CalDAV and CardDAV.
1382 These protocols are implemented in backends which behave like local
1384 datastores. SyncEvolution then synchronizes data between a pair of
1385 backends. Because the entire sync logic (matching of items, merging) is
1386 done locally by SyncEvolution, this mode of operation is called local
1387 sync.
1388 Some examples of things that can be done with local sync:
1390 • synchronize events with a CalDAV server and contacts with a CardDAV
1392 server
1393 • mirror a local database as items in a directory, with format conver‐
1395 sion and one-way or two-way data transfer (export vs. true syncing)
1396 Because local sync involves two sides, two sync configurations are
1398 needed. One is called the target config. Traditionally, this really was
1399 a configuration called target-config, for example target-config@google.
1400 Using this particular name is no longer required.
1401 The target config can hold properties which apply to all datastores in‐
1403 side its context, like user name, password and URL for the server (more
1404 on that below) and sync settings (like logging and data backups). Once
1405 configured, the target config can be used to list/import/export/update
1406 items via the SyncEvolution command line. It cannot be used for syn‐
1407 chronization because it does not defined what the items are supposed to
1408 be synchronized with.
1409 For synchronization, a second originating config is needed. This config
1411 has the same role as the traditional SyncML sync configs and is typi‐
1412 cally defined in the same implicit @default context as those configs.
1413 All configs in that context use the same local data, thus turning that
1414 local data into the hub through with data flows to all peers that the
1415 host is configured to sync with.
1416 A sync config becomes an originating config in a local sync by setting
1418 the syncURL to the special URL local://[<target config name>][@<some
1419 context name>]. This selects the target config to sync with. If the
1420 target config name is left out, the actual string target-config is used
1421 as name. The context can be omitted if the target config name is
1422 unique. Originating and target config can be in the same context. Care
1423 must be taken to not use a datastore more than once in a local sync.
1424 In addition, peerIsClient=1 must be set in the originating config, be‐
1426 cause SyncEvolution only supports running the SyncML client on the tar‐
1427 get side. It makes sense to use the local databases on originating
1428 side, because that side requires more frequent access to the data.
1429 The originating config defines the database pairs, either implicitly
1431 (by using the same datastore names on both sides, which is possible
1432 when different contexts are used) or explicitly (via the uri properties
1433 set for the datastores on the originating side). The originating config
1434 also defines the sync mode for each pair. uri and sync values on the
1435 target side are ignored and do not have to be specified.
1436 As a special case, datastores used in combination with the target con‐
1438 fig may access the credentials and syncURL stored there as fallback
1439 when nothing was specified for the datastores directly. This makes
1440 sense for the WebDAV and ActiveSync backends where the credentials are
1441 typically the same and (depending on the web server) the same start URL
1442 can be used to find calendar and contact databases.
1443 Warning: when setting password for the target config and using a
1444 keyring, a syncURL or a unique remoteDeviceID string must be set,
1445 because they are needed to identify the host in the keyring.
1446 If this feature is not used, the syncURL could be left empty because
1448 local sync itself does not use it. However, the command line expects it
1449 to be set to none explicitly to detect typos.
1450 Warning: because the client in the local sync starts the sync, pre‐
1451 ventSlowSync=0 must be set in the target config to have an effect.
1452
1454 This section explains how to use local syncing for CalDAV and CardDAV.
1455 Both protocols are based on WebDAV and are provided by the same back‐
1456 end. They share username/password/syncURL properties defined in their
1457 target config.
1458 The credentials must be provided if the server is password protected.
1460 The syncURL is optional if the username is an email address and the
1461 server supports auto-discovery of its CalDAV and/or CardDAV services
1462 (using DNS SRV entries, .well-known URIs, properties of the current
1463 principal, ...).
1464 Alternatively, credentials can also be set in the databaseUser and
1466 databasePassword properties of the datastore. The downside is that
1467 these values have to be set for each datastore and cannot be shared.
1468 The advantage is that, in combination with setting database, such data‐
1469 stores can be used as part of a normal SyncML server or client sync
1470 config. SyncEvolution then reads and writes data directly from the
1471 server and exchanges it via SyncML with the peer that is defined in the
1472 sync config.
1473 The database property of each datastore can be set to the URL of a spe‐
1475 cific collection (= database in WebDAV terminology). If not set, then
1476 the WebDAV backend first locates the server based on username or syn‐
1477 cURL and then scans it for the default event resp. contact collection.
1478 This is done once in the initial synchronization. At the end of a suc‐
1479 cessful synchroniation, the automatic choice is made permanent by set‐
1480 ting the database property.
1481 Warning: the protocols do not uniquely identify this default collec‐
1482 tion. The backend tries to make an educated guess, but it might pick
1483 the wrong one if the server provides more than one address book or
1484 calendar. It is safer to scan for collections manually with
1485 --print-databases and then use the URL of the desired collection as
1486 value of database.
1487 To scan for collections, use:
1489 syncevolution --print-databases \
1491 backend=<caldav or carddav> \
1492 username=<email address or user name> \
1493 "password=!@#ABcd1234" \
1494 syncURL=<base URL of server, if server auto-discovery is not supported>
1495 Configuration templates for Google Calendar/Contacts, Yahoo Calendar
1497 and a generic CalDAV/CardDAV server are included in SyncEvolution. The
1498 Yahoo template also contains an entry for contact synchronization, but
1499 using it is not recommended due to known server-side issues.
1500 The following commands set up synchronization with a generic WebDAV
1502 server that supports CalDAV, CardDAV and scanning starting at the root
1503 of the server.
1504 # configure target config
1506 syncevolution --configure \
1507 --template webdav \
1508 syncURL=http://example.com \
1509 username=123456 \
1510 "password=!@#ABcd1234" \
1511 target-config@webdav
1512 # configure sync config
1514 syncevolution --configure \
1515 --template SyncEvolution_Client \
1516 syncURL=local://@webdav \
1517 username= \
1518 password= \
1519 webdav \
1520 calendar addressbook
1521 # initial slow sync
1523 syncevolution --sync slow webdav
1524 # incremental sync
1526 syncevolution webdav
1527 Here are some alternative ways of configuring the target config:
1529 # A) Server supports DNS auto-discovery via domain name in the username.
1531 syncevolution --configure \
1532 --template webdav \
1533 username=123456@example.com \
1534 "password=!@#ABcd1234" \
1535 target-config@webdav
1536 # B) Explicitly specify collections (from server documentation or --print-databases).
1538 # The 'calendar' and 'addressbook' names are the ones expected by the sync config
1539 # above, additional datastores can also be configured and/or the names can be changed.
1540 syncevolution --configure \
1541 username=123456 \
1542 "password=!@#ABcd1234" \
1543 --template none \
1544 syncURL=http://example.com \
1545 addressbook/backend=carddav \
1546 addressbook/database=http://example.com/addressbooks/123456/ \
1547 calendar/backend=caldav \
1548 calendar/database=http://example.com/calendar/123456/ \
1549 target-config@webdav \
1550 calendar addressbook
1551 When creating these target configs, the command line tool tries to ver‐
1553 ify that the datastores really work and (in the case of --template web‐
1554 dav) will enable only datastores which really work. This involves con‐
1555 tacting the WebDAV server.
1556 Finally, here is how the @webdav context needs to be configured so that
1558 SyncML clients or servers can be added to it:
1559 # configure datastores
1561 syncevolution --configure \
1562 databaseUser=123456 \
1563 "databasePassword=!@#ABcd1234" \
1564 addressbook/backend=carddav \
1565 addressbook/database=http://example.com/addressbooks/123456/ \
1566 calendar/backend=caldav \
1567 calendar/database=http://example.com/calendar/123456/ \
1568 @webdav \
1569 calendar addressbook
1570 # configure one peer (Memotoo in this example):
1572 syncevolution --configure \
1573 username=654321 \
1574 password=^749@2524 \
1575 memotoo@webdav
1576 # sync
1578 syncevolution --sync slow memotoo@webdav
1579 Google + OAuth
1581 For Google there is no common start URL for CalDAV and CardDAV, there‐
1582 fore the "Google" template lists all that may be relevant and the setup
1583 is very similar to the generic webdav case, except that the syncURL
1584 does not have to be specified:
1585 # configure target config
1587 syncevolution --configure \
1588 --template google \
1589 username=john.doe@gmail.com \
1590 "password=!@#ABcd1234" \
1591 target-config@google
1592 # configure sync config
1594 syncevolution --configure \
1595 --template SyncEvolution_Client \
1596 syncURL=local://@google \
1597 username= \
1598 password= \
1599 google \
1600 calendar addressbook
1601 # initial slow sync
1603 syncevolution --sync slow google
1604 # incremental sync
1606 syncevolution google
1607 If your Google account is configured to use two-factor login, then you
1609 need to create an application specific password for SyncEvolution. See
1610 https://support.google.com/mail/answer/1173270
1611 Google already announced that they will turn off support for logging
1613 into their CalDAV/CardDAV services with plain username/password creden‐
1614 tials. SyncEvolution supports the new login method, OAuth, but it de‐
1615 pends on additional components to implement OAuth: GNOME Online Ac‐
1616 counts, Ubuntu Online Accounts, or gSSO.
1617 Support for GNOME Online Accounts (GOA) is compiled into syncevolu‐
1619 tion.org binaries and therefore documented here. For instructions re‐
1620 garding binaries shipped by distributions please consult the documenta‐
1621 tion provided by the distribution or search the web.
1622 For Google Calendar, GOA >= 3.8 is required. For Google Contacts, GOA
1624 3.8 may work if it was patched by the distribution (as done in Debian
1625 Jessie), otherwise a version >= 3.10 is required.
1626 Use the GNOME Control Center to create an account for Google. It is not
1628 necessary to enable any of the data categories. That would turn on ac‐
1629 cess in other GNOME apps (for example, Evolution), whereas SyncEvolu‐
1630 tion's use of the account is configured separately via the SyncEvolu‐
1631 tion command line.
1632 When configuring SyncEvolution for Google, follow the instructions
1634 above with username=goa:<Google email address> and empty password. If
1635 the email address does not uniquely identify the GOA account, the
1636 SyncEvolution command line will provide a list of accounts to choose
1637 from.
1638
1640 Exchanging Data
1641 SyncEvolution transmits address book entries as vCard 2.1 or 3.0 de‐
1642 pending on the sync format chosen in the configuration. Evolution uses
1643 3.0 internally, so SyncEvolution converts between the two formats as
1644 needed. Calendar items and tasks can be sent and received in iCalendar
1645 2.0 as well as vCalendar 1.0, but vCalendar 1.0 should be avoided if
1646 possible because it cannot represent all data that Evolution stores.
1647 NOTE:
1649 The Evolution backends are mentioned as examples; the same applies
1650 to other datastores.
1651 How the server stores the items depends on its implementation and con‐
1653 figuration. To check which data is preserved, one can use this proce‐
1654 dure (described for contacts, but works the same way for calendars and
1655 tasks):
1656 1. synchronize the address book with the server
1658 2. create a new address book in Evolution and view it in Evolution once
1660 (the second step is necessary in at least Evolution 2.0.4 to make
1661 the new address book usable in SyncEvolution)
1662 3. add a configuration for that second address book and the same URI on
1664 the SyncML server, see EXAMPLES above
1665 4. synchronize again, this time using the other datastore
1667 Now one can either compare the address books in Evolution or do that
1669 automatically, described here for contacts:
1670 • save the complete address books: mark all entries, save as vCard
1672 • invoke synccompare with two file names as arguments and it will nor‐
1674 malize and compare them automatically
1675 Normalizing is necessary because the order of cards and their proper‐
1677 ties as well as other minor formatting aspects may be different. The
1678 output comes from a side-by-side comparison, but is augmented by the
1679 script so that the context of each change is always the complete item
1680 that was modified. Lines or items following a ">" on the right side
1681 were added, those on the left side followed by a "<" were removed, and
1682 those with a "|" between text on the left and right side were modified.
1683 The automatic unit testing (see HACKING) contains a testItems test
1685 which verifies the copying of special entries using the same method.
1686 Modifying one of the address books or even both at the same time and
1688 then synchronizing back and forth can be used to verify that SyncEvolu‐
1689 tion works as expected. If you do not trust SyncEvolution or the
1690 server, then it is prudent to run these checks with a copy of the orig‐
1691 inal address book. Make a backup of the .evolution/addressbook direc‐
1692 tory.
1693 Item Changes and Data Changes
1695 SyncML clients and servers consider each entry in a database as one
1696 item. Items can be added, removed or updated. This is the item change
1697 information that client and server exchange during a normal, incremen‐
1698 tal synchronization.
1699 If an item is saved, removed locally, and reimported, then this is usu‐
1701 ally reported to a peer as "one item removed, one added" because the
1702 information available to SyncEvolution is not sufficient to determine
1703 that this is in fact the same item. One exception are iCalendar 2.0
1704 items with their globally unique ID: the modification above will be re‐
1705 ported to the server as "one item updated".
1706 That is better, but still not quite correct because the content of the
1708 item has not changed, only the meta information about it which is used
1709 to detect changes. This cannot be avoided without creating additional
1710 overhead for normal synchronizations.
1711 SyncEvolution reports item changes (the number of added, removed and
1713 updated items) as well as data changes. These data changes are calcu‐
1714 lated by comparing database dumps using the synccompare tool. Because
1715 this data comparison ignores information about which data belongs to
1716 which item, it is able to detect that re-adding an item that was re‐
1717 moved earlier does not change the data, in contrast to the item
1718 changes. On the other hand, removing one item and adding a different
1719 one may look like updating just one item.
1720 Automatic Backups and Logging
1722 To support recovery from a synchronization which damaged the local data
1723 or modified it in an unexpected way, SyncEvolution can create the fol‐
1724 lowing files during a synchronization:
1725 • a dump of the data in a format which can be restored by SyncEvolu‐
1727 tion, usually a single file per item containing in a standard text
1728 format (VCARD/VCALENDAR)
1729 • a full log file with debug information
1731 • another dump of the data after the synchronization for automatic com‐
1733 parison of the before/after state with synccompare
1734 If the sync configuration property logdir is set, then a new directory
1736 will be created for each synchronization in that directory, using the
1737 format <peer>-<yyyy>-<mm>-<dd>-<hh>-<mm>[-<seq>] with the various
1738 fields filled in with the time when the synchronization started. The
1739 sequence suffix will only be used when necessary to make the name
1740 unique. By default, SyncEvolution will never delete any data in that
1741 log directory unless explicitly asked to keep only a limited number of
1742 previous log directories.
1743 This is done by setting the maxlogdirs limit to something different
1745 than the empty string and 0. If a limit is set, then SyncEvolution will
1746 only keep that many log directories and start removing the "less inter‐
1747 esting" ones when it reaches the limit. Less interesting are those
1748 where no data changed and no error occurred.
1749 To avoid writing any additional log file or database dumps during a
1751 synchronization, the logdir can be set to none. To reduce the verbosity
1752 of the log, set loglevel. If not set or 0, then the verbosity is set to
1753 3 = DEBUG when writing to a log file and 2 = INFO when writing to the
1754 console directly. To debug issues involving data conversion, level 4
1755 also dumps the content of items into the log.
1756
1758 The following environment variables control where SyncEvolution finds
1759 files and other aspects of its operations.
1760 http_proxy
1762 Overrides the proxy settings temporarily. Setting it to an empty
1763 value disables the normal proxy settings.
1764 HOME/XDG_CACHE_HOME/XDG_CONFIG_HOME
1766 SyncEvolution follows the XDG desktop standard for its files. By
1767 default, $HOME/.config/syncevolution is the location for config‐
1768 uration files. $HOME/.cache/syncevolution holds session direc‐
1769 tories with log files and database dumps.
1770 SYNCEVOLUTION_DEBUG
1772 Setting this to any value disables the filtering of stdout and
1773 stderr that SyncEvolution employs to keep noise from system li‐
1774 braries out of the command line output.
1775 SYNCEVOLUTION_GNUTLS_DEBUG
1777 Enables additional debugging output when using the libsoup HTTP
1778 transport library.
1779 SYNCEVOLUTION_DATA_DIR
1781 Overrides the default path to the bluetooth device lookup table,
1782 normally /usr/lib/syncevolution/.
1783 SYNCEVOLUTION_BACKEND_DIR
1785 Overrides the default path to plugins, normally
1786 /usr/lib/syncevolution/backends.
1787 SYNCEVOLUTION_LIBEXEC_DIR
1789 Overrides the path where additional helper executables are
1790 found, normally /usr/libexec.
1791 SYNCEVOLUTION_LOCALE_DIR
1793 Overrides the path to directories with the different transla‐
1794 tions, normally /usr/share/locale.
1795 SYNCEVOLUTION_TEMPLATE_DIR
1797 Overrides the default path to template files, normally
1798 /usr/share/syncevolution/templates.
1799 SYNCEVOLUTION_XML_CONFIG_DIR
1801 Overrides the default path to the Synthesis XML configuration
1802 files, normally /usr/share/syncevolution/xml. These files are
1803 merged into one configuration each time the Synthesis SyncML en‐
1804 gine is started as part of a sync session.
1805 Note that in addition to this directory, SyncEvolution also al‐
1807 ways searches for configuration files inside $HOME/.con‐
1808 fig/syncevolution-xml. Files with the same relative path and
1809 name as in /usr/share/syncevolution/xml override those files,
1810 others extend the final configuration.
1811
1813 See known issues and the support web page for more information.
1814
1816 http://syncevolution.org
1817
1819 Main developer
1820 Patrick Ohly <patrick.ohly@intel.com>, http://www.estamos.de
1821 Contributors
1823 http://syncevolution.org/about/contributors
1824 To contact the project publicly (preferred)
1826 syncevolution@syncevolution.org
1827 Intel-internal team mailing list (confidential)
1829 syncevolution@lists.intel.com
18302.0.0 2023-07-22 SYNCEVOLUTION(1)