Provided by: syncmaildir_1.3.0-2_amd64 bug

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>

                                         15 November 2022                           smd-config(5)