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>
