I've rebuilt my howto using the existing terminology, making only two
changes:
1. I've used 'datastore' in place of 'data source'
2. I've used 'store-access' instead of 'unshared' for per-peer-source
properties.
Other than that, the howto does without the explanation using the syncml
heritage, using only the minimal amount of concepts to get sync with EAS
going. The purpose of this HOWTO is not to explain all concepts and all
possibilities of SyncEvolution, and so it omits many of them; its
purpose is to provide an understanding of how SynceEvolution works,
broadly, so that can be used as a springboard to understand more complex
concepts and use-cases (which I will describe in separate documents,
probably re-writing existing howto's as I am doing so).
The updated document can be found at
http://reichenhack.github.io/syncevolution.html, the full text is pasted
below:
If you're getting into SyncEvolution, there are a few concepts that are
crucial to understand.
hostThe device or computer that SyncEvolution runs on.peerA peer is one
of the counterparts in a data exchange. This can be a device (like a
phone), a server (like Google) or even the host itself (useful for
synchronizing two different databases).datastoreEach peer hosts one or
more datastores holding either memos, events, contacts or tasks) that
can be synchronized (Google for example offers Calendar and Contacts).
This used to be called a source config ordata source, and you will still
see many documents referring to it by one of these terms.backendA
datastore is implemented by a SyncEvolution backend. The backend
describes what storage technology is used for that datastore; it does
not specify where that datastore lives. Some backends provide access to
data outside of the host itself (CalDAV and CardDAV,
ActiveSync).sync-configA sync-config defines a peer, implemented by
SyncEvolution. A sync-config combines information about the peer and the
datastores it can access, and provides a full specification of how those
database are to be accessed during sync; how to locate the database,
credentials to be used, etc.contextSync-configs and datastores are
defined inside an configuration context which bundles them together.
Sync-configs can only access datastores that are defined in the same
context as the sync-config. There is always a default context that is
used if none is specified explicitly.
Let's set up a simple sync using just these concepts. As SyncEvolution
is at heart a SyncML synchronization engine, the simplest case describes
everything in terms of SyncEvolution as a SyncML client, talking to a
remote SyncML server.
I will 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.
First, I set up the datastore for my contacts. Each datastore and
sync-config must live in a context, in this case, as this data lives on
my own PC, I call that context local:
syncevolution --configure --template none backend=file
database="file:///tmp/my-contacts-store" databaseformat=text/vcard
@local local-contacts
This means: on datastore local-contacts in context local, set the
following properties: backend, database and databaseFormat.
I did not explicitly create the datastore or the contexts; both are
created when first referenced, and updated if they already exist. I also
did not explicitly tell SyncEvolution that we're setting up a datastore
(rather than a sync-config, which we'll set up with a similar command);
SyncEvolution knows that we're configuring a datastore because we are
passing it properties that are relevant to datastores.
Likewise, I set up my calendar datastore:
syncevolution --configure --template none backend=file
database="file:///tmp/my-calendar-store" databaseformat=text/calendar
@Local local-calendar
Next, I need to set up the local peer which will contact the remote
SyncML server later by setting up a sync-config. This sync-config
specifies, for example, the location of 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 SyncEvolution that I want to set up a sync-config (implied
by the syncURL property being set) named Horde in context local, and
that I want to sync the two datastores local-calendar and local-contacts
using that sync-config.
If you're setting up a sync-config, the first non-assignment on the
command line is the name of the sync-config and the context in which it
is to be created (Horde@local); all following non-assignments
(local-calendar, local-contacts) are the datastores it will synchronize.
SyncEvolution knows these must live in the local context, as
sync-configs can only access datastores in its own context.
We still need to tell SyncEvolution which direction we want to sync
these datastores, so we set store-access ("unshared") properties on the
sync-config:
syncevolution --configure sync=two-way Horde@Local local-calendar
syncevolution --configure sync=two-way Horde@Local local-contacts
Which means "if I start a sync using sync-config Horde from context
local, offer datastore local-calendar/local-contacts to the remote
server, each 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 data-stores that have been tied to this sync-config
using store-access properties. After this first time, you can do an
incremental (much faster) sync with
syncevolution Horde@Local
Synchronization beyond SyncML
Synchronizing between a remote SyncML server and a local file-based
store (or a local evolution datastore -- hence the name SyncEvolution)
is not all that SyncEvolution can do. It can also synchronize with
"server-based" datastores, 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 SyncEvolution, but data storage engines. While it would be in
principle possible to pair up 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 SyncEvolution
sync-config set up like the scenario 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 datastores with.
Since SyncEvolution doesn't consider EAS to be a sync peer but a
datastore, we will need to set up a peer through which we can access
EAS. Such a peer is called a target-config in SyncEvolution terms. We
set up this peer by setting up a sync-config; this sync-config must be
called target-config for SyncEvolution to recognize it as such.
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 SyncEvolution
where activesyncd can find it: your username/password for the EAS
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 this up, we can go back to SyncEvolution. First we
configure the contacts datastore:
syncevolution --configure --template none backend=eas-contacts
database=<contacts folder name> @Exchange exchange-contacts
This means: in context exchange, create a datastore exchange-contacts
(SyncEvolution again knows that we're configuring a datastore because we
are passing it properties that are relevant to datastores), 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 SyncEvolution logs on. The name of your contacts
folder can be seen in Outlook, or you can list the available folders
using SyncEvolution:
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
We set up our EAS calendar store in the same way:
syncevolution --configure --template none backend=eas-events
database=<calendar folder name> @Exchange exchange-calendar
At this point we have two datastores in the exchange context, named
exchange-contacts and exchange-calendar, but we still need to set up the
peer by setting up a sync-config, which, as noted before, must be named
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 SyncEvolution 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 datastore 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. In principle this could have been handled with
databaseUser and databasePassword, but as activesyncd is a different
software component, this probably got complex quickly.
Giving the target-config something to talk about
Now we still need to tell SyncEvolution which datastores can be synced
through the target-config. These are specified as store-access
properties 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 peer target-config in context exchange is synced, it has
datastores exchange-calendar/exchange-contacts available"
We're setting sync=none here because it is a store-access property,
which has the side effect of setting up store-access for the
target-config. We could have used any value for sync, as its value is
ignored; the sync value of the peer for the target-config takes
precedence.
Pairing the peers
Now that we have our target-config set up, it's time to pair it up with
a sync-config in the local context. For this, we'll need to create a new
sync-config, and with it, the required store-access properties. First
the sync-config.
syncevolution --configure syncUrl=local://@exchange peerIsClient=1
ExchangeSync@local
which means: create sync-config ExchangeSync 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), just as I didn't have to use exchange-calendar or
local-calendar but could have just used calendar for both (as they live
in different contexts), but I want to distinguish between these two
different things (context and sync-config) explicitly for clarity. 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, store-access for the
peer:
syncevolution --configure sync=two-way uri=exchange-contacts
ExchangeSync@local local-contacts
syncevolution --configure sync=two-way uri=exchange-calendar
ExchangeSync@local local-calendar
Which means: When I sync ExchangeSync@local, perform a two-way sync
between local-contacts from context local with exchange-contacts from
context exchange; we know exchange-contacts lives in context exchange
because the syncURL from ExchangeSync (local://@Exchange) tells us that
we're syncing with the target-config in that context. Likewise, perform
a two-way sync between local-calendar from context local with
exchange-calendar from context exchange.
Finally, the sync
And that was all she wrote. Just like the simple example, we must first
perform a slow sync
syncevolution --sync slow ExchangeSync@local
Which will sync all datastores associated with ExchangeSync@local. After
this first time, you can do an incremental (much faster) sync with
syncevolution ExchangeSync@local
And that, was that.
_______________________________________________
SyncEvolution mailing list
[email protected]
https://lists.syncevolution.org/mailman/listinfo/syncevolution
