From 684f9a4812cd209b598d1ce76d5613076c55890f Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 5 Jul 2019 06:12:05 +0200 Subject: typofix --- doc/build.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/build.md b/doc/build.md index 38d1bfb..681f143 100644 --- a/doc/build.md +++ b/doc/build.md @@ -78,12 +78,12 @@ The `doc` target generates all documentation, manpages as well as HTML pages. -Build custom Debian package -=========================== +Build custom Debian packages +============================ Debian GNU/Linux users can also use [`gbp`(1)] from [`git-buildpackage`](https://tracker.debian.org/pkg/git-buildpackage) in -order to build their own package: +order to build their own packages: $ git checkout debian $ gbp buildpackage -- cgit v1.2.3 From 3811a6846c0174c1c91730844ce8ef98627508cc Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 5 Jul 2019 06:04:26 +0200 Subject: Use mailto: links for names of copyright holders. --- doc/build.md | 2 +- doc/development.md | 2 +- doc/index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/build.md b/doc/build.md index 681f143..ec87e73 100644 --- a/doc/build.md +++ b/doc/build.md @@ -1,5 +1,5 @@ % Build instructions -% Guilhem Moulin +% [Guilhem Moulin](mailto:guilhem@fripost.org) On Debian 9 (codename *Stretch*) and later, installing [`interimap`(1)] is a single command away: diff --git a/doc/development.md b/doc/development.md index 406207a..87eb32c 100644 --- a/doc/development.md +++ b/doc/development.md @@ -1,5 +1,5 @@ % Test environment setup for [`interimap`(1)] and [`pullimap`(1)] -% Guilhem Moulin +% [Guilhem Moulin](mailto:guilhem@fripost.org) Introduction ============ diff --git a/doc/index.md b/doc/index.md index 12de956..281317e 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,5 +1,5 @@ % [`interimap`(1)] and [`pullimap`(1)] documentation -% Guilhem Moulin +% [Guilhem Moulin](mailto:guilhem@fripost.org) Manuals (HTML versions) ----------------------- -- cgit v1.2.3 From 21d6363c406bd0301b52711a30f98e1f03d0afaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20D=C3=A9trez?= Date: Fri, 5 Jul 2019 15:25:29 +0200 Subject: doc/template.html: Add parent links at the top. --- doc/template.html | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/template.html b/doc/template.html index e17f0e3..ceb2576 100644 --- a/doc/template.html +++ b/doc/template.html @@ -19,6 +19,12 @@ $endif$ span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} + @media only screen and (min-width: 600px) { + .parent { + float: right; + margin-left: 1em; + } + } $if(quotes)$ q { quotes: "“" "”" "‘" "’"; } $endif$ @@ -48,14 +54,18 @@ $endfor$ $for(include-before)$ $include-before$ $endfor$ -
+
$if(title)$ -

$title$

+
+$if(parent)$ +
Parent
+$endif$ +

$title$

+
$endif$ $body$ -
@@ -72,5 +82,6 @@ $endif$
+ -- cgit v1.2.3 From 420cd08692d4962155b23925eabc74d9002bf55d Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 5 Jul 2019 15:29:07 +0200 Subject: doc/template.html: Fix minor space damage. --- doc/template.html | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) (limited to 'doc') diff --git a/doc/template.html b/doc/template.html index ceb2576..17cbdbe 100644 --- a/doc/template.html +++ b/doc/template.html @@ -15,18 +15,21 @@ $if(keywords)$ $endif$ $if(title-prefix)$$title-prefix$ – $endif$$pagetitle$ $if(highlighting-css)$ @@ -37,11 +40,6 @@ $endif$ $for(css)$ $endfor$ - $if(math)$ $math$ $endif$ -- cgit v1.2.3 From 060554e73c9effe783a10c25e83df80c5e7a33ea Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 5 Jul 2019 15:31:31 +0200 Subject: doc/*.md: Improve wording. --- doc/development.md | 2 +- doc/index.md | 2 +- doc/template.html | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/development.md b/doc/development.md index 87eb32c..428c11d 100644 --- a/doc/development.md +++ b/doc/development.md @@ -1,4 +1,4 @@ -% Test environment setup for [`interimap`(1)] and [`pullimap`(1)] +% Test environment setup % [Guilhem Moulin](mailto:guilhem@fripost.org) Introduction diff --git a/doc/index.md b/doc/index.md index 281317e..a403a3e 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,4 +1,4 @@ -% [`interimap`(1)] and [`pullimap`(1)] documentation +% [`interimap`(1)] and [`pullimap`(1)] % [Guilhem Moulin](mailto:guilhem@fripost.org) Manuals (HTML versions) diff --git a/doc/template.html b/doc/template.html index 17cbdbe..97062e3 100644 --- a/doc/template.html +++ b/doc/template.html @@ -70,7 +70,7 @@ $body$
$if(author)$ - © + Copyright © $for(author)$$author$$sep$, $endfor$ $endif$
-- cgit v1.2.3 From 955cda2cfa32ca6e475b6726df4732f5dc98a30f Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 5 Jul 2019 17:39:46 +0200 Subject: doc/template.html: Justify paragraphs on larger screens. --- doc/template.html | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/template.html b/doc/template.html index 97062e3..a3a3938 100644 --- a/doc/template.html +++ b/doc/template.html @@ -24,6 +24,9 @@ $endif$ float: right; margin-left: 1em; } + .content p { + text-align: justify; + } } @media(max-width: 1440px) { .container{ max-width: 1080px; } } @media(max-width: 1280px) { .container{ max-width: 960px; } } @@ -64,6 +67,7 @@ $endif$ $endif$ $body$ +
@@ -80,6 +84,5 @@ $endif$
- -- cgit v1.2.3 From 4b61d5e13773bf8bf25537f28d1a42f7c6473b75 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sat, 6 Jul 2019 14:55:04 +0200 Subject: doc/*: Fix minor space damage. Also, set tab size to 4 spaces in the HTML for consistency. --- doc/build.md | 10 +++++----- doc/development.md | 14 +++++++------- doc/template.html | 1 + 3 files changed, 13 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/build.md b/doc/build.md index ec87e73..5c362f1 100644 --- a/doc/build.md +++ b/doc/build.md @@ -33,9 +33,9 @@ On Debian GNU/Linux systems, the dependencies can be installed with the following command: $ apt install libconfig-tiny-perl \ - libdbi-perl \ - libdbd-sqlite3-perl \ - libnet-ssleay-perl + libdbi-perl \ + libdbd-sqlite3-perl \ + libnet-ssleay-perl Additional packages are required in order to run the test suite: @@ -68,8 +68,8 @@ the `CSS` environment variable (the value of which defaults to For instance, use $ CSS="https://guilhem.org/static/css/bootstrap.min.css" \ - HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \ - make html + HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \ + make html to generate the HTML documentation under directory `$XDG_RUNTIME_DIR/interimap` (which needs to exist) using a remote CSS file. diff --git a/doc/development.md b/doc/development.md index 428c11d..49e8d74 100644 --- a/doc/development.md +++ b/doc/development.md @@ -83,7 +83,7 @@ pre-authenticated [IMAP4rev1] in the test environment for username `testuser`, list mailboxes, and exit, run: $ env -i PATH="/usr/bin:/bin" USER="testuser" \ - doveadm -c "$BASEDIR/dovecot.conf" exec imap + doveadm -c "$BASEDIR/dovecot.conf" exec imap * PREAUTH [CAPABILITY IMAP4rev1 …] Logged in as testuser a LIST "" "*" * LIST (\HasNoChildren) "." INBOX @@ -98,10 +98,10 @@ the latter to create a mailbox `foo`, add a sample message to it, and finally mark it as `\Seen`. $ env -i PATH="/usr/bin:/bin" USER="testuser" \ - doveadm -c "$BASEDIR/dovecot.conf" mailbox create "foo" + doveadm -c "$BASEDIR/dovecot.conf" mailbox create "foo" $ env -i PATH="/usr/bin:/bin" USER="testuser" HOME="$BASEDIR/testuser" \ - doveadm -c "$BASEDIR/dovecot.conf" exec dovecot-lda -e -m "foo" <<-EOF + doveadm -c "$BASEDIR/dovecot.conf" exec dovecot-lda -e -m "foo" <<-EOF From: To: Subject: Hello world! @@ -112,7 +112,7 @@ finally mark it as `\Seen`. EOF $ env -i PATH="/usr/bin:/bin" USER="testuser" \ - doveadm -c "$BASEDIR/dovecot.conf" flags add "\\Seen" mailbox "foo" "*" + doveadm -c "$BASEDIR/dovecot.conf" flags add "\\Seen" mailbox "foo" "*" Normally [`dovecot-lda`(1)](https://wiki.dovecot.org/LDA) tries to do a userdb lookup in order to determine the user's home directory. Since we @@ -155,7 +155,7 @@ You can now run [`interimap`(1)] with `--watch` set, here to one second to observe synchronisation steps early. $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf" \ - --watch=1 --debug + --watch=1 --debug Use instructions from the [previous section][Mail storage access] (substituting `testuser` with `local` or `remote`) in order to simulate @@ -179,12 +179,12 @@ Create a [`pullimap`(1)] configuration file with as section `[foo]`. Run [`pullimap`(1)] without `--idle` in order to create the state file. $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \ - --no-delivery foo + --no-delivery foo You can now run [`pullimap`(1)] with `--idle` set. $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \ - --no-delivery --idle --debug foo + --no-delivery --idle --debug foo Use instructions from the [previous section][Mail storage access] in order to simulate activity on the “remote” server (in the relevant diff --git a/doc/template.html b/doc/template.html index a3a3938..2cd7cc9 100644 --- a/doc/template.html +++ b/doc/template.html @@ -19,6 +19,7 @@ $endif$ span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} + pre{tab-size: 4; -moz-tab-size: 4;} @media only screen and (min-width: 600px) { .parent { float: right; -- cgit v1.2.3 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') 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') 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') 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 +++++---- doc/pullimap.1.md | 9 +++++---- 2 files changed, 10 insertions(+), 8 deletions(-) (limited to 'doc') 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` diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md index 1b2e509..d40ece8 100644 --- a/doc/pullimap.1.md +++ b/doc/pullimap.1.md @@ -57,10 +57,11 @@ Options `--debug` -: Turn on debug mode. Debug messages are written to the error output. - 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') 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') 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') 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') 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