Merge branch 'main' into var-expand-system

.github/actions/spelling/patterns.txt

@@ -107,7 +107,8 @@ d88ff1001d4bf753a1b800001accfe22
 &U,BTFw-
 &ZeVnLIqe-
 -adnPNSx
-
+F=DFMPhnu9,
+SPfne
 \bAPPEND(?:ed|s)
 
 #
@@ -156,3 +157,6 @@ key=[0-9a-f]+:\w+\}\s*=\s*(?:[0-9a-f$]+|pass)
 
 # ignore long runs of a single character:
 \b([A-Za-z])\g{-1}{3,}\b
+
+# directory permissions
+[-bcdlpsw](?:[-r][-w][-SsTtx]){3}[\.+*]?\s+\d+\s+\S+\s+\S+\s+\d+\s+

source/admin_manual/clients.rst

@@ -42,7 +42,7 @@ the beginning of the mbox file.
 
 In any case it's still a good idea to filter out X-UID: and other
 metadata headers in your MDA. :ref:`Dovecot's deliver <lda>` does
-this internally. See :ref:`known_issues_mbox_problems` for a list
+this internally. See :ref:`known_issues-mbox_problems` for a list
 of headers to filter out.
 
 Fixing

source/admin_manual/debugging/debugging_authentication.rst

@@ -34,7 +34,7 @@ For simulating a full login with both passdb and userdb lookup, use:
 PLAIN SASL mechanism
 ====================
 
-With IMAP and POP3 it's easy to log in manually using the IMAP's LOGIN command or POP3's USER and PASS commands (see `TestInstallation <https://wiki.dovecot.org/TestInstallation>`_ and `TestPop3Installation <https://wiki.dovecot.org/TestPop3Installation>`_ for details), but with SMTP AUTH you'll need to use PLAIN authentication mechanism, which requires you to build a base64-encoded string in the correct format. The PLAIN authentication is also used internally by both IMAP and POP3 to authenticate to dovecot-auth, so you see it in the debug logs.
+With IMAP and POP3 it's easy to log in manually using the IMAP's LOGIN command or POP3's USER and PASS commands (see :ref:`testing_installation` for details), but with SMTP AUTH you'll need to use PLAIN authentication mechanism, which requires you to build a base64-encoded string in the correct format. The PLAIN authentication is also used internally by both IMAP and POP3 to authenticate to dovecot-auth, so you see it in the debug logs.
 
 The PLAIN mechanism's authentication format is: <authorization ID> NUL <authentication ID> NUL <password>. Authorization ID is the username who you want to log in as, and authentication ID is the username whose password you're giving. If you're not planning on doing a `master user login <authentication-master_users>`, you can either set both of these fields to the same username, or leave the authorization ID empty.
 

source/admin_manual/debugging/mail_debugging.rst

@@ -4,7 +4,7 @@
  Mail Debugging
 ==================
 
-Setting ``mail_debug=yes`` will make Dovecot log all kinds of things about mailbox initialization. Note that it won't increase error logging at all, so if you're having some random problems it's unlikely to provide any help.
+Setting :dovecot_core:ref:`log_debug` will make Dovecot log all kinds of things about mailbox initialization. Note that it won't increase error logging at all, so if you're having some random problems it's unlikely to provide any help.
 
 If there are any problems with a mailbox, Dovecot should automatically fix it. If that doesn't work for any reason, you can manually also request fixing a mailbox by running: ``doveadm force-resync -u user@domain INBOX``
 
@@ -14,4 +14,4 @@ Users may sometimes complain that they have lost emails. The problem is almost a
 
 For this reason it's very useful to enable the ``mail_log`` plugin and enable logging for all the events that may cause mails to be lost. This way it's always possible to find out from the logs what exactly caused messages to be deleted.
 
-If you're familiar enough with Dovecot's index files, you can use ``doveadm dump`` command to look at their contents in human readable format and possibly determine if there is something wrong in them.
+If you're familiar enough with Dovecot's index files, you can use ``doveadm dump`` command to look at their contents in human readable format and possibly determine if there is something wrong in them.

source/admin_manual/find_mail_location.rst

@@ -0,0 +1,66 @@
+.. _find_mail_location:
+
+Finding Your Mail
+=================
+
+Before configuring Dovecot, you'll need to know where your mails are
+located. You should already have an SMTP server installed and configured
+to deliver mails somewhere, so the easiest way to make Dovecot work is
+to just use the same location. Otherwise you could create a ``~/Maildir``
+directory and configure your SMTP server to use the Maildir format.
+
+First send a test mail to yourself (as your own non-root user):
+
+::
+
+   echo "Hello me" | mail -s "Dovecot test" $USER
+
+Now, find where the mail went. Here's a simple script which checks the
+most common locations:
+
+::
+
+   for mbox in /var/mail/$USER /var/spool/mail/$USER ~/mbox ~/mail/* ~/*; do
+     grep -q "Dovecot test" "$mbox" && echo "mbox: $mbox"
+   done
+   grep -q "Dovecot test" ~/Maildir/new/* 2>/dev/null && echo "Maildir: ~/Maildir"
+
+mbox
+----
+
+In most installations your mail went to ``/var/mail/username`` file.
+This file is called **INBOX** in IMAP world. Since IMAP supports
+multiple mailboxes, you'll also have to have a directory for them as
+well. Usually ``~/mail`` is a good choice for this. For installation
+such as this, the mail location is specified with (typically in
+``conf.d/10-mail.conf``):
+
+::
+
+   mail_location = mbox:~/mail:INBOX=/var/mail/%u
+
+Where ``%u`` is replaced with the username that logs in. Similarly if
+your INBOX is in ``~/mbox``, use:
+
+::
+
+   mail_location = mbox:~/mail:INBOX=~/mbox
+
+Maildir
+-------
+
+Maildir exists almost always in ``~/Maildir`` directory. The mail
+location is specified with (typically in ``conf.d/10-mail.conf``):
+
+::
+
+   mail_location = maildir:~/Maildir
+
+Problems?
+---------
+
+If you can't find the mail, you should check your SMTP server logs and
+configuration to see where it went or what went wrong.
+
+If you can find the mail, but it's in more exotic location, see if
+:ref:`mail_location_settings` can help you to configure it.

source/admin_manual/importing_mailboxes.rst

@@ -4,7 +4,7 @@
 Importing mailboxes
 ===================
 
-For importing mails, dovecot has `doveadm import <https://wiki.dovecot.org/Tools/Doveadm/Import>`_ command.
+For importing mails, dovecot has the :man:`doveadm-import(1)` command.
 
 .. warning::
 
@@ -63,7 +63,7 @@ In some disaster recovery cases you may end up having mails for the same user
 in two different locations, and need to merge them. For example the storage
 goes down and fixing it takes a long time, so during the fixing you can let the
 users access their emails as an empty account, which can receive new mails.
-Later on you can use ``doveadm import`` to merge the mailboxes.
+Later on you can use :man:`doveadm-import(1)` to merge the mailboxes.
 
 Note that there is no way to make this solution perfect:
  * IMAP clients that have cached mails locally will delete their local caches
@@ -107,7 +107,7 @@ mails") where mail storage broke down, but a separate index storage is ok, and
 index storage supports snapshots:
 
  * Snapshot the current index volume at the time of breakage
- * Make sure ``mail_location`` setting has ``ITERINDEX`` feature enabled, so
+ * Make sure :dovecot_core:ref:`mail_location` setting has ``ITERINDEX`` feature enabled, so
    folder listing is done using the index volume rather than the mail volume.
  * Mount a new empty mail volume
 
@@ -124,13 +124,13 @@ index storage supports snapshots:
    looks exactly like it was at the time of breakage.
  * Mount the new mail volume to some temporary mountpoint.
  * Mount the second index snapshot to some temporary mountpoint.
- * Use ``doveadm import`` to recover new mails:
+ * Use :man:`doveadm-import(1)` to recover new mails:
 
    .. code-block::
 
      doveadm import -u [email protected] sdbox:/mnt/temp-mail-storage/user:INDEX=/mnt/temp-index-storage/user:CONTROL=/mnt/temp-index-storage/user:ITERINDEX "" all
 
-   If your normal ``mail_location`` has other settings, you may also want to
+   If your normal :dovecot_core:ref:`mail_location` has other settings, you may also want to
    specify them using some temporary locations. For example
    ``VOLATILEDIR=/tmp/doveadm-import/user:LISTINDEX=/tmp/doveadm-import/user/dovecot.list.index``
    and after importing delete the directories.

source/admin_manual/index.rst

@@ -21,6 +21,7 @@ Administrative Manual
    errors/index
    event_design
    event_reasons
+   find_mail_location
    filesystem_permission
    health_check
    imap_preview
@@ -47,6 +48,7 @@ Administrative Manual
    ssl/index
    submission_server
    system_users_used_by_dovecot
+   test_installation
    testing
    timeouts
    troubleshooting

source/admin_manual/known_issues/mbox_problems.rst

@@ -1,4 +1,4 @@
-.. _known_issues_mbox_problems:
+.. _known_issues-mbox_problems:
 
 =============
 mbox problems

source/admin_manual/logging.rst

@@ -145,7 +145,7 @@ There are several settings that control logging verbosity. By default they're al
 
 * :dovecot_core:ref:`auth_debug_passwords=yes <auth_debug_passwords>` removes password hiding (but only if you are not using PAM, since PAM errors aren't written to Dovecot's own logs).
 
-* :dovecot_core:ref:`mail_debug=yes <mail_debug>` enables all kinds of mail related debug logging, such as showing where Dovecot is looking for mails.
+* :dovecot_core:ref:`log_debug = category=mail <log_debug>` enables all kinds of mail related debug logging, such as showing where Dovecot is looking for mails.
 
 * :dovecot_core:ref:`verbose_ssl=yes <verbose_ssl>` enables logging SSL errors and warnings. Even without this setting if connection is closed because of an SSL error, the error is logged as the disconnection reason.
 

source/admin_manual/mailbox_formats/dbox.rst

@@ -160,7 +160,7 @@ mails to other mdbox files (to the same files as where newly saved messages
 would also go), updates the map index and finally deletes the original file.
 So there is never any overwriting or file truncation.
 
-The purging can be invoked explicitly running `doveadm purge`_.
+The purging can be invoked explicitly running :man:`doveadm-purge(1)`.
 
 There are several safety features built into dbox to avoid losing messages or
 their state if map index or mailbox index gets corrupted:
@@ -177,8 +177,6 @@ their state if map index or mailbox index gets corrupted:
   to their initial mailboxes. This is better than placing everything into a
   single mailbox.
 
-.. _`doveadm purge`: https://wiki.dovecot.org/Tools/Doveadm/Purge
-
 .. _dbox_mbox_format_alt_storage:
 
 Alternate Storage
@@ -200,7 +198,7 @@ under ``mdbox``) is moved to alternate storage; everything else remains in
 the primary storage.
 
 Message data can be moved from primary storage to alternate storage using
-`doveadm altmove`_. (In theory you could also do this with some combination
+:man:`doveadm-altmove(1)`. (In theory you could also do this with some combination
 of cp/mv, but better not to go there unless you really need to. The updates
 must be atomic in any case, so cp won't work.)
 
@@ -219,8 +217,6 @@ IMAP/POP command which could be used to expose this information. It is
 entirely possible to have a mail folder which contains a mix of messages
 stored in primary storage and alternate storage.
 
-.. _`doveadm altmove`: https://wiki.dovecot.org/Tools/Doveadm/Altmove
-
 dbox and Mail Header Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -248,7 +244,7 @@ Accessing Expunged Mails with mdbox
 ``mdbox_deleted`` storage can be used to access mdbox's all mails that are
 completely deleted (reference count = 0). The ``mdbox_deleted`` parameters
 should otherwise be exactly the same as ``mdbox``'s. Then you can use
-e.g. `doveadm fetch`_ or `doveadm import`_ commands to access the mails.
+e.g. :man:`doveadm-fetch(1)` or :man:`doveadm-import(1)` commands to access the mails.
 
 For example:
 
@@ -259,9 +255,6 @@ For example:
 
 This finds a deleted mail with subject "oops" and imports it into INBOX.
 
-.. _`doveadm fetch`: https://wiki.dovecot.org/Tools/Doveadm/Fetch
-.. _`doveadm import`: https://wiki.dovecot.org/Tools/Doveadm/Import
-
 Mail Delivery
 ^^^^^^^^^^^^^
 

source/admin_manual/mailbox_formats/mbox.rst

@@ -292,4 +292,4 @@ How a message is read stored in mbox extension
 See also
 ========
 
- - :ref:`known_issues_mbox_problems`
+ - :ref:`known_issues-mbox_problems`

source/admin_manual/mda.rst

@@ -15,8 +15,8 @@ virtual mailbox.
 
 Common choices include:
 
--  `maildrop <https://maildrop.cc>`_
+-  `maildrop <https://www.courier-mta.org/maildrop/download.html>`_
 
--  `procmail <https://www.procmail.org/>`_ (appears to be unmaintained)
+-  `procmail <https://porkmail.org/era/procmail/>`__
 
--  :ref:`Dovecot's \`dovecot-lda\` LDA <lda>`
+-  :ref:`Dovecot's 'dovecot-lda' LDA <lda>`

source/admin_manual/pigeonhole_managesieve_server.rst

@@ -24,8 +24,6 @@ Configuration and Use
 =====================
 
 * :ref:`Download and Installation <sieve_installation>`
-* `Configuration
-  <https://wiki.dovecot.org/Pigeonhole/ManageSieve/Configuration>`_
-* `Troubleshooting
-  <https://wiki.dovecot.org/Pigeonhole/ManageSieve/Troubleshooting>`_
-* `Client Issues <https://wiki.dovecot.org/Pigeonhole/ManageSieve/Clients>`_
+* :ref:`Configuration <sieve_managesieve-configuration>`
+* :ref:`Troubleshooting <sieve_managesieve-troubleshooting>`
+* :ref:`Client Issues <sieve_managesieve-client_issues>`

source/admin_manual/post_login_scripting.rst

@@ -79,8 +79,7 @@ You can change any Dovecot settings using the above method.
 Changing user's password after login
 ====================================
 
-See `HowTo/ConvertPasswordSchemes
-<https://wiki.dovecot.org/HowTo/ConvertPasswordSchemes>`_
+See :ref:`howto-convert_password_schemes`
 
 Last-login tracking
 ===================

source/admin_manual/system_users_used_by_dovecot.rst

@@ -6,56 +6,56 @@ System users used by Dovecot
 
 Dovecot typically requires 3 or more system users:
 
-* `root`: Dovecot is started as root.
-* `dovenull`: Dovecot uses an unprivileged dovenull user for untrusted login
+* ``root``: Dovecot is started as root.
+* ``dovenull``: Dovecot uses an unprivileged dovenull user for untrusted login
   processes.
-* `dovecot`: Dovecot uses an unprivileged dovecot user for internal processes.
-* `auth user`: Password and user database lookups are done as auth user.
-* `mail user(s)`: Mails are accessed using yet another user. The mail user
+* ``dovecot``: Dovecot uses an unprivileged dovecot user for internal processes.
+* ``auth user``: Password and user database lookups are done as auth user.
+* ``mail user(s)``: Mails are accessed using yet another user. The mail user
   should not be dovecot user.
 
 Using multiple users allows privilege separation, which makes it harder for
 attackers to compromise the whole system if a security hole is found from one
 component. However, if you really want to run everything under a single user,
-`it's possible <https://wiki.dovecot.org/HowTo/Rootless>`_.
+:ref:`it's possible <howto-rootless>`.
 
 Dovenull user
 =============
 
-`dovenull` user is used internally for processing users' logins. It shouldn't
+``dovenull`` user is used internally for processing users' logins. It shouldn't
 have access to any files, authentication databases or anything else either. It
 should belong to its own private **dovenull** group where no one else belongs
 to, and which doesn't have access to any files either (other than what Dovecot
 internally creates).
 
-You can change the default `dovenull` user to something else from
-``default_login_user`` setting.
+You can change the default ``dovenull`` user to something else from
+:dovecot_core:ref:`default_login_user` setting.
 
 Dovecot user
 ============
 
-`dovecot` user is used internally for unprivileged Dovecot processes. It should
-belong to its own private dovecot group. Mail files are not accessed as dovecot
-user, so you shouldn't give it access to mails.
+``dovecot`` user is used internally for unprivileged Dovecot processes.
+It should belong to its own private ``dovecot`` group. Mail files are
+not accessed as dovecot user, so you shouldn't give it access to mails.
 
-You can change the default dovecot user to something else from
-``default_internal_user`` setting.
+You can change the default ``dovecot`` user to something else from
+:dovecot_core:ref:`default_internal_user` setting.
 
 Mail users
 ==========
 
 You can use one or more system users for accessing users' mails. Most
 configurations can be placed to two categories:
 
-1. `System users <https://wiki.dovecot.org/SystemUsers>`_ where each Dovecot
+1. :ref:`System users <system_users>` where each Dovecot
    user has their own system user in ``/etc/passwd``. For system user setups
    you generally don't have to worry about UIDs or GIDs, they are returned by
    the userdb passwd lookup.
-2. `Virtual users <https://wiki.dovecot.org/VirtualUsers>`_ where all Dovecot
+2. :ref:`Virtual users <virtual_users>` where all Dovecot
    users run under a single system user. Typically you'd set this with
-   ``mail_uid`` setting (e.g. ``mail_uid=vmail``). Note that you most likely
+   :dovecot_core:ref:`mail_uid` setting (e.g. ``mail_uid=vmail``). Note that you most likely
    don't want the userdb lookup to return any UID/GID, as they override the
-   ``mail_uid`` setting.
+   :dovecot_core:ref:`mail_uid` setting.
 
 However it's possible to use a setup that is anything between these two. For
 example use a separate system user for each domain. See below for more
@@ -83,7 +83,7 @@ There are a few things you should know about them:
 * By default Dovecot allows users to log in only with UID numbers 500 and
   above. This check tries to make sure that no-one can ever log in as daemons
   or other system users. If you're using an UID lower than 500, you'll need to
-  change the ``first_valid_uid`` setting.
+  change the :dovecot_core:ref:`first_valid_uid` setting.
 
 GIDs
 ====
@@ -114,7 +114,7 @@ version the whole GID list will be configurable without help from
 ``/etc/group``.
 
 It's also possible to give all the users access to extra groups with
-``mail_access_groups`` setting.
+:dovecot_core:ref:`mail_access_groups` setting.
 
 Authentication process user
 ===========================