--- name: "smd-config" section: "5" platform: "linux" package: "syncmaildir" version: "1.3.0-1" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/smd-config" --- # smd-config(5) configuration file for smd-pull and smd-push ## NAME **smd** - configuration file for smd-pull and smd-push ## GENERAL SETUP **To generate a template config file run [smd-pull(1)](/smd-pull/1.md) 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)](/bash/1.md) 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)](/glob/7.md) 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)](/fnmatch/3.md) 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)](/mddiff/1.md), [smd-server(1)](/smd-server/1.md), [smd-client(1)](/smd-client/1.md), [smd-push(1)](/smd-push/1.md), [smd-loop(1)](/smd-loop/1.md), [smd-translate(1)](/smd-translate/1.md)** ## AUTHOR **Enrico Tassi \**