diff options
Diffstat (limited to 'doc/development.md')
| -rw-r--r-- | doc/development.md | 87 |
1 files changed, 46 insertions, 41 deletions
diff --git a/doc/development.md b/doc/development.md index 52ebf90..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 =================== @@ -72,7 +78,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 S: * PREAUTH [CAPABILITY IMAP4rev1 …] Logged in as testuser C: a LIST "" "*" S: * LIST (\HasNoChildren) "." INBOX @@ -88,10 +94,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 --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 + doveadm -c "$BASEDIR/dovecot.conf" exec dovecot-lda -e -m "foo" <<-EOF From: <sender@example.net> To: <recipient@example.net> Subject: Hello world! @@ -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,8 +150,8 @@ 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" \ - --watch=1 --debug + $ env -i PATH="$PATH" perl -T ./interimap --config="$BASEDIR/interimap.conf" \ + --watch=1 --debug Use instructions from the [previous section][Mail storage access] (substituting `testuser` with `local` or `remote`) in order to simulate @@ -168,13 +174,13 @@ 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 + $ 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" \ - --no-delivery --idle --debug foo + $ 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] in order to simulate activity on the “remote” server (in the relevant @@ -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/dovecot_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 |