aboutsummaryrefslogtreecommitdiffstats
path: root/doc
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
parent590bf57446967d897ee8327c8b2df57b77f4744e (diff)
parenta4a371234215a7705f304875cc8af067bf3142af (diff)
Merge branch 'master' into debian
Diffstat (limited to 'doc')
-rw-r--r--doc/build.md18
-rw-r--r--doc/development.md18
-rw-r--r--doc/index.md4
-rw-r--r--doc/interimap.1.md55
-rw-r--r--doc/pullimap.1.md9
-rw-r--r--doc/template.html41
6 files changed, 97 insertions, 48 deletions
diff --git a/doc/build.md b/doc/build.md
index 38d1bfb..5c362f1 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -1,5 +1,5 @@
% Build instructions
-% Guilhem Moulin <guilhem@fripost.org>
+% [Guilhem Moulin](mailto:guilhem@fripost.org)
On Debian 9 (codename *Stretch*) and later, installing [`interimap`(1)]
is a single command away:
@@ -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.
@@ -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
diff --git a/doc/development.md b/doc/development.md
index 406207a..49e8d74 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@fripost.org>
+% Test environment setup
+% [Guilhem Moulin](mailto:guilhem@fripost.org)
Introduction
============
@@ -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: <sender@example.net>
To: <recipient@example.net>
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/index.md b/doc/index.md
index 12de956..a403a3e 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -1,5 +1,5 @@
-% [`interimap`(1)] and [`pullimap`(1)] documentation
-% Guilhem Moulin <guilhem@fripost.org>
+% [`interimap`(1)] and [`pullimap`(1)]
+% [Guilhem Moulin](mailto:guilhem@fripost.org)
Manuals (HTML versions)
-----------------------
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
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`
diff --git a/doc/template.html b/doc/template.html
index e17f0e3..2cd7cc9 100644
--- a/doc/template.html
+++ b/doc/template.html
@@ -15,12 +15,25 @@ $if(keywords)$
$endif$
<title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
<style type="text/css">
- code{white-space: pre-wrap;}
- span.smallcaps{font-variant: small-caps;}
- span.underline{text-decoration: underline;}
- div.column{display: inline-block; vertical-align: top; width: 50%;}
+ code{white-space: pre-wrap;}
+ 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;
+ margin-left: 1em;
+ }
+ .content p {
+ text-align: justify;
+ }
+ }
+ @media(max-width: 1440px) { .container{ max-width: 1080px; } }
+ @media(max-width: 1280px) { .container{ max-width: 960px; } }
+ @media(max-width: 1024px) { .container{ max-width: 768px; } }
$if(quotes)$
- q { quotes: "“" "”" "‘" "’"; }
+ q { quotes: "“" "”" "‘" "’"; }
$endif$
</style>
$if(highlighting-css)$
@@ -31,11 +44,6 @@ $endif$
$for(css)$
<link rel="stylesheet" href="$css$" />
$endfor$
- <style type="text/css">
- @media(max-width: 1440px) { .container{ max-width: 1080px; } }
- @media(max-width: 1280px) { .container{ max-width: 960px; } }
- @media(max-width: 1024px) { .container{ max-width: 768px; } }
- </style>
$if(math)$
$math$
$endif$
@@ -48,21 +56,26 @@ $endfor$
$for(include-before)$
$include-before$
$endfor$
-<div class="container text-justify">
+<div class="container">
<div class="content">
$if(title)$
- <div class="page-header"><h1>$title$</h1></div>
+ <div class="page-header">
+$if(parent)$
+ <div class=parent><a href="$parent$"><span class="glyphicon glyphicon-circle-arrow-up" aria-hidden="true"></span> Parent</a></div>
+$endif$
+ <h1 style="">$title$</h1>
+ </div>
$endif$
$body$
- </div>
+</div>
<footer>
<hr/>
<div class="row">
<div class="col-md-8 text-muted">
$if(author)$
- <a href="https://git.guilhem.org/interimap/plain/COPYING">&copy;</a>
+ <a href="https://git.guilhem.org/interimap/plain/COPYING">Copyright</a> &copy;
$for(author)$$author$$sep$, $endfor$
$endif$
</div>