aboutsummaryrefslogtreecommitdiffstats
path: root/doc/interimap.1.md
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@fripost.org>2019-11-07 20:54:08 +0100
committerGuilhem Moulin <guilhem@fripost.org>2019-11-07 20:54:08 +0100
commita8c3a40c6cb3d05115c0213243edff52ba5f3dcf (patch)
tree21546e3a77eac185c614989b4c2535face1f17c2 /doc/interimap.1.md
parent590bf57446967d897ee8327c8b2df57b77f4744e (diff)
parenta4a371234215a7705f304875cc8af067bf3142af (diff)
Merge branch 'master' into debian
Diffstat (limited to 'doc/interimap.1.md')
-rw-r--r--doc/interimap.1.md55
1 files changed, 45 insertions, 10 deletions
diff --git a/doc/interimap.1.md b/doc/interimap.1.md
index 387850a..ee92668 100644
--- a/doc/interimap.1.md
+++ b/doc/interimap.1.md
@@ -85,7 +85,10 @@ However if some extra argument are provided on the command line,
`interimap` ignores these options and synchronizes the given
*MAILBOX*es instead. Note that each *MAILBOX* is taken “as is”; in
particular, it must be [UTF-7 encoded][RFC 2152], unquoted, and the list
-wildcards ‘\*’ and ‘%’ are passed verbatim to the IMAP server.
+wildcards ‘\*’ and ‘%’ are passed verbatim to the IMAP server. If the
+local and remote hierarchy delimiter differ, then within the *MAILBOX*
+names the *local* delimiter should be used (it is transparently
+substituted for remote commands and responses).
If the synchronization was interrupted during a previous run while some
messages were being replicated (but before the `UIDNEXT` or
@@ -175,10 +178,11 @@ Options
`--debug`
-: Turn on debug mode. Debug messages are written to the given *logfile*.
- Note that this include all IMAP traffic (except literals).
- Depending on the chosen authentication mechanism, this might include
- authentication credentials.
+: Turn on debug mode. Debug messages, which includes all IMAP traffic
+ besides literals, are written to the given *logfile*. The `LOGIN`
+ and `AUTHENTICATE` commands are however redacted (in order to avoid
+ disclosing authentication credentials) unless the `--debug` flag is
+ set multiple times.
`-h`, `--help`
@@ -245,7 +249,13 @@ Valid options are:
Two wildcards are available, and passed verbatim to the IMAP server:
a ‘\*’ character matches zero or more characters, while a ‘%’
character matches zero or more characters up to the hierarchy
- delimiter.
+ delimiter. Hardcoding the hierarchy delimiter in this setting is
+ not advised because the server might silently change it at some
+ point. A null character should be used instead. For instance, if
+ *list-mailbox* is set `"foo\x00bar"` then, assuming the hierarchy
+ delimiter is ‘/’, only the mailbox named `foo/bar` is considered for
+ synchronization.
+
This option is only available in the default section.
(The default pattern, `*`, matches all visible mailboxes on the
server.)
@@ -266,7 +276,10 @@ Valid options are:
: An optional Perl Compatible Regular Expressions ([PCRE]) covering
mailboxes to exclude: any ([UTF-7 encoded][RFC 2152] and unquoted)
mailbox listed in the initial `LIST` responses is ignored if it
- matches the given expression.
+ matches the given expression after trimming the reference names and
+ substituting the hierarchy delimiter with the null character. For
+ instance, specifying `^virtual(?:\x00|$)` excludes the mailbox named
+ “virtual” as well as its descendants.
Note that the *MAILBOX*es given as command-line arguments bypass the
check and are always considered for synchronization. This option is
only available in the default section.
@@ -277,6 +290,19 @@ Valid options are:
default these messages are written to the error output.) This
option is only available in the default section.
+*log-prefix*
+
+: A `printf`(3)-like format string to use as prefix for each log
+ message. Interpreted sequences are `%n` and `%m`, expanding
+ respectively to the component name (*local*/*remote*) and to the
+ name of the mailbox relevant for the log entry. Conditions on a
+ specifier `%X` can be obtained with `%?X?then?` or `%?X?then&else?`,
+ which expands to *then* if the `%X` specifier expands to a non-empty
+ string, and to *else* (or the empty string if there is no else
+ condition) if it doesn't. Literal `%` characters need to be escaped
+ as `%%`, while `&`, `?` and `\` characters need to be `\`-escaped.
+ (Default: `%?n?%?m?%n(%m)&%n?: ?`.)
+
*type*
: One of `imap`, `imaps` or `tunnel`.
@@ -422,9 +448,10 @@ Known bugs and limitations
* Using `interimap` on two identical servers with a non-existent or
empty *database* will duplicate each message due to the absence of
- local ↔ remote UID association. Hence one needs to manually empty
- the mail store on one end when migrating to `interimap` from another
- synchronisation solution.
+ local ↔ remote UID association. (Should they arise, an external tool
+ such as [`doveadm-deduplicate`(1)] can be used to weed them out.)
+ Hence one needs to manually empty the mail store on one end when
+ migrating to `interimap` from another synchronization solution.
* `interimap` is single threaded and doesn't use IMAP command
pipelining. Synchronization could be boosted up by sending
@@ -439,6 +466,13 @@ Known bugs and limitations
was deleted while another one (which is replicated again) was added
to the other mailbox in the meantime.
+ * Because the [IMAP protocol][RFC 3501] doesn't provide a way for
+ clients to determine whether a disappeared mailbox was deleted or
+ renamed, `interimap` aborts when a known mailbox disappeared from one
+ server but not the other. The `--delete` (resp. `rename`) command
+ should be used instead to delete (resp. rename) the mailbox on both
+ servers as well as within `interimap`'s internal database.
+
* `PLAIN` and `LOGIN` are the only authentication mechanisms currently
supported.
@@ -524,3 +558,4 @@ Standards
[PCRE]: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions
[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html
[`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/verify.html
+[`doveadm-deduplicate`(1)]: https://wiki.dovecot.org/Tools/Doveadm/Deduplicate