SYNC MAIL DIR
=============

Sync Mail Dir (`smd`) is a set of tools to synchronize a pair of mailboxes
in Maildir format. It is Free Software, released under the terms of GPLv3.

It differs from other solutions in terms of performances and lower
installation requirements. The widespread solution IMAP-server plus
[OfflineIMAP](http://software.complete.org/software/projects/show/offlineimap)
requires an IMAP server to be installed. Alternatively
[Maildirsync](http://hacks.dlux.hu/maildirsync/) requires no IMAP server,
just ssh, but it used to load my laptop CPU too much and it seems its
development stopped in 2004.  Other general purpose tools like rsync or
unison may work too, but not benefit from the fact that they are
synchronizing mail messages. Sync Mail Dir is similar to Maildirsync in its
design and requirements, but is more efficient, having its mechanisms
written in C (around 700 lines), while policies are written in scripting
languages (other 700 lines).

Overview
--------

Sync Mail Dir uses `ssh` to transmit and receive data, and to run commands
on the remote host (but in principle it could use any bi-directional
channel, like `nc` for example).

Sync Mail Dir needs to be installed on both hosts: we call server the host
we push to and pull from, we call client the host we push from and pull to.
In the most common scenario, the server is our mail server, while the
client is our laptop.

The directory `~/.smd/` contains the configuration file(s), some `fifo` needed
to short-circuit the softwares running on the client and on the server, and
a cache file (called db-file from now on) that represents the status of the
mailbox las time we successfully pushed. The configuration file is needed
only on the client host (the one that will run `smd-pull` and `smd-push`).

Sync Mail Dir is a layered set of tools, where low level tools are
implemented in low level languages (to achieve decent performances) and
high level tools are written in scripting languages (to achieve better
flexibility). 

- `mddiff` is a small and hopefully efficient C program that given a
  db-file (a snapshot of a previous mailbox status) generates a set of
  actions (a diff) a client should perform to synchronize its local mailbox
  copy. It is a low level tool, not meant to be used directly by the user.
- `smd-server` a simple script that calls `mddiff` to compute the diff,
  sends it to the client and then listen for client requests like getting a
  mail body or header. Even if this tool is simple to run, redirecting its
  input and output to `smd-client` over a network may not be straightforward,
  thus users should not call it directly.
- `smd-client` a quite complex script applying a diff locally, eventually
  requesting data to the server. In case the diff cannot be applied
  cleanly, it outputs an error message that higher level tools should display
  to the user. As `smd-server` it is a quite high level tool, but should not
  be called directly by the average user.
- `smd-pull` thanks to ssh, it executes `smd-server` on the server host and
  `smd-client` on the client host. This allows to pull remote changes and
  apply them locally.  The remote mailbox is left untouched. This tool is
  meant to be called by the user.
- `smd-push` thanks to ssh, it executes `smd-client` on the server host and
  `smd-serer` on the client host. This allows to push local changes to
  apply them on the remote host.  The local mailbox is left untouched. This
  tool is meant to be called by the user.

HOW-TO
------

Till now, two end-user tools are available (more will be added in the
future, possibly equipped with an eye-candy notification icon for modern
desktops):

- `smd-pull [name]` to obtain the changes made on the remote mailbox applied
  locally
- `smd-push [name]` vice versa

Both tools read a configuration file in `~/.smd/config.name`, that is a simple
shell script sourced by both when called with argument `name`. If no argument
is given, they source `~/.smd/config.default`.
This file defines the following variables:

- `SERVERNAME` is a valid alias for ssh. It should be defined in 
  your `~/.ssh/config`, with compression enabled. For example:

    Host smd-server-foo
      Compression yes
      Hostname your.real.server.name
      Username you

- `CLIENTNAME` a name for your client: the host name concatenated with
   the server name should be fine. Note that you can pull and push from
   different hosts, and each of them needs a unique CLIENTNAME in its
   configuration file.

- `MAILBOX` a list of roots to be synchronized. There is no support for
  name mapping, thus they should be named the same on the remote host.

- `DEBUG` can be set to true to log the traffic between client and server

The first time you run `smd-pull` or `smd-push` a template file will be 
generated for you. 

Notes on performances
---------------------

On my core duo 2 laptop equipped with a 5400rpm hard drive and with an hot
cache, copying a 150MB mailbox with `tar cf - Mail | ssh -C localhost tar
xf -` takes 17 seconds. Doing the same with `smd-pull` takes 19 seconds.
This is clearly an uncommon workload, since you rarely get 150MB of new
mails, but it shows the extra work the tool is doing (like calculating
`sha1` sums for every mail, or the client-server protocol overhead) makes
`smd` not so inefficient.  Once the mailbox has been copied, running
`smd-pull` again to check for updates is almost instantaneous.

Advanced Usage
==============

From verion `0.9.4` multiple configuration files are supported. This means
you can push/pull from/to different remote mailboxes (one at a time). This
proved to be useful when migrating a mailbox:

    smd-pull oldserver
    smd-push newserver

Note that you can run this for a while, not just one time. This can smooth
the transition from a mail-address to another, since simply forwarding mail
from the old to the new one makes you believe you changed the subscription
to all your mailling lists, that is obviously not always the case since
nobody remembers all the mailing lists he is subscribed to.

Design
======

The design of the software is detailed in the [design document](design.html).
If you are interested in hacking `smd`, it may be helpful.

Download
========

The software can be download from the Source Forge 
[download page](http://sourceforge.net/project/showfiles.php?group_id=259152)

Author
======

The software is distributed as-is, with no warranties, so if your mailbox 
is irremediably lost due to Sync Mail Dir, you will get nothing back, but
you can complain with me, of course. If you find the software useful, 
an happy-user report is also welcome. For patches, bug-reports, etc. refer to
Enrico Tassi, gareuselesinge at users dot sourceforge dot net.

...to be finished for version 1.0

