Provided by: syncmaildir_1.3.0-2_amd64 
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)