By Jove, I do think I've got it. The full howto is below.

 

If you’re getting into SyncEvolution (hereafter SE), there are a few concepts that are crucial to understand. As SE is at heart a SyncML synchronization engine, the simplest case describes everything in terms of SE as a SyncML client, talking to a remote SyncML server.

• Contexts. Contexts mainly group data stores, client endpoints and server endpoints together; each of these always lives in exactly one context.
• Data stores, or stores for short. In the existing SE parlance these are called sources or data sources. You can think of a data store as you would of an individual database, with a single table. The table can store items of exactly one kind (in the case of SE: events, memos, contacts or tasks), and the data store configuration holds all information required to access that database. Specifically, you will at least need to set up the first two properties for a data store, and optionally more, depending on the backend selected:
  • backend, which specifies the storage ‘engine’
  • database: a specification of where the database can be found. It needs to be fully specified, but its format depends on the backend. The ‘file’ backend will take full paths to a directory, for example (in url format), the carddav backend requires the carddav url for the carddav server
  • dataFormat, in case the storage engine is capable of implementing more than one kind of ‘table’. The ‘file’ backend, for example, can be used to store either contacts or events. The carddav backend can only store contacts, so for this engine the only possible format is implied
  • databaseUser, databasePassword: credentials to access the database, if required. Obviously not necessary for the ‘file’ backend, but in some instances, the credentials can be provided by a different path – more on that later.
• Client Endpoints, or sync configs in the existing SE parlance. These describe an SyncML client, implemented in SE. To set up a client endpoint, you provide the following properties:
  • username, password: credentials to access the remote SyncML server
  • syncURL: URL of the remote SyncML server
• Synced stores. Synced stores specify which data stores within the same context a client endpoint wants to sync with the SyncML server above. a client endpoint on its own can’t do anything since it doesn’t know what needs to be synced; you can tie these together by specifying the desired client endpoint and data store, and then specifying how you want to sync that data store with the remote server
  • two-way: only send/receive changes since last sync
  • slow: two-way, 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
  • disabled (or none): synchronization disabled

So if I want to set up a file-based datastore called ‘local-contacts’, and a file-based datastore called ‘local-calendar, which I want to sync with a remote Horde SyncML server at https://horde.example.com/rpc.php, I would do the following

syncevolution –configure –template none backend=file database=”file:///tmp/my-contacts-store” databaseformat=text/vcard @Local local-contacts

This means: in context ‘@Local’ (contexts are created whenever they’re referenced), create (or update) a datastore ‘local-contacts’ (SE knows that we’re configuring a data store because we are passing it properties that are relevant to data stores), and on that datastore set the following properties: backend, database and databaseFormat.

Likewise, I set up my calendar data store:

syncevolution –configure –template none backend=file database=”file:///tmp/my-calendar-store” databaseformat=text/calendar @Local local-calendar

Next, I need to set up my client endpoint so I can specify the server to sync with:

syncevolution –configure –template none syncURL=https://horde.example.com/rpc.php username=<your Horde username> password= <your Horde password> Horde@Local local-calendar local-contacts

Which tells SE that I want to set up a client endpoint (implied by the syncURL property being set) named ‘Horde’ (if you’re setting a client endpoint property, the first name on the command line is the client endpoint) in context @Local, and that you want to sync the two data stores ‘local-calendar’ and ‘local-contacts’ using that endpoint (also in context @Local).

Then we still need to tell SE which direction we want to sync these, so we set up synced stores for these:

syncevolution –configure sync=two-way Horde@Local local-calendar

syncevolution –configure sync=two-way Horde@Local local-contacts

Which means ‘if I sync client endpoint Horde from context @Local, offer data store local-calendar/local-contacts to the remote server for two-way sync’. Now we should be all set to sync. The first time, it is required to do a slow sync:

syncevolution –sync slow Horde@Local

Which will sync all synced stores for this endpoint. After this first time, you can do an incremental (much faster) sync with

syncevolution Horde@Local

Synchronization beyond SyncML

But synchronizing between a remote SyncML server and a local file-based store (or a local evolution data store – hence the name) is not all that SE can do. It can also synchronize with ‘server-based’ data stores, such as Exchange (through activesync, aka EAS) or WebDAV-based servers that implement the CalDAV and/or CardDAV protocols.

EAS and WebDAV are not considered sync engine technologies within the scope of SE, but data storage engines. While it would be in principle possible to set up a pair of server-based backends, for simplicity and debuggability, we set up a hub-and-spoke system with the hub a simple backend such as the ‘file’ or ‘eds’ backends. The hub will be SE as a syncml client, as described above. We shall leave the setup from the first section in place, but add an Exchange server (which understands both contacts and calendars) to sync our data stores with.

Since SE really only speaks SyncML for synchronization, we need a SyncML ‘server front’ for EAS and WebDAV servers to talk to. Fortunately, SE itself implements such a faux SyncML server.

SE implements this faux server in what it calls a ‘target config’, and which I’ll call a ‘Faux Server Endpoint’ (FSE) here. The FSE must always be named ‘target-config’, so ‘target-config’ might seem the best way to go for naming, but I want to distinguish between the concept of the FSE, and any particular FSE, which must have the name ‘target-config’.

The FSE (conceptually) awaits an incoming connection from the SE client endpoint set up above. This incoming server must know what data stores it has available, so we set it up with some synced stores – in this case, EAS-based stores.

Exchange activesync

EAS based stores take a little more tending to than file-based stores, but nothing beyond some mild head-against-concrete bashing. For EAS, you will need to have activesyncd installed in addition to syncevolution, and you’ll need to store some configuration data outside SE where activesyncd can find it: your username/password on the server, and the activesync URL. These can be set up as follows:

gconftool-2 –set –type=string “/apps/activesyncd/accounts/<your exchange email address>/username” <your username, including domain>

gconftool-2 –set –type=string “/apps/activesyncd/accounts/<your exchange email address>/password” <your password>

gconftool-2 –set –type=string “/apps/activesyncd/accounts/<your exchange email address>/serverUri” <your exchange activesync URL>

The EAS URL will usually look something like ‘https://owa.example.com/Microsoft-Server-ActiveSync’; if you don’t know it, head over to https://testconnectivity.microsoft.com/, select tab ‘Exchange Server’, option ‘Automatic detection of Exchange ActiveSync’ and let it discover the settings; in the resulting page, expand everything, and search for <Name>; in it will be the full EAS url.

After we’ve set up the credentials, we can go back to SE. First the contacts data store:

syncevolution –configure –template none backend=eas-contacts database=<contacts folder name> @Exchange exchange-contacts

This means: in context ‘@Exchange’, create a datastore ‘exchange-contacts’ (SE again knows that we’re configuring a data store because we are passing it properties that are relevant to data stores), and on that datastore set the following properties: backend, database. In this case, we do not need to set up databaseFormat, since the backend ‘eas-contacts’ can only store contacts. The database in this case is a little different than the file stores we set up above, since it is not a full specification of where to find your EAS contacts; it is instead resolved from at the moment SE logs on, and the information is specified later. We will get back to this in a bit. The name of your contacts folder can be seen in Outlook, or you can list the available folders using SE:

syncevolution –print-databases username=<your exchange email address> backend=eas-contacts

and likewise, for your calendars, which we’ll need in a bit:

syncevolution –print-databases username=<your exchange email address> backend=eas-events

In the same way, we set up our calendar store:

syncevolution –configure –template none backend=eas-events database=<calendar folder name> @Exchange exchange-calendar

At this point we have two data stores in the @Exchange context, named ‘exchange-contacts’ and ‘exchange-calendar’, but we still need to set up the corresponding synced stores:

So now we set up the actual FSE. Notice the name: it must be ‘target-config’

syncevolution –configure –template none username=<your exchange email address> password= printChanges=1 target-config@Exchange

We don’t need to set a password, since we’ve already handed that to activesyncd, but SE does need to know which activesyncd user to use, so <your exchange email address> is passed as a matching key; hence the <your exchange email address> in the gconftool-2 invocations. It is here where the ‘database’ property from the data store becomes fully meaningful in combination with the data we stuffed into activesyncd; there is no meaningful direct URL to any Exchange folder when it comes to activesync.

Now we still need to tell SE which data stores can be synced through the FSE. These are specified as synced stores much like we did before:

syncevolution –configure sync=none target-config@Exchange exchange-contacts

syncevolution –configure sync=none target-config@Exchange exchange-calendar

Which means ‘if I am contacted for sync in context @Exchange, I have data stores exchange-calendar/exchange-contacts in context @Exhange available for sync’. We’re setting sync=none here only to trigger the creating of a synced store. We could have used any value for ‘sync’, as its value is ignored; the ‘sync’ value of the client side will take precedence.

Giving the FSE something to do

Next, we set up the available stores for the FSE:

syncevolution –configure sync=none target-config@Exchange exchange-contacts

syncevolution –configure sync=none target-config@Exchange exchange-calendar

Which means 'if I am contacted for sync in context @Exchange, I have data stores exchange-calendar/exchange-contacts in
context @Exhange available for sync'.

We're setting sync=none here only to trigger the creating of a synced store. We could have used any value for 'sync', as
its value is ignored; the 'sync' value of the client side will take precedence.

Connecting with the FSE

Now that we have our FSE(s) set up, it’s time to tie them together with our data stores that we set up in the @Local context. For this, we’ll need to create a new client endpoint, and with it, the required synced stores. First the client endpoint:

syncevolution –configure syncUrl=local://@Exchange peerIsClient=1 ExchangeEP@Local

which means: create client endpoint ‘ExchangeEP’ in context @Local, and give it syncURL ‘local://@Exchange’. I could have named my client endpoint ‘Exchange’ without any problem (and it would indeed be common practice to do it this way), but I want to distinguish between these two different things (context and client endpoint) explicitly for the moment. As for the peerIsClient – it is just required at this point. The URL is special, and we will get to that in a bit. Next, some synced stores:

syncevolution –configure sync=two-way uri=exchange-contacts ExchangeEP@Local local-contacts

syncevolution –configure sync=two-way uri=exchange-calendar ExchangeEP@Local local-calendar

Which means: When I sync ExchangeEP@Local, perform a two-way sync between local-contacts from context @Local with exchange-contacts from context @Exchange; we know this exchange-contacts lives in @Exchange because the syncURL from ExchangeEP (local://@Exchange) tells us that we’re syncing with an FSE in that context. Likewise perform a two-way sync between local-calendar from context @Local with exchange-calendar from context @Exchange.

And Syncing with the FSE

And that was all she wrote. Just like the simple example, we must first perform a slow sync

syncevolution –sync slow ExchangeEP@Local

Which will sync all synced stores for this endpoint. After this first time, you can do an incremental (much faster) sync with

syncevolution ExchangeEP@Local

And that, was that.