Merge tag 'v0.5.8' into debian/latest

Release version 0.5.8

1 files changed, 37 insertions, 32 deletions

diff --git a/doc/development.md b/doc/development.md
index 0fe54f4..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
@@ -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://doc.dovecot.org/configuration_manual/protocols/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://doc.dovecot.org/configuration_manual/mail_location/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