diff options
Diffstat (limited to 'doc/interimap.1.md')
| -rw-r--r-- | doc/interimap.1.md | 55 |
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 |