aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/benchmark.md4
-rw-r--r--doc/build.md73
-rw-r--r--doc/development.md77
-rw-r--r--doc/getting-started.md26
-rw-r--r--doc/interimap.1.md101
-rw-r--r--doc/multi-account.md25
-rw-r--r--doc/pullimap.1.md102
-rw-r--r--doc/template.html2
8 files changed, 261 insertions, 149 deletions
diff --git a/doc/benchmark.md b/doc/benchmark.md
index 72f51a4..3b58e10 100644
--- a/doc/benchmark.md
+++ b/doc/benchmark.md
@@ -48,8 +48,8 @@ by placing packet counters on the interface.
[OfflineIMAP]: https://www.offlineimap.org/
[benchmark-script]: https://git.guilhem.org/interimap/plain/benchmark/run
[Dovecot]: https://dovecot.org
-[dbox]: https://wiki.dovecot.org/MailboxFormat/dbox
-[maildir]: https://wiki.dovecot.org/MailboxFormat/Maildir
+[dbox]: https://doc.dovecot.org/latest/core/config/mailbox_formats/dbox.html
+[maildir]: https://doc.dovecot.org/latest/core/config/mailbox_formats/maildir.html
-----------------------------------------------------------------------
diff --git a/doc/build.md b/doc/build.md
index 4a4f80d..b40760e 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -1,7 +1,7 @@
% Build instructions
% [Guilhem Moulin](mailto:guilhem@fripost.org)
-On Debian 9 (codename *Stretch*) and later, installing [`interimap`(1)]
+On Debian 10 (codename *Buster*) and later, installing [`interimap`(1)]
is a single command away:
$ sudo apt install interimap
@@ -24,7 +24,7 @@ following Perl modules:
* [`Getopt::Long`](https://perldoc.perl.org/Getopt/Long.html) (*core module*)
* [`MIME::Base64`](https://perldoc.perl.org/MIME/Base64.html) (*core module*) — if authentication is required
* [`List::Util`](https://perldoc.perl.org/List/Util.html) (*core module*)
- * [`Net::SSLeay`](https://metacpan.org/pod/Net::SSLeay) ≥1.73
+ * [`Net::SSLeay`](https://metacpan.org/pod/Net::SSLeay) ≥1.86_06
* [`POSIX`](https://perldoc.perl.org/POSIX.html) (*core module*)
* [`Socket`](https://perldoc.perl.org/Socket.html) (*core module*)
* [`Time::HiRes`](https://perldoc.perl.org/Time/HiRes.html) (*core module*) — if `logfile` is set
@@ -38,10 +38,10 @@ Additional packages are required in order to run the test suite:
$ sudo apt install dovecot-imapd dovecot-lmtpd openssl procps sqlite3 xxd
<!-- -->
- $ make test
+ $ make check
-(The test suite also needs to bind to TCP ports 10024, 10143 and 10993
-on the loopback interface.)
+(Note also that the test suite needs to bind to TCP ports 10024, 10143
+and 10993 on the loopback interface.)
Generate documentation
======================
@@ -51,32 +51,53 @@ Yet another set of packages is needed to generate the documentation:
$ sudo apt install jq pandoc
Run `` `make manual` `` (or just `` `make` ``) in order to generate the
-manpages. You'll find them at `doc/*.[1-9]`. Use for instance `` `man
--l doc/interimap.1` `` in order to read your copy of the [`interimap`(1)]
-manpage.
+manuals. You'll find them at `build/doc/*.[1-9]`. Then use for
+instance `` `man -l build/doc/interimap.1` `` to read your local copy of
+the [`interimap`(1)] manual.
-The HTML documentation can be built with `` `make html` ``. HTML files
-are generated alongside their Markdown source by default, but you can
-choose another target directory using the `HTML_ROOTDIR` environment
-variable (the value of which defaults to `./doc`). Moreover the
-[`libjs-bootstrap`](https://tracker.debian.org/libjs-bootstrap) is
-needed by default for the local CSS file; this can be controlled with
-the `CSS` environment variable (the value of which defaults to
-`/usr/share/javascript/bootstrap/css/bootstrap.min.css`).
+The HTML documentation can be built with `` `make html` ``. By default
+HTML files are generated at `build/doc/*.html`, and a local CSS file is
+used — namely `/usr/share/javascript/bootstrap4/css/bootstrap.css`,
+shipped the by [`libjs-bootstrap`](https://tracker.debian.org/libjs-bootstrap)
+package. But this is configurable: use for instance
-For instance, use
+ $ make html builddir="$XDG_RUNTIME_DIR/interimap" \
+ CSS="https://cdn.jsdelivr.net/npm/bootstrap@4.6.1/dist/css/bootstrap.min.css"
- $ env CSS="https://guilhem.org/static/css/bootstrap.min.css" \
- HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \
- make html
+to generate the HTML documentation under `$XDG_RUNTIME_DIR/interimap/doc`
+using a remote CSS file.
-to generate the HTML documentation under directory `$XDG_RUNTIME_DIR/interimap`
-(which needs to exist) using a remote CSS file.
-
-The `doc` target generates all documentation, manpages as well as HTML
+The `doc` target generates all documentation, manuals as well as HTML
pages.
+Installation without root privileges
+====================================
+
+By default `` `make install` `` installs [`interimap`(1)] under
+`/usr/local`, hence requires root privileges. However another prefix
+can be used in order to perform the (un)installation as an unprivileged
+user. For instance
+
+ $ install -m0700 -vd ${XDG_DATA_HOME:-~/.local/share}/interimap
+ $ make install-nodoc \
+ prefix=$HOME/.local \
+ sitelib=${XDG_DATA_HOME:-~/.local/share}/interimap/lib \
+ systemd_userunitdir=${XDG_DATA_HOME:-~/.local/share}/systemd/user
+
+skips documentation and installs
+
+ * executables into `~/.local/bin` (instead of `/usr/local/bin`);
+ * libraries into `$XDG_DATA_HOME/interimap/lib` or `~/.local/share/interimap/lib`
+ (instead of `/usr/local/lib/site_perl`); and
+ * [systemd user unit files][`systemd.unit`(5)] into `$XDG_DATA_HOME/systemd/user`
+ or `~/.local/share/systemd/user` (instead of `/usr/local/lib/systemd/user`).
+
+Note that for uninstallation one must call `` `make uninstall prefix=…` ``
+with the very same assignment(s) used for installation.
+
+[`systemd.unit`(5)]: https://www.freedesktop.org/software/systemd/man/systemd.unit.html
+
Build custom Debian packages
============================
@@ -84,12 +105,12 @@ 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 packages:
- $ git checkout debian
+ $ git checkout debian/latest
$ gbp buildpackage
Alternatively, for the development version:
- $ git checkout debian
+ $ git checkout debian/latest
$ git merge master
$ gbp buildpackage --git-force-create --git-upstream-tree=BRANCH
diff --git a/doc/development.md b/doc/development.md
index f4578b9..f739dc0 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -15,14 +15,18 @@ Dovecot configuration
=====================
Create a file `$BASEDIR/dovecot.conf`, which will be used as
-configuration for the various Dovecot commands (the system configuration
-will be skipped).
+configuration for the various Dovecot 2.4 commands (the system
+configuration will be skipped).
$ cat >"$BASEDIR/dovecot.conf" <<-EOF
- log_path = "$BASEDIR/dovecot.log"
- ssl = no
- mail_home = "$BASEDIR/%u"
- mail_location = maildir:~/Mail
+ dovecot_config_version = 2.4.0
+ dovecot_storage_version = 2.4.0
+ log_path = "$BASEDIR/dovecot.log"
+ ssl = no
+
+ mail_home = "$BASEDIR/%{user | username | lower}"
+ mail_driver = maildir
+ mail_path = ~/Mail
EOF
Here are some details on the above:
@@ -36,18 +40,17 @@ Here are some details on the above:
`mail_home`
: Dovecot needs the name of the user to (pre-)authenticate. It is shown
- in the greeting line, and also used in [`%`-variable] expansion.
+ in the greeting line, and also used in [settings variables] expansion.
Several [`doveadm`(1)] sub-commands have a `-u` (or `-d`) option which
- can be used to determine the username. When this option is not set,
- the username is taken from the `USER` environment variable. If that
- environment variable is unset as well, then the return string of
- [`getlogin`(3)] is used.
+ can be used to determine the username. To avoid performing the userdb
+ lookup one can pass `--no-userdb-lookup` instead, in which case the
+ username is taken from the `USER` environment variable.
Similarly, the user's home directory is used in (`~`- and)
- [`%`-variable] expansion. It's taken from the `HOME` environment
- variable when the `mail_home` setting is left unset in the Dovecot
- configuration (and not overridden by the [user database][User
- Databases].
+ [settings variables] expansion. It's taken from the `HOME`
+ environment variable when the `mail_home` setting is left unset in
+ the Dovecot configuration (and not overridden by the
+ [user database][User Databases].
`mail_home` can therefore be left unset if the `HOME` environment
variable is consistently set to `$BASEDIR/$USER`. However it's
@@ -55,14 +58,17 @@ Here are some details on the above:
command run in a non-curated environment might mess up with your own
mail storage…
-`mail_location`
+`mail_driver`
- : The user's mail storage resides — in [Maildir] format — in a directory
- `Mail` under their home directory. This is enough if you're fine with
- the default IMAP hierarchy delimiter (which depends on the mail format)
- is used, and if you need a single [IMAP namespace][RFC 2342]. For more
- complex setups you'll need one or more [`namespace {…}` block][Dovecot
- Namespaces].
+ : Use the [Maildir] format for mail storage..
+
+`mail_path`:
+
+ : The user's mail storage resides in a directory `Mail` under their
+ home directory. This is enough if you're fine with the default IMAP
+ hierarchy delimiter (which depends on the mail format) is used, and
+ if you need a single [IMAP namespace][RFC 2342]. For more complex
+ setups you'll need one or more [`namespace {…}` block][Dovecot Namespaces].
Mail storage access
===================
@@ -88,7 +94,7 @@ 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 --no-userdb-lookup "foo"
<!-- -->
$ env -i PATH="/usr/bin:/bin" USER="testuser" HOME="$BASEDIR/testuser" \
doveadm -c "$BASEDIR/dovecot.conf" exec dovecot-lda -e -m "foo" <<-EOF
@@ -102,7 +108,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 --no-userdb-lookup "\\Seen" mailbox "foo" "*"
Normally [`dovecot-lda`(1)][Dovecot LDA] tries to do a userdb lookup in
order to determine the user's home directory. Since we didn't configure
@@ -136,7 +142,7 @@ and `remote` accounts.
Run [`interimap`(1)] without `--watch` in order to create the database.
- $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf"
+ $ env -i PATH="$PATH" perl -T ./interimap --config="$BASEDIR/interimap.conf"
Creating new schema in database file …/interimap.db
database: Created mailbox INBOX
[…]
@@ -144,7 +150,7 @@ Run [`interimap`(1)] without `--watch` in order to create the database.
You can now run [`interimap`(1)] with `--watch` set, here to one second
to observe synchronization steps early.
- $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf" \
+ $ env -i PATH="$PATH" perl -T ./interimap --config="$BASEDIR/interimap.conf" \
--watch=1 --debug
Use instructions from the [previous section][Mail storage access]
@@ -168,12 +174,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" \
+ $ env -i PATH="$PATH" perl -T ./pullimap --config="$BASEDIR/pullimap.conf" \
--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" \
+ $ env -i PATH="$PATH" perl -T ./pullimap --config="$BASEDIR/pullimap.conf" \
--no-delivery --idle --debug foo
Use instructions from the [previous section][Mail storage access]
@@ -193,14 +199,13 @@ recursively remove the directory `$BASEDIR`.
[IMAP4rev1]: https://tools.ietf.org/html/rfc3501
[Dovecot]: https://dovecot.org
-[Dovecot Logging]: https://doc.dovecot.org/admin_manual/logging/
-[Dovecot LDA]: https://wiki.dovecot.org/LDA
-[`getlogin`(3)]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getlogin.html
-[User Databases]: https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb/
-[Maildir]: https://wiki.dovecot.org/MailLocation/Maildir
+[Dovecot Logging]: https://doc.dovecot.org/latest/core/admin/logging.html#dovecot-logging
+[Dovecot LDA]: https://doc.dovecot.org/latest/core/config/delivery/lda.html
+[User Databases]: https://doc.dovecot.org/latest/core/config/auth/userdb.html
+[Maildir]: https://doc.dovecot.org/latest/core/config/mailbox_formats/maildir.html
[RFC 2342]: https://tools.ietf.org/html/rfc2342
-[Dovecot Namespaces]: https://doc.dovecot.org/configuration_manual/namespace/
+[Dovecot Namespaces]: https://doc.dovecot.org/latest/core/config/namespaces.html
[`interimap`(1)]: interimap.1.html
[`pullimap`(1)]: pullimap.1.html
-[`doveadm`(1)]: https://wiki.dovecot.org/Tools/Doveadm
-[`%`-variable]: https://doc.dovecot.org/configuration_manual/config_file/config_variables/
+[`doveadm`(1)]: https://doc.dovecot.org/latest/core/man/doveadm.1.html
+[settings variables]: https://doc.dovecot.org/latest/core/settings/variables.html
diff --git a/doc/getting-started.md b/doc/getting-started.md
index 1d059b4..e89eb19 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -20,7 +20,7 @@ format][mbox]). Local mail clients usually access it directly. They
also often maintain their own cache in order to speed up message header
listing and searches.
-While most bidirectional synchronisation software (such as [OfflineIMAP])
+While most bidirectional synchronization software (such as [OfflineIMAP])
are able to handle a mail storage in Maildir format, *InterIMAP is
not*. Instead, InterIMAP needs an [IMAP4rev1] server on *both* peers
to synchronize. This may sound like a severe limitation at first, but by
@@ -84,7 +84,7 @@ mailbox delivery) then don't disable them, and modify Dovecot's system
wide configuration instead. Same thing if your mail client isn't able
to spawn a command for IMAP communication, and instead insists on
connecting to a network socket (in that case you'll even need to
-configure [user authentication](https://wiki.dovecot.org/Authentication)
+configure [user authentication](https://doc.dovecot.org/latest/core/config/auth/overview.html)
for the IMAP service, which is out of scope for the present document).
Run the following command to terminate and disable the system-wide
@@ -94,14 +94,19 @@ Dovecot processes.
Create a new directory `$XDG_CONFIG_HOME/dovecot` holding the local
-Dovecot configuration:
+Dovecot 2.4 configuration:
$ install -m0700 -vd ${XDG_CONFIG_HOME:-~/.config}/dovecot
<!-- -->
$ cat >${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf <<-EOF
+ dovecot_config_version = 2.4.0
+ dovecot_storage_version = 2.4.0
+
ssl = no
- mail_location = maildir:~/Mail
- namespace {
+ mail_home = /home/%{user | username | lower}
+ mail_driver = maildir
+ mail_path = ~/Mail
+ namespace inbox {
inbox = yes
separator = /
}
@@ -113,9 +118,10 @@ Some remarks on the above:
running `` `doveconf -nc ${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf` ``.
* Messages will be stored in Maildir format under `~/Mail`. Ensure
the directory is either *empty* or *doesn't exist* before
- continuing! You may want to choose a different [format](https://wiki.dovecot.org/MailboxFormat)
- here, or simply append `:LAYOUT=fs` to the `mail_location` value in
- order to use a nicer (File System like) Maildir layout.
+ continuing! You may want to choose a different
+ [format](https://doc.dovecot.org/latest/core/config/mailbox_formats/overview.html)
+ here, or simply set `mailbox_list_layout = fs` in order to use a
+ nicer (File System like) Maildir layout.
* The `separator` setting defines the IMAP hierarchy delimiter. This
is orthogonal to the Maildir layout delimiter, and you can safely
change it later (even on an existing mail store). Popular hierarchy
@@ -198,7 +204,7 @@ for the sake of clarity we start from an empty file here.
shell process doesn't linger around during the IMAP session.)
3. And finally append a `[remote]` section with your account
- information at `imap.example.org` (adapt the values accordingly):
+ information at `imap.example.net` (adapt the values accordingly):
$ cat >>${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF
@@ -281,7 +287,7 @@ Manual
[IMAP4rev1]: https://tools.ietf.org/html/rfc3501
[INI file]: https://en.wikipedia.org/wiki/INI_file
[`interimap`(1)]: interimap.1.html
-[LMTP server]: https://doc.dovecot.org/configuration_manual/protocols/lmtp_server/
+[LMTP server]: https://doc.dovecot.org/latest/core/config/delivery/lmtp.html
[Maildir]: https://en.wikipedia.org/wiki/Maildir
[mbox]: https://en.wikipedia.org/wiki/Mbox
[MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent
diff --git a/doc/interimap.1.md b/doc/interimap.1.md
index 5370d79..18b3581 100644
--- a/doc/interimap.1.md
+++ b/doc/interimap.1.md
@@ -249,7 +249,7 @@ 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. Hardcoding the hierarchy delimiter in this setting is
+ delimiter. Hard-coding 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
@@ -309,7 +309,7 @@ Valid options are:
`type=imap` and `type=imaps` are respectively used for IMAP and IMAP
over SSL/TLS connections over an INET socket.
`type=tunnel` causes `interimap` to create an unnamed pair of
- connected sockets for interprocess communication with a *command*
+ connected sockets for inter-process communication with a *command*
instead of opening a network socket.
Note that specifying `type=tunnel` in the `[remote]` section makes
the default *database* to be `localhost.db`.
@@ -317,7 +317,9 @@ Valid options are:
*host*
-: Server hostname, for `type=imap` and `type=imaps`.
+: Server hostname or IP address, for `type=imap` and `type=imaps`.
+ The value can optionally be enclosed in square brackets to force its
+ interpretation as an IP literal (hence skip name resolution).
(Default: `localhost`.)
*port*
@@ -327,8 +329,8 @@ Valid options are:
*proxy*
-: An optional SOCKS proxy to use for TCP connections to the IMAP
- server (`type=imap` and `type=imaps` only), formatted as
+: Optional SOCKS proxy to use for TCP connections to the IMAP server
+ (`type=imap` and `type=imaps` only), formatted as
`PROTOCOL://[USER:PASSWORD@]PROXYHOST[:PROXYPORT]`.
If `PROXYPORT` is omitted, it is assumed at port 1080.
Only [SOCKSv5][RFC 1928] is supported (with optional
@@ -376,29 +378,44 @@ Valid options are:
*null-stderr*
: Whether to redirect *command*'s standard error to `/dev/null` for
- `type=tunnel`. (Default: `NO`.)
+ `type=tunnel`. This option is ignored when the `--debug` flag is
+ set. (Default: `NO`.)
*SSL_protocols*
-: A space-separated list of SSL protocols to enable or disable (if
- prefixed with an exclamation mark `!`. Known protocols are `SSLv2`,
- `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`. Enabling a
- protocol is a short-hand for disabling all other protocols.
- (Default: `!SSLv2 !SSLv3 !TLSv1 !TLSv1.1`, i.e., only enable TLSv1.2
- and above.)
+: Space-separated list of SSL/TLS protocol versions to explicitly
+ enable (or disable if prefixed with an exclamation mark `!`).
+ Potentially known protocols are `SSLv2`, `SSLv3`, `TLSv1`,
+ `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL
+ version used.
+ Enabling a protocol is a short-hand for disabling all other
+ protocols.
-*SSL_cipher_list*
+ *DEPRECATED*: Use *SSL_protocol_min* and/or *SSL_protocol_max*
+ instead.
-: The cipher list to send to the server. Although the server
- determines which cipher suite is used, it should take the first
- supported cipher in the list sent by the client. See
- [`ciphers`(1ssl)] for more information.
+*SSL_protocol_min*, *SSL_protocol_max*
+
+: Set minimum resp. maximum SSL/TLS protocol version to use for the
+ connection. Potentially recognized values are `SSLv3`, `TLSv1`,
+ `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL
+ version used.
+
+*SSL_cipherlist*, *SSL_ciphersuites*
+
+: Sets the TLSv1.2 and below cipher list resp. TLSv1.3 cipher suites.
+ The combination of these lists is sent to the server, which then
+ determines which cipher to use (normally the first supported one
+ from the list sent by the client). The default suites depend on the
+ OpenSSL version and its configuration, see [`ciphers`(1ssl)] for
+ more information.
*SSL_fingerprint*
-: Fingerprint of the server certificate's Subject Public Key Info, in
- the form `[ALGO$]DIGEST_HEX` where `ALGO` is the used algorithm (by
- default `sha256`).
+: Space-separated list of acceptable fingerprints for the server
+ certificate's Subject Public Key Info, in the form
+ `[ALGO$]DIGEST_HEX` where `ALGO` is the digest algorithm (by default
+ `sha256`).
Attempting to connect to a server with a non-matching certificate
SPKI fingerprint causes `interimap` to abort the connection during
the SSL/TLS handshake.
@@ -409,25 +426,47 @@ Valid options are:
| openssl pkey -pubin -outform DER \
| openssl dgst -sha256
+ Specifying multiple digest values can be useful in key rollover
+ scenarios and/or when the server supports certificates of different
+ types (for instance a dual-cert RSA/ECDSA setup). In that case the
+ connection is aborted when none of the specified digests matches.
+
*SSL_verify*
-: Whether to verify the server certificate chain.
- Note that using *SSL_fingerprint* to specify the fingerprint of the
- server certificate is an orthogonal authentication measure as it
- ignores the CA chain.
+: Whether to 1/ verify the server certificate chain; and 2/ match its
+ Subject Alternative Name (SAN) or Subject CommonName (CN) against
+ the value of the *host* option.
(Default: `YES`.)
+ Note that using *SSL_fingerprint* to specify the fingerprint of the
+ server certificate provides an independent server authentication
+ measure as it pins directly its key material and ignore its chain of
+ trust.
+
+*SSL_CAfile*
+
+: File containing trusted certificates to use during server
+ certificate verification when `SSL_verify=YES`.
+
+ Trusted CA certificates are loaded from the default system locations
+ unless one (or both) of *SSL_CAfile* or *SSL_CApath* is set.
+
*SSL_CApath*
-: Directory to use for server certificate verification if
+: Directory to use for server certificate verification when
`SSL_verify=YES`.
This directory must be in “hash format”, see [`verify`(1ssl)] for
more information.
-*SSL_CAfile*
+ Trusted CA certificates are loaded from the default system locations
+ unless one (or both) of *SSL_CAfile* or *SSL_CApath* is set.
-: File containing trusted certificates to use during server
- certificate authentication if `SSL_verify=YES`.
+*SSL_hostname*
+
+: Name to use for the TLS SNI (Server Name Indication) extension. The
+ default value is taken from the *host* option when it is a hostname,
+ and to the empty string when it is an IP literal.
+ Setting *SSL_hostname* to the empty string explicitly disables SNI.
Supported extensions {#supported-extensions}
====================
@@ -561,6 +600,6 @@ A _getting started_ guide is available [there](getting-started.html).
[INI file]: https://en.wikipedia.org/wiki/INI_file
[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
+[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html
+[`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-verify.html
+[`doveadm-deduplicate`(1)]: https://doc.dovecot.org/latest/core/man/doveadm-deduplicate.1.html
diff --git a/doc/multi-account.md b/doc/multi-account.md
index cc0a1b8..58fdd2d 100644
--- a/doc/multi-account.md
+++ b/doc/multi-account.md
@@ -82,20 +82,23 @@ over: they will only live on the local instance.
$ cat >${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf <<-EOF
ssl = no
- namespace {
- location = maildir:~/Mail
- inbox = yes
- separator = /
+ namespace indbox {
+ mail_driver = maildir
+ mail_path = ~/Mail
+ inbox = yes
+ separator = /
}
namespace perso {
- prefix = perso/
- location = maildir:~/Mail/perso
- separator = /
+ prefix = perso/
+ mail_driver = maildir
+ mail_path = ~/Mail/perso
+ separator = /
}
namespace work {
- prefix = work/
- location = maildir:~/Mail/work
- separator = /
+ prefix = work/
+ mail_driver = maildir
+ mail_path = ~/Mail/work
+ separator = /
}
EOF
@@ -205,5 +208,5 @@ Template user unit for systemd are provided in order to run these
[Getting Started]: getting-started.html
[RFC 2342]: https://tools.ietf.org/html/rfc2342
[RFC 3501]: https://tools.ietf.org/html/rfc3501
-[Dovecot namespaces]: https://doc.dovecot.org/configuration_manual/namespace/
+[Dovecot namespaces]: https://doc.dovecot.org/latest/core/config/namespaces.html
[`interimap`(1)]: interimap.1.html
diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md
index 0055675..89969b2 100644
--- a/doc/pullimap.1.md
+++ b/doc/pullimap.1.md
@@ -106,14 +106,14 @@ Valid options are:
*deliver-ehlo*
-: Hostname to use in `EHLO` or `LHLO` commands.
+: Name to use in `EHLO` or `LHLO` commands.
(Default: `localhost.localdomain`.)
*deliver-rcpt*
: Message recipient. Note that the local part needs to quoted if it
contains special characters; see [RFC 5321] for details.
- (Default: the username associated with the effective uid of the
+ (Default: the username associated with the effective user ID of the
`pullimap` process.)
*purge-after*
@@ -123,7 +123,7 @@ Valid options are:
`SEARCH` criterion ignoring time and timezone.)
If *purge-after* is set to `0` then messages are deleted immediately
after delivery. Otherwise `pullimap` issues an IMAP `SEARCH` (or
- extended `SEARCH` on servers advertizing the [`ESEARCH`][RFC 4731]
+ extended `SEARCH` on servers advertising the [`ESEARCH`][RFC 4731]
capability) command to list old messages; if `--idle` is set then
the `SEARCH` command is issued again every 12 hours.
@@ -133,13 +133,15 @@ Valid options are:
`type=imap` and `type=imaps` are respectively used for IMAP and IMAP
over SSL/TLS connections over an INET socket.
`type=tunnel` causes `pullimap` to create an unnamed pair of
- connected sockets for interprocess communication with a *command*
+ connected sockets for inter-process communication with a *command*
instead of opening a network socket.
(Default: `imaps`.)
*host*
-: Server hostname, for `type=imap` and `type=imaps`.
+: Server hostname or IP address, for `type=imap` and `type=imaps`.
+ The value can optionally be enclosed in square brackets to force its
+ interpretation as an IP literal (hence skip name resolution).
(Default: `localhost`.)
*port*
@@ -149,8 +151,8 @@ Valid options are:
*proxy*
-: An optional SOCKS proxy to use for TCP connections to the IMAP
- server (`type=imap` and `type=imaps` only), formatted as
+: Optional SOCKS proxy to use for TCP connections to the IMAP server
+ (`type=imap` and `type=imaps` only), formatted as
`PROTOCOL://[USER:PASSWORD@]PROXYHOST[:PROXYPORT]`.
If `PROXYPORT` is omitted, it is assumed at port 1080.
Only [SOCKSv5][RFC 1928] is supported (with optional
@@ -200,25 +202,39 @@ Valid options are:
*SSL_protocols*
-: A space-separated list of SSL protocols to enable or disable (if
- prefixed with an exclamation mark `!`. Known protocols are `SSLv2`,
- `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`. Enabling a
- protocol is a short-hand for disabling all other protocols.
- (Default: `!SSLv2 !SSLv3 !TLSv1 !TLSv1.1`, i.e., only enable TLSv1.2
- and above.)
+: Space-separated list of SSL/TLS protocol versions to explicitly
+ enable (or disable if prefixed with an exclamation mark `!`).
+ Potentially known protocols are `SSLv2`, `SSLv3`, `TLSv1`,
+ `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL
+ version used.
+ Enabling a protocol is a short-hand for disabling all other
+ protocols.
-*SSL_cipher_list*
+ *DEPRECATED*: Use *SSL_protocol_min* and/or *SSL_protocol_max*
+ instead.
-: The cipher list to send to the server. Although the server
- determines which cipher suite is used, it should take the first
- supported cipher in the list sent by the client. See
- [`ciphers`(1ssl)] for more information.
+*SSL_protocol_min*, *SSL_protocol_max*
+
+: Set minimum resp. maximum SSL/TLS protocol version to use for the
+ connection. Potentially recognized values are `SSLv3`, `TLSv1`,
+ `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL
+ version used.
+
+*SSL_cipherlist*, *SSL_ciphersuites*
+
+: Sets the TLSv1.2 and below cipher list resp. TLSv1.3 cipher suites.
+ The combination of these lists is sent to the server, which then
+ determines which cipher to use (normally the first supported one
+ from the list sent by the client). The default suites depend on the
+ OpenSSL version and its configuration, see [`ciphers`(1ssl)] for
+ more information.
*SSL_fingerprint*
-: Fingerprint of the server certificate's Subject Public Key Info, in
- the form `[ALGO$]DIGEST_HEX` where `ALGO` is the used algorithm (by
- default `sha256`).
+: Space-separated list of acceptable fingerprints for the server
+ certificate's Subject Public Key Info, in the form
+ `[ALGO$]DIGEST_HEX` where `ALGO` is the digest algorithm (by default
+ `sha256`).
Attempting to connect to a server with a non-matching certificate
SPKI fingerprint causes `pullimap` to abort the connection during
the SSL/TLS handshake.
@@ -229,25 +245,47 @@ Valid options are:
| openssl pkey -pubin -outform DER \
| openssl dgst -sha256
+ Specifying multiple digest values can be useful in key rollover
+ scenarios and/or when the server supports certificates of different
+ types (for instance a dual-cert RSA/ECDSA setup). In that case the
+ connection is aborted when none of the specified digests matches.
+
*SSL_verify*
-: Whether to verify the server certificate chain.
- Note that using *SSL_fingerprint* to specify the fingerprint of the
- server certificate is an orthogonal authentication measure as it
- ignores the CA chain.
+: Whether to 1/ verify the server certificate chain; and 2/ match its
+ Subject Alternative Name (SAN) or Subject CommonName (CN) against
+ the value of the *host* option.
(Default: `YES`.)
+ Note that using *SSL_fingerprint* to specify the fingerprint of the
+ server certificate provides an independent server authentication
+ measure as it pins directly its key material and ignore its chain of
+ trust.
+
+*SSL_CAfile*
+
+: File containing trusted certificates to use during server
+ certificate verification when `SSL_verify=YES`.
+
+ Trusted CA certificates are loaded from the default system locations
+ unless one (or both) of *SSL_CAfile* or *SSL_CApath* is set.
+
*SSL_CApath*
-: Directory to use for server certificate verification if
+: Directory to use for server certificate verification when
`SSL_verify=YES`.
This directory must be in “hash format”, see [`verify`(1ssl)] for
more information.
-*SSL_CAfile*
+ Trusted CA certificates are loaded from the default system locations
+ unless one (or both) of *SSL_CAfile* or *SSL_CApath* is set.
-: File containing trusted certificates to use during server
- certificate authentication if `SSL_verify=YES`.
+*SSL_hostname*
+
+: Name to use for the TLS SNI (Server Name Indication) extension. The
+ default value is taken from the *host* option when it is a hostname,
+ and to the empty string when it is an IP literal.
+ Setting *SSL_hostname* to the empty string explicitly disables SNI.
Control flow {#control-flow}
============
@@ -303,7 +341,7 @@ In more details, `pullimap` works as follows:
to terminate it gracefully.
3. Issue a `UID STORE` command to mark all retrieved messages (and
- stalled UIDs found in the *statefile* after the eigth byte) as
+ stalled UIDs found in the *statefile* after the eighth byte) as
`\Seen`.
4. Update the *statefile* with the new UIDNEXT value (bytes 5-8).
@@ -372,5 +410,5 @@ Standards
[`fetchmail`(1)]: https://www.fetchmail.info/
[`getmail`(1)]: http://pyropus.ca/software/getmail/
[`write`(2)]: https://man7.org/linux/man-pages/man2/write.2.html
-[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html
-[`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/verify.html
+[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html
+[`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-verify.html
diff --git a/doc/template.html b/doc/template.html
index d825cde..c3809ad 100644
--- a/doc/template.html
+++ b/doc/template.html
@@ -14,7 +14,7 @@ $if(keywords)$
<meta name="keywords" content="$for(keywords)$$keywords$$sep$, $endfor$" />
$endif$
<title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
- <style type="text/css">
+ <style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-01 00:38:54 +0000