SyncEvolution(1)

📦
version 2.0.0 · 8 versions
, in ubuntu stonking

✨ NAME ✨

SyncEvolution — straight outta the General Commands Manual, bestie — synchronize personal information management data 💖

Okay so real talk, this is the manual page for SyncEvolution(1), and she does a LOT. Buckle up, we're going section by section, no skipping, no skimming, fr fr. 🦋

🌸 SYNOPSIS 🌸

Lowkey the vibe here is: there's like a million ways to call her, and each one does a different thing. Here's every single one, exactly as written, so you can copy-paste and slay. 💅

🎀 List and manipulate databases

syncevolution
--print-databases|--create-database|--remove-database
[<properties>] [<config> <store>]

🎀 Show information about configuration(s)

syncevolution --print-servers|--print-configs|--print-peers

🎀 Show information about a specific configuration

syncevolution --print-config [--quiet] [--] <config>
[main|<store> ...]

🎀 List sessions

syncevolution --print-sessions [--quiet] [--] <config>

🎀 Show information about SyncEvolution

syncevolution --help|-h|--version

🎀 Run a synchronization as configured

syncevolution <config> [<store> ...]

🎀 Run a synchronization with properties changed just for this run

syncevolution --run <options for run> [--] <config> [<store> ...]

🎀 Restore data from the automatic backups

syncevolution --restore <session directory> --before|--after
[--dry-run] [--] <config> <store> ...

🎀 Create, update or remove a configuration

syncevolution --configure <options> [--] <config> [<store> ...]

syncevolution --remove|--migrate <options> [--] <config>

🎀 List items

syncevolution --print-items [--] [<config> [<store>]]

🎀 Export item(s)

syncevolution [--delimiter <string>] --export <dir>|<file>|- [--]
[<config> [<store> [<luid> ...]]]
       --luids <luid> ...

🎀 Add item(s)

syncevolution [--delimiter <string>|none] --import <dir>|<file>|-
[--] [<config> [<store>]]
       --luids <luid> ...

🎀 Update item(s)

syncevolution --update <dir> [--] <config> <store>

syncevolution [--delimiter <string>|none] --update <file>|- [--]
<config> <store> <luid> ...
       --luids <luid> ...

🎀 Remove item(s)

syncevolution --delete-items [--] <config> <store> (<luid> ... |
'*')

👑 DESCRIPTION 👑

This text explains the usage of the SyncEvolution command line. Yes, that's literally what we're doing here. It's giving manual inception. 🙈

SyncEvolution synchronizes personal information management (PIM) data — think contacts, appointments, tasks and memos — using the Synthesis sync engine, which provides support for the SyncML synchronization protocol. So, like, the whole point: your data stays in sync. Iconic behavior tbh. 💖

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 🎀
  • MeeGo (formerly Moblin) 🌈
  • 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. So yes bestie, you can absolutely go build your own thing with it. Main character energy. 👑

Stay tuned, there's so much more of this page coming up — we've barely scratched the surface. 💅

✨ TERMINOLOGY ✨

okay bestie, before we go anywhere, we gotta get the vocab straight. no cap, these words show up everywhere later, so let's lock them in. 🫶

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).

host

The device or computer that SyncEvolution runs on.

item

The smallest unit of synchronization. Examples of items include calendar events and individual contacts, memos, or tasks.

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.

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 (CalDAV and CardDAV, ActiveSync).

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.

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.

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.

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.

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).

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 originating config and target config.

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 (per-peer). One of these, the sync property, defines if and how a datastore is used during a sync.

context

Sync and datastore configs are defined inside one or more configuration contexts. There is always a @default context that gets used if nothing else is specified.

Typically each context represents a certain set of related datastores. For example, normally the @default context is used for local databases. Datastores related to a certain peer can be defined in a context @peer-name named after that peer.

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.

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).

Sync properties are set for sync configs, independently of a particular datastore. Properties that cannot be set without specifying the datastore that they apply to are datastore properties. This includes properties that belong both to a datastore and a sync config.

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.

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.

A property can be unshared (has separate values for each peer, therefore sometimes also called per-peer; for example the sync property), shared (same value for all peers; for example the database property for selecting the local database) or global (exactly one value).

Together with the distinction between sync and datastore properties, this currently results in five different groups of properties:

  • 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):
    • global (= ~/.config/syncevolution/config.ini): independent of a particular context, for example keyring
    • shared (= ~/.config/syncevolution/<context name>/config.ini): set once for each context, for example logdir
    • unshared (= ~/.config/syncevolution/<context name>/peers/<peer name>/config.ini): set separately for each sync config, for example syncURL
  • Datastore properties:
    • shared (= ~/.config/syncevolution/<context name>/sources/<store name>/config.ini): the properties required for access to the data, primarily backend and database
    • unshared (= ~/.config/syncevolution/<context name>/peers/<peer name>/sources/<store name>/config.ini): the already mentioned sync and uri properties, but also a per-peer sync format properties

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.

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).

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.

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 resetting the existing settings.

In SyncEvolution's predefined configuration templates, the following names for datastores are used. Different names can be chosen for datastores that are defined manually.

  • addressbook: a list of contacts
  • calendar: calendar events
  • memo: plain text notes
  • todo: task list
  • calendar+todo: a virtual datastore combining one local "calendar" and one "todo" datastore (required for synchronizing with some phones)

local sync

Traditionally, a sync config specifies SyncML as the synchronization protocol via the syncURL property. The peer must support SyncML for this to work.

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.

See Synchronization beyond SyncML.

originating config

In a local sync, the sync config used to start the sync is called the originating sync config, or just originating config.

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.

COMMAND LINE CONVENTIONS 💅

Okay so boom 💥 — the <config> and <store> strings in the command line synopsis? They're the little treasure maps 🗺️ that find the sync resp. datastore configs. Depending on which other parameters you hand over, different operations get executed. It's giving choose-your-own-adventure, but make it config files.

The <config> string has the format [<peer>][@<context>]. When the context is not specified explicitly, SyncEvolution first searches for an existing sync configuration with the given <peer> name. If not found, the configuration can only be created, but not read. It will be created in the @default context as fallback. The empty <config> string is an alias for @default. Periodt. 💖

The <peer> part identifies a specific sync or target config inside the context. It's optional and does not have to be specified when not needed, for example when configuring the shared settings of datastores (--configure @default addressbook) or accessing items inside a datastore (--print-items @work calendar). Slay, options stay optional. 🫶

Listing datastores on the command line limits the operation to those datastores (called active datastores below). If not given, all datastores enabled for the config are active. Some operations require the name of exactly one datastore. So pick your faves or let the whole squad show up. 🌈

Properties are set with key/value assignments and/or the --sync/store-property 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. No manual vibe check required. ✨

A <property> assignment has the following format:

[<store>/]<name>[@<context>|@<peer>@<context>]=<value>

The optional <context> or <peer>@<context> 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:

--run loglevel@default=1 loglevel@google-calendar=4 google-calendar@default

A string without a second @ sign inside is always interpreted as a context name, so in contrast to the <config> string, foo cannot be used to reference the foo@default configuration. Use the full name including the context for that. Iykyk — context matters, literally. 💅

When no config or context is specified explicitly, a value is changed in all active configs, typically the one given with <config>. The priority of multiple values for the same config is more specific definition wins, so <peer>@<context> overrides @<context>, which overrides no suffix given. Specifying some suffix which does not apply to the current operation does not trigger an error, so beware of typos. 👀

Datastore properties can be specified with a <store>/ prefix. This allows limiting the value to the selected datastore. For example:

--configure "addressbook/database=My Addressbook" \
            "calendar/database=My Calendar" \
            @default addressbook calendar

Another way to achieve the same effect is to run the --configure operation twice, once for addressbook and once for calendar:

--configure "database=My Addressbook" @default addressbook
--configure "database=My Calendar" @default calendar

If the same property is set both with and without a <store>/ 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:

--configure addressbook/sync=none \
            sync=two-way \
            <sync config>

💖 USAGE 💖

🗂️ syncevolution --print-databases [<properties>] [<config> <store>]

Bestie, if you give it no extra arguments, SyncEvolution literally just lists all the available backends and every database you can reach through each one. And the gag? You don't even need an existing configuration for this to work. 👑

caveat time tho — some backends (looking at you, CalDAV) need extra info first, like credentials or the URL of a remote server. You can hand that over right on the command line with property assignments (username=...) or just have it in an existing configuration.

When it's listing all the databases of all active datastores, the output kicks off with a heading that lists the values for the backend property — that's the thing that selects the backend — and then comes the databases. Each database has a name and a unique ID (in brackets). Usually you can use either one as the value of the database property. One database might be marked as default — that's the one it grabs when database isn't set explicitly.

When you're selecting an existing datastore configuration, or you specified the backend property right on the command line, then only the databases for that backend get listed, and the opening line shows you how that backend was selected (<config>/<store> resp. backend value).

And heads up: some backends literally do not support listing databases. The file backend is the prime example — it syncs directories with one file per item and it always needs an explicit database property, because it cannot guess which directory you meant. It's giving no vibes, no clues. 💀

🌱 syncevolution --create-database [<properties>] [<config> <store>]

This one makes a brand new database for the backend you selected, using the info you put in the database property. Same energy as --print-databases: you can toss the properties in directly without configuring a datastore first. ✨

How the database property gets interpreted? Depends entirely on the backend. And ngl, not all backends support this operation at all.

The EDS backend uses the value of database as the name of the new database and automatically assigns a unique URI for it. Slay.

🗑️ syncevolution --remove-database [<properties>] [<config> <store>]

Looks up the database based on the database property (depending on the backend, both a name and a URI are valid values), then deletes the data.

⚠️ Note that datastore configurations using the database are not removed. Just the data. Don't come for me, I'm just the messenger. 🫶

🔄 syncevolution <config>

No optional list of datastores? Then all the datastores that are enabled in their configuration file get synchronized. That's the default vibe.

🎯 syncevolution <config> <store> ...

But if you do list them, only the ones you mentioned on the command line are active. And yes, you can totally configure datastores without ever activating their synchronization: if the synchronization mode of a datastore is set to disabled, that datastore gets ignored. Buuut if you explicitly list such a datastore, it will synchronize it in two-way mode once. Just the one time. A lil treat. 🍓

Progress and error messages get written into a log file that's preserved for each synchronization run — the deets live in the Automatic Backups and Logging section below. All errors and warnings also get printed directly to the console on top of going into the log file. And before quitting, SyncEvolution prints a summary of how your local data was modified. That part's handled by the synccompare utility script described in the Exchanging Data section.

When the logdir property is enabled (since v0.9 that's done by default for new configurations), that same comparison also runs before the synchronization starts. Double-checking queen. 👑

If there's a severe error, the synchronization run gets aborted prematurely and SyncEvolution returns a non-zero value. Recovery from a failed sync works by forcing a full synchronization during the next run — 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.

After a successful sync, the server's configuration file gets updated so the next run can be done incrementally. If the config file has to be recreated (say it got lost 🙈), the next run recovers by doing a full synchronization. The risk there: the server might not recognize items that it already has stored previously, which then would lead to duplication of items.

⚙️ syncevolution --configure <options for configuration> <config> [<store> ...]

You can modify options in the configuration straight from the command line. The <config> and optional <store> parameters define what gets created or modified. The remaining parameters define which values get set or modified.

To change settings of specific datastores, either invoke syncevolution multiple times with exactly one <store> parameter, or use the [<store>/] prefix described above for property assignments. Pick your fighter. 💅

💥 syncevolution --remove <config>

Deletes the configuration. If <config> refers to a specific peer, only that peer's configuration is removed. If it refers to a context, then that context and all peers and datastores defined inside it get removed.

🚨 There is no confirmation question. And neither local data referenced by the configuration nor the content of log dirs are deleted. So it's deleting exactly what it says and nothing more, but it is NOT asking first. Be so serious.

🏃 syncevolution --run <options for run> <config> [<store> ...]

Options can also be overridden for just the current run, without changing the configuration. And to prevent you from accidentally running a sync session when you actually meant to change the configuration, either --configure or --run must be given explicitly if options are specified on the command line. It's a vibe check for your intent. ✨

🔍 syncevolution --status <config> [<store> ...]

Prints what changes were made locally since the last synchronization. This depends on access to database dumps from the last run, so enabling the logdir property is recommended. Receipts, bestie. 🧾

📋 syncevolution --print-servers|--print-configs|--print-peers

syncevolution --print-config [--quiet] <config> [main|<store> ...]
syncevolution --print-sessions [--quiet] <config>

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. main, on its own or in combination with datastores, lists only the main peer configuration.

♻️ syncevolution --restore <session directory> --before|--after

              [--dry-run] <config> <store> ...

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. 🧪

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.

A restore tries to minimize the number of item changes (see the section Item Changes and Data Changes). 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 --sync refresh-from-local in the next run. Fresh start, no baggage. 🦋

📦 Item data access

syncevolution --print-items <config> <store>
syncevolution [--delimiter <string>] --export <dir>|<file>|- [<config> [<store> [<luid> ...]]]
syncevolution [--delimiter <string>|none] --import <dir>|<file>|- [<config> <store>]
syncevolution --update <dir> <config> <store>
syncevolution [--delimiter <string>|none] --update <file>|- <config> <store> <luid> ...
syncevolution --delete-items <config> <store> (<luid> ... | *)

Restore depends on the specific format of the automatic backups created by SyncEvolution. Arbitrary access to item data is provided with these additional options. <luid> 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 --luids keyword.

<config> and <store> 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 backend property, like this:

syncevolution --print-items backend=evolution-contacts
syncevolution --export - backend=evolution-contacts \
              --luids pas-id-4E33F24300000006 pas-id-4E36DD7B00000007

The desired backend database can be chosen via database=<identifier>. See --print-databases. 🎀

✨ OPTIONS ✨

Okay bestie, here's the FULL rundown of every <options> that can go in front of the server name. Yes, all of them. Grab a snack. 💖

Whenever an option accepts multiple values, you can throw in a question mark ? to get the matching help text and/or a list of valid values. Chef's kiss — no cap. ✨

  • --sync|-s <mode>|? — Temporarily syncs the active datastores in that mode. It's giving very "clear everything on one side and copy it all over from the other," which is exactly what you want for a refresh-from-local or refresh-from-remote sync. Super useful, lowkey iconic.
⚠️ Warning: local is the data you get at via the sync config directly, and remote is the data sitting on the peer — regardless of where that data is actually stored physically. Don't let the names fool you, babe. 🙈
  • --print-servers|--print-configs|--print-peers — Prints the names of all your configured peers to stdout. There is no difference between these three options, they're just aliases. Same vibe, three names. 💅
  • --print-servers|--print-configs|--print-peers|-p — Yes bestie, the same alias names again (and now with -p) — read on, this one does something else. It prints the complete configuration for the selected <config> to stdout, including up-to-date comments for all properties. 🎀 The format is your normal .ini format, with datastore configurations living in different sections introduced by [<store>] lines. You can combine it with --sync-property and --datastore-property to modify the configuration on-the-fly. When one or more datastores are listed after the <config> name on the command line, only the configs of those datastores get printed. main selects the main configuration instead of datastore configurations. Using --quiet suppresses the comments for each property. And when you're setting a --template, the reference configuration for that peer is printed instead of an existing configuration. so many layers fr fr 🦋
  • --print-sessions — Prints info about previous synchronization sessions for the selected peer or context. This depends on the logdir property. 📂 The info includes the log directory name (super handy for --restore) and the synchronization report. In combination with --quiet, only the paths are listed. Clean and simple, periodt.
  • --configure|-c — Modifies the configuration files for the selected peer and/or datastores. ✍️

If no such configuration exists, a new one gets created using one of the template configurations (see the --template option). Choosing a template sets most of the relevant properties for the peer and the default set of datastores (there's a list of those above 👆). Anything specific to you (like username/password) still has to be set manually — the template can't read your mind, bestie. 😭

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. Like, syncevolution -c memotoo addressbook followed by syncevolution memotoo 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.

By default, creating a config requires a template. Datastore names on the command line must match those in the template. This catches your typos in the peer and datastore names (thank u honestly 🫶) — but it also prevents some advanced use cases. So you can disable these checks in two ways:

  • use --template none or
  • specify all required sync and datastore properties that are normally in the templates on the command line (syncURL, backend, ...)
  • --run|-r — This one exists to stop you from accidentally syncing when what you actually wanted was a configuration change but you forgot the --configure option. 😬 --run must be specified explicitly when sync or datastore properties are selected on the command line and they're meant to be used during a sync session triggered by the invocation. Think of it as the little "yes I'm sure" gate. 🔥
  • --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 <config> into <config>.old to prevent accidental use of the old configuration. 🧚
⚠️ WARNING: old SyncEvolution releases cannot use the new configuration!

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.

--migrate implies --configure and can be combined with modifying properties. 💜

  • --print-items — Shows all existing items, one line per item, using the format "<luid>[: <short description>]". Whether the description is available depends on the backend and the kind of data that it stores. 🌸
  • --export — Writes all items in the datastore, or all items whose <luid> is given, into a directory if the --export parameter exists and is a directory. The <luid> 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. ➖

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. ✨

When exporting, the default delimiter will always insert two line breaks regardless of 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. Obsessed with how clever that is tbh. 👑

  • --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. 🍓
  • --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. No mismatches allowed, bestie. 💀
  • --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 it 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. ⭐
  • --sync-property|-y <property>=<value>|<property>=?|? — 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. 🚨
  • --datastore-property|--source-property|-z <property>=<value>|<property>=?|? — Same as --sync-property, but it applies to the configuration of all active datastores. And --sync <mode> is a shortcut for --datastore-property sync=<mode>. Efficiency queen. 💅
  • --template|-l <peer name>|default|?<device> — Can be used to select from one of the built-in default configurations for known SyncML peers. Defaults to the <config> name, so --template only has to be specified when you're creating multiple different configurations for the same peer, or when you're using a template that's named differently than the peer. default is an alias for memotoo and can be used as the starting point for servers which do not have a built-in template. 🌈

A pseudo-random device ID is generated automatically. Therefore setting the deviceId sync property is only necessary when manually recreating a configuration, or when a more descriptive name is desired. 🎀

The available templates for different known SyncML servers get listed when you use a single question mark instead of a template name. When using the ?<device> 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 <device> = <Manufacturer> <Model>. If you don't 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 of how well the template matches the device (100% is best). ⭐

  • --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. Peek first, sync later. 👀
  • --quiet|-q — Suppresses most of the normal output during a synchronization. The log file still contains all the information, so nothing's actually lost. 🔕
  • --keyring[=<value>]|-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. 🔑💖
  • --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. 🧚
  • --help|-h — Prints usage information. Your lil rescue blanket. 🫶
  • --version — Prints the SyncEvolution version. 👑

💖 CONFIGURATION PROPERTIES 💖

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 --sync/datastore-property ? to get an up-to-date list. ✨

Same energy, bestie: the predefined properties can be read a little differently by each backend and sync protocol. Sometimes that's spelled out in the comment next to a property, sometimes it's buried over in the docs for the backend or the sync protocol. Each property shows up here alongside every alias it's ever been known by (because, yeah, some of them got renamed at some point, we've all been through rebrands 💅), plus its default value and its sharing state (unshared/shared/global). And some of them have to be set — those get the word required slapped on them, no skipping.

🔄 Sync properties 🔄

  • syncURL (no default, unshared, required) — this one's the whole "how do we even reach our peer" situation, and honestly it explains itself better with examples.

HTTP(S) SyncML servers, iconic behaviour:

http://example.com/sync

OBEX over Bluetooth goes by MAC address, and the channel gets picked automatically, no notes:

obex-bt://00:0A:94:03:F3:7E

If that automatism decides to flop, bestie you can just say the channel out loud:

obex-bt://00:0A:94:03:F3:7E+16

When peers are the ones hitting us over Bluetooth, the MAC address is what identifies them before the sync even starts. And yes, you can stack multiple urls in one syncURL property:

obex-bt://00:0A:94:03:F3:7E obex-bt://00:01:02:03:04:05

In the future this might get used to reach the peer over one of several transports — but rn? Only the first one gets tried. That's it. That's the whole vibe. 🦋

  • username (no default, unshared) — the user name used for authorization with the SyncML server.
  • password (no default, unshared) — the password used for authorization with the peer. You don't have to hardcode it as plain text either, bestie, it can be read from standard input or from an environment variable of your choice:
plain text  : password = <insert your password here>
ask         : password = -
env variable: password = ${<name of environment variable>}
  • logdir (no default, shared) — the full path to the directory where all automatic backups and logs get stored, for all synchronizations. If you leave it unset, then "${XDG_CACHE_HOME}/syncevolution/<server>" gets used instead (which usually expands to ${HOME}/.cache/..., iykyk). And if you set it to "none", then no backups of the databases are made at all and any output gets printed directly to the screen. 🎀
  • loglevel (0, unshared) — the 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
  • notifyLevel (3, unshared) — the level of detail for desktop notifications. Currently such notifications only get generated for automatically started sync sessions, so this is a niche queen:
    • 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
  • printChanges (TRUE, unshared) — enables or disables the detailed (and sometimes slow 😭) comparison of database content before and after a sync session.
  • dumpData (TRUE, unshared) — enables or disables the automatic backup of database content before and after a sync session (always enabled if printChanges is enabled, so don't try it).
  • maxlogdirs (10, shared) — controls how many session directories are kept at most in the logdir. Unless it's set to zero, SyncEvolution will remove old directories and all their content to stop the number of log directories from growing past the given limit. It tries to be intelligent about it 🧠 and will remove sessions where nothing interesting happened (no errors, no data changes) in favor of keeping the sessions where something did happen, even if those sessions are older. Respect the algorithm's priorities.
  • 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 gives you detailed control over which transports may be used for automatic synchronization:
    • 0 — don't do auto sync
    • 1 — do automatic sync, using whatever transport is available
    • http — only via HTTP transport
    • obex-bt — only via Bluetooth transport
    • http,obex-bt — pick one of these
  • autoSyncInterval (30M, unshared) — 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. Before you go 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, and you don't want to be that person. The value 0 has the effect of only running automatic synchronization when changes are detected (not implemented yet, therefore it basically disables automatic synchronization). 😭
  • 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. This prevents running a sync when network connectivity is unreliable or was recently established for some other purpose. It's also a heuristic that attempts to predict how long connectivity will be available in the future, because it should better be available long enough to complete the synchronization. Manifesting stable wifi fr fr 🌈
  • preventSlowSync (TRUE, unshared) — okay so 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 (the 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:
    • running as client with no local data => unproblematic, slow sync is allowed to proceed automatically
    • running as client with local data => client has no information about server, so slow sync might be problematic and is prevented
    • client has data, server asks for slow sync because all its data was deleted (done by Memotoo and Mobical, because they treat this as 'user wants to start from scratch') => the sync would recreate all the client's data, even if the user really wanted to have it deleted, therefore slow sync is prevented
  • 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.
  • proxyHost (no default, unshared) — proxy URL (http://<host>:<port>).
  • proxyUsername (no default, unshared) — authentication for proxy: username.
  • proxyPassword (no default, unshared) — proxy password, can be specified in different ways, see SyncML server password for details.
  • clientAuthType (md5, unshared)
    • empty or "md5" for secure method (recommended)
    • "basic" for insecure method

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. 🫶

  • 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. When acting as server, this setting controls how long a client is allowed to not send a message before the synchronization is aborted.
  • 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. Servers cannot resend messages, so this setting has no effect in that case. 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. Math girl summer 🔥
  • remoteIdentifier (no default, unshared) — the identifier sent to the remote peer for a server initiated sync. If not set, deviceId will be used instead.
  • PeerIsClient (FALSE, unshared) — indicates whether this configuration is about a client peer or server peer.
  • SyncMLVersion (no default, unshared) — on a client, the latest commonly supported SyncML version is used when contacting a server. One of '1.0/1.1/1.2' can be used to pick a specific version explicitly. 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.

Instead or in addition to the version, several keywords can be set in this property (separated by spaces or commas):

  • NOCTCAP - avoid sending CtCap meta information
  • NORESTART — turns OFF the sync mode extension that SyncEvolution client + server use to negotiate whether both sides can handle running multiple sync iterations inside the same session 💫
    • REQUESTMAXTIME=<time> — overrides how often the SyncML server sends preliminary replies while it's prepping local storages in the background. Why do we care? Because it helps dodge timeouts on the SyncML client side, bestie. Depends on multithreading btw. This particular SyncEvolution binary is thread-safe, so this feature is enabled by default for HTTP servers, with a delay of 2 minutes between messages. Other servers (Bluetooth, local sync) shouldn't need preliminary replies, so it's disabled there — although you can turn it on by setting the time explicitly. <time> gets specified like any other duration in the config, e.g. like REQUESTMAXTIME=2m. ⏱️
Setting these flags should only be necessary as a workaround for broken peers. Like, only reach for these if something else is being rude. 🙈
  • PeerName — (no default, unshared) — an arbitrary name for the peer this config points at. A GUI might use it. The command line tool always uses the configuration name instead, no cap.
  • deviceId — (no default, shared) — the SyncML server grabs this string and uses it to keep track of changes that still need syncing with this specific client. It must be set to something unique (like the pseudo-random string that gets created automatically for new configs) among all clients hitting the same server. Also myFUNAMBOL requires the string to start with sc-pim-. 👑
  • remoteDeviceId — (no default, unshared) — SyncML ID of our peer, empty if unknown. Only set this when the peer is a SyncML client contacting us via HTTP. Clients reaching us over OBEX/Bluetooth can be identified either by this remoteDeviceId property or by their MAC address, if that was set in the syncURL property.

And here's the cute part: if this property is empty and the peer syncs with this configuration because it was chosen some other way, then its ID gets recorded here automatically and later used to verify the configuration isn't accidentally being used by a different peer. Iconic behavior honestly. 🫶

  • enableWBXML — (TRUE, unshared) — use the more compact binary XML (WBXML) for messages between client and server. Not applicable when the peer is a SyncML client, because then the client picks the encoding. ✨
  • enableRefreshSync — (FALSE, unshared) — use the more advanced refresh-from-server sync mode to implement the refresh-from-remote operation. Some SyncML servers just don't support this, so the default is to delete local data before doing a slow sync, which has the same effect. But some servers work better when you explicitly tell them the sync is a refresh sync. Example: Funambol's One Media server rejects too many slow syncs in a row with a 417 'retry later' error. 💀
  • maxMsgSize — (150000, unshared) and maxObjSize — (4000000, unshared) — you can cap the maximum size of each message (maxMsgSize), and you can tell the peer to never send items bigger than a certain threshold (maxObjSize). Presumably the peer then has to truncate or skip the larger items 🤷 Sizes are specified as number of bytes.
  • SSLServerCertificates — (/etc/ssl/certs/ca-certificates.crt:/etc/pki/tls/certs/ca-bundle.crt:/usr/share/ssl/certs/ca-bundle.crt, unshared) — a string specifying where the certificates live that are used to authenticate the server. When it's empty, the system's default location gets searched.
Heads up: SSL support when acting as an HTTP server is implemented by the HTTP server frontend, not with these properties.
  • SSLVerifyServer — (TRUE, unshared) — the client refuses to establish the connection unless the server presents a valid certificate. Disabling this option considerably reduces the security of SSL (man-in-the-middle attacks become possible) and is not recommended. Please don't, bestie. 🚨
  • SSLVerifyHost — (TRUE, unshared) — the client refuses to establish the connection unless the server's certificate matches its host name. In cases where the certificate still seems valid, it might make sense to disable this option and allow such connections. 🌸
  • WebURL — (no default, unshared) — the URL of a web page with more info about the server. Used only by the GUI. 💅
  • IconURI — (no default, unshared) — the URI of an icon representing the server graphically. Should be a 48x48 pixmap or an SVG (preferred ✨). Used only by the GUI.
  • ConsumerReady — (FALSE, unshared) — set to true in a configuration template to indicate the server works well enough and is available for normal users. The GUI uses it to limit the choice of configurations offered to users. Has no effect in a user's server configuration. 🎀
  • peerType — (no default, unshared) — defines what a configuration is meant to be used for. Used in templates and the resulting configs to tell a GUI that special handling may be necessary. GUIs should ignore unknown types. The traditional SyncML configs use an empty value. "WebDAV" is used for the WebDAV side in a local synchronization.
  • defaultPeer — (no default, global) — the peer which is used by default in some frontends, like the sync-UI. ⭐
  • keyring — (yes, global) — explicitly selects a certain safe password storage. Depending on how SyncEvolution was compiled and installed, these values are possible:
    • GNOME — GNOME Keyring 🌈
    • KDE — KWallet
    • yes/true/1 — pick one automatically
    • no/false/0 — store passwords in SyncEvolution config files

If it's unset, the default is to pick one automatically if support for any kind of password storage was enabled, and use the config files otherwise. When choosing automatically, GNOME keyring is tried first, because distinguishing between KDE and GNOME sessions automatically is tricky. 😭

Note that using this option applies to all passwords in a configuration, and that the --keyring command line option is merely an alias for setting the global property. So setting a single password like this sets both keyring and proxyPasswords, and also moves the other passwords into the keyring, even if they weren't stored there already: text --keyring --configure proxyPassword=foo

When passwords were stored in a safe storage, their value is set to a single hyphen ("-") in the configuration. Which means: when running a synchronization without using the storage, the password has to be entered interactively. And the --print-config output always shows "-" instead of retrieving the password from the keyring. 💜

🗂️ Datastore properties 🗂️

  • sync — (disabled, unshared, required) — requests a certain synchronization mode when initiating a sync:
    • two-way — only send/receive changes since last sync
    • slow — exchange all items
    • refresh-from-remote — discard all local items and replace with the items on the peer
    • refresh-from-local — discard all items on the peer and replace with the local items
    • one-way-from-remote — transmit changes from peer
    • one-way-from-local — transmit local changes
    • local-cache-slow (server only) — mirror remote data locally, transferring all data
    • local-cache-incremental (server only) — mirror remote data locally, transferring only changes; falls back to local-cache-slow automatically if necessary
    • disabled (or none) — synchronization disabled

refresh/one-way-from-server/client are also supported. Their use is discouraged because the direction of the data transfer depends on the role of the local side (can be server or client), which is not always obvious. 🙈

When accepting a sync session in a SyncML server (HTTP server), only datastores with sync != disabled are made available to the client, which chooses the final sync mode based on its own configuration. When accepting a sync session in a SyncML client (local sync with the server contacting SyncEvolution on a device), the sync mode specified in the client is typically overriden by the server.

  • uri — (no default, unshared) — this gets appended to the server's URL to identify the server's database; if unset, the datastore name is used as fallback. 🍓
  • backend — (select backend, shared) — specifies the SyncEvolution backend and thus the data this datastore synchronizes. Each backend may support multiple databases (see the database property), different formats inside that database (see databaseFormat), and different formats when talking to the sync peer (see syncFormat and forceSyncFormat).

A special virtual backend combines several other datastores and presents them as one set of items to the peer. For example, Nokia phones typically exchange tasks and events as part of one set of calendar items. 📱

Right now such a virtual backend is limited to combining one calendar datastore with events and one task datastore. They have to be specified in the database property, typically like this: calendar,todo

Different datastores combined in one virtual datastore must have a common format. As with other backends, the preferred format can be influenced via the syncFormat attribute. ✨

Here's the full list of potentially supported backends, valid backend values for each of them, and possible formats. Note that SyncEvolution installations usually support only a subset of the backends — that's why e.g. "addressbook" is unambiguous even though there are multiple address book backends. 👑

  • syncFormat — (no default, unshared) — when there are alternative formats for the same data, each side of a sync offers all that it supports and marks one as preferred. If set, this property overrides the format that would normally be marked as preferred by a backend.

Valid values depend on the backend. Here are some examples:

  • contacts 💖
    • text/vcard = vCard 3.0 format
    • text/x-vcard = legacy vCard 2.1 format
    • calendar 💖
      • text/calendar = iCalendar 2.0 format
      • text/x-vcalendar = legacy vCalendar 1.0 format

Errors that happen while starting to sync and while parsing and/or storing items on either the client or the server can totally be caused by a mismatch between the sync format and the uri on the peer side. bestie, check both sides, fr fr. 😭

  • forceSyncFormat (FALSE, unshared) — okay so some peers get confused when you offer them multiple choices for the sync format, or they just pick the less optimal one 🙈. In that case, setting this property enforces that the preferred format you specified with syncFormat is really used. no vibes-based guessing allowed.
  • database = evolutionsource (no default, shared) — this one picks one of the backend's databases. Depending on the backend, you can set the name and/or a unique identifier. 💅

Most backends have a default database, like for example the system address book. If you don't set this property, you get that default database. easy.

If the backend is a virtual data datastore, this field must contain a comma separated list of the sub datasources actually used to store data. And if your sub datastore has a comma in its name, you must stop that comma from being mistaken as the separator by putting a backslash in front of it, like this:

database=Source1PartA\,PartB,Source2\\Backslash

To get a full list of available databases, run syncevolution --print-databases. The name is printed in front of the colon, followed by an identifier in brackets. Usually the name is unique and can be used to reference the data datastore ⭐. The default data datastore is marked with <default> at the end of the line, if there is a default.

  • databaseFormat (no default, shared) — defines the data format the backend uses for its own storage ✨. Typically backends only support one format and ignore this property, but for example the file backend uses it. See the backend property for more info. iykyk.
  • databaseUser = evolutionuser (no default, shared), databasePassword = evolutionpassword (no default, shared) — authentication for the backend data datastore; the password can be specified in multiple ways, see SyncML server password for details. 🫶
⚠️ Warning: setting database user/password when it's not needed — like, say, with local Evolution calendars and addressbooks — can cause the Evolution backend to hang. not the cute kind of hang either. 💀

✨ EXAMPLES ✨

List the known configuration templates:

syncevolution --template ?

Create a new configuration, using the existing Memotoo template:

syncevolution --configure \
              username=123456 \
              "password=!@#ABcd1234" \
              memotoo

Note that putting passwords into the command line, even for short-lived processes like the one above, is a security risk in shared environments, because the password is visible to everyone on the machine 😱. To avoid this, remove the password from the command above, then add the password to the right config.ini file with a text editor. This command shows the directory containing the file:

syncevolution --print-configs

Review configuration:

syncevolution --print-config memotoo

Synchronize all datastores:

syncevolution memotoo

Deactivate all datastores:

syncevolution --configure \
              sync=none \
              memotoo

Activate address book synchronization again, using the --sync shortcut:

syncevolution --configure \
              --sync two-way \
              memotoo addressbook

Change the password for a configuration:

syncevolution --configure \
              password=foo \
              memotoo

Set up another configuration for a different account, using the same default databases as above:

syncevolution --configure \
              username=joe \
              password=foo \
              --template memotoo \
              memotoo_joe

Set up another configuration using the same account, but different local databases (can be used to simulate synchronizing between two clients, see Exchanging Data):

syncevolution --configure \
              username=123456 \
              password=!@#ABcd1234" \
              sync=none \
              memotoo@other

syncevolution --configure \
              database=<name of other address book> \
              @other addressbook

syncevolution --configure \
              sync=two-way \
              memotoo@other addressbook

syncevolution memotoo
syncevolution memotoo@other

Migrate a configuration from the <= 0.7 format to the current one and/or update the configuration so that it looks like configurations created anew with the current syncevolution:

syncevolution --migrate memotoo

🌈 Synchronization beyond SyncML 🌈

In the simple examples above, SyncEvolution exchanges data with servers via the SyncML protocol. Starting with release 1.2, SyncEvolution also supports other protocols like CalDAV and CardDAV. slay, it's giving versatility 💅

These protocols are implemented in backends that behave like local datastores. SyncEvolution then synchronizes data between a pair of backends. And because the entire sync logic (matching of items, merging) is done locally by SyncEvolution, this mode of operation is called local sync ✨.

Some examples of things that can be done with local sync:

  • synchronize events with a CalDAV server and contacts with a CardDAV server 📅
  • mirror a local database as items in a directory, with format conversion and one-way or two-way data transfer (export vs. true syncing) 🦋

Because local sync involves two sides, two sync configurations are needed. One is called the target config. Traditionally, this really was a configuration called target-config, for example target-config@google. Using this particular name is no longer required.

The target config can hold properties which apply to all datastores inside its context, like user name, password and URL for the server (more on that below) and sync settings (like logging and data backups). Once configured, the target config can be used to list/import/export/update items via the SyncEvolution command line 📝. It cannot be used for synchronization, because it does not define what the items are supposed to be synchronized with. periodt.

For synchronization, a second originating config is needed. This config has the same role as the traditional SyncML sync configs and is typically defined in the same implicit @default context as those configs. All configs in that context use the same local data, thus turning that local data into the hub through which data flows to all peers that the host is configured to sync with. main character data energy, honestly 👑

A sync config becomes an originating config in a local sync by setting the syncURL to the special URL local://[<target config name>][@<some context name>]. This selects the target config to sync with. If the target config name is left out, the actual string target-config is used as the name. The context can be omitted if the target config name is unique. Originating and target config can be in the same context. Care must be taken to not use a datastore more than once in a local sync 🙈.

In addition, peerIsClient=1 must be set in the originating config, because SyncEvolution only supports running the SyncML client on the target side. It makes sense to use the local databases on the originating side, because that side requires more frequent access to the data.

The originating config defines the database pairs, either implicitly (by using the same datastore names on both sides, which is possible when different contexts are used) or explicitly (via the uri properties set for the datastores on the originating side). The originating config also defines the sync mode for each pair. uri and sync values on the target side are ignored and do not have to be specified.

As a special case, datastores used in combination with the target config may access the credentials and syncURL stored there as a fallback when nothing was specified for the datastores directly. This makes sense for the WebDAV and ActiveSync backends, where the credentials are typically the same and (depending on the web server) the same start URL can be used to find calendar and contact databases. 🎀

⚠️ Warning: when setting the password for the target config and using a keyring, a syncURL or a unique remoteDeviceID string must be set, because they are needed to identify the host in the keyring. 🔑

If this feature is not used, the syncURL could be left empty because local sync itself does not use it. However, the command line expects it to be set to none explicitly to detect typos. 👀

⚠️ Warning: because the client in the local sync starts the sync, preventSlowSync=0 must be set in the target config to have an effect.

CalDAV and CardDAV 🦋✨

okay so this bit is all about how to use local syncing for CalDAV and CardDAV. Both protocols are based on WebDAV (periodt) and are provided by the same backend, which is so efficient of them. They share the username/password/syncURL properties defined in their target config, so you set those once and you're golden. 💅

The credentials must be provided if the server is password protected, no cap. The syncURL is optional tho — but only if the username is an email address and the server supports auto-discovery of its CalDAV and/or CardDAV services (using DNS SRV entries, .well-known URIs, properties of the current principal, ...). iykyk 🧚

Alternatively, credentials can also be set in the databaseUser and databasePassword properties of the datastore. The downside? 😭 these values have to be set for each datastore and cannot be shared. The advantage? in combination with setting database, such datastores can be used as part of a normal SyncML server or client sync config. SyncEvolution then reads and writes data directly from the server and exchanges it via SyncML with the peer that is defined in the sync config. chef's kiss honestly. 🫶

The database property of each datastore can be set to the URL of a specific collection (= database in WebDAV terminology 💀). If it's not set, then the WebDAV backend first locates the server based on username or syncURL and then scans it for the default event resp. contact collection. This is done once in the initial synchronization. At the end of a successful synchronization, the automatic choice is made permanent by setting the database property. iconic behavior.

Warning 🚨 the protocols do not uniquely identify this default collection. The backend tries to make an educated guess, but it might pick the wrong one if the server provides more than one address book or calendar. It is safer to scan for collections manually with --print-databases and then use the URL of the desired collection as value of database. do NOT skip this bestie, fr fr.

To scan for collections, use:

syncevolution --print-databases \
              backend=<caldav or carddav> \
              username=<email address or user name> \
              "password=!@#ABcd1234" \
              syncURL=<base URL of server, if server auto-discovery is not supported>

Configuration templates for Google Calendar/Contacts, Yahoo Calendar and a generic CalDAV/CardDAV server are included in SyncEvolution. The Yahoo template also contains an entry for contact synchronization, but using it is not recommended due to known server-side issues (not us being dramatic, it's literally in there 💀).

The following commands set up synchronization with a generic WebDAV server that supports CalDAV, CardDAV and scanning starting at the root of the server:

# configure target config
syncevolution --configure \
              --template webdav \
              syncURL=http://example.com \
              username=123456 \
              "password=!@#ABcd1234" \
              target-config@webdav

# configure sync config
syncevolution --configure \
              --template SyncEvolution_Client \
              syncURL=local://@webdav \
              username= \
              password= \
              webdav \
              calendar addressbook

# initial slow sync
syncevolution --sync slow webdav

# incremental sync
syncevolution webdav

Here are some alternative ways of configuring the target config, because we love options:

# A) Server supports DNS auto-discovery via domain name in the username.
syncevolution --configure \
              --template webdav \
              username=123456@example.com \
              "password=!@#ABcd1234" \
              target-config@webdav

# B) Explicitly specify collections (from server documentation or --print-databases).
#    The 'calendar' and 'addressbook' names are the ones expected by the sync config
#    above, additional datastores can also be configured and/or the names can be changed.
syncevolution --configure \
              username=123456 \
              "password=!@#ABcd1234" \
              --template none \
              syncURL=http://example.com \
              addressbook/backend=carddav \
              addressbook/database=http://example.com/addressbooks/123456/ \
              calendar/backend=caldav \
              calendar/database=http://example.com/calendar/123456/ \
              target-config@webdav \
              calendar addressbook

When creating these target configs, the command line tool tries to verify that the datastores really work and (in the case of --template webdav) will enable only datastores which really work. This involves contacting the WebDAV server, so like, it's doing the most but for your own good. 💖

Finally, here is how the @webdav context needs to be configured so that SyncML clients or servers can be added to it:

# configure datastores
syncevolution --configure \
              databaseUser=123456 \
              "databasePassword=!@#ABcd1234" \
              addressbook/backend=carddav \
              addressbook/database=http://example.com/addressbooks/123456/ \
              calendar/backend=caldav \
              calendar/database=http://example.com/calendar/123456/ \
              @webdav \
              calendar addressbook

# configure one peer (Memotoo in this example):
syncevolution --configure \
              username=654321 \
              password=^749@2524 \
              memotoo@webdav

# sync
syncevolution --sync slow memotoo@webdav

Google + OAuth 🎀🔥

For Google there is no common start URL for CalDAV and CardDAV, therefore the "Google" template lists all that may be relevant and the setup is very similar to the generic webdav case, except that the syncURL does not have to be specified. thank u next, one less thing to type. 🙈

# configure target config
syncevolution --configure \
              --template google \
              username=john.doe@gmail.com \
              "password=!@#ABcd1234" \
              target-config@google

# configure sync config
syncevolution --configure \
              --template SyncEvolution_Client \
              syncURL=local://@google \
              username= \
              password= \
              google \
              calendar addressbook

# initial slow sync
syncevolution --sync slow google

# incremental sync
syncevolution google

If your Google account is configured to use two-factor login, then you need to create an application specific password for SyncEvolution. See https://support.google.com/mail/answer/1173270 ✨

Google already announced that they will turn off support for logging into their CalDAV/CardDAV services with plain username/password credentials. 😭 SyncEvolution supports the new login method, OAuth, but it depends on additional components to implement OAuth: GNOME Online Accounts, Ubuntu Online Accounts, or gSSO.

Support for GNOME Online Accounts (GOA) is compiled into syncevolution.org binaries and therefore documented here. For instructions regarding binaries shipped by distributions please consult the documentation provided by the distribution or search the web. 👑

For Google Calendar, GOA >= 3.8 is required. For Google Contacts, GOA 3.8 may work if it was patched by the distribution (as done in Debian Jessie), otherwise a version >= 3.10 is required. so like, check your version bestie, don't come for me. 💅

Use the GNOME Control Center to create an account for Google. It is not necessary to enable any of the data categories. That would turn on access in other GNOME apps (for example, Evolution), whereas SyncEvolution's use of the account is configured separately via the SyncEvolution command line. we keep it exclusive. 🦋

When configuring SyncEvolution for Google, follow the instructions above with username=goa:<Google email address> and empty password. If the email address does not uniquely identify the GOA account, the SyncEvolution command line will provide a list of accounts to choose from. cute, it's giving customer service. 🫶

💅 NOTES 💅

🫶 Exchanging Data 🫶

SyncEvolution sends address book entries as vCard 2.1 or vCard 3.0, and which one it picks depends on the sync format you chose in the configuration. Evolution uses 3.0 internally, so SyncEvolution converts between the two formats whenever it needs to. Calendar items and tasks can go out and come in as iCalendar 2.0 as well as vCalendar 1.0 — but bestie, please avoid vCalendar 1.0 if you can, because it literally cannot represent all the data Evolution stores. it's giving lossy 💀

Note: the Evolution backends are just the examples here — the exact same thing applies to other datastores too. ✨

How the server stores the items is entirely up to its implementation and its configuration. So to check which data actually survives the trip, you can run this procedure (written out for contacts, but it works the same way for calendars and tasks):

  1. synchronize the address book with the server
  2. create a new address book in Evolution and view it in Evolution once (this second step is necessary in at least Evolution 2.0.4 to make the new address book usable in SyncEvolution)
  3. add a configuration for that second address book and the same URI on the SyncML server, see EXAMPLES above
  4. synchronize again, this time using the other datastore

Now you can either eyeball-compare the address books in Evolution, or have it done for you automatically — here's how, described for contacts:

  • save the complete address books: mark all entries, save as vCard
  • invoke synccompare with two file names as arguments and it will normalize and compare them automatically

Normalizing is necessary because the order of cards and their properties, plus other minor formatting aspects, may differ. The output comes from a side-by-side comparison, but the script augments it so that the context of each change is always the complete item that got modified. Lines or items following a > on the right side were added, those on the left side followed by a < were removed, and those with a | between text on the left and right side were modified. iykyk 🌈

The automatic unit testing (see HACKING) contains a testItems test which verifies the copying of special entries using the same method. 👑

Modifying one of the address books — or even both at the same time — and then synchronizing back and forth is a great way to verify that SyncEvolution works as expected. But if you don't trust SyncEvolution or the server, then it is prudent to run these checks with a copy of the original address book. Make a backup of the .evolution/addressbook directory. seriously, do it. 🫶

🌸 Item Changes and Data Changes 🌸

SyncML clients and servers treat each entry in a database as one item. Items can be added, removed, or updated. That's the item change information that client and server exchange during a normal, incremental synchronization.

Now here's the tea 🍓: if an item is saved, removed locally, and then reimported, this usually gets reported to a peer as "one item removed, one added" — because the info SyncEvolution has available is not sufficient to determine that it's actually the same item. There's one exception: iCalendar 2.0 items, with their globally unique ID. For those, the modification above gets reported to the server as "one item updated".

That's better, but still not quite correct, because the content of the item hasn't changed — only the meta information about it that's used to detect changes. And there's no avoiding that without adding extra overhead to normal synchronizations. 🙈

SyncEvolution reports item changes (the number of added, removed, and updated items) as well as data changes. Those data changes are calculated by comparing database dumps using the synccompare tool. Because this data comparison ignores information about which data belongs to which item, it's able to detect that re-adding an item that was removed earlier doesn't change the data — unlike the item changes. On the flip side, removing one item and adding a different one may look like updating just one item. balance ✨

🎀 Automatic Backups and Logging 🎀

To support recovery from a synchronization that damaged your local data or modified it in a way you did not expect, SyncEvolution can create the following files during a synchronization:

  • a dump of the data in a format which can be restored by SyncEvolution, usually a single file per item containing in a standard text format (VCARD/VCALENDAR)
  • a full log file with debug information
  • another dump of the data after the synchronization, for automatic comparison of the before/after state with synccompare

If the sync configuration property logdir is set, then a new directory gets created for each synchronization inside that directory, using the format:

<peer>-<yyyy>-<mm>-<dd>-<hh>-<mm>[-<seq>]

with the various fields filled in with the time when the synchronization started. The sequence suffix is only used when necessary to make the name unique. By default, SyncEvolution will never delete any data in that log directory unless you explicitly ask it to keep only a limited number of previous log directories. 👑

You do that by setting the maxlogdirs limit to something different than the empty string and 0. If a limit is set, then SyncEvolution only keeps that many log directories and starts removing the "less interesting" ones when it hits the limit. Less interesting = those where no data changed and no error occurred. bye felicia 💅

To avoid writing any additional log file or database dumps during a synchronization, logdir can be set to none. To reduce the verbosity of the log, set loglevel. If it's not set or 0, then the verbosity is set to 3 = DEBUG when writing to a log file, and 2 = INFO when writing to the console directly. And if you're debugging issues involving data conversion: level 4 also dumps the content of items into the log. 🔥

🌈 ENVIRONMENT 🌈

The following environment variables control where SyncEvolution finds files and other aspects of its operations. ✨

  • http_proxy — Overrides the proxy settings temporarily. Setting it to an empty value disables the normal proxy settings.
  • HOME/XDG_CACHE_HOME/XDG_CONFIG_HOME — SyncEvolution follows the XDG <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html> desktop standard for its files. By default, $HOME/.config/syncevolution is the location for configuration files. $HOME/.cache/syncevolution holds session directories with log files and database dumps.
  • SYNCEVOLUTION_DEBUG — Setting this to any value disables the filtering of stdout and stderr that SyncEvolution employs to keep noise from system libraries out of the command line output.
  • SYNCEVOLUTION_GNUTLS_DEBUG — Enables additional debugging output when using the libsoup HTTP transport library.
  • SYNCEVOLUTION_DATA_DIR — Overrides the default path to the bluetooth device lookup table, normally /usr/lib/syncevolution/.
  • SYNCEVOLUTION_BACKEND_DIR — Overrides the default path to plugins, normally /usr/lib/syncevolution/backends.
  • SYNCEVOLUTION_LIBEXEC_DIR — Overrides the path where additional helper executables are found, normally /usr/libexec.
  • SYNCEVOLUTION_LOCALE_DIR — Overrides the path to directories with the different translations, normally /usr/share/locale.
  • SYNCEVOLUTION_TEMPLATE_DIR — Overrides the default path to template files, normally /usr/share/syncevolution/templates.
  • SYNCEVOLUTION_XML_CONFIG_DIR — Overrides the default path to the Synthesis XML configuration files, normally /usr/share/syncevolution/xml. These files are merged into one configuration each time the Synthesis SyncML engine is started as part of a sync session.
Note that in addition to this directory, SyncEvolution also always searches for configuration files inside $HOME/.config/syncevolution-xml. Files with the same relative path and name as in /usr/share/syncevolution/xml override those files, others extend the final configuration. 🦋

💀 BUGS 💀

See known issues <http://syncevolution.org/documentation/known-issues> and the support <http://syncevolution.org/support> web page for more information. (they're not hiding anything, fr fr 🫶)

⭐ SEE ALSO ⭐

<http://syncevolution.org>

👑 AUTHORS 👑

and that's the whole page bestie, we ate and left no crumbs 💅✨ this one's from SyncEvolution 2.0.0, dated Apr 28, 2010, and it's the SyncEvolution(1) manual page — go sync something gorgeous 🌸🦋🎀

📦 where this page comes from