.\" Man page generated from reStructuredText. . .TH SYNCEVOLUTION 1 "2015-01-03" "1.4.99.4" "" .SH NAME SyncEvolution \- synchronize personal information management data . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .INDENT 0.0 .TP .B List and manipulate databases: syncevolution \-\-print\-databases|\-\-create\-database|\-\-remove\-database [] [ ] .TP .B Show information about configuration(s): syncevolution \-\-print\-servers|\-\-print\-configs|\-\-print\-peers .TP .B Show information about a specific configuration: syncevolution \-\-print\-config [\-\-quiet] [\-\-] [main| ...] .TP .B List sessions: syncevolution \-\-print\-sessions [\-\-quiet] [\-\-] .TP .B Show information about SyncEvolution: syncevolution \-\-help|\-h|\-\-version .TP .B Run a synchronization as configured: syncevolution [ ...] .TP .B Run a synchronization with properties changed just for this run: syncevolution \-\-run [\-\-] [ ...] .TP .B Restore data from the automatic backups: syncevolution \-\-restore \-\-before|\-\-after [\-\-dry\-run] [\-\-] ... .TP .B Create, update or remove a configuration: syncevolution \-\-configure [\-\-] [ ...] .sp syncevolution \-\-remove|\-\-migrate [\-\-] .TP .B List items: syncevolution \-\-print\-items [\-\-] [ []] .TP .B Export item(s): .INDENT 7.0 .TP .B syncevolution [\-\-delimiter ] \-\-export ||\- [\-\-] [ [ [ ...]]] \-\-luids ... .UNINDENT .TP .B Add item(s): .INDENT 7.0 .TP .B syncevolution [\-\-delimiter |none] \-\-import ||\- [\-\-] [ []] \-\-luids ... .UNINDENT .TP .B Update item(s): syncevolution \-\-update [\-\-] .INDENT 7.0 .TP .B syncevolution [\-\-delimiter |none] \-\-update |\- [\-\-] ... \-\-luids ... .UNINDENT .TP .B Remove item(s): syncevolution \-\-delete\-items [\-\-] ( ... | \(aq*\(aq) .UNINDENT .SH DESCRIPTION .sp This text explains the usage of the SyncEvolution command line. .sp SyncEvolution synchronizes personal information management (PIM) data such as contacts, appointments, tasks and memos using the Synthesis sync engine, which provides support for the SyncML synchronization protocol. .sp SyncEvolution synchronizes with SyncML servers over HTTP and with SyncML capable phones locally over Bluetooth (new in 1.0). Plugins provide access to the data which is to be synchronized. Binaries are available for Linux desktops (synchronizing data in GNOME Evolution, with KDE supported indirectly already and Akonadi support in development), for MeeGo (formerly Moblin) and for Maemo 5/Nokia N900. The source code can be compiled for Unix\-like systems and provides a framework to build custom SyncML clients or servers. .SH TERMINOLOGY .INDENT 0.0 .TP .B peer A peer is the entity that data is synchronized with. This can be another device (like a phone), a server (like Google) or even the host itself (useful for synchronizing two different databases). .TP .B host The device or computer that SyncEvolution runs on. .TP .B item The smallest unit of synchronization. Examples of items include calendar events and individual contacts, memos, or tasks. .TP .B database Each peer has one or more databases that get synchronized (Google Calendar, Google Contacts). Conceptually a database is a set of items where each item is independent of the others. .TP .B backend Access to databases is provided by SyncEvolution backends. It does not matter where that data is stored. Some backends provide access to data outside of the host itself (\fI\%CalDAV and CardDAV\fP, ActiveSync). .TP .B datastore (or just "store") Used for the combination of SyncEvolution backend and database settings. A datastore provides read/write access to a database, which is a prerequisite for syncing the database. The datastore is independent of the peers that the database might be synchronized with. .sp This used to be called "data source" or just "source", which is a term still found in older documentation, some file paths and the source code of SyncEvolution. .TP .B local/remote Synchronization always happens between a pair of databases and thus has two sides. One database or side of a sync is remote (the one of the peer), the other is local (SyncEvolution). For the sake of consistency (and lack of better terms), these terms are used even if the peer is another instance of SyncEvolution and/or all data resides on the same storage. .TP .B sync config A sync configuration defines how to talk with a peer: the protocol which is to be used, how to find the peer, credentials, etc. .sp Sync configs can be used to initiate a sync (like contacting a SyncML server) or to handle an incoming sync request (when acting as SyncML server which is contacted by the peer). .sp If the peer supports SyncML as sync protocol, a sync only uses one sync config on the SyncEvolution side. If the peer supports data access via some other protocols, then SyncEvolution can make that data available via SyncML and run a sync where SyncML is used internally. Such a sync involves two sync configs, see \fBoriginating config\fP and \fBtarget config\fP\&. .sp A sync config can use all datastores defined in the same context (see below). Some properties of the datastore can be set differently for each peer and thus sync config (\fBper\-peer\fP). One of these, the \fBsync\fP property, defines if and how a datastore is used during a sync. .TP .B context Sync and datastore configs are defined inside one or more configuration contexts. There is always a \fB@default\fP context that gets used if nothing else is specified. .sp Typically each context represents a certain set of related datastores. For example, normally the \fB@default\fP context is used for local databases. Datastores related to a certain peer can be defined in a context \fB@peer\-name\fP named after that peer. .TP .B configuration properties SyncEvolution uses key/value pairs to store configuration options. A configuration is a set of unique keys and their values that together describe a certain object. .sp These sets of properties are addressed via the main config name (a sync config name with or without an explicit context, or just the context name) and optionally the datastore name (if the properties are for a specific datastore). .sp Sync properties are set for sync configs, independently of a particular datastore. Properties that cannot be set without specifying they datastore that they apply to are datastore properties. This includes properties that belong both to a datastore and a sync config. .sp The property names were chosen so that they are unique, i.e., no sync property has the same name as a datastore property. For historic reasons, internally these properties are treated as two different sets and there are two different command line options to query the list of sync resp. datastore properties. .sp Some configuration properties are shared between configurations automatically. This sharing is hard\-coded and cannot be configured. It has the advantage that certain settings only need to be set once and/or can be changed for several different configs at once. .sp A property can be \fIunshared\fP (has separate values for each peer, therefore sometimes also called \fIper\-peer\fP; for example the \fBsync\fP property), \fIshared\fP (same value for all peers; for example the \fBdatabase\fP property for selecting the local database) or \fIglobal\fP (exactly one value). .sp Together with the distinction between sync and datastore properties, this currently results in five different groups of properties: .INDENT 7.0 .IP \(bu 2 Sync properties (by definition, this also includes properties independent of a particular sync config because they are set for all sync configs at once, independently of any particular datastore): .INDENT 2.0 .IP \(bu 2 global (= \fB~/.config/syncevolution/config.ini\fP): independent of a particular context, for example \fBkeyring\fP .IP \(bu 2 shared (= \fB~/.config/syncevolution//config.ini\fP): set once for each context, for example \fBlogdir\fP .IP \(bu 2 unshared (= \fB~/.config/syncevolution//peers//config.ini\fP): set separately for each sync config, for example \fBsyncURL\fP .UNINDENT .IP \(bu 2 Datastore properties: .INDENT 2.0 .IP \(bu 2 shared (= \fB~/.config/syncevolution//sources//config.ini\fP): the properties required for access to the data, primarily \fBbackend\fP and \fBdatabase\fP .IP \(bu 2 unshared (= \fB~/.config/syncevolution//peers//sources//config.ini\fP): the already mentioned \fBsync\fP and \fBuri\fP properties, but also a per\-peer sync format properties .UNINDENT .UNINDENT .sp Many properties have reasonable defaults, either defined in the configuration layer or chosen at runtime by the SyncEvolution engine reading the configuration, and therefore do not have to be set. .sp The configuration layer in SyncEvolution has a very limited understanding of the semantic of each property. It just knows about some generic types (strings, boolean, integers, ...) and where properties are supposed to be stored. It is the layer above that, the one which actually tries to use the configuration, that determines whether the property values make sense as specified. Beware that it is possible to set properties to values that conflict with other property values (triggering errors when using the configuration) or to set properties that are not used (typically they get ignored silently, unless an explicit error check was implemented). .TP .B configuration template Templates define the settings for specific peers. Some templates are packaged together with SyncEvolution, others may be added by packagers or users. Settings from templates are copied once into the sync config when creating it. There is no permanent link back to the template, so updating a template has no effect on configs created from it earlier. .sp A template only contains unshared properties. Therefore it is possible to first set shared properties (for example, choosing which databases to synchronize in the default context), then add sync configs for different peers to that context without reseting the existing settings. .sp In SyncEvolution\(aqs predefined configuration templates, the following names for datastores are used. Different names can be chosen for datastores that are defined manually. .INDENT 7.0 .IP \(bu 2 addressbook: a list of contacts .IP \(bu 2 calendar: calendar \fIevents\fP .IP \(bu 2 memo: plain text notes .IP \(bu 2 todo: task list .IP \(bu 2 calendar+todo: a virtual datastore combining one local "calendar" and one "todo" datastore (required for synchronizing with some phones) .UNINDENT .TP .B local sync Traditionally, a sync config specifies SyncML as the synchronization protocol via the \fIsyncURL\fP property. The peer must support SyncML for this to work. .sp In a so called local sync, SyncEvolution acts as SyncML server and client at the same time, connecting the two sides via internal message passing. Both sides have their own set of datastores, which may use CalDAV, CardDAV or ActiveSync to access the data. .sp See \fI\%Synchronization beyond SyncML\fP\&. .TP .B originating config In a local sync, the sync config used to start the sync is called the originating sync config, or just originating config. .TP .B target config In addition to the originating config, a local sync also uses a target config. At the configuration level, this target config is just another sync config. It becomes a target config when referenced by a sync config for local syncing. .UNINDENT .SH COMMAND LINE CONVENTIONS .sp The \fB\fP and the \fB\fP strings in the command line synopsis are used to find the sync resp. datastore configs. Depending on which other parameters are given, different operations are executed. .sp The \fB\fP string has the format \fB[][@]\fP\&. When the context is not specified explicitly, SyncEvolution first searches for an existing sync configuration with the given \fB\fP name. If not found, the configuration can only be created, but not read. It will be created in the \fB@default\fP context as fallback. The empty \fB\fP string is an alias for \fB@default\fP\&. .sp The \fB\fP part identifies a specific sync or target config inside the context. It is optional and does not have to be specified when not needed, for example when configuring the shared settings of datastores (\fB\-\-configure @default addressbook\fP) or accessing items inside a datastore (\fB\-\-print\-items @work calendar\fP). .sp Listing datastores on the command line limits the operation to those datastores (called \fIactive datastores\fP below). If not given, all datastores enabled for the config are active. Some operations require the name of exactly one datastore. .sp Properties are set with key/value assignments and/or the \fB\-\-sync/store\-property\fP keywords. Those keywords are only needed for the hypothetical situation that a sync and datastore property share the same name (which was intentionally avoided). Without them, SyncEvolution automatically identifies which kind of property is meant based on the name. .sp A \fB\fP assignment has the following format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [/][@|@@]= .ft P .fi .UNINDENT .UNINDENT .sp The optional \fB\fP or \fB@\fP suffix limits the scope of the value to that particular configuration. This is useful when running a local sync, which involves a sync and a target configuration. For example, the log level can be specified separately for both sides: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-run loglevel@default=1 loglevel@google\-calendar=4 google\-calendar@default .ft P .fi .UNINDENT .UNINDENT .sp A string without a second @ sign inside is always interpreted as a context name, so in contrast to the \fB\fP string, \fBfoo\fP cannot be used to reference the \fBfoo@default\fP configuration. Use the full name including the context for that. .sp When no config or context is specified explicitly, a value is changed in all active configs, typically the one given with \fB\fP\&. The priority of multiple values for the same config is \fImore specific definition wins\fP, so \fB@\fP overrides \fB@\fP, which overrides \fIno suffix given\fP\&. Specifying some suffix which does not apply to the current operation does not trigger an error, so beware of typos. .sp Datastore properties can be specified with a \fB/\fP prefix. This allows limiting the value to the selected datastore. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-configure "addressbook/database=My Addressbook" \e "calendar/database=My Calendar" \e @default addressbook calendar .ft P .fi .UNINDENT .UNINDENT .sp Another way to achieve the same effect is to run the \fB\-\-configure\fP operation twice, once for \fBaddressbook\fP and once for \fBcalendar\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-configure "database=My Addressbook" @default addressbook \-\-configure "database=My Calendar" @default calendar .ft P .fi .UNINDENT .UNINDENT .sp If the same property is set both with and without a \fB/\fP prefix, then the more specific value with that prefix is used for that datastore, regardless of the order on the command line. The following command enables all datastores except for the addressbook: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-configure addressbook/sync=none \e sync=two\-way \e .ft P .fi .UNINDENT .UNINDENT .SH USAGE .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-print\-databases [] [ ] .ft P .fi .UNINDENT .UNINDENT .sp If no additional arguments are given, then SyncEvolution will list all available backends and the databases that can be accessed through each backend. This works without existing configurations. However, some backends, like for example the CalDAV backend, need additional information (like credentials or URL of a remote server). This additional information can be provided on the command line with property assignments (\fBusername=...\fP) or in an existing configuration. .sp When listing all databases of all active datastores, the output starts with a heading that lists the values for the \fBbackend\fP property which select the backend, followed by the databases. Each database has a name and a unique ID (in brackets). Typically both can be used as value of the \(aqdatabase\(aq property. One database might be marked as \fBdefault\fP\&. It will be used when \fBdatabase\fP is not set explicitly. .sp When selecting an existing datastore configuration or specifying the \fBbackend\fP property on the command line, only the databases for that backend are listed and the initial line shows how that backend was selected (/ resp. backend value). .sp Some backends do not support listing of databases. For example, the file backend synchronizes directories with one file per item and always needs an explicit \fBdatabase\fP property because it cannot guess which directory it is meant to use. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-create\-database [] [ ] .ft P .fi .UNINDENT .UNINDENT .sp Creates a new database for the selected \fBbackend\fP, using the information given in the \fBdatabase\fP property. As with \fB\-\-print\-databases\fP, it is possible to give the properties directly without configuring a datastore first. .sp The interpretation of the \fBdatabase\fP property depends on the backend. Not all backends support this operation. .sp The EDS backend uses the value of the \fBdatabase\fP as name of the new database and assigns a unique URI automatically. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-remove\-database [] [ ] .ft P .fi .UNINDENT .UNINDENT .sp Looks up the database based on the \fBdatabase\fP property (depending on the backend, both name and a URI are valid), then deletes the data. Note that datastore configurations using the database are not removed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution .ft P .fi .UNINDENT .UNINDENT .sp Without the optional list of datastores, all datastores which are enabled in their configuration file are synchronized. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution ... .ft P .fi .UNINDENT .UNINDENT .sp Otherwise only the ones mentioned on the command line are active. It is possible to configure datastores without activating their synchronization: if the synchronization mode of a datastore is set to \fIdisabled\fP, the datastore will be ignored. Explicitly listing such a datastore will synchronize it in \fItwo\-way\fP mode once. .sp Progress and error messages are written into a log file that is preserved for each synchronization run. Details about that is found in the \fIAutomatic Backups and Logging\fP section below. All errors and warnings are printed directly to the console in addition to writing them into the log file. Before quitting SyncEvolution will print a summary of how the local data was modified. This is done with the \fIsynccompare\fP utility script described in the \fI\%Exchanging Data\fP section. .sp When the \fBlogdir\fP property is enabled (since v0.9 done by default for new configurations), then the same comparison is also done before the synchronization starts. .sp In case of a severe error the synchronization run is aborted prematurely and SyncEvolution will return a non\-zero value. Recovery from failed synchronization is done by forcing a full synchronization during the next run, i.e. by sending all items and letting the SyncML server compare against the ones it already knows. This is avoided whenever possible because matching items during a slow synchronization can lead to duplicate entries. .sp After a successful synchronization the server\(aqs configuration file is updated so that the next run can be done incrementally. If the configuration file has to be recreated e.g. because it was lost, the next run recovers from that by doing a full synchronization. The risk associated with this is that the server might not recognize items that it already has stored previously which then would lead to duplication of items. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-configure [ ...] .ft P .fi .UNINDENT .UNINDENT .sp Options in the configuration can be modified via the command line. The and the optional parameters define what gets created or modified. The remaining parameters define which values get set or modified. .sp To change settings of specific datastores, either invoke syncevolution multiple times with exactly one parameter or use the \fB[/]\fP prefix described above for property assignments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-remove .ft P .fi .UNINDENT .UNINDENT .sp Deletes the configuration. If the refers to a specific peer, only that peer\(aqs configuration is removed. If it refers to a context, that context and all peers and datastores defined inside it are removed. .sp Note that there is no confirmation question. Neither local data referenced by the configuration nor the content of log dirs are deleted. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-run [ ...] .ft P .fi .UNINDENT .UNINDENT .sp Options can also be overridden for just the current run, without changing the configuration. In order to prevent accidentally running a sync session when a configuration change was intended, either \-\-configure or \-\-run must be given explicitly if options are specified on the command line. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-status [ ...] .ft P .fi .UNINDENT .UNINDENT .sp Prints what changes were made locally since the last synchronization. Depends on access to database dumps from the last run, so enabling the \fBlogdir\fP property is recommended. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-print\-servers|\-\-print\-configs|\-\-print\-peers syncevolution \-\-print\-config [\-\-quiet] [main| ...] syncevolution \-\-print\-sessions [\-\-quiet] .ft P .fi .UNINDENT .UNINDENT .sp These commands print information about existing configurations. When printing a configuration a short version without comments can be selected with \-\-quiet. When datastores are listed, only their configuration is shown. \fIMain\fP instead or in combination with datastores lists only the main peer configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-restore \-\-before|\-\-after [\-\-dry\-run] ... .ft P .fi .UNINDENT .UNINDENT .sp This restores local data from the backups made before or after a synchronization session. The \-\-print\-sessions command can be used to find these backups. The datastore(s) have to be listed explicitly. There is intentionally no default, because as with \-\-remove there is no confirmation question. With \-\-dry\-run, the restore is only simulated. .sp The session directory has to be specified explicitly with its path name (absolute or relative to current directory). It does not have to be one of the currently active log directories, as long as it contains the right database dumps for the selected datastores. .sp A restore tries to minimize the number of item changes (see section \fI\%Item Changes and Data Changes\fP). This means that items that are identical before and after the change will not be transmitted anew to the peer during the next synchronization. If the peer somehow needs to get a clean copy of all local items, then use \fB\-\-sync refresh\-from\-local\fP in the next run. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-print\-items syncevolution [\-\-delimiter ] \-\-export ||\- [ [ [ ...]]] syncevolution [\-\-delimiter |none] \-\-import ||\- [ ] syncevolution \-\-update syncevolution [\-\-delimiter |none] \-\-update |\- ... syncevolution \-\-delete\-items ( ... | *) .ft P .fi .UNINDENT .UNINDENT .sp Restore depends on the specific format of the automatic backups created by SyncEvolution. Arbitrary access to item data is provided with additional options. here is the unique local identifier assigned to each item in the datastore, transformed so that it contains only alphanumeric characters, dash and underscore. A star * in \-\-delete\-items selects all items for deletion. There are two ways of specifying luids: either as additional parameters after the config and datastore parameters (which may be empty in this case, but must be given) or after the \fB\-\-luids\fP keyword. .sp and may be given to define the database which is to be used. If not given or not refering to an existing configuration (which is not an error, due to historic reasons), the desired backend must be given via the \fBbackend\fP property, like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncevolution \-\-print\-items backend=evolution\-contacts syncevolution \-\-export \- backend=evolution\-contacts \e \-\-luids pas\-id\-4E33F24300000006 pas\-id\-4E36DD7B00000007 .ft P .fi .UNINDENT .UNINDENT .sp The desired backend database can be chosen via \fBdatabase=\fP\&. See \fB\-\-print\-databases\fP\&. .SH OPTIONS .sp Here is a full description of all that can be put in front of the server name. Whenever an option accepts multiple values, a question mark can be used to get the corresponding help text and/or a list of valid values. .INDENT 0.0 .TP .B \-\-sync|\-s |? Temporarily synchronize the active datastores in that mode. Useful for a \fIrefresh\-from\-local\fP or \fIrefresh\-from\-remote\fP sync which clears all data at one end and copies all items from the other. .sp \fBWarning:\fP \fIlocal\fP is the data accessed via the sync config directly and \fIremote\fP is the data on the peer, regardless where the data is actually stored physically. .TP .B \-\-print\-servers|\-\-print\-configs|\-\-print\-peers Prints the names of all configured peers to stdout. There is no difference between these options, the are just aliases. .TP .B \-\-print\-servers|\-\-print\-configs|\-\-print\-peers|\-p Prints the complete configuration for the selected to stdout, including up\-to\-date comments for all properties. The format is the normal .ini format with datastore configurations in different sections introduced with [] lines. Can be combined with \-\-sync\-property and \-\-datastore\-property to modify the configuration on\-the\-fly. When one or more datastores are listed after the name on the command line, then only the configs of those datastores are printed. \fImain\fP selects the main configuration instead of datastore configurations. Using \-\-quiet suppresses the comments for each property. When setting a \-\-template, then the reference configuration for that peer is printed instead of an existing configuration. .TP .B \-\-print\-sessions Prints information about previous synchronization sessions for the selected peer or context are printed. This depends on the \fBlogdir\fP property. The information includes the log directory name (useful for \-\-restore) and the synchronization report. In combination with \-\-quiet, only the paths are listed. .TP .B \-\-configure|\-c Modify the configuration files for the selected peer and/or datastores. .sp If no such configuration exists, then a new one is created using one of the template configurations (see \-\-template option). Choosing a template sets most of the relevant properties for the peer and the default set of datastores (see above for a list of those). Anything specific to the user (like username/password) still has to be set manually. .sp When creating a new configuration and listing datastores explicitly on the command line, only those datastores will be set to active in the new configuration, i.e. \fIsyncevolution \-c memotoo addressbook\fP followed by \fIsyncevolution memotoo\fP will only synchronize the address book. The other datastores are created in a disabled state. When modifying an existing configuration and datastores are specified, then the datastore properties of only those datastores are modified. .sp By default, creating a config requires a template. Datastore names on the command line must match those in the template. This allows catching typos in the peer and datastore names. But it also prevents some advanced use cases. Therefore it is possible to disable these checks in two ways: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- use \(ga\-\-template none\(ga or \- specify all required sync and datastore properties that are normally in the templates on the command line (syncURL, backend, ...) .ft P .fi .UNINDENT .UNINDENT .TP .B \-\-run|\-r To prevent accidental sync runs when a configuration change was intended, but the \fI\-\-configure\fP option was not used, \fI\-\-run\fP must be specified explicitly when sync or datastore properties are selected on the command line and they are meant to be used during a sync session triggered by the invocation. .TP .B \-\-migrate In older SyncEvolution releases a different layout of configuration files was used. Using \-\-migrate will automatically migrate to the new layout and rename the into .old to prevent accidental use of the old configuration. WARNING: old SyncEvolution releases cannot use the new configuration! .sp The switch can also be used to migrate a configuration in the current configuration directory: this preserves all property values, discards obsolete properties and sets all comments exactly as if the configuration had been created from scratch. WARNING: custom comments in the configuration are not preserved. .sp \-\-migrate implies \-\-configure and can be combined with modifying properties. .TP .B \-\-print\-items Shows all existing items using one line per item using the format "[: ]". Whether the description is available depends on the backend and the kind of data that it stores. .TP .B \-\-export Writes all items in the datastore or all items whose is given into a directory if the \-\-export parameter exists and is a directory. The of each item is used as file name. Otherwise it creates a new file under that name and writes the selected items separated by the chosen delimiter string. stdout can be selected with a dash. .sp The default delimiter (two line breaks) matches a blank line. As a special case, it also matches a blank line with DOS line ending (line break, carriage return, line break). This works for vCard 3.0 and iCalendar 2.0, which never contain blank lines. .sp When exporting, the default delimiter will always insert two line breaks regardless whether the items contain DOS line ends. As a special case, the initial newline of a delimiter is skipped if the item already ends in a newline. .TP .B \-\-import Adds all items found in the directory or input file to the datastore. When reading from a directory, each file is treated as one item. Otherwise the input is split at the chosen delimiter. "none" as delimiter disables splitting of the input. .TP .B \-\-update Overwrites the content of existing items. When updating from a directory, the name of each file is taken as its luid. When updating from file or stdin, the number of luids given on the command line must match with the number of items in the input. .TP .B \-\-delete\-items Removes the specified items from the datastore. Most backends print some progress information about this, but besides that, no further output is produced. Trying to remove an item which does not exist typically leads to an ERROR message, but is not reflected in a non\-zero result of the command line invocation itself because the situation is not reported as an error by backends (removal of non\-existent items is not an error in SyncML). Use a star * instead or in addition to listing individual luids to delete all items. .TP .B \-\-sync\-property|\-y =|=?|? Overrides a datastore\-independent configuration property for the current synchronization run or permanently when \-\-configure is used to update the configuration. Can be used multiple times. Specifying an unused property will trigger an error message. .TP .B \-\-datastore\-property|\-\-source\-property|\-z =|=?|? Same as \-\-sync\-property, but applies to the configuration of all active datastores. \fI\-\-sync \fP is a shortcut for \fI\-\-datastore\-property sync=\fP\&. .TP .B \-\-template|\-l |default|? Can be used to select from one of the built\-in default configurations for known SyncML peers. Defaults to the name, so \-\-template only has to be specified when creating multiple different configurations for the same peer, or when using a template that is named differently than the peer. \fIdefault\fP is an alias for \fImemotoo\fP and can be used as the starting point for servers which do not have a built\-in template. .sp A pseudo\-random device ID is generated automatically. Therefore setting the \fIdeviceId\fP sync property is only necessary when manually recreating a configuration or when a more descriptive name is desired. .sp The available templates for different known SyncML servers are listed when using a single question mark instead of template name. When using the \fI?\fP format, a fuzzy search for a template that might be suitable for talking to such a device is done. The matching works best when using \fI = \fP\&. If you don\(aqt know the manufacturer, you can just keep it as empty. The output in this mode gives the template name followed by a short description and a rating how well the template matches the device (100% is best). .TP .B \-\-status|\-t The changes made to local data since the last synchronization are shown without starting a new one. This can be used to see in advance whether the local data needs to be synchronized with the server. .TP .B \-\-quiet|\-q Suppresses most of the normal output during a synchronization. The log file still contains all the information. .TP .B \-\-keyring[=]|\-k A legacy option, now the same as setting the global keyring sync property. When not specifying a value explicitly, "true" for "use some kind of keyring" is implied. See "\-\-sync\-property keyring" for details. .TP .B \-\-daemon[=yes/no] By default, the SyncEvolution command line is executed inside the syncevo\-dbus\-server process. This ensures that synchronization sessions started by the command line do not conflict with sessions started via some other means (GUI, automatically). For debugging purposes or very special use cases (running a local sync against a server which executes inside the daemon) it is possible to execute the operation without the daemon (\-\-daemon=no). .TP .B \-\-help|\-h Prints usage information. .TP .B \-\-version Prints the SyncEvolution version. .UNINDENT .SH CONFIGURATION PROPERTIES .sp This section lists predefined properties. Backends can add their own properties at runtime if none of the predefined properties are suitable for a certain setting. Those additional properties are not listed here. Use \fB\-\-sync/datastore\-property ?\fP to get an up\-to\-date list. .sp The predefined properties may also be interpreted slightly differently by each backend and sync protocol. Sometimes this is documented in the comment for each property, sometimes in the documentation of the backend or sync protocol. .sp Properties are listed together with all recognized aliases (in those cases where a property was renamed at some point), its default value, sharing state (unshared/shared/global). Some properties must be defined, which is marked with the word \fIrequired\fP\&. .SS Sync properties .INDENT 0.0 .TP .B syncURL (no default, unshared, required) Identifies how to contact the peer, best explained with some examples. .sp HTTP(S) SyncML servers: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C http://example.com/sync .ft P .fi .UNINDENT .UNINDENT .sp OBEX over Bluetooth uses the MAC address, with the channel chosen automatically: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C obex\-bt://00:0A:94:03:F3:7E .ft P .fi .UNINDENT .UNINDENT .sp If the automatism fails, the channel can also be specified: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C obex\-bt://00:0A:94:03:F3:7E+16 .ft P .fi .UNINDENT .UNINDENT .sp For peers contacting us via Bluetooth, the MAC address is used to identify it before the sync starts. Multiple urls can be specified in one syncURL property: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C obex\-bt://00:0A:94:03:F3:7E obex\-bt://00:01:02:03:04:05 .ft P .fi .UNINDENT .UNINDENT .sp In the future this might be used to contact the peer via one of several transports; right now, only the first one is tried. .TP .B username (no default, unshared) user name used for authorization with the SyncML server .TP .B password (no default, unshared) password used for authorization with the peer; in addition to specifying it directly as plain text, it can also be read from the standard input or from an environment variable of your choice: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C plain text : password = ask : password = \- env variable: password = ${} .ft P .fi .UNINDENT .UNINDENT .TP .B logdir (no default, shared) full path to directory where automatic backups and logs are stored for all synchronizations; if unset, then "${XDG_CACHE_HOME}/syncevolution/" (which usually expands to ${HOME}/.cache/...) will be used; if "none", then no backups of the databases are made and any output is printed directly to the screen .TP .B loglevel (0, unshared) level of detail for log messages: \- 0 (or unset) = INFO messages without log file, DEBUG with log file \- 1 = only ERROR messages \- 2 = also INFO messages \- 3 = also DEBUG messages > 3 = increasing amounts of debug messages for developers .TP .B notifyLevel (3, unshared) Level of detail for desktop notifications. Currently such notifications are generated only for automatically started sync sessions. .sp 0 \- suppress all notifications 1 \- show only errors 2 \- show information about changes and errors (in practice currently the same as level 3) 3 \- show all notifications, including starting a sync .TP .B printChanges (TRUE, unshared) enables or disables the detailed (and sometimes slow) comparison of database content before and after a sync session .TP .B dumpData (TRUE, unshared) enables or disables the automatic backup of database content before and after a sync session (always enabled if printChanges is enabled) .TP .B maxlogdirs (10, shared) Controls how many session directories are kept at most in the logdir. Unless set to zero, SyncEvolution will remove old directories and all their content to prevent the number of log directories from growing beyond the given limit. It tries to be intelligent and will remove sessions in which nothing interesting happened (no errors, no data changes) in favor of keeping sessions where something happened, even if those sessions are older. .TP .B autoSync (0, unshared) Controls automatic synchronization. Currently, automatic synchronization is done by running a synchronization at regular intervals. This may drain the battery, in particular when using Bluetooth! Because a peer might be reachable via different transports at some point, this option provides detailed control over which transports may be used for automatic synchronization: .INDENT 7.0 .TP .B 0 don\(aqt do auto sync .TP .B 1 .INDENT 7.0 .TP .B do automatic sync, using whatever transport is available .UNINDENT .TP .B http only via HTTP transport .TP .B obex\-bt only via Bluetooth transport .TP .B http,obex\-bt pick one of these .UNINDENT .TP .B autoSyncInterval (30M, unshared) This is the minimum number of seconds since the start of the last synchronization that has to pass before starting an automatic synchronization. Can be specified using a 1h30m5s format. .sp Before reducing this interval, consider that it will increase resource consumption on the local and remote side. Some SyncML server operators only allow a certain number of sessions per day. The value 0 has the effect of only running automatic synchronization when changes are detected (not implemented yet, therefore it basically disables automatic synchronization). .TP .B autoSyncDelay (5M, unshared) An automatic sync will not be started unless the peer has been available for this duration, specified in seconds or 1h30m5s format. .sp This prevents running a sync when network connectivity is unreliable or was recently established for some other purpose. It is also a heuristic that attempts to predict how long connectivity be available in the future, because it should better be available long enough to complete the synchronization. .TP .B preventSlowSync (TRUE, unshared) During a slow sync, the SyncML server must match all items of the client with its own items and detect which ones it already has based on properties of the items. This is slow (client must send all its data) and can lead to duplicates (when the server fails to match correctly). It is therefore sometimes desirable to wipe out data on one side with a refresh\-from\-client/server sync instead of doing a slow sync. When this option is enabled, slow syncs that could cause problems are not allowed to proceed. Instead, the affected datastores are skipped, allowing the user to choose a suitable sync mode in the next run (slow sync selected explicitly, refresh sync). The following situations are handled: .INDENT 7.0 .IP \(bu 2 running as client with no local data => unproblematic, slow sync is allowed to proceed automatically .IP \(bu 2 running as client with local data => client has no information about server, so slow sync might be problematic and is prevented .IP \(bu 2 client has data, server asks for slow sync because all its data was deleted (done by Memotoo and Mobical, because they treat this as \(aquser wants to start from scratch\(aq) => the sync would recreate all the client\(aqs data, even if the user really wanted to have it deleted, therefore slow sync is prevented .UNINDENT .TP .B useProxy (FALSE, unshared) set to T to choose an HTTP proxy explicitly; otherwise the default proxy settings of the underlying HTTP transport mechanism are used; only relevant when contacting the peer via HTTP .TP .B proxyHost (no default, unshared) proxy URL (\fBhttp://:\fP) .TP .B proxyUsername (no default, unshared) authentication for proxy: username .TP .B proxyPassword (no default, unshared) proxy password, can be specified in different ways, see SyncML server password for details .TP .B clientAuthType (md5, unshared) .INDENT 7.0 .IP \(bu 2 empty or "md5" for secure method (recommended) .IP \(bu 2 "basic" for insecure method .UNINDENT .sp This setting is only for debugging purpose and only has an effect during the initial sync of a client. Later it remembers the method that was supported by the server and uses that. When acting as server, clients contacting us can use both basic and md5 authentication. .TP .B RetryDuration (5M, unshared) The total amount of time in seconds in which the SyncML client tries to get a response from the server. During this time, the client will resend messages in regular intervals (RetryInterval) if no response is received or the message could not be delivered due to transport problems. When this time is exceeded without a response, the synchronization aborts without sending further messages to the server. .sp When acting as server, this setting controls how long a client is allowed to not send a message before the synchronization is aborted. .TP .B RetryInterval (2M, unshared) The number of seconds between the start of SyncML message sending and the start of the retransmission. If the interval has already passed when a message send returns, the message is resent immediately. Resending without any delay will never succeed and therefore specifying 0 disables retries. .sp Servers cannot resend messages, so this setting has no effect in that case. .sp The WebDAV backend also resends messages after a temporary network error. It uses exponential backoff to determine when the server is available again. This setting is divided by 24 to obtain the initial delay (default: 2m => 5s), which is then doubled for each retry. .TP .B remoteIdentifier (no default, unshared) the identifier sent to the remote peer for a server initiated sync. if not set, deviceId will be used instead .TP .B PeerIsClient (FALSE, unshared) Indicates whether this configuration is about a client peer or server peer. .TP .B SyncMLVersion (no default, unshared) On a client, the latest commonly supported SyncML version is used when contacting a server. One of \(aq1.0/1.1/1.2\(aq can be used to pick a specific version explicitly. .sp On a server, this option controls what kind of Server Alerted Notification is sent to the client to start a synchronization. By default, first the format from 1.2 is tried, then in case of failure, the older one from 1.1. 1.2/1.1 can be set explicitly, which disables the automatism. .sp Instead or in adddition to the version, several keywords can be set in this property (separated by spaces or commas): .INDENT 7.0 .IP \(bu 2 NOCTCAP \- avoid sending CtCap meta information .IP \(bu 2 NORESTART \- disable the sync mode extension that SyncEvolution client and server use to negotiate whether both sides support running multiple sync iterations in the same session .IP \(bu 2 REQUESTMAXTIME=