No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

smd-config.5.txt 6.0KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146
  1. NAME
  2. smd - configuration file for smd-pull and smd-push
  3. GENERAL SETUP
  4. To generate a template config file run smd-pull(1) with the -t option.
  5. If no endpoint is specified, the configuration file is named
  6. ~/.smd/config.default, otherwise it is named ~/.smd/config.endpoint.
  7. That file is composed by the following fields
  8. CLIENTNAME name of the client host
  9. SERVERNAME name of the server host
  10. MAILBOX list of directories, separated by space
  11. The field SERVERNAME must be a valid name for ssh, thus can be an alias like
  12. smd-server-foo. The default configuration file contains an example of how
  13. to set up an alias for ssh.
  14. The field CLIENTNAME is just an ID for the local host. If you plan to sync
  15. the same host with multiple remote hosts, you MUST use different values
  16. for CLIENTNAME for every configuration file.
  17. The field MAILBOX is a space separated list or roots that will be scanned
  18. for maildirs. Typically it is just one directory name, Mail or Maildir.
  19. The roots must be paths relative to the home directory.
  20. In the simplest case, the roots are named the same on both the local and
  21. the remote hosts.
  22. If the roots have different names on the local and remote hosts, but
  23. their internal structure is the same, the simplest solution is to just
  24. use a symlink on one of the two hosts so that a single name can be used
  25. to refer to both.
  26. If the internal sub folder structure differ, for example because on the remote
  27. hosts sub folders names are prefixed with a dot but it is not the case on the
  28. local one, refer to the MAIL FOLDER RENAMING section of this document.
  29. The configuration file is a regular shell script, refer to bash(1) for
  30. its syntax.
  31. HOOKS
  32. The content of the directories ~/.smd/hooks/{pre,post}-pull.d/ is executed
  33. respectively before and after smd-pull does it's job. They receive
  34. four arguments: "pre" or "post", "pull", the endpoint name and the status.
  35. The status is always 0 (meaning success) for pre hooks, while can be 1 (for
  36. failure) for post hooks. Hooks should not fail, if they do so then
  37. smd-pull will fail too.
  38. The content of the directories ~/.smd/hooks/{pre,post}-push.d/ is executed
  39. respectively before and after smd-push does it's job. They receive
  40. four arguments: "pre" or "post", "push", the endpoint name and the status.
  41. The status is always 0 (meaning success) for pre hooks, while can be 1 (for
  42. failure) for post hooks. Hooks should not fail, if they do so then
  43. smd-push will fail too.
  44. MAIL FOLDER RENAMING
  45. To make the transition from other synchronization tools smooth, the folders
  46. structure on the local and remote host are allowed to differ. For example,
  47. offlineimap usually removes trailing dots from the names of sub folders.
  48. To take advantage of folder renaming, the configuration file can contain
  49. the following fields:
  50. MAILBOX_LOCAL the local roots of maildirs
  51. MAILBOX_REMOTE the remote roots of maildirs
  52. TRANSLATOR_RL a program to translate remote mailbox names to local ones
  53. TRANSLATOR_LR a program to translate local mailbox names to remote ones
  54. The fields MAILBOX_LOCAL and MAILBOX_REMOTE must substitute the MAILBOX
  55. fields explained above.
  56. The fields TRANSLATOR_RL and TRANSLATOR_LR must define two translator
  57. programs that will be run to translate remote mailbox names to local
  58. ones (TRANSLATOR_RL) and vice versa (TRANSLATOR_LR).
  59. A translator program must fulfil the following requirements:
  60. - must be an absolute path or relative to the $HOME directory or in the
  61. user $PATH and must be executable
  62. - receives in standard input one or more paths starting with one of the
  63. roots listed in MAILBOX_LOCAL (for TRANSLATOR_LR) or MAILBOX_REMOTE
  64. (for TRANSLATOR_RL) and ending with cur, new or tmp
  65. - it can fail, returning 1 and writing on standard output the string
  66. ERROR followed by a new line and a human readable error message in
  67. the following lines
  68. - it can succeed, returning 0 and printing on standard output the
  69. corresponding translated paths
  70. PATHS EXCLUSION
  71. In case some paths need to be skipped, they can be specified as
  72. space separated glob(7) expressions in the variable:
  73. EXCLUDE glob expressions identifying paths to be excluded
  74. Note that these expressions must match real paths, no translation operation
  75. is applied to them, so it may be necessary to specify different expressions
  76. for the local and remote endpoint. In that case the following variables can
  77. be set:
  78. EXCLUDE_LOCAL glob expressions identifying local paths to be excluded
  79. EXCLUDE_REMOTE glob expressions identifying remote paths to be excluded
  80. Matching is performed using fnmatch(3) with no special flags, thus `*' and
  81. `?' match any character including `/'. Last, note that spaces in glob
  82. expressions must be replaced by %20. For example, to exclude all
  83. paths matching the expression `Mail/delayed [1-5] days/*' the variable
  84. EXCLUDE must be set to `Mail/delayed%20[1-5]%20days/*'
  85. Last, matching is performed every time a directory is entered, and if
  86. the matching succeeds the directory and all its subdirectories are skipped.
  87. Thus there is no need to specify a trailing '/*' in every expression.
  88. LOCAL SYNCHRONIZATION
  89. If the local and remote mailboxes are on the same host the following
  90. option must be added to the configuration file:
  91. SMDCLIENTOPTS=-l
  92. Note that this options has also the effect that ssh is not used. A a simple
  93. pair of pipes is used instead.
  94. DELETIONS
  95. In some cases, usually unidirectional synchronizations, one may want
  96. to not propagate deletions. E.g. one keeps a slim working mailbox but
  97. pushes to a backup mailbox to save every email. For that scenario
  98. smd-pull and smd-push accept a -n, --no-delete, option.
  99. To avoid specifying this option every time one can put it in the
  100. configuration file:
  101. SMDSERVEROPTS=-n
  102. FILES
  103. ~/.smd/config.*
  104. ~/.smd/hooks/pre-pull.d/
  105. ~/.smd/hooks/post-pull.d/
  106. ~/.smd/hooks/pre-push.d/
  107. ~/.smd/hooks/post-push.d/
  108. SEE ALSO
  109. mddiff(1), smd-server(1), smd-client(1), smd-push(1), smd-loop(1), smd-translate(1)
  110. AUTHOR
  111. Enrico Tassi <gares@fettunta.org>