mswatch - watch mailstores for changes and initiate mailbox syncs
http://mswatch.sf.net/

* About and Rationale

mswatch is a command line unix program that keeps two mailboxes synchronized
/more efficiently/ and with /shorter delays/ than periodically
synchronizing the two the two mailboxes.

mswatch watches mailboxes to know when to initiate mailbox syncs.
Using mswatch, your mail synchronization program can be called
on demand instead of through polling, resulting in prompter mail
delivery and lower bandwidth usage and server load.

mswatch is designed to work in conjunction with mailbox
synchronization programs, currently supports watching Linux (2.4+)
hosted Maildirs (including Maildir folders, Maildir++), and is
released under the terms of version 2 of the GNU General Public License
as published by the Free Software Foundation.

More information at the mswatch website: http://mswatch.sf.net/

* Requirements

General:
	GLib 2.6+
	C and C++ compiler (GCC tested)

mswatch: a mailbox synchronizer (such as mbsync); also, ssh suggested

watch_maildirs: Linux 2.4+ with inotify (2.6.13+) or dnotify (2.4.19+) support

socketwatch: support for LD_PRELOAD; also, see man page for limitations

* Installation

You must install (at least part of) mswatch on each host on which you wish
to watch for mailbox changes. The exact programs to install:
- 'mswatch' must be installed on some host that can communicate with the
  hosts with mailboxes being watched
- 'socketwatach' is a helpful program for the host that runs mswatch
  (socketwatch makes mail synchronization more robust against hangs)
- 'watch_maildirs' must be installed on each host with mailboxes being watched
- 'inputkill' is a helpful program for each host remote to mswatch with
  mailboxes being watched (inputkill promptly kills watch_maildirs if
  its ssh connection is lost)

$ ./configure [--prefix=PREFIX] \
	[--disable-watchmaildirs] [--disable-inputkill] [--disable-socketwatch] \
	[--disable-mswatch]
$ make install

* Configuration

** mswatch

mswatch requires a configuration file; by default at ~/.mswatchrc.
The file 'mswatchrc.sample' is an example configuration for using
mswatch to watch a local maildir and via ssh a remote maildir and to
synchronize these two mailstores using mbsync. mswatch(1) also documents
this configuration file.

** watch_maildirs

watch_maildirs expects the INBOX folder to reside in the base maildir
(often ~/Maildir/) and for a folder x to reside in the maildir ~/Maildir/.x/

* Limitations

** mswatch with mbsync

When a mailbox is deleted and mbsync is ran for the mailbox,
mbsync recreates the deleted mailbox instead of propagating the deletion.

** watch_maildirs

watch_maildirs uses Linux's inotify or dnotify interface to detect
file system changes.

The inotify backend does not detect:
- base Maildir (or parent directory) rename while under watch;
  eg "mv ~/Maildir ~/old_Maildir"
  (sub-folder renames are detected)
  [correction planned for a future mswatch]
- for symlinks to directories, watch_maildirs will not detect changes to
  the symlink itself
  [correction planned for a future mswatch]
- directories that are reachable through multiple paths, possible using
  symlinks, cannot be watched. watch_maildirs will exit.


The dnotify backend does not detect:
- base Maildir (or parent directory) rename while under watch;
  eg "mv ~/Maildir ~/old_Maildir"
  (sub-folder renames are detected)
- "fast directory name reuse"
  If a watched directory is moved elsewhere and another directory is created
  in its place, the change may not be detected while the directory
  is under watch. Such renaming is expected to be rare, and when it does
  occur, take much longer than tenths of a second.
  But should it occur, restart watch_maildirs to detect the changes.
  The inotify backend does not have this limitation.
- change notification queue overflow
  The dnotify backend receives a real-time unix signal for each file change;
  the dnotify backend does not detect signal queue overflow, which could
  happen if file system changes occur faster than watch_maildirs can send them
  to mswatch.
  The inotify backend does not have this limitation.
- for symlinks to directories, watch_maildirs will not detect changes to
  the symlink itself
- directories that are reachable through multiple paths, possible using
  symlinks, cannot be watched. watch_maildirs will exit.

* Copyright

Copyright (C) 2006-2011 Chris Frost

mswatch is free software; you can redistribute it and/or modify
it under the terms of version 2 of the GNU General Public License
as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

- Chris Frost <chris@frostnet.net>