1SYNCEVOLUTION(1)                                              SYNCEVOLUTION(1)
2
3
4

NAME

6       SyncEvolution - synchronize personal information management data
7

SYNOPSIS

9       List and manipulate databases:
10              syncevolution --print-databases|--create-database|--remove-data‐
11              base [<properties>] [<config> <store>]
12
13       Show information about configuration(s):
14              syncevolution --print-servers|--print-configs|--print-peers
15
16       Show information about a specific configuration:
17              syncevolution    --print-config    [--quiet]    [--]    <config>
18              [main|<store> ...]
19
20       List sessions:
21              syncevolution --print-sessions [--quiet] [--] <config>
22
23       Show information about SyncEvolution:
24              syncevolution --help|-h|--version
25
26       Run a synchronization as configured:
27              syncevolution <config> [<store> ...]
28
29       Run a synchronization with properties changed just for this run:
30              syncevolution  --run  <options  for  run> [--] <config> [<store>
31              ...]
32
33       Restore data from the automatic backups:
34              syncevolution  --restore  <session  directory>  --before|--after
35              [--dry-run] [--] <config> <store> ...
36
37       Create, update or remove a configuration:
38              syncevolution --configure <options> [--] <config> [<store> ...]
39
40              syncevolution --remove|--migrate <options> [--] <config>
41
42       List items:
43              syncevolution --print-items [--] [<config> [<store>]]
44
45       Export item(s):
46
47              syncevolution  [--delimiter  <string>]  --export  <dir>|<file>|-
48              [--] [<config> [<store> [<luid> ...]]]
49                     --luids <luid> ...
50
51       Add item(s):
52
53              syncevolution     [--delimiter      <string>|none]      --import
54              <dir>|<file>|- [--] [<config> [<store>]]
55                     --luids <luid> ...
56
57       Update item(s):
58              syncevolution --update <dir> [--] <config> <store>
59
60              syncevolution [--delimiter <string>|none] --update <file>|- [--]
61              <config> <store> <luid> ...
62                     --luids <luid> ...
63
64       Remove item(s):
65              syncevolution --delete-items [--] <config> <store> (<luid> ... |
66              '*')
67

DESCRIPTION

69       This text explains the usage of the SyncEvolution command line.
70
71       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
76       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

TERMINOLOGY

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
91       host   The device or computer that SyncEvolution runs on.
92
93       item   The smallest unit of synchronization. Examples of items  include
94              calendar events and individual contacts, memos, or tasks.
95
96       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
101       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
107       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
114              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
118       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
126       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
130              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
134              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
141              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
147       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
152              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
155              defined in a context @peer-name named after that peer.
156
157       configuration properties
158              SyncEvolution  uses  key/value  pairs  to  store   configuration
159              options.  A configuration is a set of unique keys and their val‐
160              ues that together describe a certain object.
161
162              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
167              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
173              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
179              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
185              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
191              Together with the distinction between sync and datastore proper‐
192              ties, this currently results in five different groups of proper‐
193              ties:
194
195              · 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
200                · global (=  ~/.config/syncevolution/config.ini):  independent
201                  of a particular context, for example keyring
202
203                · shared    (=   ~/.config/syncevolution/<context   name>/con‐
204                  fig.ini): set once for each context, for example logdir
205
206                · unshared         (=         ~/.config/syncevolution/<context
207                  name>/peers/<peer name>/config.ini): set separately for each
208                  sync config, for example syncURL
209
210              · Datastore properties:
211
212                · shared          (=          ~/.config/syncevolution/<context
213                  name>/sources/<store   name>/config.ini):   the   properties
214                  required for access to the data, primarily backend and data‐
215                  base
216
217                · 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
222              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
227              The  configuration  layer  in  SyncEvolution  has a very limited
228              understanding 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
239       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
247              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
253              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
257              · addressbook: a list of contacts
258
259              · calendar: calendar events
260
261              · memo: plain text notes
262
263              · todo: task list
264
265              · calendar+todo: a virtual datastore combining one local "calen‐
266                dar" and one "todo" datastore (required for synchronizing with
267                some phones)
268
269       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
274              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
280              See Synchronization beyond SyncML.
281
282       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
286       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

COMMAND LINE CONVENTIONS

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
297       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
304       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
310       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
315       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
322       A <property> assignment has the following format:
323
324          [<store>/]<name>[@<context>|@<peer>@<context>]=<value>
325
326       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
329       example, the log level can be specified separately for both sides:
330
331          --run loglevel@default=1 loglevel@google-calendar=4 google-calendar@default
332
333       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
338       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
345       Datastore properties can be specified  with  a  <store>/  prefix.  This
346       allows limiting the value to the selected datastore. For example:
347
348          --configure "addressbook/database=My Addressbook" \
349                      "calendar/database=My Calendar" \
350                      @default addressbook calendar
351
352       Another way to achieve the same effect is to run the --configure opera‐
353       tion twice, once for addressbook and once for calendar:
354
355          --configure "database=My Addressbook" @default addressbook
356          --configure "database=My Calendar" @default calendar
357
358       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
363          --configure addressbook/sync=none \
364                      sync=two-way \
365                      <sync config>
366

USAGE

368          syncevolution --print-databases [<properties>] [<config> <store>]
369
370       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
375       information can be provided on the command line with  property  assign‐
376       ments (username=...) or in an existing configuration.
377
378       When  listing all databases of all active datastores, the output starts
379       with a heading that lists the values for  the  backend  property  which
380       select  the  backend,  followed  by the databases.  Each database has a
381       name and a unique ID (in brackets). Typically both can be used as value
382       of the 'database' property. One database might be marked as default. It
383       will be used when database is not set explicitly.
384
385       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
390       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
393       directory it is meant to use.
394
395          syncevolution --create-database [<properties>] [<config> <store>]
396
397       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
402       The interpretation of the database property depends on the backend. Not
403       all backends support this operation.
404
405       The EDS backend uses the value of the database as name of the new data‐
406       base and assigns a unique URI automatically.
407
408          syncevolution --remove-database [<properties>] [<config> <store>]
409
410       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
414          syncevolution <config>
415
416       Without  the  optional  list  of  datastores,  all datastores which are
417       enabled in their configuration file are synchronized.
418
419          syncevolution <config> <store> ...
420
421       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
427       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
435       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
439       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
447       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
454          syncevolution --configure <options for configuration> <config> [<store> ...]
455
456       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
461       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
465          syncevolution --remove <config>
466
467       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
470       removed.
471
472       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
475          syncevolution --run <options for run> <config> [<store> ...]
476
477       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
483          syncevolution --status <config> [<store> ...]
484
485       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
489          syncevolution --print-servers|--print-configs|--print-peers
490          syncevolution --print-config [--quiet] <config> [main|<store> ...]
491          syncevolution --print-sessions [--quiet] <config>
492
493       These commands print information about  existing  configurations.  When
494       printing  a  configuration  a  short  version  without  comments can be
495       selected with --quiet. When datastores are listed, only their  configu‐
496       ration  is  shown. Main instead or in combination with datastores lists
497       only the main peer configuration.
498
499          syncevolution --restore <session directory> --before|--after
500                        [--dry-run] <config> <store> ...
501
502       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
508       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
513       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
520          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
527       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
531       alphanumeric  characters,  dash   and   underscore.   A   star   *   in
532       --delete-items  selects  all  items for deletion. There are two ways of
533       specifying luids: either as additional parameters after the config  and
534       datastore  parameters  (which  may  be  empty in this case, but must be
535       given) or after the --luids keyword.
536
537       <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
542          syncevolution --print-items backend=evolution-contacts
543          syncevolution --export - backend=evolution-contacts \
544                        --luids pas-id-4E33F24300000006 pas-id-4E36DD7B00000007
545
546       The  desired  backend database can be chosen via database=<identifier>.
547       See --print-databases.
548

OPTIONS

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
555       --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
560              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
564       --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
568       --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
582       --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
589       --configure|-c
590              Modify  the  configuration  files  for  the selected peer and/or
591              datastores.
592
593              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
600              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
609              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
615                 - use `--template none` or
616                 - specify all required sync and datastore properties that are normally
617                   in the templates on the command line (syncURL, backend, ...)
618
619       --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
623              selected  on the command line and they are meant to be used dur‐
624              ing a sync session triggered by the invocation.
625
626       --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
633              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
636              exactly  as  if the configuration had been created from scratch.
637              WARNING: custom comments in the configuration are not preserved.
638
639              --migrate implies --configure and can be combined with modifying
640              properties.
641
642       --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
648       --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
653              selected items separated by the chosen delimiter string.  stdout
654              can be selected with a dash.
655
656              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
661              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
666       --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
672       --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
675              updating from file or stdin, the number of luids  given  on  the
676              command line must match with the number of items in the input.
677
678       --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
683              reflected  in  a  non-zero result of the command line invocation
684              itself because the situation is not  reported  as  an  error  by
685              backends  (removal  of  non-existent  items  is  not an error in
686              SyncML). Use a star * instead or in addition to listing individ‐
687              ual luids to delete all items.
688
689       --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
695       --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
701       --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
710              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
715              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
725       --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
731       --quiet|-q
732              Suppresses  most  of the normal output during a synchronization.
733              The log file still contains all the information.
734
735       --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
741       --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
751       --help|-h
752              Prints usage information.
753
754       --version
755              Prints the SyncEvolution version.
756

CONFIGURATION PROPERTIES

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
763       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
768       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
771       defined, which is marked with the word required.
772
773   Sync properties
774       syncURL (no default, unshared, required)
775              Identifies  how  to  contact  the peer, best explained with some
776              examples.
777
778              HTTP(S) SyncML servers:
779
780                 http://example.com/sync
781
782              OBEX over Bluetooth uses the MAC address, with the channel  cho‐
783              sen automatically:
784
785                 obex-bt://00:0A:94:03:F3:7E
786
787              If the automatism fails, the channel can also be specified:
788
789                 obex-bt://00:0A:94:03:F3:7E+16
790
791              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
795                 obex-bt://00:0A:94:03:F3:7E obex-bt://00:01:02:03:04:05
796
797              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
800       username (no default, unshared)
801              user name used for authorization with the SyncML server
802
803       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
809                 plain text  : password = <insert your password here>
810                 ask         : password = -
811                 env variable: password = ${<name of environment variable>}
812
813       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
817              expands to ${HOME}/.cache/...) will be used; if "none", then  no
818              backups  of  the  databases  are  made and any output is printed
819              directly to the screen
820
821       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  =
825              increasing amounts of debug messages for developers
826
827       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
832              0  -  suppress  all  notifications 1 - show only errors 2 - show
833              information about changes and errors (in practice currently  the
834              same  as level 3) 3 - show all notifications, including starting
835              a sync
836
837       printChanges (TRUE, unshared)
838              enables or disables the detailed (and sometimes slow) comparison
839              of database content before and after a sync session
840
841       dumpData (TRUE, unshared)
842              enables  or  disables  the  automatic backup of database content
843              before and after a sync session (always enabled if  printChanges
844              is enabled)
845
846       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
849              directories  and  all their content to prevent the number of log
850              directories 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
856       autoSync (0, unshared)
857              Controls automatic synchronization.  Currently,  automatic  syn‐
858              chronization  is  done  by  running a synchronization at regular
859              intervals. 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
864              0      don't do auto sync
865
866              1
867
868                     do automatic sync, using whatever transport
869                            is available
870
871              http   only via HTTP transport
872
873              obex-bt
874                     only via Bluetooth transport
875
876              http,obex-bt
877                     pick one of these
878
879       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
884              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
891       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
896              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
902       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
913              selected explicitly, refresh sync).   The  following  situations
914              are handled:
915
916              · running  as  client  with no local data => unproblematic, slow
917                sync is allowed to proceed automatically
918
919              · 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
923              · 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
929       useProxy (FALSE, unshared)
930              set to T to choose  an  HTTP  proxy  explicitly;  otherwise  the
931              default  proxy  settings of the underlying HTTP transport mecha‐
932              nism are used; only relevant when contacting the peer via HTTP
933
934       proxyHost (no default, unshared)
935              proxy URL (http://<host>:<port>)
936
937       proxyUsername (no default, unshared)
938              authentication for proxy: username
939
940       proxyPassword (no default, unshared)
941              proxy password, can be specified in different ways,  see  SyncML
942              server password for details
943
944       clientAuthType (md5, unshared)
945
946              · empty or "md5" for secure method (recommended)
947
948              · "basic" for insecure method
949
950              This  setting  is  only  for  debugging  purpose and only has an
951              effect 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
956       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
965              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
969       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
972              already  passed  when  a  message  send  returns, the message is
973              resent immediately. Resending without any delay will never  suc‐
974              ceed and therefore specifying 0 disables retries.
975
976              Servers cannot resend messages, so this setting has no effect in
977              that case.
978
979              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
982              obtain the initial delay (default: 2m => 5s), which is then dou‐
983              bled for each retry.
984
985       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
989       PeerIsClient (FALSE, unshared)
990              Indicates  whether  this configuration is about a client peer or
991              server peer.
992
993       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
998              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
1004              Instead or in adddition to the version, several keywords can  be
1005              set in this property (separated by spaces or commas):
1006
1007              · NOCTCAP - avoid sending CtCap meta information
1008
1009              · 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
1013              · 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
1018                default for HTTP servers, with a delay of  2  minutes  between
1019                messages.  Other  servers  (Bluetooth,  local sync) should not
1020                need preliminary replies and the feature is disabled, although
1021                it  can be enabled by setting the time explicitly.  <time> can
1022                be specified like other durations in the config,  for  example
1023                as REQUESTMAXTIME=2m.
1024
1025              Setting  these  flags should only be necessary as workaround for
1026              broken peers.
1027
1028       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
1033       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
1041       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
1048              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
1053       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
1058       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
1062              before  doing  a  slow sync, which has the same effect. However,
1063              some servers work better when they are told explicitly that  the
1064              sync is a refresh sync. For example, Funambol's One Media server
1065              rejects too many slow syncs in a row with a  417  'retry  later'
1066              error.
1067
1068       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
1074       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
1078              authenticate  the server. When empty, the system's default loca‐
1079              tion will be searched.
1080
1081              SSL support when acting as HTTP server  is  implemented  by  the
1082              HTTP server frontend, not with these properties.
1083
1084       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
1090       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
1096       WebURL (no default, unshared)
1097              The URL of a web page with further information about the server.
1098              Used only by the GUI.
1099
1100       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
1104       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
1110       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
1117       defaultPeer (no default, global)
1118              the peer which is used by default in some  frontends,  like  the
1119              sync-UI
1120
1121       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
1126              GNOME  GNOME Keyring
1127
1128              KDE    KWallet
1129
1130              yes/true/1
1131                     pick one automatically
1132
1133              no/false/0
1134                     store passwords in SyncEvolution config files
1135
1136              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
1142              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
1150              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
1157   Datastore properties
1158       sync (disabled, unshared, required)
1159              Requests a certain synchronization mode when initiating a sync:
1160
1161                 two-way
1162                        only send/receive changes since last sync
1163
1164                 slow   exchange all items
1165
1166                 refresh-from-remote
1167                        discard  all local items and replace with the items on
1168                        the peer
1169
1170                 refresh-from-local
1171                        discard all items on the peer  and  replace  with  the
1172                        local items
1173
1174                 one-way-from-remote
1175                        transmit changes from peer
1176
1177                 one-way-from-local
1178                        transmit local changes
1179
1180                 local-cache-slow (server only)
1181                        mirror remote data locally, transferring all data
1182
1183                 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
1188                 disabled (or none)
1189                        synchronization disabled
1190
1191              refresh/one-way-from-server/client are also supported. Their use
1192              is discouraged  because  the  direction  of  the  data  transfer
1193              depends on the role of the local side (can be server or client),
1194              which is not always obvious.
1195
1196              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
1201              device),  the  sync  mode  specified  in the client is typically
1202              overriden by the server.
1203
1204       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
1208       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
1212              inside that database (see 'databaseFormat'), and different  for‐
1213              mats  when  talking  to  the  sync  peer  (see  'syncFormat' and
1214              'forceSyncFormat').
1215
1216              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
1221              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
1226              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
1230              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
1236       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
1242              Valid values depend on the backend. Here are some examples:
1243
1244                     contacts - text/vcard = vCard 3.0 format
1245                            text/x-vcard = legacy vCard 2.1 format
1246
1247                     calendar - text/calendar = iCalendar 2.0 format
1248                            text/x-vcalendar = legacy vCalendar 1.0 format
1249
1250              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
1254       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
1260       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
1264              Most backends have a default database, like for example the sys‐
1265              tem address  book.   Not  setting  this  property  selects  that
1266              default database.
1267
1268              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
1275              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
1279              default data datastore is marked with <default> at  the  end  of
1280              the line, if there is a default.
1281
1282       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
1288       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
1293              Warning: setting database user/password in cases where it is not
1294              needed,  as  for  example  with  local  Evolution  calendars and
1295              addressbooks, can cause the Evolution backend to hang.
1296

EXAMPLES

1298       List the known configuration templates:
1299
1300          syncevolution --template ?
1301
1302       Create a new configuration, using the existing Memotoo template:
1303
1304          syncevolution --configure \
1305                        username=123456 \
1306                        "password=!@#ABcd1234" \
1307                        memotoo
1308
1309       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
1316          syncevolution --print-configs
1317
1318       Review configuration:
1319
1320          syncevolution --print-config memotoo
1321
1322       Synchronize all datastores:
1323
1324          syncevolution memotoo
1325
1326       Deactivate all datastores:
1327
1328          syncevolution --configure \
1329                        sync=none \
1330                        memotoo
1331
1332       Activate address book synchronization again, using the --sync shortcut:
1333
1334          syncevolution --configure \
1335                        --sync two-way \
1336                        memotoo addressbook
1337
1338       Change the password for a configuration:
1339
1340          syncevolution --configure \
1341                        password=foo \
1342                        memotoo
1343
1344       Set  up  another configuration for under a different account, using the
1345       same default databases as above:
1346
1347          syncevolution --configure \
1348                        username=joe \
1349                        password=foo \
1350                        --template memotoo \
1351                        memotoo_joe
1352
1353       Set up another configuration using  the  same  account,  but  different
1354       local  databases  (can  be  used  to simulate synchronizing between two
1355       clients, see Exchanging Data:
1356
1357          syncevolution --configure \
1358                        username=123456 \
1359                        password=!@#ABcd1234" \
1360                        sync=none \
1361                        memotoo@other
1362
1363          syncevolution --configure \
1364                        database=<name of other address book> \
1365                        @other addressbook
1366
1367          syncevolution --configure \
1368                        sync=two-way \
1369                        memotoo@other addressbook
1370
1371          syncevolution memotoo
1372          syncevolution memotoo@other
1373
1374       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
1378          syncevolution --migrate memotoo
1379

SYNCHRONIZATION BEYOND SYNCML

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
1385       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
1391       Some examples of things that can be done with local sync:
1392
1393       · synchronize events with a CalDAV server and contacts with  a  CardDAV
1394         server
1395
1396       · 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
1399       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
1404       The  target  config  can  hold properties which apply to all datastores
1405       inside its context, like user name, password and  URL  for  the  server
1406       (more on that below) and sync settings (like logging and data backups).
1407       Once   configured,   the    target    config    can    be    used    to
1408       list/import/export/update  items via the SyncEvolution command line. It
1409       cannot be used for synchronization because it does not defined what the
1410       items are supposed to be synchronized with.
1411
1412       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
1419       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
1427       In addition, peerIsClient=1 must be  set  in  the  originating  config,
1428       because  SyncEvolution  only  supports running the SyncML client on the
1429       target side. It makes sense to use the local databases  on  originating
1430       side, because that side requires more frequent access to the data.
1431
1432       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
1439       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
1449       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

CALDAV AND CARDDAV

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
1461       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
1467       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
1476       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
1490       To scan for collections, use:
1491
1492          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
1498       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
1503       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
1507          # 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
1515          # configure sync config
1516          syncevolution --configure \
1517                        --template SyncEvolution_Client \
1518                        syncURL=local://@webdav \
1519                        username= \
1520                        password= \
1521                        webdav \
1522                        calendar addressbook
1523
1524          # initial slow sync
1525          syncevolution --sync slow webdav
1526
1527          # incremental sync
1528          syncevolution webdav
1529
1530       Here are some alternative ways of configuring the target config:
1531
1532          # 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
1539          # 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
1554       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
1559       Finally, here is how the @webdav context needs to be configured so that
1560       SyncML clients or servers can be added to it:
1561
1562          # 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
1573          # configure one peer (Memotoo in this example):
1574          syncevolution --configure \
1575                        username=654321 \
1576                        password=^749@2524 \
1577                        memotoo@webdav
1578
1579          # sync
1580          syncevolution --sync slow memotoo@webdav
1581
1582   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
1588          # configure target config
1589          syncevolution --configure \
1590                       --template google \
1591                       username=john.doe@gmail.com \
1592                       "password=!@#ABcd1234" \
1593                       target-config@google
1594
1595          # configure sync config
1596          syncevolution --configure \
1597                        --template SyncEvolution_Client \
1598                        syncURL=local://@google \
1599                        username= \
1600                        password= \
1601                        google \
1602                        calendar addressbook
1603
1604          # initial slow sync
1605          syncevolution --sync slow google
1606
1607          # incremental sync
1608          syncevolution google
1609
1610       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
1614       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
1617       depends on additional  components  to  implement  OAuth:  GNOME  Online
1618       Accounts, Ubuntu Online Accounts, or gSSO.
1619
1620       Support  for  GNOME  Online  Accounts (GOA) is compiled into syncevolu‐
1621       tion.org binaries  and  therefore  documented  here.  For  instructions
1622       regarding binaries shipped by distributions please consult the documen‐
1623       tation provided by the distribution or search the web.
1624
1625       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
1629       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
1631       access 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
1635       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

NOTES

1642   Exchanging Data
1643       SyncEvolution transmits address  book  entries  as  vCard  2.1  or  3.0
1644       depending  on  the  sync  format chosen in the configuration. Evolution
1645       uses 3.0 internally, so SyncEvolution converts between the two  formats
1646       as needed. Calendar items and tasks can be sent and received in iCalen‐
1647       dar 2.0 as well as vCalendar 1.0, but vCalendar 1.0 should  be  avoided
1648       if possible because it cannot represent all data that Evolution stores.
1649
1650       NOTE:
1651          The  Evolution  backends are mentioned as examples; the same applies
1652          to other datastores.
1653
1654       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
1659       1. synchronize the address book with the server
1660
1661       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
1665       3. add a configuration for that second address book and the same URI on
1666          the SyncML server, see EXAMPLES above
1667
1668       4. synchronize again, this time using the other datastore
1669
1670       Now one can either compare the address books in Evolution  or  do  that
1671       automatically, described here for contacts:
1672
1673       · save the complete address books: mark all entries, save as vCard
1674
1675       · invoke  synccompare with two file names as arguments and it will nor‐
1676         malize and compare them automatically
1677
1678       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
1686       The automatic unit testing (see  HACKING)  contains  a  testItems  test
1687       which verifies the copying of special entries using the same method.
1688
1689       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
1696   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
1702       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
1707       reported to the server as "one item updated".
1708
1709       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
1714       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
1719       removed 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
1723   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
1728       · 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
1732       · a full log file with debug information
1733
1734       · another dump of the data after the synchronization for automatic com‐
1735         parison of the before/after state with synccompare
1736
1737       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
1746       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
1752       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

ENVIRONMENT

1760       The  following  environment variables control where SyncEvolution finds
1761       files and other aspects of its operations.
1762
1763       http_proxy
1764              Overrides the proxy settings temporarily. Setting it to an empty
1765              value disables the normal proxy settings.
1766
1767       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
1773       SYNCEVOLUTION_DEBUG
1774              Setting this to any value disables the filtering of  stdout  and
1775              stderr  that  SyncEvolution  employs  to  keep noise from system
1776              libraries out of the command line output.
1777
1778       SYNCEVOLUTION_GNUTLS_DEBUG
1779              Enables additional debugging output when using the libsoup  HTTP
1780              transport library.
1781
1782       SYNCEVOLUTION_DATA_DIR
1783              Overrides the default path to the bluetooth device lookup table,
1784              normally /usr/lib/syncevolution/.
1785
1786       SYNCEVOLUTION_BACKEND_DIR
1787              Overrides   the    default    path    to    plugins,    normally
1788              /usr/lib/syncevolution/backends.
1789
1790       SYNCEVOLUTION_LIBEXEC_DIR
1791              Overrides  the  path  where  additional  helper  executables are
1792              found, normally /usr/libexec.
1793
1794       SYNCEVOLUTION_LOCALE_DIR
1795              Overrides the path to directories with  the  different  transla‐
1796              tions, normally /usr/share/locale.
1797
1798       SYNCEVOLUTION_TEMPLATE_DIR
1799              Overrides   the   default   path  to  template  files,  normally
1800              /usr/share/syncevolution/templates.
1801
1802       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
1806              engine is started as part of a sync session.
1807
1808              Note  that  in  addition  to  this directory, SyncEvolution also
1809              always  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

BUGS

1815       See known issues and the support web page for more information.
1816

SEE ALSO

1818       http://syncevolution.org
1819

AUTHORS

1821       Main developer
1822              Patrick Ohly <patrick.ohly@intel.com>, http://www.estamos.de
1823
1824       Contributors
1825              http://syncevolution.org/about/contributors
1826
1827       To contact the project publicly (preferred)
1828              syncevolution@syncevolution.org
1829
1830       Intel-internal team mailing list (confidential)
1831              syncevolution@lists.intel.com
1832
1833
1834
1835
18361.5.3                             2020-07-30                  SYNCEVOLUTION(1)
Impressum