Fetching latest commit…
Cannot retrieve the latest commit at this time
|Failed to load latest commit information.|
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 like Lua and shell script (other 900 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 last 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 and to apply them on the remote host. The local mailbox is left untouched. This tool is meant to be called by the user. - `smd-loop` runs runs smd-push and smd-pull at regular intervals as defined by the user in a configuration file, in the style of a crontab, but catches recoverable errors (like a, non recurrent, network problem), bailing out only in cases where human intervention is needed. This is the utility you may want to run if you are using a textual environment or a graphical one not based on GNOME. - `smd-applet` is an applet for the GNOME notification area, that runs `smd-loop`, eventually notifying the user for critical events and allowing him to solve them clicking on buttons instead of running commands from the shell. HOW-TO ------ Four end-user tools are provided. You need to configure them bottom-up, starting from the simpler ones (`smd-pull` and `smd-push`), that already allow to synchronize two mailboxes. Anyway it is recommended to use higher level tools like `smd-loop` or `smd-applet`. ### smd-push and smd-pull - `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. Maildirs will be searched starting from these roots, traversing subdirectories recursively. - `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. ### smd-loop `smd-loop` runs `smd-push` and `smd-pull` at regular intervals as defined by the user in the `~/.smd/loop` configuration file. On errors that are reported to be transient, its retries a second time before failing. The first time you run `smd-loop` a sample config file is created for you. The configuration file is line oriented. Each line is composed of three space separated fields: - `pull-frequency` - `push-frequency` - `endpoint-name` Frequencies are expressed in minutes, while endpoint name is a valid name for `smd-pull` and `smd-push`. Lines beginning with # are considered as comments. The following example calls the command `smd-pull default` every 3 minutes, and `smd-push default` every 10. # pull-frequency push-frequency endpoint-name 3 10 default ### smd-applet smd-applet just runs `smd-loop`, notifying the user if errors occur. It can be run with `--configure` to pop-up its configuration window, that allows to tune its notification behaviour and to edit the configuration files for `smd-loop` and `smd-push/pull`. 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 mailing lists, that is obviously not always the case since nobody remembers all the mailing lists he is subscribed to. Installation ============ Syncmaildir is part of the Debian archive. If you are running Debian or one of its derivatives, you can install the `syncmaildir` and `syncmaildir-applet` packages with your favourite package manager. If you want to install it from source you need a C compiler, the development files for GLib, GNU make and sed. For `smd-applet` you also need the Vala compiler, libgee and GTK+ 2. You may also want to customize few variables in the `Makefile`. Then typing `make && make install` should be enough to have syncmaildir installed. Some known platforms are supported by templates defined at the end of `Makefile`, for example you may want to run `make osx/text/all && make osx/text/install` to properly build and install text mode only syncmaildir utilities on an MacOSX platform. Runtime dependencies are: `ssh`, `xdelta`, `sha1sum`, `lua5.1` and `bash`. 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, login gares on fettunta dot org.