From 550f778dbcb84a9aa67732b1fff0191b55bea24c Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sat, 6 Jul 2019 19:50:06 +0200 Subject: interimap: clarify that 'ignore-mailbox' is matched against internal names. That is, without leading reference, and where the hierarchy delimiter is replaced with null characters. /!\ This changes breaks backward compatibility! --- doc/interimap.1.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'doc/interimap.1.md') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index 387850a..d7c3711 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -266,7 +266,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 hiearchy 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. -- cgit v1.2.3 From 17ecce0dd72fd3b857210fbff3f356afc9ba0f75 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sun, 7 Jul 2019 03:45:35 +0200 Subject: interimap.1: Clarify handling of delimiter in mailbox names. --- doc/interimap.1.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'doc/interimap.1.md') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index d7c3711..b7707af 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 @@ -245,7 +248,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.) -- cgit v1.2.3 From 67e0d741f21bd589a2cbb4d23f07f5fb5eae889b Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 28 Aug 2019 10:58:59 +0200 Subject: typofix --- doc/interimap.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/interimap.1.md') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index b7707af..0fb83ea 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -276,7 +276,7 @@ Valid options are: 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 after trimming the reference names and - substituting the hiearchy delimiter with the null character. For + 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 -- cgit v1.2.3 From 2f8350700091e766bdab24e7e8d8e051701da9e2 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 6 Nov 2019 02:55:18 +0100 Subject: pullimap, interimap: redact AUTHENTICATE and LOGIN commands In --debug mode in order to avoid inadvertently receiving credentials in bug reports. --debug can be set twice to spell out these commands in full. --- doc/interimap.1.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'doc/interimap.1.md') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index 0fb83ea..8fa5def 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -178,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` -- cgit v1.2.3 From 30276bbc82ca770500531d872666f48493749285 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 6 Nov 2019 03:46:36 +0100 Subject: interimap.1.md: Document that DELETE and RENAME commands should be avoided. --- doc/interimap.1.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'doc/interimap.1.md') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index 8fa5def..42db381 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -437,7 +437,7 @@ Known bugs and limitations 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. + synchronization solution. * `interimap` is single threaded and doesn't use IMAP command pipelining. Synchronization could be boosted up by sending @@ -452,6 +452,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 disapeared mailbox was deleted or + renamed, `interimap` aborts when a known mailbox disapeared 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. -- cgit v1.2.3 From ab2774a3039efc0efe0a4bc840675bf6d36435d7 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 6 Nov 2019 18:20:04 +0100 Subject: interimap.1.md: Hint to `doveadm-deduplicate` to weed out duplicates. --- doc/interimap.1.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'doc/interimap.1.md') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index 42db381..d5dd685 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -435,9 +435,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 - synchronization 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 @@ -544,3 +545,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 -- cgit v1.2.3 From e8c3b83914fe86edfa9c209de64fcc225c820bc7 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Thu, 7 Nov 2019 20:32:44 +0100 Subject: typofix --- doc/interimap.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/interimap.1.md') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index d5dd685..febec28 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -454,8 +454,8 @@ Known bugs and limitations to the other mailbox in the meantime. * Because the [IMAP protocol][RFC 3501] doesn't provide a way for - clients to determine whether a disapeared mailbox was deleted or - renamed, `interimap` aborts when a known mailbox disapeared from one + 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. -- cgit v1.2.3 From a4a371234215a7705f304875cc8af067bf3142af Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Thu, 7 Nov 2019 16:42:52 +0100 Subject: Refactor logging logic. Also, introduce new option 'logger-prefix' to determine the prefix of each log line. Closes: #942725. --- doc/interimap.1.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'doc/interimap.1.md') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index febec28..ee92668 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -290,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`. -- cgit v1.2.3