smd-config(5)						 Sync Mail Dir (smd) documentation					     smd-config(5)

NAME

       smd - configuration file for smd-pull and smd-push

GENERAL SETUP

       To  generate  a	template  config  file	run  smd-pull(1) with the -t option.  If no endpoint is specified, the configuration file is named
       ~/.smd/config.default, otherwise it is named ~/.smd/config.endpoint.  That file is composed by the following fields

       CLIENTNAME
	      name of the client host

       SERVERNAME
	      name of the server host

       MAILBOX
	      list of directories, separated by space

       The field SERVERNAME must be a valid name for ssh, thus can be an alias like smd-server-foo. The default  configuration	file  contains	an
       example of how to set up an alias for ssh.

       The field CLIENTNAME is just an ID for the local host. If you plan to sync the same host with multiple remote hosts, you MUST use different
       values for CLIENTNAME for every configuration file.

       The field MAILBOX is a space separated list or roots that will be scanned for maildirs. Typically it is just one directory  name,  Mail	or
       Maildir.  The roots must be paths relative to the home directory.  In the simplest case, the roots are named the same on both the local and
       the remote hosts.

       If the roots have different names on the local and remote hosts, but their internal structure is the same, the simplest solution is to just
       use a symlink on one of the two hosts so that a single name can be used to refer to both.

       If  the	internal  sub folder structure differ, for example because on the remote hosts sub folders names are prefixed with a dot but it is
       not the case on the local one, refer to the MAIL FOLDER RENAMING section of this document.

       The configuration file is a regular shell script, refer to bash(1) for its syntax.

HOOKS

       The content of the directories ~/.smd/hooks/{pre,post}-pull.d/ is executed respectively before and  after  smd-pull  does  it's	job.  They
       receive four arguments: "pre" or "post", "pull", the endpoint name and the status.  The status is always 0 (meaning success) for pre hooks,
       while can be 1 (for failure) for post hooks. Hooks should not fail, if they do so then smd-pull will fail too.

       The content of the directories ~/.smd/hooks/{pre,post}-push.d/ is executed respectively before and  after  smd-push  does  it's	job.  They
       receive four arguments: "pre" or "post", "push", the endpoint name and the status.  The status is always 0 (meaning success) for pre hooks,
       while can be 1 (for failure) for post hooks. Hooks should not fail, if they do so then smd-push will fail too.

MAIL FOLDER RENAMING

       To make the transition from other synchronization tools smooth, the folders structure on the local and remote host are allowed  to  differ.
       For example, offlineimap usually removes trailing dots from the names of sub folders.

       To take advantage of folder renaming, the configuration file can contain the following fields:

       MAILBOX_LOCAL
	      the local roots of maildirs

       MAILBOX_REMOTE
	      the remote roots of maildirs

       TRANSLATOR_RL
	      a program to translate remote mailbox names to local ones

       TRANSLATOR_LR
	      a program to translate local mailbox names to remote ones

       The fields MAILBOX_LOCAL and MAILBOX_REMOTE must substitute the MAILBOX fields explained above.

       The  fields TRANSLATOR_RL and TRANSLATOR_LR must define two translator programs that will be run to translate remote mailbox names to local
       ones (TRANSLATOR_RL) and vice versa (TRANSLATOR_LR).  A translator program must fulfil the following requirements:

       o  must be an absolute path or relative to the $HOME directory or in the user $PATH and must be executable

       o  receives in standard input one or more paths starting with one of the  roots	listed	in  MAILBOX_LOCAL  (for  TRANSLATOR_LR)  or  MAIL-
	  BOX_REMOTE (for TRANSLATOR_RL) and ending with cur, new or tmp

       o  it  can  fail,  returning 1 and writing on standard output the string ERROR followed by a new line and a human readable error message in
	  the following lines

       o  it can succeed, returning 0 and printing on standard output the corresponding translated paths

PATHS EXCLUSION

       In case some paths need to be skipped, they can be specified as space separated glob(7) expressions in the variable:

       EXCLUDE
	      glob expressions identifying paths to be excluded

       Note that these expressions must match real paths, no translation operation is applied to them, so it may be necessary to specify different
       expressions for the local and remote endpoint. In that case the following variables can be set:

       EXCLUDE_LOCAL
	      glob expressions identifying local paths to be excluded

       EXCLUDE_REMOTE
	      glob expressions identifying remote paths to be excluded

       Matching is performed using fnmatch(3) with no special flags, thus `*' and `?' match any character including `/'. Last, note that spaces in
       glob expressions must be replaced by %20. For example, to exclude all paths matching the expression `Mail/delayed [1-5] days/*'	the  vari-
       able EXCLUDE must be set to `Mail/delayed%20[1-5]%20days/*'

       Last,  matching	is  performed every time a directory is entered, and if the matching succeeds the directory and all its subdirectories are
       skipped.  Thus there is no need to specify a trailing '/*' in every expression.

LOCAL SYNCHRONIZATION

       If the local and remote mailboxes are on the same host the following option must be added to the configuration file:

       SMDCLIENTOPTS=-l

       Note that this options has also the effect that ssh is not used. A a simple pair of pipes is used instead.

DELETIONS

       In some cases, usually unidirectional synchronizations, one may want to not propagate deletions. E.g. one keeps a slim working mailbox  but
       pushes  to a backup mailbox to save every email. For that scenario smd-pull and smd-push accept a -n, --no-delete, option.  To avoid speci-
       fying this option every time one can put it in the configuration file:

       SMDSERVEROPTS=-n

FILES

       ~/.smd/config.*	~/.smd/hooks/pre-pull.d/ ~/.smd/hooks/post-pull.d/ ~/.smd/hooks/pre-push.d/ ~/.smd/hooks/post-push.d/

SEE ALSO

       mddiff(1), smd-server(1), smd-client(1), smd-push(1), smd-loop(1), smd-translate(1)

AUTHOR

       Enrico Tassi <gares@fettunta.org>

								   11 June 2012 						     smd-config(5)