From 3db2d1d326bea54311e0c664f6b63a33b2850c23 Mon Sep 17 00:00:00 2001 From: Aki Tuomi Date: Wed, 11 Oct 2023 15:16:59 +0300 Subject: [PATCH 01/10] global: Remove wiki.dovecot.org links that are in doc already and fix some links --- source/admin_manual/clients.rst | 2 +- source/admin_manual/importing_mailboxes.rst | 10 +++---- .../known_issues/mbox_problems.rst | 2 +- source/admin_manual/mailbox_formats/dbox.rst | 13 ++------- source/admin_manual/mailbox_formats/mbox.rst | 2 +- .../system_users_used_by_dovecot.rst | 28 +++++++++---------- .../authentication/domain_lost.rst | 2 ++ .../multiple_authentication_databases.rst | 4 +-- .../authentication/passwd_file.rst | 3 +- .../authentication/sql.rst | 2 +- .../howto/postfix_dovecot_lmtp.rst | 2 ++ .../configuration_manual/howto/rootless.rst | 2 ++ .../mail_compress_plugin.rst | 3 +- .../configuration_manual/namespace/index.rst | 2 +- source/configuration_manual/plugins/index.rst | 2 ++ source/configuration_manual/protocols/lda.rst | 3 +- .../protocols/lmtp_server.rst | 4 +-- .../protocols/pop3_server.rst | 6 ++-- .../sieve/pigeonhole_sieve_interpreter.rst | 2 +- .../sieve/plugins/extprograms.rst | 3 +- .../sieve/sieve_and_smtp_submission.rst | 2 +- source/configuration_manual/virtual_users.rst | 2 ++ .../development_tips/debugging_tips.rst | 2 +- .../upgrading/from-0.9-to-1.0.rst | 2 +- .../upgrading/from-2.2-to-2.3.rst | 2 +- .../settings/plugin/pop3-migration-plugin.rst | 2 +- 26 files changed, 54 insertions(+), 55 deletions(-) diff --git a/source/admin_manual/clients.rst b/source/admin_manual/clients.rst index fa70475ec8..1bfe64a79a 100644 --- a/source/admin_manual/clients.rst +++ b/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 ` 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 diff --git a/source/admin_manual/importing_mailboxes.rst b/source/admin_manual/importing_mailboxes.rst index 499c3a5082..c4b30623d1 100644 --- a/source/admin_manual/importing_mailboxes.rst +++ b/source/admin_manual/importing_mailboxes.rst @@ -4,7 +4,7 @@ Importing mailboxes =================== -For importing mails, dovecot has `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 user@example.com 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. diff --git a/source/admin_manual/known_issues/mbox_problems.rst b/source/admin_manual/known_issues/mbox_problems.rst index 4f43011fa3..4b2e4903f8 100644 --- a/source/admin_manual/known_issues/mbox_problems.rst +++ b/source/admin_manual/known_issues/mbox_problems.rst @@ -1,4 +1,4 @@ -.. _known_issues_mbox_problems: +.. _known_issues-mbox_problems: ============= mbox problems diff --git a/source/admin_manual/mailbox_formats/dbox.rst b/source/admin_manual/mailbox_formats/dbox.rst index e8c0be8c59..642d3e3bd8 100644 --- a/source/admin_manual/mailbox_formats/dbox.rst +++ b/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 ^^^^^^^^^^^^^ diff --git a/source/admin_manual/mailbox_formats/mbox.rst b/source/admin_manual/mailbox_formats/mbox.rst index 1146191dbb..8296115589 100644 --- a/source/admin_manual/mailbox_formats/mbox.rst +++ b/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` diff --git a/source/admin_manual/system_users_used_by_dovecot.rst b/source/admin_manual/system_users_used_by_dovecot.rst index 2ede6f9f88..dc174b3dc2 100644 --- a/source/admin_manual/system_users_used_by_dovecot.rst +++ b/source/admin_manual/system_users_used_by_dovecot.rst @@ -7,9 +7,9 @@ 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 +* ``dovenull``: Dovecot uses an unprivileged dovenull user for untrusted login processes. -* `dovecot`: Dovecot uses an unprivileged dovecot user for internal 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 should not be dovecot user. @@ -17,29 +17,29 @@ Dovecot typically requires 3 or more system users: 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 `_. +:ref:`it's possible `. 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 +``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. +:dovecot_core:ref:`default_internal_user` setting. Mail users ========== @@ -47,15 +47,15 @@ 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 `_ where each Dovecot +1. :ref:`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 `_ where all Dovecot +2. :ref:`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 =========================== diff --git a/source/configuration_manual/authentication/domain_lost.rst b/source/configuration_manual/authentication/domain_lost.rst index 78aa19b32d..29054c1558 100644 --- a/source/configuration_manual/authentication/domain_lost.rst +++ b/source/configuration_manual/authentication/domain_lost.rst @@ -1,3 +1,5 @@ +.. _authentication-domain_lost: + ==================== Domain (%d) is empty ==================== diff --git a/source/configuration_manual/authentication/multiple_authentication_databases.rst b/source/configuration_manual/authentication/multiple_authentication_databases.rst index c781e353af..6bd67f7eee 100644 --- a/source/configuration_manual/authentication/multiple_authentication_databases.rst +++ b/source/configuration_manual/authentication/multiple_authentication_databases.rst @@ -13,8 +13,8 @@ Currently the fallback works only with the PLAIN authentication mechanism. Often you also want a different mail location for system and virtual users. The best way to do this would be to always have mails stored below the home -directory (`virtual users should have a home directory too -`_): +directory (:ref:`virtual users should have a home directory too +`): * System users' mails: /home/user/Maildir * Virtual users' mails: /var/vmail/domain/user/Maildir diff --git a/source/configuration_manual/authentication/passwd_file.rst b/source/configuration_manual/authentication/passwd_file.rst index 77c9130597..66cd6f3274 100644 --- a/source/configuration_manual/authentication/passwd_file.rst +++ b/source/configuration_manual/authentication/passwd_file.rst @@ -14,8 +14,7 @@ plugin. It's in the following format: For a password database it's enough to have only the user and password fields. For a user database, you need to set also uid, gid and preferably also home -(see `VirtualUsers `_). (gecos) and -(shell) fields are unused by Dovecot. +(see :ref:`virtual_users`). (gecos) and (shell) fields are unused by Dovecot. The password field can be in four formats: diff --git a/source/configuration_manual/authentication/sql.rst b/source/configuration_manual/authentication/sql.rst index 8c5ae0a22a..6bff3cc713 100644 --- a/source/configuration_manual/authentication/sql.rst +++ b/source/configuration_manual/authentication/sql.rst @@ -54,7 +54,7 @@ meaning. You can't use multiple statements in one query, but you could use a stored procedure. If you want something like a last login update, use -`PostLoginScripting `_ instead. +:ref:`post_login_scripting` instead. Password verification by SQL server =================================== diff --git a/source/configuration_manual/howto/postfix_dovecot_lmtp.rst b/source/configuration_manual/howto/postfix_dovecot_lmtp.rst index 86f1447ff4..22623f4d68 100644 --- a/source/configuration_manual/howto/postfix_dovecot_lmtp.rst +++ b/source/configuration_manual/howto/postfix_dovecot_lmtp.rst @@ -1,3 +1,5 @@ +.. _howto-postfix_dovecot_lmtp: + ======================== Postfix and Dovecot LMTP ======================== diff --git a/source/configuration_manual/howto/rootless.rst b/source/configuration_manual/howto/rootless.rst index eaa4095b8a..7fbce710a7 100644 --- a/source/configuration_manual/howto/rootless.rst +++ b/source/configuration_manual/howto/rootless.rst @@ -1,3 +1,5 @@ +.. _howto-rootless: + ===================== Rootless Installation ===================== diff --git a/source/configuration_manual/mail_compress_plugin.rst b/source/configuration_manual/mail_compress_plugin.rst index a58a5c25e5..0e16a2a873 100644 --- a/source/configuration_manual/mail_compress_plugin.rst +++ b/source/configuration_manual/mail_compress_plugin.rst @@ -42,8 +42,7 @@ or .bz2 extension. There is no support for compression during saving. ----------------------- Mails can be stored as compressed. Existing uncompressed mails can't currently -be directly compressed (or vice versa). You could, however, use `dsync -`_ +be directly compressed (or vice versa). You could, however, use :man:`doveadm-sync(1)` to copy all mails to another location (which saves them compressed) and then replace the original location with the new compressed location. You can do this by treating the operation the same as if you were migrating from one mailbox diff --git a/source/configuration_manual/namespace/index.rst b/source/configuration_manual/namespace/index.rst index 7b0bbc5e88..116f5cb6e3 100644 --- a/source/configuration_manual/namespace/index.rst +++ b/source/configuration_manual/namespace/index.rst @@ -441,7 +441,7 @@ The alternative configuration is not recommended, as it may introduce issues: (Sent, Drafts etc) if the client settings refer to old paths while the server lists new paths. -See also `Migration/Courier `_ +See also :ref:`migrating_mailboxes` Per-user Namespace Location From SQL ------------------------------------ diff --git a/source/configuration_manual/plugins/index.rst b/source/configuration_manual/plugins/index.rst index 2ed741509f..dbac8c17d2 100644 --- a/source/configuration_manual/plugins/index.rst +++ b/source/configuration_manual/plugins/index.rst @@ -1,3 +1,5 @@ +.. _plugins: + ===================== Plugin configurations ===================== diff --git a/source/configuration_manual/protocols/lda.rst b/source/configuration_manual/protocols/lda.rst index 61cdf3bcff..c4b7d8322f 100644 --- a/source/configuration_manual/protocols/lda.rst +++ b/source/configuration_manual/protocols/lda.rst @@ -4,8 +4,7 @@ Dovecot LDA =========== -The Dovecot LDA is a `local delivery -agent `_, which takes mail from an :ref:`mta` +The Dovecot LDA is a :ref:`mail delivery agent `, which takes mail from an :ref:`mta` and delivers it to a user's mailbox, while keeping Dovecot index files up to date. Nowadays you should probably use the `LMTP server ` instead, because it's somewhat easier to configure (especially related to diff --git a/source/configuration_manual/protocols/lmtp_server.rst b/source/configuration_manual/protocols/lmtp_server.rst index 98cc1a6111..c3228ee0db 100644 --- a/source/configuration_manual/protocols/lmtp_server.rst +++ b/source/configuration_manual/protocols/lmtp_server.rst @@ -88,7 +88,7 @@ For rawlogs, please see :ref:`debugging_rawlog` Plugins ======= -* Most of the `Dovecot plugins `_ work with LMTP. +* Most of the :ref:`Dovecot plugins ` work with LMTP. * Virtual quota can be enforced using :ref:`Quota plugin `. @@ -107,7 +107,7 @@ To make address extension work with LMTP you must check these variables are set Using LMTP with different MTAs ============================== -* `Postfix `_ +* :ref:`Postfix ` * `Exim `_ diff --git a/source/configuration_manual/protocols/pop3_server.rst b/source/configuration_manual/protocols/pop3_server.rst index 245429f8ca..d8179932c6 100644 --- a/source/configuration_manual/protocols/pop3_server.rst +++ b/source/configuration_manual/protocols/pop3_server.rst @@ -101,7 +101,7 @@ which the users don't really appreciate. Dovecot supports multiple different ways to set the UIDL format, mostly to make migrations from other POP3 servers transparent by preserving the old UIDL -values. See `Migration `_ for how to set +values. See :ref:`migrating_mailboxes` for how to set the UIDLs to be compatible with your previous POP3 server. For new POP3 servers, the easiest way to set up UIDLs is to use IMAP's @@ -138,9 +138,9 @@ files in ways that Dovecot doesn't like, without causing the UIDLs to change. For example: * Inserting messages in the middle of mbox files (eg. restoring mbox files from - backups can cause `Expunged message reappeared` errors) + backups can cause ``Expunged message reappeared`` errors) * Reordering messages inside mbox -* `Other random problems `_ causing UID +* :ref:`Other random problems ` causing UID renumbering (although you should figure out why they're happening) The MD5 summing method however doesn't work well if you receive two identical diff --git a/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst b/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst index ee419588c5..2787d62642 100644 --- a/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst +++ b/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst @@ -90,7 +90,7 @@ Extension `vnd.dovecot.environment `_ supported (v0.4.14+) no Extends the standard "environment" extension with extra items and a variables namespace for direct access `vnd.dovecot.execute `_ :ref:`Extprograms Plugin ` (v0.3+) no Implements executing a pre-defined set of external programs with the option to process string data through the external program `vnd.dovecot.filter `_ :ref:`Extprograms plugin ` (v0.3+) no Implements filtering messages through a pre-defined set of external programs -`vnd.dovecot.pipe `_ `Pipe Plugin `_ (v0.2), no Implements piping messages to a pre-defined set of external programs +`vnd.dovecot.pipe `_ See :ref:`Extprograms plugin ` no Implements piping messages to a pre-defined set of external programs :ref:`pigeonhole_plugin_extprograms` (v0.3+) vnd.dovecot.report `_ supported (v0.4.14+) no Implements sending Messaging Abuse Reporting Format (MARF) reports (:rfc:`5965`) ============================================================================================================================================ =================================================================================================================== ===================== ================================================================================================================================================== diff --git a/source/configuration_manual/sieve/plugins/extprograms.rst b/source/configuration_manual/sieve/plugins/extprograms.rst index 0509457698..fee78b84d8 100644 --- a/source/configuration_manual/sieve/plugins/extprograms.rst +++ b/source/configuration_manual/sieve/plugins/extprograms.rst @@ -14,8 +14,7 @@ programs are restricted through administrator configuration. This plugin is only available for Pigeonhole v0.3 and higher (available for Dovecot v2.1). For Pigeonhole -v0.4 this plugin is part of the release. This an evolution of the `Pipe -plugin `_ +v0.4 this plugin is part of the release. This is an evolution of the pipe plugin for Pigeonhole v0.2 and now provides the ``filter`` and ``execute`` commands (and corresponding extensions) in addition to the ``pipe`` command that was provided earlier by the Pipe plugin. diff --git a/source/configuration_manual/sieve/sieve_and_smtp_submission.rst b/source/configuration_manual/sieve/sieve_and_smtp_submission.rst index 458c677e0a..74c847f302 100644 --- a/source/configuration_manual/sieve/sieve_and_smtp_submission.rst +++ b/source/configuration_manual/sieve/sieve_and_smtp_submission.rst @@ -11,7 +11,7 @@ Email address to use in the From: field for outgoing email rejections. The ``%d`` variable expands to the recipient domain. -See https://wiki.dovecot.org/DomainLost for details when this does not work. +See :ref:`authentication-domain_lost` details when this does not work. .. code-block:: none diff --git a/source/configuration_manual/virtual_users.rst b/source/configuration_manual/virtual_users.rst index f51347c925..50128faf82 100644 --- a/source/configuration_manual/virtual_users.rst +++ b/source/configuration_manual/virtual_users.rst @@ -87,6 +87,8 @@ and multiple UIDs, it doesn't really matter what GIDs you use. You can, for example, use a single GID for all users, or create a separate GID for each user. See :ref:`system_users_used_by_dovecot` for more information. +.. _virtual_users-homedir: + Home directories ---------------- diff --git a/source/developer_manual/development_tips/debugging_tips.rst b/source/developer_manual/development_tips/debugging_tips.rst index 72e88ff451..9fbaaadf9a 100644 --- a/source/developer_manual/development_tips/debugging_tips.rst +++ b/source/developer_manual/development_tips/debugging_tips.rst @@ -71,7 +71,7 @@ Standalone non-root debugging environments Dovecot can be instructed to run the imap handler as a non-root user, and therefore that binary can be debugged by that same non-root user. At the moment, only manual (telnet) interaction is possible. This setup is -documented in https://wiki.dovecot.org/HowTo/Rootless. +documented in :ref:`howto-rootless`. Disabling optimizations ======================= diff --git a/source/installation_guide/upgrading/from-0.9-to-1.0.rst b/source/installation_guide/upgrading/from-0.9-to-1.0.rst index 9efa2e605f..71d4476d98 100644 --- a/source/installation_guide/upgrading/from-0.9-to-1.0.rst +++ b/source/installation_guide/upgrading/from-0.9-to-1.0.rst @@ -84,7 +84,7 @@ The port settings are different. The new settings are:: Log Changes for POP before SMTP ------------------------------- -If you used `POP-before-SMTP `_ , the log strings are different. This should work with new versions:: +If you used POP before SMTP, the log strings are different. This should work with new versions:: $s =~ s/^... .. ..:..:.. .* dovecot: (pop3|imap)-login: Login: .+ rip=(\d+\.\d+\.\d+\.\d+),.*$/$2/i; diff --git a/source/installation_guide/upgrading/from-2.2-to-2.3.rst b/source/installation_guide/upgrading/from-2.2-to-2.3.rst index 48b36ec0e2..d49bf5a950 100644 --- a/source/installation_guide/upgrading/from-2.2-to-2.3.rst +++ b/source/installation_guide/upgrading/from-2.2-to-2.3.rst @@ -118,7 +118,7 @@ Diffie-Hellman Parameters for SSL Other Changes ------------- - * Invalid :dovecot_core:ref:`postmaster_address` now causes a failure early on with sieve/imap_sieve plugin enabled. It still defaults to ``postmaster@%d``, which expands to invalid ``postmaster@`` address if your usernames do not contain a domain, or are converted into domainless usernames by passdb/userdb. See https://wiki.dovecot.org/DomainLost. + * Invalid :dovecot_core:ref:`postmaster_address` now causes a failure early on with sieve/imap_sieve plugin enabled. It still defaults to ``postmaster@%d``, which expands to invalid ``postmaster@`` address if your usernames do not contain a domain, or are converted into domainless usernames by passdb/userdb. See :ref:`authentication-domain_lost`. * Linux: Dovecot no longer enables core dumping for "setuid processes", which most of them are. * To enable them with Linux kernel v3.6+: Make sure core dumps get written to a globally shared directory and enable them with: ``sysctl -w fs.suid_dumpable=2`` diff --git a/source/settings/plugin/pop3-migration-plugin.rst b/source/settings/plugin/pop3-migration-plugin.rst index 7213e2bab6..e33ffe5853 100644 --- a/source/settings/plugin/pop3-migration-plugin.rst +++ b/source/settings/plugin/pop3-migration-plugin.rst @@ -17,7 +17,7 @@ For some POP3 servers it's possible to use the more efficient correctly. If the UIDL format is wrong, all the mails have to be re-migrated. -.. seealso:: `Migrating from any IMAP/POP3 server to Dovecot via dsync `_ +.. seealso:: :ref:`Migrating from any IMAP/POP3 server to Dovecot via dsync ` This plugin requires a :ref:`pop3c ` namespace configured for accessing the source POP3 server. For example: From 9167177ed7fe924ab3affc34aac3e628391df536 Mon Sep 17 00:00:00 2001 From: Aki Tuomi Date: Wed, 11 Oct 2023 15:35:53 +0300 Subject: [PATCH 02/10] Add rest of managesieve documentation --- .../pigeonhole_managesieve_server.rst | 8 +- source/configuration_manual/sieve/index.rst | 6 + .../sieve/managesieve/client_issues.rst | 70 +++++++ .../sieve/managesieve/configuration.rst | 185 +++++++++++++++++ .../sieve/managesieve/troubleshooting.rst | 191 ++++++++++++++++++ source/settings/pigeonhole.rst | 13 ++ 6 files changed, 468 insertions(+), 5 deletions(-) create mode 100644 source/configuration_manual/sieve/managesieve/client_issues.rst create mode 100644 source/configuration_manual/sieve/managesieve/configuration.rst create mode 100644 source/configuration_manual/sieve/managesieve/troubleshooting.rst diff --git a/source/admin_manual/pigeonhole_managesieve_server.rst b/source/admin_manual/pigeonhole_managesieve_server.rst index a5a002ccab..e9166de322 100644 --- a/source/admin_manual/pigeonhole_managesieve_server.rst +++ b/source/admin_manual/pigeonhole_managesieve_server.rst @@ -24,8 +24,6 @@ Configuration and Use ===================== * :ref:`Download and Installation ` -* `Configuration - `_ -* `Troubleshooting - `_ -* `Client Issues `_ +* :ref:`Configuration ` +* :ref:`Troubleshooting ` +* :ref:`Client Issues ` diff --git a/source/configuration_manual/sieve/index.rst b/source/configuration_manual/sieve/index.rst index b5ac7a335f..5aea39ae90 100644 --- a/source/configuration_manual/sieve/index.rst +++ b/source/configuration_manual/sieve/index.rst @@ -29,6 +29,12 @@ Sieve troubleshooting + managesieve/configuration + + managesieve/troubleshooting + + managesieve/client_issues + .. _sieve_plugins: Sieve extensions and plugins diff --git a/source/configuration_manual/sieve/managesieve/client_issues.rst b/source/configuration_manual/sieve/managesieve/client_issues.rst new file mode 100644 index 0000000000..7e7f6c530d --- /dev/null +++ b/source/configuration_manual/sieve/managesieve/client_issues.rst @@ -0,0 +1,70 @@ +.. _sieve_managesieve-client_issues: + +ManageSieve Client Issues +========================= + +Although this ManageSieve server should comply with the :rfc:`5804` +specification of the ManageSieve protocol, quite a few clients don't. +This page lists the known client problems. + +The TLS problem +--------------- + +The core of the TLS problem is that a ManageSieve server is required +to send an unsolicited CAPABILITY response right after successful TLS +negotiation. Older Cyrus servers did not do this and many clients +incorporated this protocol error as the standard, meaning that these +do not expect the CAPABILITY response and thus fail with subsequent +commands. However, now that Cyrus' Timsieved has changed its +behaviour towards protocol compliance, all those clients will follow +eventually. The following clients are known to have this TLS issue: + +Thunderbird Sieve add-on + TLS broken for old versions. Starting with version 0.1.5 the + Thunderbird Sieve add-on properly supports TLS. + +KMail + kio_sieve + TLS broken for old versions. This issue is fixed at least in kmail + 1.9.9 / kde 3.5.9. + +SquirrelMail/AvelSieve + For some users the Avelsieve client stores scripts but fails to + retrieve them later. This problem is directly caused by + AvelSieve's TLS support. A quick way to fix this is not to enable + TLS for ManageSieve. AvelSieve stable (v1.0.1) does not have TLS + support at all, so you will see this happen only with the + development or SVN versions. Another issue is that (at least with + avelsieve-1.9.7) it is impossible to delete the last rule of a + script. For avelsieve-1.9.7 you find a patch that fixes these two + issues `here `__. + +Smartsieve, Websieve +-------------------- + +These clients are specifically written for Cyrus timsieved and fail +on multiple stages of the protocol when connected to Pigeonhole +ManageSieve. See: + + - https://sourceforge.net/projects/websieve/ + - https://github.com/secnextechnologies/WebSieve + - https://smartsieve.sourceforge.net/ + + +Ruby/Managesieve +---------------- + +Ruby command line client and library to managesieve works fine. +See https://rubygems.org/gems/ruby-managesieve/versions/0.4.0 + +Ruby/Sieve-Parser +----------------- + +Ruby library for sieve parsing, see https://rubygems.org/gems/sieve-parser/versions/0.0.4 + +.. note:: + + If you add new issues to this list, notify the author or send + an e-mail to the `Dovecot mailing + list `__. In any case, you must + make sure that the issue is properly explained and that the author can + contact you for more information. diff --git a/source/configuration_manual/sieve/managesieve/configuration.rst b/source/configuration_manual/sieve/managesieve/configuration.rst new file mode 100644 index 0000000000..b86ea0603c --- /dev/null +++ b/source/configuration_manual/sieve/managesieve/configuration.rst @@ -0,0 +1,185 @@ +.. _sieve_managesieve-configuration: + +ManageSieve Configuration +========================= + +**NOTE**: If you have used the Sieve plugin before and you have +``.dovecot.sieve`` files in user directories, you are advised to **make +a backup first**. Although the ManageSieve daemon takes care to move +these files to the Sieve storage before it is substituted with a +symbolic link, this is not a very well tested operation, meaning that +there is a possibility that existing Sieve scripts get lost. + +The ManageSieve configuration consists of ManageSieve protocol settings +and :ref:`Sieve interpreter `-related +settings. The Sieve interpreter settings are shared with settings of the +:ref:`Sieve plugin ` +for Dovecot's :ref:`Local Delivery Agent (LDA) ` and :ref:`LMTP `. +First, the ManageSieve protocol settings are outlined and then the +relevant Sieve settings are described. + +Protocol Configuration +---------------------- + +Along with all other binaries that Dovecot uses, the ``managesieve`` and +``managesieve-login`` binaries are installed during ``make install`` of the +:ref:`Pigeonhole ` package. +The only thing you need to do to activate the ManageSieve +protocol support in Dovecot is to add ``sieve`` to the :dovecot_core:ref:`protocols= ` +setting. The managesieve daemon will listen on port 4190 by default. +As the implementation of the managesieve daemon is largely based on the +original IMAP implementation, it is very similar in terms of configuration. +In addition to most mail daemon config settings, the managesieve daemon +accepts a few more. The following settings can be configured in the +``protocol sieve`` section: + +:pigeonhole:ref:`managesieve_max_line_length` + The maximum ManageSieve command line length in bytes. + +:pigeonhole:ref:`managesieve_logout_format` + Specifies the string pattern used to compose the logout message of an + authenticated session. + +:pigeonhole:ref:`managesieve_implementation_string` + Implementation name. + +:pigeonhole:ref:`managesieve_max_compile_errors` + Maximum compile errors. + +:pigeonhole:ref:`managesieve_client_workarounds` + List of client workarounds to enable. + +:pigeonhole:ref:`managesieve_sieve_capability` + +:pigeonhole:ref:`managesieve_notify_capability` + Respectively the SIEVE and NOTIFY capabilities reported by the ManageSieve + service before authentication. + +Sieve Interpreter Configuration +------------------------------- + +The part of the :ref:`Sieve interpreter ` +configuration that is relevant for ManageSieve mainly consists of the +settings that specify where the user's scripts are stored and where the +active script is located. The ManageSieve service primarily uses the +following Sieve interpreter setting in the ``plugin`` section of the +Dovecot configuration: + +:pigeonhole:ref:`sieve` = ``file:~/sieve;active=~/.dovecot.sieve`` + This specifies the + :ref:`location ` + where the scripts that are uploaded through ManageSieve are stored. + +Quota Support +------------- + +By default, users can manage an unlimited number of Sieve scripts on the +server through ManageSieve. However, ManageSieve can be configured to +enforce limits on the number of personal Sieve scripts per user and/or +the amount of disk storage used by these scripts. The maximum size of +individual uploaded scripts is dictated by the configuration of the +:ref:`Sieve interpreter `. +The limits are configured in the plugin section of the Dovecot +configuration as follows: + +:pigeonhole:ref:`sieve_max_script_size` + The maximum size of a Sieve script. + +:pigeonhole:ref:`sieve_quota_max_scripts` + The maximum number of personal Sieve scripts a single user can have. + +:pigeonhole:ref:`sieve_quota_max_storage` + The maximum amount of disk storage a single user's scripts may + occupy. + +Examples +-------- + +The following provides example configurations for ManageSieve in +dovecot.conf for the various versions. Only sections relevant to +ManageSieve and the Sieve plugin are shown. Refer to 20-managesieve.conf +in ``doc/dovecot/example-config/conf.d``, but don't forget to add ``sieve`` +to the :dovecot_core:ref:`protocols` setting if you use it. + +:: + + ... + service managesieve-login { + #inet_listener sieve { + # port = 4190 + #} + + #inet_listener sieve_deprecated { + # port = 2000 + #} + + # Number of connections to handle before starting a new process. Typically + # the only useful values are 0 (unlimited) or 1. 1 is more secure, but 0 + # is faster. + #service_count = 1 + + # Number of processes to always keep waiting for more connections. + #process_min_avail = 0 + + # If you set service_count=0, you probably need to grow this. + #vsz_limit = 64M + } + + service managesieve { + # Max. number of ManageSieve processes (connections) + #process_limit = 1024 + } + + # Service configuration + + protocol sieve { + # Maximum ManageSieve command line length in bytes. ManageSieve usually does + # not involve overly long command lines, so this setting will not normally need + # adjustment + #managesieve_max_line_length = 65536 + + # Maximum number of ManageSieve connections allowed for a user from each IP address. + # NOTE: The username is compared case-sensitively. + #mail_max_userip_connections = 10 + + # Space separated list of plugins to load (none known to be useful so far). Do NOT + # try to load IMAP plugins here. + #mail_plugins = + + # MANAGESIEVE logout format string: + # %i - total number of bytes read from client + # %o - total number of bytes sent to client + #managesieve_logout_format = bytes=%i/%o + + # To fool ManageSieve clients that are focused on CMU's timesieved you can specify + # the IMPLEMENTATION capability that the dovecot reports to clients. + # For example: 'Cyrus timsieved v2.2.13' + #managesieve_implementation_string = Dovecot Pigeonhole + + # Explicitly specify the SIEVE and NOTIFY capability reported by the server before + # login. If left unassigned these will be reported dynamically according to what + # the Sieve interpreter supports by default (after login this may differ depending + # on the user). + #managesieve_sieve_capability = + #managesieve_notify_capability = + + # The maximum number of compile errors that are returned to the client upon script + # upload or script verification. + #managesieve_max_compile_errors = 5 + + # Refer to 90-sieve.conf for script quota configuration and configuration of + # Sieve execution limits. + } + + + plugin { + # Used by both the Sieve plugin and the ManageSieve protocol + sieve = file:~/sieve;active=~/.dovecot.sieve + } + +Proxy +----- + +Like Dovecot's imapd, the ManageSieve login daemon supports proxying to +multiple backend servers. The :ref:`authentication-proxies` page +for POP3 and IMAP applies automatically to ManageSieve as well. diff --git a/source/configuration_manual/sieve/managesieve/troubleshooting.rst b/source/configuration_manual/sieve/managesieve/troubleshooting.rst new file mode 100644 index 0000000000..13c57c4cce --- /dev/null +++ b/source/configuration_manual/sieve/managesieve/troubleshooting.rst @@ -0,0 +1,191 @@ +.. _sieve_managesieve-troubleshooting: + +ManageSieve Troubleshooting +=========================== + +Like Dovecot itself, **the ManageSieve service always logs a detailed +error message** if something goes wrong at the server (refer to :ref:`Dovecot +Logging ` for more details): the logs are the first place to look if you suspect +something is wrong. To get additional debug messages in your log file, +you should set :dovecot_core:ref:`log_debug=category=sieve ` in dovecot.conf (inside +``protocol sieve {...}``\ if you want to enable this for ManageSieve +only). + +If the client commits protocol violations or sends invalid scripts, an +error response is provided to the client which is not necessarily logged +on the server. A good ManageSieve client presents such error messages to +the user. + +Keep in mind that the ManageSieve service only provides the Sieve +*protocol*, which may be somewhat confusing. This protocol can only be +used to *upload* Sieve scripts and *activate* them for execution. +Performing the steps below therefore only verifies that this +functionality is working and **not** whether Sieve scripts are correctly +being executed upon delivery. The execution of Sieve scripts is +performed by the Dovecot :ref:`Local Delivery Agent ` or its :ref:`LMTP service ` +using the :ref:`LDA Sieve plugin `. +If you have problems with Sieve script execution upon delivery, you are +referred to the :ref:`Sieve Troubleshooting +page `. + +Manual Login and Script Upload +------------------------------ + +If you fail to login or upload scripts to the server, it is not +necessarily caused by Dovecot or your configuration. It is often best to +test your ManageSieve server manually first. This also provides you with +the direct error messages from the server without intermission of your +client. If you do not use TLS, you can connect using a simple ``telnet`` +or ``netcat`` connection to the configured port (typically 4190 or 2000 +for older setups). Otherwise you must use a TLS-capable text protocol +client like ``gnutls-cli`` as described below. Upon connection, the +server presents the initial greeting with its capabilities: + +:: + + "IMPLEMENTATION" "dovecot" + "SASL" "PLAIN" + "SIEVE" "comparator-i;ascii-numeric fileinto reject vacation imapflags notify include envelope body relational regex subaddress copy" + "STARTTLS" + OK "Dovecot ready." + +Note that the reported ``STARTTLS`` capability means that the server +accepts TLS, but, since you are using telnet/netcat, you cannot use this +(refer to Manual TLS Login below). The ``SASL`` capability lists the +available SASL authentication mechanisms. If this list is empty and +``STARTTLS`` is available, it probably means that the server forces you +to initiate TLS first (as dictated by :dovecot_core:ref:`auth_allow_cleartext=yes ` +in dovecot.conf). + +Now you need to log in. Although potentially multiple SASL mechanisms +are available, only ``PLAIN`` is described here. Authentication is +performed using the ManageSieve ``AUTHENTICATE`` command. This command +typically looks as follows when the ``PLAIN`` mechanism is used: + +:: + + AUTHENTICATE "PLAIN" "" + +The credentials are the base64-encoded version of the string +``"\0\0`__ +and used as follows: + +:: + + sieve-auth-command.pl + +The command is written to stdout and you can paste this to your protocol +session, e.g.: + +:: + + AUTHENTICATE "PLAIN" "" + OK "Logged in." + +Now that you are logged in, you can upload a script. This is done using +the ``PUTSCRIPT`` command. Its first argument is the name for the script +and its second argument is a string literal. A string literal starts +with a length specification ``'{+}'`` followed by a newline. +Thereafter the server expects ```` bytes of script data. The +following uploads a trivial 6 byte long sieve script that keeps every +message (6th byte is the newline character): + +:: + + PUTSCRIPT "example" {6+} + keep; + OK "Putscript completed." + +Upon successful upload, you should find a file called +``example.sieve`` in your ``sieve_dir`` directory. The script should +also be listed by the server as follows when the ``LISTSCRIPTS`` command +is issued: + +:: + + LISTSCRIPTS + "example" + OK "Listscripts completed." + +You can check whether your script is uploaded correctly by downloading +it using the ``GETSCRIPT`` command. This command accepts the name of the +downloaded script as its only parameter: + +:: + + GETSCRIPT "example" + {6} + keep; + OK "Getscript completed." + +To let the Sieve plugin use your newly uploaded script, you must +activate it using the ``SETACTIVE`` command (only one script can be +active at any time). The active script is indicated ``ACTIVE`` in the +``LISTSCRIPTS`` output, e.g.: + +:: + + SETACTIVE "example" + OK "Setactive completed." + LISTSCRIPTS + "example" ACTIVE + OK "Listscripts completed. + +The symbolic link configured with the ``sieve`` setting should now point +to the activated script in the ``sieve_dir`` directory. If no script is +active, this symbolic link is absent. + +Manual TLS Login +---------------- + +When TLS needs to be used during manual testing, ``gnutls-cli`` provides +the means to do so. This command-line utility is part of the GNUTLS +distribution and on most systems this should be easy to install. It is +used to connect to ManageSieve as follows: + +:: + + gnutls-cli --starttls -p + +This starts the client in plain text mode first. As shown in the +previous section, the server presents a greeting with all capabilities +of the server. If ``STARTTLS`` is listed, you can issue the ``STARTTLS`` +command as follows: + +:: + + STARTTLS + OK "Begin TLS negotiation now." + +If an OK response is given by the server you can press ``Ctrl-D`` to +make ``gnutls-cli`` start the TLS negotiation. Upon pressing ``Ctrl-D``, +``gnutls-cli`` will show information on the negotiated TLS session and +finally the first response of the server is shown: + +:: + + "IMPLEMENTATION" "dovecot" + "SASL" "PLAIN" + "SIEVE" "comparator-i;ascii-numeric fileinto reject vacation imapflags notify include envelope body relational regex subaddress copy" + OK "TLS negotiation successful." + +Hereafter, you can continue to authenticate and upload a script as +described in the previous section. + +Client Problems +--------------- + +See :ref:`debugging_rawlog` for details how to log client-server traffic. + +Refer to the :ref:`ManageSieve Clients page ` +for information on known client problems. + +Known Server Issues and Protocol Deviations +------------------------------------------- + +- The ANONYMOUS authentication mechanism is currently not supported and + explicitly denied. diff --git a/source/settings/pigeonhole.rst b/source/settings/pigeonhole.rst index 38dcc5f2aa..da95613205 100644 --- a/source/settings/pigeonhole.rst +++ b/source/settings/pigeonhole.rst @@ -526,6 +526,19 @@ Sieve Plugin Settings matched in those tests. ============= =========================================================== +.. pigeonhole:setting:: sieve_quota_max_scripts + :plugin: sieve + :values: @uint + + The maximum number of personal Sieve scripts a single user can have. + Default is 0, which is unlimited. + +.. pigeonhole:setting:: sieve_quota_max_storage + :plugin: sieve + :values: @uint + + The maximum amount of disk storage a single user's scripts may + occupy. Default is 0, which is unlimited. .. pigeonhole:setting:: sieve_user_email :added: pigeonhole-0.4.14 From 669a604d5bc5340c376a607b27d4b35e17a450fd Mon Sep 17 00:00:00 2001 From: Aki Tuomi Date: Wed, 11 Oct 2023 16:01:48 +0300 Subject: [PATCH 03/10] howto: Add convert password schemes --- source/admin_manual/post_login_scripting.rst | 3 +- .../authentication/password_schemes.rst | 4 +- .../howto/convert_password_schemes.rst | 301 ++++++++++++++++++ 3 files changed, 304 insertions(+), 4 deletions(-) create mode 100644 source/configuration_manual/howto/convert_password_schemes.rst diff --git a/source/admin_manual/post_login_scripting.rst b/source/admin_manual/post_login_scripting.rst index 4951ddd636..025e49d74f 100644 --- a/source/admin_manual/post_login_scripting.rst +++ b/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 -`_ +See :ref:`howto-convert_password_schemes` Last-login tracking =================== diff --git a/source/configuration_manual/authentication/password_schemes.rst b/source/configuration_manual/authentication/password_schemes.rst index ebd0b2aa9b..1f8d430039 100644 --- a/source/configuration_manual/authentication/password_schemes.rst +++ b/source/configuration_manual/authentication/password_schemes.rst @@ -70,8 +70,8 @@ A few articles about why choosing a good password scheme is important: It's not possible to easily switch from one password scheme to another. The only practical way to do this is to wait until user logs in and change the -password during the login. `This HOWTO -`_ shows one way to do +password during the login. :ref:`This HOWTO +` shows one way to do this. Generating encrypted passwords diff --git a/source/configuration_manual/howto/convert_password_schemes.rst b/source/configuration_manual/howto/convert_password_schemes.rst new file mode 100644 index 0000000000..b5a5c8cabe --- /dev/null +++ b/source/configuration_manual/howto/convert_password_schemes.rst @@ -0,0 +1,301 @@ +.. _howto-convert_password_schemes: + +=========================== +Converting password schemes +=========================== + +Introduction +============ + +Through the years computers are being faster and faster, and so with it +the encryption of passwords have to more secure. In this example we +convert passwords stored in MySQL with basic CRYPT-encryption to +SSHA256-encryption (Salted SHA256). + +See :ref:`authentication-password_schemes` for a list of supported password schemes. + +We used php to generate the new passwords, but you can use any language +you want + +Alternative example can be found from +``__ + +Example +======= + +* Copy the CRYPT-passwords to a new field (newpassword) but with the prefix + ``{CRYPT}``. This might start you off in the right direction for + mysql: + :literal:`UPDATE \`your_table\` SET field_name = CONCAT('{CRYPT}', field_name)` + +* Change dovecot-sql.conf, so it will look at the new fields + +:: + + # Comment default_pass_scheme so dovecot will look at the prefix + # default_pass_scheme = CRYPT + + # update your password_query so it will look at the new field + # AND add a %w field in the query so we have the plain password in our Enviroment ($PLAIN_PASS) + password_query = SELECT id as user, newpassword as password, home as userdb_home, \ + uid as userdb_uid, gid as userdb_gid, '%w' as userdb_plain_pass FROM users WHERE id = '%u' + + # Alternatively, here is another config that worked for me with SHA512-CRYPT (note: uncomment the lines relevant for your setup): + # + # driver = mysql + # connect = host=127.0.0.1 user=mailauth password=secret dbname=postfixadmin + # default_pass_scheme = SHA512-CRYPT + # password_query = SELECT username AS user, password, CONCAT('/var/mail/vdomains/', maildir) as userdb_home, 'vmail' as userdb_uid, 'vmail' as userdb_gid, '%w' as userdb_plain_pass FROM mailbox WHERE username = '%u' + # user_query = SELECT CONCAT('/var/mail/vdomains/', maildir) AS home, 'vmail' AS uid, 'vmail' AS gid, password FROM mailbox WHERE username = '%u' AND active = 1 + +* Make sure you configured + +:: + + userdb { + driver = prefetch + } + +* Now reload dovecot, and see everything is still working + +* Make the postlogin-script (which is executed after login) and save it + as ``/usr/local/etc/popafter.sh`` + +.. code:: bash + + #!/bin/sh + /usr/local/etc/convertpw.php $USER $PLAIN_PASS + exec "$@" + +* Make the php-script which updates the password and save it as ``/usr/local/etc/convertpw.php`` + +.. code:: php + + #!/usr/local/bin/php + + +* update your dovecot.conf so it will use the scripts we just made + +:: + + # insert these lines so dovecot uses our scripts + service pop3 { + executable = pop3 pop3-postlogin + } + service pop3-postlogin { + executable = script-login /usr/local/etc/popafter.sh + user = $default_internal_user + unix_listener pop3-postlogin { + } + } + # end insert + +* now reload dovecot. + +As of now each user which connects through POP will convert their +password to SSHA256. If you look at the database you will see for +example +``{SSHA256.hex}fb0e7f39c88c1d7017169f7f6b9cd6977d1e3291149382b90da4a390a31e81bab3cdced8`` +instead of ``{CRYPT}$1$.gvrgDqc$Slvoapz5zkpVmmJAxi.0k1`` + +If you are using IMAP, you will need to add the same kind of commands +(i.e. imap-postlogin) to your config, too. + +When every record is updated you can update dovecot.conf (remove the +extra lines), and dovecot-sql (remove the %w-part). + +SHA512-CRYPT +============ + +To use SHA512-CRYPT passwords use ``/usr/local/etc/popafter.sh`` + +.. code:: bash + + #!/bin/sh + DOVECOTPW=$(doveadm pw -s SHA512-CRYPT -p $PLAIN_PASS) + /usr/local/etc/convertpw.php $USER $DOVECOTPW + exec "$@" + +A variant that does not leak the password to the process list: + +.. code:: bash + + #!/bin/sh + NEWPASSWORD=$(doveadm pw -s SHA512-CRYPT <> /tmp/log + # echo "PLAIN-PASS: $PLAIN_PASS" >> /tmp/log + DOVECOTPW=$(/usr/local/bin/doveadm pw -s SHA512-CRYPT -p "$PLAIN_PASS") + # echo $DOVECOTPW >> /tmp/log + /usr/local/etc/convertpw.php $USER $DOVECOTPW + exec "$@" + # note: if enabled, some of the lines above will log passwords to /tmp/log. Create the file first, and delete it when no longer needed - + # this while approach is a security risk and should *never* be done in a production system. I had to use it for troubleshooting for a very limited period of time. + # + +``/usr/local/etc/convertpw.php - alternate version with debugging logs`` + +.. code:: php + + #!/usr/bin/php + + +selinux +======= + +.. code:: bash + + chcon -u system_u /usr/local/etc/convertpw.php + chcon -t bin_t /usr/local/etc/convertpw.php + chcon -u system_u /usr/local/etc/popafter.sh + chcon -t bin_t /usr/local/etc/popafter.sh + +Example for SHA512-Crypt with passwd-files +========================================== + +This example has been tested on Dovecot 2.2.19 in a virtual user setup. + +Create a new service for the postlogin script and reference it in the +``imap`` service section. + +``/etc/dovecot/conf.d/10-master.conf`` + +.. code:: bash + + service imap { + executable = imap imap-postlogin + unix_listener imap-master { + user = dovecot + } + } + + service imap-postlogin { + executable = script-login /var/vmail/conf.d/scripts/postlogin.sh + user = vmail + unix_listener imap-postlogin { + } + } + +Enable the ``plain_pass`` variable in the auth-passwdfile configuration. + +``/etc/dovecot/conf.d/auth-passwdfile.conf.ext`` + +.. code:: bash + + passdb { + driver = passwd-file + args = username_format=%u /var/vmail/auth.d/%d/passwd + } + + userdb { + driver = passwd-file + args = username_format=%u /var/vmail/auth.d/%d/passwd + default_fields = plain_pass=%w + } + +This script will act on all users for a particular domain specified via +the ``MIGRATE_DOMAIN`` variable. + +``/var/vmail/conf.d/scripts/postlogin.sh`` + +.. code:: bash + + #!/bin/sh + # Split out domain part from $USER user@domain + MAIL_ALIAS=${USER%@*} + MAIL_DOMAIN=${USER#*@} + MIGRATE_DOMAIN="domain.tld" + + case "$MAIL_DOMAIN" in + $MIGRATE_DOMAIN) + DOVECOTPW=$(/usr/bin/doveadm pw -s SHA512-CRYPT -p "$PLAIN_PASS") + echo "user: $USER" >> /tmp/log + echo $DOVECOTPW >> /tmp/log + ;; + esac + + exec "$@" + +Exemplary directory permissions (Setup is using ``vmail`` context for +the users): + +.. code:: bash + + $ l /var/vmail/conf.d/scripts/ + total 4 + -r-x------ 1 vmail vmail 322 Nov 23 09:58 postlogin.sh + + $ l /tmp/log + -rw------- 1 vmail root 1160 Nov 23 10:27 /tmp/log From 8a05e2d5c044320270a7ee0e653ed2f299cd0550 Mon Sep 17 00:00:00 2001 From: Aki Tuomi Date: Wed, 11 Oct 2023 16:24:00 +0300 Subject: [PATCH 04/10] Import pages --- .../debugging/debugging_authentication.rst | 2 +- source/admin_manual/find_mail_location.rst | 66 +++++ source/admin_manual/index.rst | 2 + .../system_users_used_by_dovecot.rst | 14 +- source/admin_manual/test_installation.rst | 232 ++++++++++++++++++ .../basic_configuration.rst | 162 ++++++++++++ source/configuration_manual/index.rst | 1 + 7 files changed, 471 insertions(+), 8 deletions(-) create mode 100644 source/admin_manual/find_mail_location.rst create mode 100644 source/admin_manual/test_installation.rst create mode 100644 source/configuration_manual/basic_configuration.rst diff --git a/source/admin_manual/debugging/debugging_authentication.rst b/source/admin_manual/debugging/debugging_authentication.rst index 317ec3e5e3..424e95afe8 100644 --- a/source/admin_manual/debugging/debugging_authentication.rst +++ b/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 `_ and `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: NUL NUL . 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 `, you can either set both of these fields to the same username, or leave the authorization ID empty. diff --git a/source/admin_manual/find_mail_location.rst b/source/admin_manual/find_mail_location.rst new file mode 100644 index 0000000000..5ded54b704 --- /dev/null +++ b/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. diff --git a/source/admin_manual/index.rst b/source/admin_manual/index.rst index d099046f59..75c3daefa5 100644 --- a/source/admin_manual/index.rst +++ b/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 diff --git a/source/admin_manual/system_users_used_by_dovecot.rst b/source/admin_manual/system_users_used_by_dovecot.rst index dc174b3dc2..f5263d9377 100644 --- a/source/admin_manual/system_users_used_by_dovecot.rst +++ b/source/admin_manual/system_users_used_by_dovecot.rst @@ -6,12 +6,12 @@ System users used by Dovecot Dovecot typically requires 3 or more system users: -* `root`: Dovecot is started as root. +* ``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 +* ``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 @@ -34,11 +34,11 @@ You can change the default ``dovenull`` user to something else from 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 +You can change the default ``dovecot`` user to something else from :dovecot_core:ref:`default_internal_user` setting. Mail users diff --git a/source/admin_manual/test_installation.rst b/source/admin_manual/test_installation.rst new file mode 100644 index 0000000000..df7bd9aedc --- /dev/null +++ b/source/admin_manual/test_installation.rst @@ -0,0 +1,232 @@ +.. _testing_installation: + +==================== +Testing installation +==================== + +Check that it's running +======================= + +First check with ``ps`` that the ``dovecot`` process is actually running. If +it's not, you had an error in ``dovecot.conf`` and the error message was +written to log. Go back to :ref:`running_dovecot` and :ref:`dovecot_logging` +if you can't find it. + +Check that it's listening +========================= + +Next check that Dovecot is listening for connections: + +:: + + # telnet localhost 143 + Trying 127.0.0.1... + Connected to localhost. + Escape character is '^]'. + * OK [CAPABILITY IMAP4rev1 LITERAL+ SASL-IR LOGIN-REFERRALS ID ENABLE STARTTLS AUTH=PLAIN] Dovecot ready. + +If you got "connection refused", make sure that Dovecot is configured to +serve the imap protocol and listening on the expected +interfaces/addresses. The simplest way to do that would be using +:man:`doveconf(1)`: + +:: + + # doveconf protocols listen + protocols = imap pop3 lmtp sieve + listen = *, :: + +If the protocols setting doesn't contain ``imap`` then add it. Also make +sure, that relevant ``!include`` or ``!include_try`` configuration lines +are not commented. + +If the telnet fails and dovecot emits a log "*auth: Fatal: Support not +compiled in for passdb driver 'pam'*", then rebuild dovecot with the pam development headers +package installed. In that case you have to re-run the configure +script, possibly including option **--with-pam** to the configure +command line. + +Next check that it also works from remote host: + +:: + + # telnet imap.example.com 143 + Trying 1.2.3.4... + Connected to imap.example.com. + Escape character is '^]'. + * OK [CAPABILITY IMAP4rev1 LITERAL+ SASL-IR LOGIN-REFERRALS ID ENABLE STARTTLS AUTH=PLAIN] Dovecot ready. + +If that didn't work, check all possible firewalls in between, and check +that ``listen`` setting is ``*`` in ``dovecot.conf``. + +If you have only imaps enabled, see :ref:`remote login ` section below for how +to test using openssl s_client. + +Check that it's allowing logins +=============================== + +:: + + # telnet localhost 143 + a login "username" "password" + +Replace the username and password with the ones you added to +``passwd.dovecot`` in :ref:`basic_configuration`. +Note that all IMAP commands begin with a tag, which is basically any +string you want, but it must be there. So don't leave out the "a" in the +above example. If the password contains ``"`` character, escape it with +``\\`` (e.g. ``"foo\"bar"``). + +You should get an "a OK Logged in." reply. If you get "Authentication +failed" error, set :dovecot_core:ref:`auth_verbose = yes ` +and :dovecot_core:ref:`log_debug = category=auth ` in +``dovecot.conf``, restart Dovecot and try again. The log file should now +show enough information to help you fix the problem. + +.. _remote_login: + +Check that it's allowing remote logins +====================================== + +You'll need to try this from another computer, since all local IPs are +treated as secure: + +:: + + # telnet imap.example.com 143 + a login "username" "password" + +If the connection is hanging instead of giving ``* Dovecot ready``, you +have a firewall that's preventing the connections. + +Otherwise, the only difference here compared to step above is that you +might get: + +:: + + * BAD [ALERT] Plaintext authentication is disabled, but your client sent password in plaintext anyway. If anyone was listening, the password was exposed. + a NO Plaintext authentication disabled. + +If this is the case, you didn't set :dovecot_core:ref:`auth_allow_cleartext = yes `. You +could alternatively use OpenSSL to test that the server works with SSL: + +- Test using imaps port (assuming you haven't disabled imaps port): + + :: + + # openssl s_client -connect imap.example.com:993 + * OK Dovecot ready. + +- Test using imap port and STARTTLS command (works also with imap + port): + + :: + + # openssl s_client -connect imap.example.com:143 -starttls imap + * OK Dovecot ready. + +Check that it finds INBOX +========================= + +After logging in, check that the INBOX is found: + +:: + + b select inbox + * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + * OK [PERMANENTFLAGS (\Answered \Flagged \Deleted \Seen \Draft \*)] Flags permitted. + * 1 EXISTS + * 1 RECENT + * OK [UIDVALIDITY 1106186941] UIDs valid + * OK [UIDNEXT 2] Predicted next UID + b OK [READ-WRITE] Select completed. + +It should contain the mail that you sent to yourself in +:ref:`find_mail_location` step. + +If anything goes wrong, set :dovecot_core:ref:`log_debug = category=mail ` and try again. The log +file should now contain debugging information of where Dovecot is trying +to find the mails. Fix :dovecot_core:ref:`mail_location` setting and try again. + +Check that it finds other mailboxes +=================================== + +If you already have other mailboxes created, you can check that Dovecot +finds them: + +:: + + c list "" * + * LIST (\NoInferiors) "/" "test" + * LIST (\NoInferiors) "/" "INBOX" + c OK List completed. + +If they weren't found, set :dovecot_core:ref:`log_debug = category=mail ` and look at the +debugging information. Fix :dovecot_core:ref:`mail_location` setting and try again. + +Check out some other IMAP commands +================================== + +If you already have some emails, you can try reading them: + +:: + + 1 SELECT INBOX + 2 FETCH 1:* (FLAGS INTERNALDATE BODY.PEEK[HEADER.FIELDS (SUBJECT)]) + 3 FETCH 1 BODY[TEXT] + +``1:*`` means all messages + +You can also try moving a mail to Trash: + +:: + + 4 CREATE Trash + 5 COPY 1 Trash + 6 STORE 1 +FLAGS \Deleted + 7 EXPUNGE + +Check that real mail clients work +================================= + +Since mail clients can be configured in various ways, please check first +if the problem is with Dovecot configuration or with the client's +configuration. You can rule out it being Dovecot's problem with the +"telnet" methods described above. + +If you can't log in, + +- Make sure SSL/TLS settings are correct. + +- Make sure the client uses plaintext authentication method, unless + you've specifically configured Dovecot to accept others. + +If you can see only INBOX, + +- Clear out any "IMAP namespace prefix" or similar settings from + clients. + +- Check if client is configured to show only "subscribed mailboxes". If + so, you'll have to subscribe to the mailboxes you wish to see. You + can see a list of subscribed mailboxes with: + + :: + + d lsub "" * + * LSUB () "/" "INBOX" + d OK Lsub completed. + +Most IMAP clients have been tested with Dovecot and they work. + +Make a graceful exit +==================== + +To close the connection to Dovecot issue a logout: + +:: + + e logout + * BYE Logging out + e OK Logout completed. + +.. seealso:: :ref:`debugging` diff --git a/source/configuration_manual/basic_configuration.rst b/source/configuration_manual/basic_configuration.rst new file mode 100644 index 0000000000..6bd56d7df2 --- /dev/null +++ b/source/configuration_manual/basic_configuration.rst @@ -0,0 +1,162 @@ +.. _basic_configuration: + +Basic Configuration +=================== + +This page tells you the basics that you'll need to get a working Dovecot +installation. + +Find Dovecot configuration file location using: + +:: + + doveconf -n | head -n1 + +Your configuration file doesn't exist if you installed Dovecot from +sources. The config directory should contain a ``README`` file pointing +to an example configuration, which you can use as your basic +configuration. For example: + +:: + + cp -r /usr/share/doc/dovecot/example-config/* /etc/dovecot/ + +The default configuration starts from ``dovecot.conf``, which contains +an ``!include conf.d/*.conf`` statement to read the rest of the +configuration. This split of configuration files isn't a requirement to +use, and it doesn't really matter which .conf file you add any +particular setting, just as long as it isn't overridden in another file. +You can verify with ``doveconf -n`` that everything looks as you +intended. + +Authentication +-------------- + +By default Dovecot is set up to use system user authentication. If +you're planning on using system users, you can simply skip this section +and read +:ref:`PAM ` (or :ref:`bsdauth `) +for configuring it. + +If you're planning on using virtual users, it's easier to first create a +simple passwd-like file to make sure that the authentication will work. +Later when you know Dovecot is working, you can do it differently (see +:ref:`virtual_users`). + +Run as your own non-root user: + +:: + + echo "$USER:{PLAIN}password:$UID:$GID::$HOME" > users + sudo mv users /etc/dovecot/ + + # If SELinux is enabled: + restorecon -v /etc/dovecot/users + +You can (and should) replace the "password" with whatever password you +wish to use, but don't use any important password here as we'll be +logging in with insecure plaintext authentication until +:ref:`SSL ` is +configured. + +If you used the example configuration files, switch to passwd-file by +modifying ``conf.d/10-auth.conf``: + +:: + + # Add '#' to comment out the system user login for now: + + # Remove '#' to use passwd-file: + !include auth-passwdfile.conf.ext + +In ``conf.d/auth-passwdfile.conf.ext`` you should have: + +:: + + passdb { + driver = passwd-file + args = scheme=CRYPT username_format=%u /etc/dovecot/users + } + userdb { + driver = passwd-file + args = username_format=%u /etc/dovecot/users + } + +Verify with ``doveconf -n passdb userdb`` that the output looks like +above (and there are no other passdbs or userdbs). + +Plaintext Authentication +------------------------ + +To allow any Authentication without SSL, disable SSL in the +``conf.d/10-ssl.conf`` file. This has to be done because Dovecot (now) +uses SSL as default. You probably want to switch this back to "yes" or +other options afterward. + +:: + + ssl = no + +Until SSL is configured, allow plaintext authentication in the +``conf.d/10-auth.conf`` file. You probably want to switch this back to +"yes" afterward. + +:: + + auth_allow_cleartext = yes + +If you didn't use the temporary passwd-file created above, don't do this +if you don't want your password to be sent in clear to network. Instead +get SSL configuration working and connect to Dovecot only using SSL. + +Mail Location +------------- + +Set the :dovecot_core:ref:`mail_location` in ``conf.d/10-mail.conf`` as determined by +the instructions in :ref:`find_mail_location`. + +mbox +~~~~ + +If you're using mboxes, it's important to have locking configuration +correct. See :ref:`mbox_locking` for more information. + +If you're using ``/var/mail/`` or ``/var/spool/mail/`` directory for +INBOXes, you may need to give Dovecot additional permissions so it can +create dotlock files there. A failure to do so will result in errors +like these: + +:: + + open(/var/mail/.temp.host.1234.abcdefg) failed: Permission denied + file_lock_dotlock() failed with mbox file /var/mail/user: Permission denied + +From here on I'm assuming the INBOX directory is ``/var/mail``. + +First check what the permissions of ``/var/mail`` are: + +:: + + # ls -ld /var/mail + drwxrwxrwt 2 root mail 47 2006-01-07 20:44 /var/mail/ + +In this case everyone has write access there and the directory is marked +sticky. This allows Dovecot to create the dotlock files, so you don't +need to do anything. + +:: + + # ls -ld /var/mail + drwxrwxr-- 2 root mail 47 2006-01-07 20:44 /var/mail/ + +In this case only the root and the ``mail`` group has write permission +to the directory. You'll need to give Dovecot's mail processes ability +to use this group by changing ``conf.d/10-mail.conf``: + +:: + + mail_privileged_group = mail + +Note: Specifying the privileged user must be done as shown. Simply +adding ``dovecot`` user to the ``mail`` group does **not** grant write +permission. diff --git a/source/configuration_manual/index.rst b/source/configuration_manual/index.rst index a9fbd25017..ecec74a85f 100644 --- a/source/configuration_manual/index.rst +++ b/source/configuration_manual/index.rst @@ -11,6 +11,7 @@ Configuration Manual acl apparmor authentication/index + basic_configuration common_configuration config_file/index dict/index From 3455196ad844e2aa2981e6b619b3a78d47eb690e Mon Sep 17 00:00:00 2001 From: Aki Tuomi Date: Wed, 11 Oct 2023 16:31:47 +0300 Subject: [PATCH 05/10] Import imapc proxy howto --- .../authentication_via_remote_imap_server.rst | 3 +- .../howto/imapc_proxy.rst | 177 ++++++++++++++++++ 2 files changed, 178 insertions(+), 2 deletions(-) create mode 100644 source/configuration_manual/howto/imapc_proxy.rst diff --git a/source/configuration_manual/authentication/authentication_via_remote_imap_server.rst b/source/configuration_manual/authentication/authentication_via_remote_imap_server.rst index e81d989dc2..28f7ae2437 100644 --- a/source/configuration_manual/authentication/authentication_via_remote_imap_server.rst +++ b/source/configuration_manual/authentication/authentication_via_remote_imap_server.rst @@ -22,8 +22,7 @@ Available driver settings: certificate isn't trusted. For v2.2 it defaults to "yes". (v2.2.30+) * rawlog_dir= -See also `HowTo/ImapcProxy `_ for -how to combine this with imapc storage. +See also :ref:`howto-imapc_proxy` for how to combine this with imapc storage. Example ======= diff --git a/source/configuration_manual/howto/imapc_proxy.rst b/source/configuration_manual/howto/imapc_proxy.rst new file mode 100644 index 0000000000..0e1ce0e236 --- /dev/null +++ b/source/configuration_manual/howto/imapc_proxy.rst @@ -0,0 +1,177 @@ +.. _howto-imapc_proxy: + +Dovecot imapc proxy +=================== + +Using Dovecot as a secure IMAP Proxy in front of Exchange, using +Exchange Authentication and IMAPC. This requires Dovecot 2.1.rc1 or +newer. + +Many thanks to Timo on the Dovecot mailing list for all his help! + +This is based on already having Dovecot already compiled and installed. + +1. Create an unprivileged, non-system account user and group for the + proxy, with a home directory. This needs to have a writable home + directory, but no other privileges. + + :: + + [root@localhost]# useradd imapproxy + +2. Verify that the user cannot login: + + :: + + [root@localhost]# grep imapproxy /etc/shadow + + You should see something like: + + :: + + imapproxy:!!:nnnn:0:nn:n::: + + The important part is the "!!". This indicates that the account is + locked. If you don't see this, lockout the account (check man passwd) + +3. Create ``/etc/dovecot/dovecot.conf`` or + (``/usr/local/etc/dovecot/dovecot.conf``) as appropriate: + + :: + + ## Dovecot configuration file + + mail_uid = imapproxy + mail_gid = imapproxy + + protocols = imap + + listen = *, :: + + mail_location = imapc:~/imapc + # Change the line below to reflect the IP address of your Exchange Server. + imapc_host = 10.1.2.3 + imapc_port = 143 + + passdb { + driver = imap + # Change the line below to reflect the IP address of your Exchange Server. + args = host=10.1.2.3 + default_fields = userdb_imapc_user=%u userdb_imapc_password=%w + } + userdb { + driver = prefetch + } + + # /home/imapproxy is the home directory for the imapproxy user, and + # %u is a subdir that will be automatically created for each IMAP user when they connect + + mail_home = /home/imapproxy/%u + + auth_mechanisms = plain login + + # This is the auth service used by Postfix to do dovecot auth. + service auth { + unix_listener auth-userdb { + } + inet_listener { + port = 12345 + } + } + + + ## + ## SSL settings + ## + + # These will need to ba adjusted to point to *your* certificates, not mine 8-) + # The ssl_ca line refers to the intermediate certificate bundle which may or may not be required by your SSL provider + + ssl_cert = Date: Wed, 11 Oct 2023 16:58:17 +0300 Subject: [PATCH 06/10] lda: Import LDA related pages and fix linking --- .github/actions/spelling/patterns.txt | 3 + source/admin_manual/mda.rst | 6 +- .../howto/dovecot_lda_exim.rst | 158 +++++++++++ .../howto/dovecot_lda_postfix.rst | 264 ++++++++++++++++++ .../howto/dovecot_lda_qmail.rst | 32 +++ .../howto/dovecot_lda_sendmail.rst | 107 +++++++ .../howto/dovecot_lda_zmailer.rst | 68 +++++ .../howto/dovecot_lmtp_exim.rst | 146 ++++++++++ .../howto/imapc_proxy.rst | 2 +- source/configuration_manual/protocols/lda.rst | 93 ++++-- .../protocols/lmtp_server.rst | 2 +- 11 files changed, 857 insertions(+), 24 deletions(-) create mode 100644 source/configuration_manual/howto/dovecot_lda_exim.rst create mode 100644 source/configuration_manual/howto/dovecot_lda_postfix.rst create mode 100644 source/configuration_manual/howto/dovecot_lda_qmail.rst create mode 100644 source/configuration_manual/howto/dovecot_lda_sendmail.rst create mode 100644 source/configuration_manual/howto/dovecot_lda_zmailer.rst create mode 100644 source/configuration_manual/howto/dovecot_lmtp_exim.rst diff --git a/.github/actions/spelling/patterns.txt b/.github/actions/spelling/patterns.txt index 8f8e626dbd..23c4f0af9a 100644 --- a/.github/actions/spelling/patterns.txt +++ b/.github/actions/spelling/patterns.txt @@ -156,3 +156,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 +[d-][rs-][ws-][xts-][rs-][ws-][xts-] diff --git a/source/admin_manual/mda.rst b/source/admin_manual/mda.rst index 1c9bc4f411..fc5dbfe0eb 100644 --- a/source/admin_manual/mda.rst +++ b/source/admin_manual/mda.rst @@ -15,8 +15,8 @@ virtual mailbox. Common choices include: -- `maildrop `_ +- `maildrop `__ -- `procmail `_ (appears to be unmaintained) +- `procmail `__ -- :ref:`Dovecot's \`dovecot-lda\` LDA ` +- :ref:`Dovecot's 'dovecot-lda' LDA ` diff --git a/source/configuration_manual/howto/dovecot_lda_exim.rst b/source/configuration_manual/howto/dovecot_lda_exim.rst new file mode 100644 index 0000000000..fc7ef1d066 --- /dev/null +++ b/source/configuration_manual/howto/dovecot_lda_exim.rst @@ -0,0 +1,158 @@ +.. _howto-dovecot_lda_exim: + +Dovecot LDA with Exim +===================== + +System users +------------ + +Change the localuser router to use dovecot_delivery transport: + +:: + + localuser: + driver = accept + check_local_user + # local_part_suffix = +* : -* + # local_part_suffix_optional + transport = dovecot_delivery + +``check_local_user`` is required. It makes Exim execute the transport +with the user's UID and GID and it also sets HOME environment. + +Next create a new transport for dovecot-lda: + +:: + + dovecot_delivery: + driver = pipe + + # Use /usr/lib/dovecot/dovecot-lda if using Debian's package. + # You may or may not want to add -d $local_part@$domain depending on if you need a userdb lookup done. + command = /usr/local/libexec/dovecot/dovecot-lda -f $sender_address + + message_prefix = + message_suffix = + log_output + delivery_date_add + envelope_to_add + return_path_add + #group = mail + #mode = 0660 + temp_errors = 64 : 69 : 70: 71 : 72 : 73 : 74 : 75 : 78 + +LDA is now running using the local user's UID and GID. The mail is +delivered to the location specified by +:dovecot_core:ref:`mail_location` +setting. Note that the above configuration doesn't do any +:ref:`userdb ` lookups, so +you can't have any per-user configuration. If you want that, see the +virtual user setup below. + +Virtual users +------------- + +Make sure that ``check_local_user`` isn't set in the router. + +Single UID +~~~~~~~~~~ + +Configure the transport to run as the user you want, for example vmail: + +:: + + dovecot_virtual_delivery: + driver = pipe + command = /usr/local/libexec/dovecot/dovecot-lda -d $local_part@$domain -f $sender_address + # v1.1+: command = /usr/local/libexec/dovecot/dovecot-lda -d $local_part@$domain -f $sender_address -a $original_local_part@$original_domain + message_prefix = + message_suffix = + delivery_date_add + envelope_to_add + return_path_add + log_output + user = vmail + temp_errors = 64 : 69 : 70: 71 : 72 : 73 : 74 : 75 : 78 + +You'll also need to have a master authentication socket and give vmail +user access to it. See :ref:`LDA ` for more information. + +List of temp_errors can be found in ``/usr/include/sysexits.h``. + +Multiple UIDs +~~~~~~~~~~~~~ + +If you need multiple uids/gids you'll need to set dovecot-lda setuid +root. See :ref:`LDA ` for how to do this securely. + +You could alternatively set ``user = root``, but this requires that you +built Exim without root being in FIXED_NEVER_USERS list. + +Multiple UIDs, without running dovecot-lda as root +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this mode, dovecot-lda won't be querying Dovecot's master socket, +instead trusting Exim to setup its execution environment. This means you +must set up Exim to get the UID, GID, Home directory from +LDAP/SQL/whatever. Here, we're setting them in the router and the +transport automatically inherits them. + +Router configuration +^^^^^^^^^^^^^^^^^^^^ + +Insert the following router after your external delivery routers and +before your local system delivery routers. + +This assumes you're using macros set elsewhere to handle your external +queries, as they can quickly become unwieldy to manage. Make sure you +adjust it to suit your installation first! + +:: + + ldap_local_user: + debug_print = "R: ldap_local_user for $local_part@$domain" + driver = accept + domains = +ldap_local_domains + condition = LDAP_VIRT_COND + router_home_directory = LDAP_VIRT_HOME + user = LDAP_VIRT_UID + group = LDAP_VIRT_GID + #local_part_suffix = +* : -* + #local_part_suffix_optional + transport = dovecot_lda + +Transport configuration +^^^^^^^^^^^^^^^^^^^^^^^ + +This transport has been tested with Exim 4.69-9 and Dovecot 1:1.2.5-2 +(backported) on Debian Lenny. You also have to set + +:: + + dovecot_lda: + debug_print = "T: dovecot_lda for $local_part@$domain" + driver = pipe + # Uncomment the following line and comment the one after it if you want dovecot-lda to try + # to deliver subaddresses into INBOX.{subaddress}. If you do this, uncomment the + # local_part_suffix* lines in the router as well. Make sure you also change the separator + # to suit your local setup. + #command = /usr/lib/dovecot/dovecot-lda -e -k -m "INBOX|${substr_1:$local_part_suffix}" \ + command = /usr/lib/dovecot/dovecot-lda -e -k \ + -f "$sender_address" -a "$original_local_part@$original_domain" + environment = USER=$local_part@$domain + home_directory = /var/mail/home/$domain/$local_part + umask = 002 + message_prefix = + message_suffix = + delivery_date_add + envelope_to_add + return_path_add + log_output + log_defer_output + return_fail_output + freeze_exec_fail + #temp_errors = * + temp_errors = 64 : 69 : 70 : 71 : 72 : 73 : 74 : 75 : 78 + +You need to have :ref:`home directory ` set +to have duplicate database enabled, among other reasons. diff --git a/source/configuration_manual/howto/dovecot_lda_postfix.rst b/source/configuration_manual/howto/dovecot_lda_postfix.rst new file mode 100644 index 0000000000..f07dac1243 --- /dev/null +++ b/source/configuration_manual/howto/dovecot_lda_postfix.rst @@ -0,0 +1,264 @@ +.. _howto-dovecot_lda_postfix: + +Dovecot LDA with Postfix +======================== + +This page contains only information specific to using LDA with Postfix, +see :ref:`LDA ` for more information about using the LDA itself. + +System users +------------ + +If you wish you use ``dovecot-lda`` for all system users on a single +domain mail host you can do it by editing ``mailbox_command`` parameter +in + +``/etc/postfix/main.cf`` +(`postconf(5) `__): + +:: + + mailbox_command = /usr/local/libexec/dovecot/dovecot-lda -f "$SENDER" -a "$RECIPIENT" + # or + mailbox_command = /usr/libexec/dovecot/dovecot-lda -f "$SENDER" -a "$RECIPIENT" + # or + mailbox_command = /usr/lib/dovecot/dovecot-lda -f "$SENDER" -a "$RECIPIENT" + # or wherever it was installed in your system. + +Then run ``postfix reload``. + +- This command doesn't do a + :ref:`userdb ` + lookup. If you want that (e.g. for per-user quota lookups) you need + to add ``-d "$USER"`` parameter. + +- Postfix runs ``mailbox_command`` with both the uid and gid of the + destination user. This may not allow ``dovecot-lda`` to write a lock + file in ``/var/mail``. When this directory is writable by a + privileged group (say ``main``, see the option + :dovecot_core:ref:`mail_privileged_group`), we can use the setgid permission bit on + the ``dovecot-lda`` executable: + + :: + + # chgrp mail /usr/lib/dovecot/dovecot-lda + # chmod 2755 /usr/lib/dovecot/dovecot-lda + + Alas these permission will disappear if you update dovecot. A more + robust way to do so is to compile a relay program + ``/etc/postfix/dovecot-lda-relay`` that has the setgid permission and + execs the real ``dovecot-lda``. + + :: + + # cd /etc/postfix + # cat >dovecot-lda-relay.c < + char *pgm = "/usr/lib/dovecot/dovecot-lda"; /* wherever dovecot-lda is located */ + int main(int argc, char**argv) { argv[0]=pgm; execv(pgm,argv); return 10; } + EOF + # gcc -o dovecot-lda-relay dovecot-lda-relay.c + # chown root:mail dovecot-lda-relay + # chmod 2755 dovecot-lda-relay + + Then, simply invoke ``/etc/postfix/dovecot-lda-relay`` instead of + ``dovecot-lda`` in ``mailbox_command``. + +- Postfix's ``mailbox_size_limit`` setting applies to all files that + are written via dovecot-lda. The default is 50 MB, so dovecot-lda + can't write **any** files larger than that, including mbox files or + log files. This shows up only in Dovecot's logs: + + :: + + dovecot-lda(user): write() failed with mbox file /home/user/mail/foo: File too large (process was started with ulimit -f limit) + +- If you have trouble seeing anything in Dovecot's logs, see :ref:`LDA `. + +Virtual users +------------- + +Dovecot LDA is very easy to use on large scale installations with +Postfix virtual domains support, just add a ``dovecot`` service in +``/etc/postfix/master.cf`` +(`master(5) `__): + +:: + + dovecot unix - n n - - pipe + flags=DRhu user=vmail:vmail argv=/usr/local/libexec/dovecot/dovecot-lda -f ${sender} -d ${recipient} + +An example using address extensions (ie user+extension@domain.com (don't +forget to define the proper recipient_delimiter in Postfix's main.cf)) +to deliver to the folder 'extension' in your maildir (If you wish to +preserve the case of ``${extension}``, remove the ``hu`` +`flags `__, and be sure to utilize +:ref:`config_variables` in your +dovecot.conf for mail locations and other configuration parameters that +are expecting lower case): + +:: + + dovecot unix - n n - - pipe + flags=DRhu user=vmail:vmail argv=/usr/local/libexec/dovecot/dovecot-lda -f ${sender} -d ${user}@${nexthop} -m ${extension} + + # or if you have a INBOX/ namespace prefix: + dovecot unix - n n - - pipe + flags=DRhu user=vmail:vmail argv=/usr/local/libexec/dovecot/dovecot-lda -f ${sender} -d ${user}@${nexthop} -m INBOX/${extension} + +This example ignores address extensions (ie user+extension@domain.com +delivers just like user@domain.com ), but still shows the original +address for Sieve: + +:: + + dovecot unix - n n - - pipe + flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/dovecot-lda -f ${sender} -a ${original_recipient} -d ${user}@${nexthop} + +Replace ``vmail`` above with your virtual mail user account. + +Then set ``virtual_transport`` to ``dovecot`` in +``/etc/postfix/main.cf``: + +:: + + dovecot_destination_recipient_limit = 1 + virtual_mailbox_domains = your.domain.here + virtual_transport = dovecot + +And remember to run + +:: + + postfix reload + +Virtual users with multiple uids/gids +------------------------------------- + +If you need multiple uids/gids you'll need to set dovecot-lda setuid +root or invoke it through sudo. See :ref:`LDA` for how to do this securely. + +Postfix with a NFS mail store +----------------------------- + +If you are experiencing problems with dovecot-lda processes hanging when +delivering to an NFS mail store, it's likely that the dovecot-lda +process is hanging while waiting for free locks. The occurrence of this +can be greatly reduced, if not eradicated, by forcing Postfix to only +deliver to the same recipient one at a time. + +:: + + dovecot_destination_concurrency_limit = 1 + +Prevent backscatter +------------------- + +To prevent backscatter you should configure Postfix to reject mail for +nonexistent recipients. + +This is the default behaviour (``smtpd_reject_unlisted_recipient = yes``) so +there's no need to set "reject_unlisted_recipient" in any of your +restriction. But: Postfix must know if a recipient exists. Depending on +how you've configured Dovecot and Postfix this can be done several ways. + +System users +~~~~~~~~~~~~ + +If you only use local system users this is no problem - all valid +recipients can be found in the local password or alias database. + +Virtual users (static) +~~~~~~~~~~~~~~~~~~~~~~ + +When you use virtual users and domains you should maintain a list of +valid recipients. The relevant settings are: + +**virtual_alias_maps, virtual_mailbox_maps** + +For static verification you can maintain the content of the files +yourself. For every recipient or alias you need one entry. Example: + +**virtual_alias_maps** + +:: + + name_recipient@example.com external@example.net + +**virtual_mailbox_maps** + +:: + + name@example.com OK + recipient@example.com available + +Don't forget to run "postmap" afterwards. + +.. note:: + + If you use the Dovecot LDA or LMTP it doesn't matter what you + use behind the recipient address. Use "OK", the full name of the user or + else. + +Virtual users (dynamic) +~~~~~~~~~~~~~~~~~~~~~~~ + +Do you already use a database (MySQL, PostgreSQL) for Dovecot? Use the +same source for Postfix. You only have to to define a valid sql query +for Postfix. Example: + +:: + + virtual_mailbox_maps = proxy:mysql:/etc/postfix/virtual_mailbox_maps.cf + +**virtual_mailbox_maps.cf** + +:: + + user = mysql-user + password = mysql-password + hosts = unix:/var/run/mysql/mysqld.sock + dbname = mailserver + query = SELECT name FROM mailbox WHERE email='%s' + +This query will return the value of the filed "name" from table +"mailbox" if the email address of the recipient matches the email from +the field "email". This is enough for Postfix because Postfix must only +know if the recipient exists. The value doesn't matter. When you use a +database (or LDAP) there's no need to manually maintain a file with +valid recipients. + +.. note:: + + If you use "relay_domains" instead of + "virtual_mailbox_domains" you have to use "relay_recipient_maps" instead + of "virtual_mailbox_maps". + +Dynamic address verification with LMTP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +With Dovecot 2.0 you can also use LMTP and the Postfix setting +"reject_unverified_recipient" for dynamic address verification. It's +really nice because Postfix doesn't need to query an external datasource +(MySQL, LDAP...). Postfix maintain a local database with existing/non +existing addresses (you can configure how long positive/negative results +should be cached). + +To use LMTP and dynamic address verification you must first get Dovecot +working. Then you can configure Postfix to use LMTP and set +"reject_unverified_recipient" in the smtpd_recipient_restrictions. + +On every incoming email Postfix will probe if the recipient address +exists. You will see similar entries in your logfile: + +:: + + Recipient address rejected: undeliverable address: host tux.example.com[private/dovecot-lmtp] said: 550 5.1.1 < tzknvtr@example.com > User doesn't exist: tzknvtr@example.com (in reply to RCPT TO command); from=< cnrilrgfclra@spammer.org > to=< tzknvtr@example.com > + +If the recipient address exists (status=deliverable) Postfix accepts the +mail. + +.. note:: + + You cannot use "reject_unverified_recipient" with "pipe" so + this doesn't work with the Dovecot LDA "deliver". diff --git a/source/configuration_manual/howto/dovecot_lda_qmail.rst b/source/configuration_manual/howto/dovecot_lda_qmail.rst new file mode 100644 index 0000000000..c5ceb23720 --- /dev/null +++ b/source/configuration_manual/howto/dovecot_lda_qmail.rst @@ -0,0 +1,32 @@ +.. _howto-dovecot_lda_qmail: + +Dovecot LDA with Qmail +====================== + +System users +------------ + +The delivery command you need is + +:: + + |/var/qmail/bin/preline -f /usr/local/libexec/dovecot/dovecot-lda + +(You may need to adjust the paths to match your qmail and dovecot +installations.) The ``preline`` command will add the ``Return-Path:`` +and ``Delivered-To:`` lines, because ``dovecot-lda`` doesn't recognize +qmail's environment variables. + +For site-wide usage, put that in ``/var/qmail/control/defaultdelivery`` +(assuming you installed qmail according to +`LWQ `__). Or, save it as +``.qmail`` in selected users' home directories. + +Virtual users +------------- + +Add the ``-d`` parameter to specify the destination username: + +:: + + |/var/qmail/bin/preline -f /usr/local/libexec/dovecot/dovecot-lda -d $EXT@$USER diff --git a/source/configuration_manual/howto/dovecot_lda_sendmail.rst b/source/configuration_manual/howto/dovecot_lda_sendmail.rst new file mode 100644 index 0000000000..93ead89608 --- /dev/null +++ b/source/configuration_manual/howto/dovecot_lda_sendmail.rst @@ -0,0 +1,107 @@ +.. _howto-dovecot_lda_sendmail: + +Dovecot LDA with Sendmail +========================= + +The following describes how to configure Sendmail to use ``dovecot-lda`` +where ``root`` permission is not granted and Dovecot runs under a single +user ID. It may need some adjustment for more typical setups. Other +assumptions are that Sendmail is configured for virtual hosting and that +local-system mail delivery is not handled by ``dovecot-lda``. + +Allowing that ``sendmail.mc`` has ``MAILER(procmail)dnl`` included, edit +``sendmail.cf`` adding these lines after the ``Mprocmail`` definition: + +:: + + ######################*****############## + ### DOVECOT Mailer specification ### + ##################*****################## + Mdovecot, P=/usr/local/libexec/dovecot/dovecot-lda, F=DFMPhnu9, + S=EnvFromSMTP/HdrFromSMTP, R=EnvToSMTP/HdrFromSMTP, + T=DNS/RFC822/X-Unix, + A=/usr/local/libexec/dovecot/dovecot-lda -d $u + +If you're using ``sendmail.mc`` then put the lines above into a new file +``/usr/share/sendmail-cf/mailer/dovecot.m4`` and put ``MAILER(dovecot)`` +into your ``sendmail.mc`` + +=================================== + +Another method of doing the above is by editing your ``hostname.mc`` +with the following three lines: + +:: + + FEATURE(`local_procmail', `/usr/local/libexec/dovecot/dovecot-lda',`/usr/local/libexec/dovecot/dovecot-lda -d $u') + MODIFY_MAILER_FLAGS(`LOCAL', `-f') + MAILER(procmail) + +After editing ``hostname.mc`` with the above, be sure to remake your +``hostname.cf`` file. This is confirmed to work with: + +- dovecot-1.0.7 + +- FreeBSD 6.3-RELEASE-p3 i386 + +- sendmail Version 8.14.2 + +- Compiled with: DNSMAP LOG MAP_REGEX MATCHGECOS MILTER MIME7TO8 + MIME8TO7 NAMED_BIND NETINET NETINET6 NETUNIX NEWDB NIS PIPELINING + SASLv2 SCANF STARTTLS TCPWRAPPERS USERDB XDEBUG + +=================================== + +If ``sendmail`` runs under a different non-``root`` UID via + +- :literal:`define(`confRUN_AS_USER', `sendmail')dnl` + +in ``sendmail.mc``, then the ``env_put(t_strconcat("RESTRICT\_`` lines in +``deliver.c`` must be commented-out. + +Now add a + +:: + + virtualdomain.example.com vmail:vmail + +line for each virtual domain to ``mailertable.cf`` and run +``makemap hash mailertable.db < mailertable.cf``. The ``dovecot`` (or +some other random text) after the colon character is required, else +``sendmail`` will fail to pass command arguments to ``dovecot-lda`` +correctly. Make sure all the virtual domains are in the +``virtuserdomains`` file. + +=========================================== + +(Fedora 14: dovecot 2.0.8 & sendmail 8.14.4) + +Summing up all previous experience, one may keep all virtual user +accounts under one system account. + +The sendmail's "U=" mailer option with changing the owner of lda (to +"keeper" here for instance): + +:: + + -rwxr-xr-x. 1 keeper mail 14536 Dec 7 16:43 /usr/libexec/dovecot/dovecot-lda + +allows to run virtual users under one system account without applying +SUID. + +Sendmail can pass a user account to LDA with or without the domain. +Passing a user name without the domain can be achieved with S=/R= +rewriting rules of the local mailer. Finally, into +``/usr/share/sendmail-cf/mailer/dovecot.m4`` goes the block of lines: + +:: + + Mdovecot, P=/usr/libexec/dovecot/dovecot-lda, + F=l59DFMPhnuS, + S=EnvFromL/HdrFromL, R=EnvToL/HdrToL, + M=51200000, + U=keeper:mail, + T=DNS/RFC822/X-Unix, + A=/usr/libexec/dovecot/dovecot-lda -d $u + +Sendmail's dovecot.m4 can be a bit more complex. diff --git a/source/configuration_manual/howto/dovecot_lda_zmailer.rst b/source/configuration_manual/howto/dovecot_lda_zmailer.rst new file mode 100644 index 0000000000..f228bf8dc2 --- /dev/null +++ b/source/configuration_manual/howto/dovecot_lda_zmailer.rst @@ -0,0 +1,68 @@ +.. _howto-dovecot_lda_zmailer: + +Dovecot LDA as local delivery agent for ZMailer +=============================================== + +1. Add to ``zmailer/sm.conf``: + +:: + + # dovecot LDA + dovecot SPfne /usr/local/libexec/dovecot/dovecot-lda dovecot-lda -e -d $u + +2. Change ``zmailer/scheduler.conf``: + +Set **local/file\*** and **local/pipe\*** to use "mailbox" delivery +agent: + +:: + + local/file* + local/pipe* + ... + # ZMailer local delivery transport agent + command="mailbox -8HS -l ${LOGDIR}/mailbox" + +and all the other **local/\*** to use Dovecot LDA: + +:: + + local/* + ... + # Dovecot as the local delivery agent: + command="sm -8Hc $channel dovecot" + +This makes all deliveries to local users go via Dovecot LDA, but users +can also run pipes or store to files in their ``.forward`` files. (This +is why there are tag-matchers for "local/file\*" and "local/pipe\*" before +"local/\*" in the ``scheduler.conf`` file; those are for the cases that +must not go via Dovecot LDA.) + +If you're going to use dovecot-lda's ``-e`` parameter you'll need to +patch either Dovecot or ZMailer sources. When dovecot-lda wants to +reject mails, it exits with EX_NOPERM code, but ZMailer thinks this +isn't normal and logs "(this is abnormal, investigate!)". + +ZMailer fix in ``zmailer/transports/libta/diagnostic.c``: + +.. code:: diff + + - case EX_NOPERM: + case EX_PROTOCOL: + case EX_USAGE: + strcat(message, + " (this is abnormal, investigate!)"); + s += strlen(s); + /* fall through */ + + case EX_NOPERM: + case EX_NOUSER: + case EX_NOHOST: + case EX_UNAVAILABLE: + +Or Dovecot fix in ``dovecot-2.0/src/lda/main.c``: + +.. code:: diff + + if (stderr_rejection) + - return EX_NOPERM; + + return EX_UNAVAILABLE; diff --git a/source/configuration_manual/howto/dovecot_lmtp_exim.rst b/source/configuration_manual/howto/dovecot_lmtp_exim.rst new file mode 100644 index 0000000000..781b624b20 --- /dev/null +++ b/source/configuration_manual/howto/dovecot_lmtp_exim.rst @@ -0,0 +1,146 @@ +.. _howto-dovecot_lmtp_exim: + +===================== +Dovecot LMTP and Exim +===================== + +Exim provides support for LMTP over UNIX sockets using the `LMTP +transport `__, +your distribution may/not provide this, run exim -bV and check for +'lmtp' in 'Transports:'. Support for LMTP over TCP sockets is provided +by the `SMTP +transport `__. + +Using LMTP over UNIX Socket +=========================== + +Use this configuration if dovecot runs on the same host as exim. + +Example router: + +:: + + local_user: + debug_print = "R: local_user for $local_part@$domain" + driver = accept + domains = +local_domains + check_local_user + transport = dovecot_lmtp + cannot_route_message = Unknown user + +Example transport: + +:: + + dovecot_lmtp: + driver = lmtp + socket = /var/run/dovecot/lmtp + #maximum number of deliveries per batch, default 1 + batch_max = 200 + #allow suffixes/prefixes (default unset) + rcpt_include_affixes + +Using LMTP over TCP Socket +========================== + +Example router: + +:: + + local_user: + transport = dovecot_lmtp + domains = +local_domains + driver = manualroute + route_list = "* 192.168.1.0 byname" + #if destination server is the local host enable this + #self = send + +Set IP and port as appropriate to your setup. + +Example transport: + +:: + + dovecot_lmtp: + driver = smtp + #allow suffixes/prefixes (default unset) + rcpt_include_affixes + protocol = lmtp + port = 2525 + +Striping domain to avoid user unknown / doesn't exist error +=========================================================== + +If you are using a userdb which does not have domain names, you may need +to add a setting to 20-lmtp.conf + +:: + + protocol lmtp { + ... + # use %n to strip away the domain part + auth_username_format = %n + } + +Symptoms: + +- Exim says something like "LMTP error after RCPT ... 550 ... User + doesn't exist user@domain" + +- Dovecot verbose log says something like "auth-worker(9048): + passwd(user@domain): unknown user" + +Verifying recipients using LMTP +=============================== + +You can use callout verification to avoid accepting mail for addresses +which do not exist in Dovecot. Below is a config snippet which could be +used in acl_smtp_rcpt to achieve this: + +:: + + deny + message = invalid recipient + domains = +local_domains + !verify = recipient/callout=no_cache + +For more information on address verification see `the related section of +the Exim +specification `__. + +Delivering mails case insensitively +=================================== + +**Warning:**\ Just use this setup if all your login names contain only +lower case characters! (On Linux see /etc/adduser.conf under NAME_REGEX +variable). + +Exim retains the case of the local part. Dovecot's LMTP *may* fail +looking up an incorrect cased local part in your userdb. You can solve +this problem by extending the *protocol lmtp* section: + +:: + + protocol lmtp { + ... + # use %Ln to strip away the domain part + auth_username_format = %Lu + } + +(If you don't mind allowing case insensitive logins for dovecot +authentication, you may set *auth_username_format* in the global +configuration accordingly and renounce the above change). + +In case you prefer to configure exim to lower case the local part +instead, add a router just before your local delivery router: + +:: + + lowercase_local: + debug_print = "R: lower case local_part for local delivery" + driver = redirect + redirect_router = local_user + data = ${lc:${local_part}} + +Make sure to reference the name you have chosen for your local delivery +router within *redirect_router*. diff --git a/source/configuration_manual/howto/imapc_proxy.rst b/source/configuration_manual/howto/imapc_proxy.rst index 0e1ce0e236..b18dcd1d81 100644 --- a/source/configuration_manual/howto/imapc_proxy.rst +++ b/source/configuration_manual/howto/imapc_proxy.rst @@ -121,7 +121,7 @@ Next, type: :: - 02 LOGIN username correctpassword + 02 LOGIN username password And should see a list similar to this: diff --git a/source/configuration_manual/protocols/lda.rst b/source/configuration_manual/protocols/lda.rst index c4b7d8322f..8be8340d4b 100644 --- a/source/configuration_manual/protocols/lda.rst +++ b/source/configuration_manual/protocols/lda.rst @@ -6,24 +6,23 @@ Dovecot LDA The Dovecot LDA is a :ref:`mail delivery agent `, which takes mail from an :ref:`mta` and delivers it to a user's mailbox, while keeping Dovecot index files up to -date. Nowadays you should probably use the `LMTP server ` +date. Nowadays you should probably use the :ref:`LMTP server ` instead, because it's somewhat easier to configure (especially related to permissions) and gives better performance. This page describes the common settings required to make LDA work. You should read it first, and then the MTA specific pages: -- `LDA/Postfix `_ -- `LDA/Exim `_ -- `LDA/Sendmail `_ -- `LDA/Qmail `_ -- `LDA/ZMailer `_ +- :ref:`Postfix ` +- :ref:`Exim ` +- :ref:`Sendmail ` +- :ref:`Qmail ` +- :ref:`ZMailer ` Main features of Dovecot LDA ----------------------------- +============================ -- `Mailbox indexing during mail - delivery `_, providing +- :ref:`Mailbox indexing during mail delivery `, providing faster mailbox access later - :ref:`Quota enforcing by a plugin ` @@ -35,7 +34,7 @@ Main features of Dovecot LDA - Vacation auto-reply Common configuration --------------------- +==================== The settings are listed in the example ``conf.d/15-lda.conf`` file. The important settings are: @@ -63,7 +62,7 @@ password related settings to a separate file, which you include with ``!include_try`` and dovecot-lda skips them. Parameters ----------- +========== Parameters accepted by dovecot-lda: @@ -124,9 +123,9 @@ Parameters accepted by dovecot-lda: this parameter multiple times. Return values -------------- +============= -dovecot-lda will exit with one of the following values: +:man:dovecot-lda(1): will exit with one of the following values: - 0 (EX_OK): Delivery was successful. @@ -142,7 +141,7 @@ dovecot-lda will exit with one of the following values: all failures. See the log file for details. System users ------------- +============ You can use LDA with a few selected system users (ie. user is found from ``/etc/passwd`` / NSS) by calling dovecot-lda in the user's @@ -153,14 +152,13 @@ You can use LDA with a few selected system users (ie. user is found from | "/usr/local/libexec/dovecot/dovecot-lda" This should work with any MTA which supports per-user ``.forward`` -files. For qmail's per-user setup, see -`LDA/Qmail `_. +files. For qmail's per-user setup, see :ref:`howto-dovecot_lda_qmail`. This method doesn't require the authentication socket explained below since it's executed as the user itself. Virtual users -------------- +============= With a lookup ~~~~~~~~~~~~~ @@ -275,7 +273,7 @@ sudo: instead of just plain ``/usr/local/libexec/dovecot/dovecot-lda``. Problems with dovecot-lda -------------------------- +========================= - If you are using :ref:`prefetch userdb `, @@ -337,7 +335,7 @@ For using syslog with dovecot-lda, set the paths empty: } Plugins -------- +======= - Most of the :ref:`Dovecot plugins ` work with dovecot-lda. @@ -345,3 +343,60 @@ Plugins - Sieve language support can be added with the :ref:`Pigeonhole Sieve plugin `. + +.. _lda-indexing: + +LDA Indexing +============ + +LDA's indexing basically does two things while message is being saved: + +1. It updates the main index file. + + - This improves performance with :Ref:`mbox ` + format, especially if :dovecot_core:ref:`mbox_very_dirty_syncs=no `. + + - With :ref:`Maildir ` the benefits of this are almost irrelevant. + +2. It updates the ``dovecot.index.cache`` file. + +Cache file +~~~~~~~~~~ + +The LDA also updates the cache file, which can be very useful with all +mailbox formats. It means that when an IMAP client wants to fetch the +message's metadata (e.g. some header fields), they're can be retrieved +from the cache file and Dovecot doesn't have to open and parse the +message file. There are some tradeoffs though: + +- LDA indexing wastes disk I/O because it has to open and update index + files + +- LDA indexing saves disk I/O because it already has the message body + in memory, so it doesn't need to read it from disk. + +- IMAP indexing wastes disk I/O because it has to open and read message + files + +- IMAP indexing may save disk I/O because IMAP process always has index + files opened, and many IMAP clients are configured to download all + new message bodies anyway, so the second time message bodies are read + they're already in memory + +So it depends on IMAP client if it's faster to use LDA or IMAP time +indexing. In any case the user experience is typically faster with LDA +indexing, because the message list metadata can be returned faster when +it's pre-indexed. + +See :ref:`mail_location_settings-index_files` for more information about +what the index files contain. + +Non-indexed mail delivery +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ignoring the benefits of cache file updates, the only thing left is the +main index updates. As mentioned above, with Maildir format these +benefits are very small. This also means that it's perfectly fine to use +a non-Dovecot MDA to deliver mails that doesn't update indexes. Dovecot +can efficiently see and index such new mails without doing anything +expensive like "rebuilding indexes". diff --git a/source/configuration_manual/protocols/lmtp_server.rst b/source/configuration_manual/protocols/lmtp_server.rst index c3228ee0db..0a9863fdef 100644 --- a/source/configuration_manual/protocols/lmtp_server.rst +++ b/source/configuration_manual/protocols/lmtp_server.rst @@ -109,7 +109,7 @@ Using LMTP with different MTAs * :ref:`Postfix ` -* `Exim `_ +* :ref:`Exim ` * `HALON `_ From a54902d54a48dd0d595f4b42c401f0c57d045e32 Mon Sep 17 00:00:00 2001 From: Aki Tuomi Date: Mon, 22 Jan 2024 20:21:27 +0200 Subject: [PATCH 07/10] sieve/pigeonhole_sieve_interpreter: Add missing backtick --- .../configuration_manual/sieve/pigeonhole_sieve_interpreter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst b/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst index 2787d62642..c22c52e1f2 100644 --- a/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst +++ b/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst @@ -92,7 +92,7 @@ Extension `vnd.dovecot.filter `_ :ref:`Extprograms plugin ` (v0.3+) no Implements filtering messages through a pre-defined set of external programs `vnd.dovecot.pipe `_ See :ref:`Extprograms plugin ` no Implements piping messages to a pre-defined set of external programs :ref:`pigeonhole_plugin_extprograms` (v0.3+) -vnd.dovecot.report `_ supported (v0.4.14+) no Implements sending Messaging Abuse Reporting Format (MARF) reports (:rfc:`5965`) +`vnd.dovecot.report `_ supported (v0.4.14+) no Implements sending Messaging Abuse Reporting Format (MARF) reports (:rfc:`5965`) ============================================================================================================================================ =================================================================================================================== ===================== ================================================================================================================================================== From 430644a34adc97bd0f181a811a95162d6e159163 Mon Sep 17 00:00:00 2001 From: Aki Tuomi Date: Tue, 23 Jan 2024 14:23:03 +0200 Subject: [PATCH 08/10] sieve/pigeonhole_sieve_interpreter: Remove duplicate link --- .../sieve/pigeonhole_sieve_interpreter.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst b/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst index c22c52e1f2..1941592ea4 100644 --- a/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst +++ b/source/configuration_manual/sieve/pigeonhole_sieve_interpreter.rst @@ -90,9 +90,8 @@ Extension `vnd.dovecot.environment `_ supported (v0.4.14+) no Extends the standard "environment" extension with extra items and a variables namespace for direct access `vnd.dovecot.execute `_ :ref:`Extprograms Plugin ` (v0.3+) no Implements executing a pre-defined set of external programs with the option to process string data through the external program `vnd.dovecot.filter `_ :ref:`Extprograms plugin ` (v0.3+) no Implements filtering messages through a pre-defined set of external programs -`vnd.dovecot.pipe `_ See :ref:`Extprograms plugin ` no Implements piping messages to a pre-defined set of external programs - :ref:`pigeonhole_plugin_extprograms` (v0.3+) -`vnd.dovecot.report `_ supported (v0.4.14+) no Implements sending Messaging Abuse Reporting Format (MARF) reports (:rfc:`5965`) +`vnd.dovecot.pipe `_ :ref:`Extprograms plugin ` (v0.3+) no Implements piping messages to a pre-defined set of external programs +`vnd.dovecot.report `_ supported (v0.4.14+) no Implements sending Messaging Abuse Reporting Format (MARF) reports (:rfc:`5965`) ============================================================================================================================================ =================================================================================================================== ===================== ================================================================================================================================================== From 78015a7c7169f4e50de1d9be5ed3d12616aaf0a1 Mon Sep 17 00:00:00 2001 From: Aki Tuomi Date: Thu, 12 Oct 2023 13:34:50 +0300 Subject: [PATCH 09/10] spelling: Update expectations --- .github/actions/spelling/expect.txt | 121 +++++++++++++++----------- .github/actions/spelling/patterns.txt | 5 +- source/admin_manual/mda.rst | 2 +- 3 files changed, 72 insertions(+), 56 deletions(-) diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index b1316a55ae..080e66c665 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -10,11 +10,8 @@ addhdrvar addprinc ADDRESULT ADH -admins -AEAD Aildir allbackups -alloca alloconly altmove altpath @@ -38,13 +35,12 @@ asdfgh Atilika atimes atmail -ATo auid authdb +AUTHENTICATIONFAILED authpriv authtok authuser -authz autocreate autocreated Autocreation @@ -61,13 +57,16 @@ autosubscribed autotools auxw avc +Avel +avelsieve azp +backported +badpassword bantime barfoo basearch bayes bcc -BDAT bernat bindir bitfield @@ -98,7 +97,6 @@ ccert cdb cdmi certbot -CFLAGS Chales changetype chasquid @@ -114,11 +112,9 @@ cifs cip cipe Ciphersuites -CJK clockspeed clucene clusterfs -cmake cmdlog cmds cmusieve @@ -131,19 +127,18 @@ commitlog Compuserve CONDSTORE CONTAINERNAME +convertpw copybox COPYUID coretest coreutils courierimapuiddb -cov cpanel CPID CPPFLAGS cql cqlsh CRLFs -CRLs crt ctlr currentdate @@ -157,7 +152,6 @@ datalake datastack datastax datatracker -dbg dbox dboxes dclocal @@ -166,6 +160,7 @@ DDTHH debian debuginfo deeplinks +defaultdelivery deinitialization Deinitialize deinitialized @@ -174,7 +169,6 @@ delaycompress deleteheader denotify dentries -deref destuser desync desynchronized @@ -192,8 +186,10 @@ distros dlog dlua DMARC +dnl dnotify dnpass +DNSMAP docidx Docindex domaindb @@ -240,9 +236,7 @@ effinger egid EID Eing -eip ekh -emacs emaillookup endscript ENHANCEDSTATUSCODES @@ -261,6 +255,7 @@ etuid eucjp euid examplescripts +execv exim exportkeytab Expu @@ -280,6 +275,7 @@ fgrep fieldvalue fileinto findtime +firewalls firstsaved flagsmodseq flatcurve @@ -306,7 +302,6 @@ ftscache FULLDIRNAME fulltext gauner -gcc gcda gcov gecos @@ -318,13 +313,13 @@ genpkey geodb gethosterror getmail -GETSCRIPT +getscript gitlab Gluster gmatch gno gnomint -GNUC +gnutls gpg gpgcheck gpgkey @@ -352,7 +347,6 @@ hostaddr hostchange hostdomain hostip -Hotspot howto howtoforge htdigest @@ -360,9 +354,8 @@ htiweb htpasswd httpchk httplog -IAT ICAL -idx +idfield IES ietf ifmail @@ -373,6 +366,7 @@ imapcpass imapd imapfilter imapflags +imapproxy imaps imapsieve imaptest @@ -388,8 +382,8 @@ INCLUDERC INDEXCACHE indexfiles INDEXPVT +inetd inka -inlines Inno inodes inodetofile @@ -417,6 +411,7 @@ johndoh joulu junkflag kadmin +kaworu kde kdump keeptemp @@ -428,9 +423,11 @@ keyspace keytab KIB kinit +kio klist kludgy kmail +kocmuk korvatunturi KPOP krb @@ -487,6 +484,7 @@ libsasldb libsodium libsqlite libstemmer +libta lifewithqmail linelen linenos @@ -494,6 +492,7 @@ listescape listfile listindex listname +listscripts LISTSERV literalinclude lmtp @@ -502,6 +501,7 @@ lmtponly lmtptest localdb localdomain +localuser lockd lockdir lockf @@ -525,8 +525,10 @@ lrwstipekxacd lsearch lucene lugog +lwq maclen madboa +mailauth mailboxdir mailboxguid mailboxlog @@ -537,6 +539,7 @@ maildirlock maildirquota maildirsize maildrop +mailertable mailfolders mailhome mailinglist @@ -549,9 +552,11 @@ mailwriter maj makecache Makefiles +makemap managesieve managesieved manmaster +manualroute mapuser MARF markasjunk @@ -559,6 +564,7 @@ masteradmin masterpass masteruser matadata +MATCHGECOS maxconn maxdepth maxproc @@ -571,8 +577,10 @@ mboxlocking mboxmetadata mboxo mboxrd +mclroy mda mdbox +Mdovecot melnikov memarea memtable @@ -585,7 +593,6 @@ metawrap millisecs mimencode missingok -mkcert mkhomedir mmap mmencode @@ -595,6 +602,7 @@ mountpoint mozilla mpi mpid +Mprocmail mseconds msn mta @@ -604,7 +612,6 @@ MULTIAPPEND multiport multiscript murchison -mutf muttmua muttrc mybox @@ -615,22 +622,31 @@ myfoldertoo myhostname mynetworks mypassword -myscript mysqld +mysqldb +mysqlhost +mysqlpass +mysqlpassword +mysqltable +mysqluser +mysqlusername myuser myusername NBF neomutt -newkey +netcat +NETINET +NETUNIX +NEWDB newlock newmail Newsgroups newtok nexthop NEXTUID -NFKD nfsmount ngrams +ngrep ninf NLEVEL nlinks @@ -646,7 +662,6 @@ nodetool nodiratime nodns noenforcing -noindex NOINFERIORS noiv nolock @@ -707,7 +722,6 @@ origbox OR'ing ORing orld -OSERROR OSFILE otherinstance otp @@ -721,12 +735,13 @@ packagecloud pacman pandoc passdb +passfield passthrough -Pbase +passwdfile pbkd -pcre +PERMANENTFLAGS pfs -PGP +Phnu pidfile pidof pids @@ -737,6 +752,7 @@ pkgsysconfdir pki plaa policyd +popafter popclient porkmail postconf @@ -744,6 +760,7 @@ postfixadmin postgresql postgrey postlogin +postmap postrotate powerdns poweruser @@ -753,6 +770,7 @@ preauthenticated precache precaching preinit +preline PREREQ princ printfa @@ -763,14 +781,11 @@ procmailrc proctitle promotionalmail proofpoint -PROT proxymap -Ptest -ptr pubout pukki pushmail -PUTSCRIPT +putscript pvo pwcheck pwdfile @@ -809,12 +824,12 @@ reqbody rescanned rescanning resolv +restorecon resyncing resyncronized RFCs rhel RHu -RLIMIT rmail Rnotation roundcube @@ -828,6 +843,7 @@ rsapubkey rspamc rspamd rsyslog +rubygems rundir Rvdm rwstipekxa @@ -843,10 +859,10 @@ savedsince SAVEONLY scalemail scality +SCANF scontext scriptname sdbox -sdc SDPS SEARCHRES seclabel @@ -865,8 +881,7 @@ seperately seqno SERVERBUG servermetadata -SETACTIVE -setcap +setactive setcred setra setspn @@ -882,6 +897,7 @@ sievemailinglist sieverules slashdot slusarz +smartsieve smbfs smi smtps @@ -916,7 +932,6 @@ sqlpass sqlpool sqlquota sqluser -srv ssd ssha ssldir @@ -936,14 +951,10 @@ strfuncs strlcpy strocpy strp -strsplit -STW subaccounts subaddress -subdomain -subfolders +subaddresses subjwas -subkey submissiond subname Subtables @@ -961,6 +972,7 @@ syslogd syslogging sysreport TABLEGEN +Taddressverification tarballs Tarpit tarpitted @@ -968,12 +980,12 @@ tarpitting tclass tcontext tcps +TCPWRAPPERS tecadmin technet tempdisabled tempfail tempfailing -templating Tenuring terabyte testdomain @@ -1008,7 +1020,6 @@ tscript TTLs tukaani tuxfamily -TYPECHECK typedef tzknvtr uidgid @@ -1024,7 +1035,6 @@ UKS unaccessed unaliased unauth -uncompressing unconfigured und UNDRAFT @@ -1032,6 +1042,7 @@ unhibernate unhibernated unhibernating unhibernation +unistd unixtime unixtimedate UNKEYWORD @@ -1046,6 +1057,7 @@ uppercased uppercasing upperfirst upserting +urandom Urg urlauth URLFETCH @@ -1058,6 +1070,7 @@ userguide userid userinfo userip +userlogin usernames userok uucp @@ -1070,12 +1083,15 @@ Valgrinding vboxadm vda vdb +vdomains Venema vfile vfuncs vgdb -virtualenv +VIRT +virtualdomain virtualised +virtuserdomains virustest Vjcm vlan @@ -1097,11 +1113,10 @@ wcf weakforced webmail webpage +websieve wforce Wietse -wikipedia wikis -WILLNEED winbind worl wrappermode @@ -1123,5 +1138,5 @@ XRCPTFORWARD xuidl yourldap zimbra -ZMailer +zmailer Zstandard diff --git a/.github/actions/spelling/patterns.txt b/.github/actions/spelling/patterns.txt index 23c4f0af9a..65c827fab4 100644 --- a/.github/actions/spelling/patterns.txt +++ b/.github/actions/spelling/patterns.txt @@ -107,7 +107,8 @@ d88ff1001d4bf753a1b800001accfe22 &U,BTFw- &ZeVnLIqe- -adnPNSx - +F=DFMPhnu9, +SPfne \bAPPEND(?:ed|s) # @@ -158,4 +159,4 @@ key=[0-9a-f]+:\w+\}\s*=\s*(?:[0-9a-f$]+|pass) \b([A-Za-z])\g{-1}{3,}\b # directory permissions -[d-][rs-][ws-][xts-][rs-][ws-][xts-] +[-bcdlpsw](?:[-r][-w][-SsTtx]){3}[\.+*]?\s+\d+\s+\S+\s+\S+\s+\d+\s+ diff --git a/source/admin_manual/mda.rst b/source/admin_manual/mda.rst index fc5dbfe0eb..a32d72f5b1 100644 --- a/source/admin_manual/mda.rst +++ b/source/admin_manual/mda.rst @@ -15,7 +15,7 @@ virtual mailbox. Common choices include: -- `maildrop `__ +- `maildrop `_ - `procmail `__ From bf174507dc7fca309549628be8f83c459ee20373 Mon Sep 17 00:00:00 2001 From: Aki Tuomi Date: Tue, 23 Jan 2024 08:54:13 +0200 Subject: [PATCH 10/10] global: Replace mail_debug with log_debug --- source/admin_manual/debugging/mail_debugging.rst | 4 ++-- source/admin_manual/logging.rst | 2 +- source/configuration_manual/apparmor.rst | 2 +- .../howto/virtual_user_flat_files_postfix.rst | 2 -- source/configuration_manual/mail_location/index.rst | 2 +- source/configuration_manual/quota/index.rst | 2 +- .../shared_mailboxes/shared_mailboxes.rst | 2 +- source/configuration_manual/sieve/troubleshooting.rst | 2 +- 8 files changed, 8 insertions(+), 10 deletions(-) diff --git a/source/admin_manual/debugging/mail_debugging.rst b/source/admin_manual/debugging/mail_debugging.rst index 3a1fac8744..c96b890678 100644 --- a/source/admin_manual/debugging/mail_debugging.rst +++ b/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. \ No newline at end of file +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. diff --git a/source/admin_manual/logging.rst b/source/admin_manual/logging.rst index 6ac02e8f7e..5e5631e713 100644 --- a/source/admin_manual/logging.rst +++ b/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 ` 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 ` enables all kinds of mail related debug logging, such as showing where Dovecot is looking for mails. +* :dovecot_core:ref:`log_debug = category=mail ` enables all kinds of mail related debug logging, such as showing where Dovecot is looking for mails. * :dovecot_core:ref:`verbose_ssl=yes ` 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. diff --git a/source/configuration_manual/apparmor.rst b/source/configuration_manual/apparmor.rst index c8863f1d00..58579126b8 100644 --- a/source/configuration_manual/apparmor.rst +++ b/source/configuration_manual/apparmor.rst @@ -35,4 +35,4 @@ Sample Configuration Debugging ========= -Enable :dovecot_core:ref:`mail_debug` to see context changes. +Enable :dovecot_core:ref:`log_debug` to see context changes. diff --git a/source/configuration_manual/howto/virtual_user_flat_files_postfix.rst b/source/configuration_manual/howto/virtual_user_flat_files_postfix.rst index d5218febf5..b0f8a9284f 100644 --- a/source/configuration_manual/howto/virtual_user_flat_files_postfix.rst +++ b/source/configuration_manual/howto/virtual_user_flat_files_postfix.rst @@ -218,7 +218,6 @@ Logging ` for more complex configurations. log_path = /var/log/dovecot.log info_log_path = /var/log/dovecot-info.log - mail_debug = no Syslog Logging ============== @@ -229,7 +228,6 @@ Syslog Logging #log_path = #info_log_path = - mail_debug = no syslog_facility = local1 ``/etc/rsyslog.conf`` diff --git a/source/configuration_manual/mail_location/index.rst b/source/configuration_manual/mail_location/index.rst index 8d4781a18f..4ba250f054 100644 --- a/source/configuration_manual/mail_location/index.rst +++ b/source/configuration_manual/mail_location/index.rst @@ -324,7 +324,7 @@ Mailbox Autocreation Autocreation is only triggered if :dovecot_core:ref:`mail_location` is correctly set. You'll see something like this if you enable -:dovecot_core:ref:`debug logging ` (example for ``mbox`` mailbox +:dovecot_core:ref:`debug logging ` (example for ``mbox`` mailbox format): .. code-block:: none diff --git a/source/configuration_manual/quota/index.rst b/source/configuration_manual/quota/index.rst index 81726aa22b..20ce9706e9 100644 --- a/source/configuration_manual/quota/index.rst +++ b/source/configuration_manual/quota/index.rst @@ -79,7 +79,7 @@ If you're wondering why per-user quota isn't working: * Check that :ref:`dovecot-lda ` is called with ``-d`` parameter. * Check that you're not using :ref:`authentication-static_user_database`. * Check that ``quota_rule`` setting is properly returned by userdb. Enable - ``log_debug = category=auth`` and ``mail_debug = yes`` to see this. + :dovecot_core:ref:`log_debug = category=auth or category=mail ` to see this. For example: diff --git a/source/configuration_manual/shared_mailboxes/shared_mailboxes.rst b/source/configuration_manual/shared_mailboxes/shared_mailboxes.rst index 99717d0eef..dc57a701e7 100644 --- a/source/configuration_manual/shared_mailboxes/shared_mailboxes.rst +++ b/source/configuration_manual/shared_mailboxes/shared_mailboxes.rst @@ -318,7 +318,7 @@ Troubleshooting --------------- - Make sure the ``%`` and ``%%`` variables are specified correctly in the - namespace location. ``mail_debug=yes`` will help you see if Dovecot + namespace location. :dovecot_core:ref:`log_debug = category=mail ` will help you see if Dovecot is trying to access correct paths. - ``doveadm acl debug -u user@domain shared/user/box`` can be helpful diff --git a/source/configuration_manual/sieve/troubleshooting.rst b/source/configuration_manual/sieve/troubleshooting.rst index 5ae9623af8..6b9bf06c9c 100644 --- a/source/configuration_manual/sieve/troubleshooting.rst +++ b/source/configuration_manual/sieve/troubleshooting.rst @@ -36,7 +36,7 @@ Your MTA is not using Dovecot LDA or LMTP e.g. Exim or Postfix, for local message delivery. Most MTAs have their own local delivery agent, and without explicit configuration this is what is used. In that case, your Sieve scripts are simply - ignored. When you set :dovecot_core:ref:`mail_debug=yes ` in + ignored. When you set :dovecot_core:ref:`log_debug = category=sieve ` in your configuration, your logs will show details of LDA and/or LMTP execution. The following is an example of the first few log lines of an LDA delivery: