smd-config.5.txt

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:

  - must be an absolute path or relative to the $HOME directory or in the
    user $PATH and must be executable
  - receives in standard input one or more paths starting with one of the
    roots listed in MAILBOX_LOCAL (for TRANSLATOR_LR) or MAILBOX_REMOTE 
    (for TRANSLATOR_RL) and ending with cur, new or tmp
  - 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
  - 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 variable
  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 specifying 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>