Update dovecot configuration comments to 2.3

This integrates the diff we had when deploying our changes on top of the
distribution-supplied Dovecot 2.3 configuration file.

Author: jchristgit

ansible/roles/dovecot/tasks/main.yml

@@ -98,17 +98,6 @@
   tags:
     - role::dovecot
 
-- name: Set up sieve configuration for dovecot
-  lineinfile:
-    path: /etc/dovecot/conf.d/90-sieve.conf
-    regexp: "sieve_after ="
-    line: "  sieve_after = /etc/dovecot/sieve-after  # (ansible managed)"
-    state: present
-  notify:
-    - Reload Dovecot
-  tags:
-    - role::dovecot
-
 - name: Create dovecot spam & ham sieve scripts
   template:
     src: "{{ item }}.j2"
@@ -149,33 +138,6 @@
   tags:
     - role::dovecot
 
-- name: Enable dovecot spamc learning integration
-  blockinfile:
-    path: /etc/dovecot/conf.d/90-sieve.conf
-    insertbefore: "^}$"
-    content: |2
-        # From elsewhere to Junk folder
-        imapsieve_mailbox1_name = Junk
-        imapsieve_mailbox1_causes = COPY
-        imapsieve_mailbox1_before = file:/etc/dovecot/sieve/learn-spam.sieve
-
-        # From Junk folder to elsewhere
-        imapsieve_mailbox2_name = *
-        imapsieve_mailbox2_from = Junk
-        imapsieve_mailbox2_causes = COPY
-        imapsieve_mailbox2_before = file:/etc/dovecot/sieve/learn-ham.sieve
-
-        sieve_pipe_bin_dir = {{ dovecot_sieve_pipe_bin_dir }}
-        sieve_global_extensions = +vnd.dovecot.pipe
-        sieve_plugins = sieve_imapsieve sieve_extprograms
-        imapsieve_url = sieve://127.0.0.1:4190
-    marker: "  # {mark} spam & ham autolearning (ansible managed)"
-    state: present
-  notify:
-    - Reload Dovecot
-  tags:
-    - role::dovecot
-
 # BEGIN temporary cleanup task
 - name: Kill Dovecot LDAP config
   file:
@@ -204,6 +166,7 @@
     - 20-lmtp.conf
     - 20-imap.conf
     - 90-acl.conf
+    - 90-sieve.conf
     - auth-ldap.conf.ext
   tags:
     - role::dovecot

ansible/roles/dovecot/templates/configs/10-auth.conf.j2

@@ -4,15 +4,18 @@
 ## Authentication processes
 ##
 
-# Disable LOGIN command and all other plaintext authentications unless
-# SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP
+#log_debug=category=auth
+#auth_debug_passwords = yes
+
+# Enable LOGIN command and all other plaintext authentications even if
+# SSL/TLS is not used (LOGINDISABLED capability). Note that if the remote IP
 # matches the local IP (ie. you're connecting from the same computer), the
-# connection is considered secure and plaintext authentication is allowed.
-# See also ssl=required setting.
+# connection is considered secure and plaintext authentication is allowed,
+# unless ssl = required.
 auth_allow_cleartext = no
 
 # Authentication cache size (e.g. 10M). 0 means it's disabled. Note that
-# bsdauth and PAM require cache_key to be set for caching to be used.
+# bsdauth, PAM and vpopmail require cache_key to be set for caching to be used.
 #auth_cache_size = 0
 # Time to live for cached data. After TTL expires the cached record is no
 # longer used, *except* if the main database lookup returns internal failure.
@@ -32,7 +35,7 @@ auth_allow_cleartext = no
 
 # Default realm/domain to use if none was specified. This is used for both
 # SASL realms and appending @domain to username in plaintext logins.
-#auth_default_realm =
+#auth_default_domain =
 
 # List of allowed characters in username. If the user-given username contains
 # a character not listed in here, the login automatically fails. This is just
@@ -46,11 +49,10 @@ auth_allow_cleartext = no
 # that '#' and '/' characters are translated to '@'.
 #auth_username_translation =
 
-# Username formatting before it's looked up from databases. You can use
-# the standard variables here, eg. %Lu would lowercase the username, %n would
-# drop away the domain if it was given, or "%n-AT-%d" would change the '@' into
-# "-AT-". This translation is done after auth_username_translation changes.
-auth_username_format = %Ln
+# Username formatting before it's looked up from databases.
+auth_username_format = %{user|lower}
+#auth_username_format = %{user|username|lower}
+
 
 # If you want to allow master users to log in by specifying the master
 # username within the normal username string (ie. not using SASL mechanism's
@@ -62,11 +64,6 @@ auth_username_format = %Ln
 # Username to use for users logging in with ANONYMOUS SASL mechanism
 #auth_anonymous_username = anonymous
 
-# Maximum number of dovecot-auth worker processes. They're used to execute
-# blocking passdb and userdb queries (eg. MySQL and PAM). They're
-# automatically created and destroyed as needed.
-#auth_worker_max_count = 30
-
 # Host name to use in GSSAPI principal names. The default is to use the
 # name returned by gethostname(). Use "$ALL" (with quotes) to allow all keytab
 # entries.
@@ -78,7 +75,7 @@ auth_username_format = %Ln
 #auth_krb5_keytab =
 
 # Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon and
-# ntlm_auth helper. <doc/wiki/Authentication/Mechanisms/Winbind.txt>
+# ntlm_auth helper. <https://doc.dovecot.org/latest/core/config/auth/mechanisms/winbind.html>
 #auth_use_winbind = no
 
 # Path for Samba's ntlm_auth helper binary.
@@ -96,10 +93,10 @@ auth_username_format = %Ln
 #auth_ssl_username_from_cert = no
 
 # Space separated list of wanted authentication mechanisms:
-#   plain login digest-md5 cram-md5 ntlm rpa apop anonymous gssapi otp
-#   gss-spnego
-# NOTE: See also disable_plaintext_auth setting.
-auth_mechanisms = plain login
+#   plain login digest-md5 cram-md5 ntlm anonymous gssapi
+#   gss-spnego xoauth2 oauthbearer
+# NOTE: See also auth_allow_cleartext setting.
+#auth_mechanisms = plain login
 
 ##
 ## Password and user databases
@@ -111,15 +108,16 @@ auth_mechanisms = plain login
 # allow both system users (/etc/passwd) and virtual users to login without
 # duplicating the system users into virtual database.
 #
-# <doc/wiki/PasswordDatabase.txt>
+# <https://doc.dovecot.org/latest/core/config/auth/passdb.html>
 #
 # User database specifies where mails are located and what user/group IDs
 # own them. For single-UID configuration use "static" userdb.
 #
-# <doc/wiki/UserDatabase.txt>
+# <https://doc.dovecot.org/latest/core/config/auth/userdb.html>
 
 #!include auth-deny.conf.ext
 #!include auth-master.conf.ext
+#!include auth-oauth2.conf.ext
 
 #!include auth-system.conf.ext
 #!include auth-sql.conf.ext

ansible/roles/dovecot/templates/configs/10-mail.conf.j2

@@ -4,7 +4,7 @@
 ## Mailbox locations and namespaces
 ##
 
-# Location for users' mailboxes. The
+# Location for users' mailboxes. The default is empty, which means that Dovecot
 # tries to find the mailboxes automatically. This won't work if the user
 # doesn't yet have any mail, so you should explicitly tell Dovecot the full
 # location.
@@ -14,21 +14,25 @@
 # kept. This is called the "root mail directory", and it must be the first
 # path given in the mail_location setting.
 #
-# There are a few special variables you can use, eg.:
+#   %{user} - username
+#   %{user|username} - user part in user@domain, same as %u if there's no domain
+#   %{user|domain} - domain part in user@domain, empty if there's no domain
+#   %{home} - home directory
 #
-#   %u - username
-#   %n - user part in user@domain, same as %u if there's no domain
-#   %d - domain part in user@domain, empty if there's no domain
-#   %h - home directory
+# See https://doc.dovecot.org/latest/core/settings/variables.html for full list
+# of variables.
 #
-# See doc/wiki/Variables.txt for full list. Some examples:
-#
-#   mail_location = maildir:~/Maildir
-#   mail_location = mbox:~/mail:INBOX=/var/mail/%u
-#   mail_location = mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%n
-#
-# <doc/wiki/MailLocation.txt>
+# Example:
+#  mail_driver = maildir
+#  mail_path = ~/Maildir
+#  mail_inbox_path = ~/Maildir/.INBOX
 #
+
+# Debian defaults
+# Note that upstream considers mbox deprecated and strongly recommends
+# against its use in production environments. See further information
+# at
+# https://doc.dovecot.org/2.4.0/core/config/mailbox/formats/mbox.html
 mail_home = /var/vmail/%{user}
 mail_driver = Maildir
 mail_path = %{home}/mail
@@ -59,7 +63,8 @@ namespace inbox {
 
   # Physical location of the mailbox. This is in same format as
   # mail_location, which is also the default for it.
-  #location =
+  # mail_driver =
+  # mail_path =
 
   # There can be only one INBOX, and this setting defines which namespace
   # has it.
@@ -85,18 +90,20 @@ namespace inbox {
 }
 
 # Example shared namespace configuration
-#namespace {
+#namespace shared {
   #type = shared
   #separator = /
 
   # Mailboxes are visible under "shared/user@domain/"
-  # %%n, %%d and %%u are expanded to the destination user.
-  #prefix = shared/%%u/
+  # $user, $domain and $username are expanded to the destination user.
+  #prefix = shared/$user/
 
-  # Mail location for other users' mailboxes. Note that %variables and ~/
-  # expands to the logged in user's data. %%n, %%d, %%u and %%h expand to the
+  # Mail location for other users' mailboxes. Note that %{variables} and ~/
+  # expands to the logged in user's data. %{owner_user} and %{owner_home}
   # destination user's data.
-  #location = maildir:%%h/Maildir:INDEX=~/Maildir/shared/%%u
+  #mail_driver = maildir
+  #mail_path = %{owner_home}/Maildir
+  #mail_index_path = ~/Maildir/shared/%{owner_user}
 
   # Use the default namespace for saving subscriptions.
   #subscriptions = no
@@ -109,11 +116,11 @@ namespace inbox {
 
 # System user and group used to access mails. If you use multiple, userdb
 # can override these by returning uid or gid fields. You can use either numbers
-# or names. <doc/wiki/UserIds.txt>
+# or names. <https://doc.dovecot.org/latest/core/config/system_users.html#uids>
 mail_uid = {{ dovecot_vmail_uid }}
 mail_gid = {{ dovecot_vmail_uid }}
 
-# Group to enable temporarily for privileged operations. Currently this is
+#  Group to enable temporarily for privileged operations. Currently this is
 # used only with INBOX when either its initial creation or dotlocking fails.
 # Typically this is set to "mail" to give access to /var/mail.
 mail_privileged_group = mail
@@ -133,7 +140,11 @@ mail_privileged_group = mail
 
 # Dictionary for key=value mailbox attributes. This is used for example by
 # URLAUTH and METADATA extensions.
-#mail_attribute_dict =
+#mail_attribute {
+#  dict file {
+#    path = %{home}/Maildir/dovecot-attributes
+#  }
+#}
 
 # A comment or note that is associated with the server. This value is
 # accessible for authenticated users through the IMAP METADATA server
@@ -216,10 +227,16 @@ mail_privileged_group = mail
 #auth_socket_path = /var/run/dovecot/auth-userdb
 
 # Directory where to look up mail plugins.
-#mail_plugin_dir = /usr/lib/dovecot/modules
+#mail_plugin_dir = /usr/lib/dovecot
 
 # Space separated list of plugins to load for all services. Plugins specific to
 # IMAP, LDA, etc. are added to this list in their own .conf files.
+#mail_plugins =
+#
+# To add plugins, use
+#mail_plugins {
+#  plugin = yes
+#}
 mail_plugins {
   welcome = yes
   notify = yes
@@ -249,7 +266,7 @@ mail_plugins {
 
 # When IDLE command is running, mailbox is checked once in a while to see if
 # there are any new mails or other changes. This setting defines the minimum
-# time to wait between those checks.
+# time to wait between those checks. Dovecot can also use inotify and
 # kqueue to find out immediately when changes occur.
 #mailbox_idle_check_interval = 30 secs
 
@@ -328,14 +345,8 @@ protocol !indexer-worker {
 # in is important to avoid deadlocks if other MTAs/MUAs are using multiple
 # locking methods as well. Some operating systems don't allow using some of
 # them simultaneously.
-#
-# The Debian value for mbox_write_locks differs from upstream Dovecot. It is
-# changed to be compliant with Debian Policy (section 11.6) for NFS safety.
-#       Dovecot: mbox_write_locks = dotlock fcntl
-#       Debian:  mbox_write_locks = fcntl dotlock
-#
 #mbox_read_locks = fcntl
-#mbox_write_locks = fcntl dotlock
+#mbox_write_locks = dotlock fcntl
 
 # Maximum time to wait for lock (all of them) before aborting.
 #mbox_lock_timeout = 5 mins
@@ -391,32 +402,6 @@ protocol !indexer-worker {
 # filesystems (ext4, xfs).
 #mdbox_preallocate_space = no
 
-##
-## Mail attachments
-##
-
-# sdbox and mdbox support saving mail attachments to external files, which
-# also allows single instance storage for them. Other backends don't support
-# this for now.
-
-# Directory root where to store mail attachments. Disabled, if empty.
-#mail_attachment_dir =
-
-# Attachments smaller than this aren't saved externally. It's also possible to
-# write a plugin to disable saving specific attachments externally.
-#mail_attachment_min_size = 128k
-
-# Filesystem backend to use for saving attachments:
-#  posix : No SiS done by Dovecot (but this might help FS's own deduplication)
-#  sis posix : SiS with immediate byte-by-byte comparison during saving
-#  sis-queue posix : SiS with delayed comparison and deduplication
-#mail_attachment_fs = sis posix
-
-# Hash format to use in attachment filenames. You can add any text and
-# variables: %{md4}, %{md5}, %{sha1}, %{sha256}, %{sha512}, %{size}.
-# Variables can be truncated, e.g. %{sha256:80} returns only first 80 bits
-#mail_attachment_hash = %{sha1}
-
 # Settings to control adding $HasAttachment or $HasNoAttachment keywords.
 # By default, all MIME parts with Content-Disposition=attachment, or inlines
 # with filename parameter are consired attachments.