Improve playbook doc

README.md

@@ -1,23 +1,21 @@
-ansible roles and playbooks for a mail server.
-
-Branch names correspond to debian release names.
-
-
 ## mail_system
 
-Setup a complete mail system with postfix, rspamd, dovecot and clamav, using PostgreSQL as backend.
+ansible role for debian buster setting up a mailserver with
+postfix, rspamd, dovecot and clamav and based on PostgreSQL
 
-* `mail_system` ansible role
-* `mail_system.yml` ansible playbook
+Attention: user and domain administration (in PostgreSQL) is not covered here
+
+* mail_system
+* mail_system.yml
 
-NB: A user and domain administration frontend is not included.
 
 ## journal-postfix
 
-Parse postfix entries in systemd journal and write delivery information to a PostgreSQL database.
+ansible role for debian buster parsing postfix entries in
+systemd journal and collecting delivery information
 
-* `journal-postfix` ansible role
-* `journal-postfix.yml` ansible playbook
-* `journal-postfix-doc` documentation
+* journal-postfix
+* journal-postfix.yml
+* journal-postfix-doc
 
 See [journal-postfix/files/srv/README.md](journal-postfix/files/srv/README.md)

mail_system.yml

@@ -1,13 +1,11 @@
-# ansible playbook
-#
-# Install a complete mail system with
+# install a complete mail system with
 #
 #   - postfix
 #   - dovecot
 #   - clamav (with unofficial signatures)
 #   - rspamd (integrating clamav)
 #
-# not included here: list server, roundcube, account and alias management
+# not included here: list server, roundcube
 #
 # Please edit the host's config (inventory/host_vars/${hostname}):
 # Add a new dictionary 'mailserver':
@@ -33,38 +31,69 @@
 #   dovecot:
 #     auth_default_realm: mymaindomain.org
 #
-# Take care thate the verp_marker only contains [a-z0-9]+ (NO UPPER CASE LETTERS!).
+# Setup a Postgresql database (named as in dbname, owned by username, reachable on
+# host and port) with something like that:
 #
-# (Use ansible-vault encrypt_string to encrypt the password.)
+#   createuser -P mailserver
+#   createdb -E utf8 -O mailserver -T template1 mailserver
+#
+# Use `ansible-vault encrypt_string` to obtain the encrypted password.
+#
+# Take care that the verp_marker only contains [a-z0-9]+ (NO UPPER CASE LETTERS!).
 #
 # TODOs after running this playbook:
 #
-# Open the firewall:
-#
-#     - open or DNAT the TCP ports 25, 143, 587, 4190 to the host (incoming)
-#     - allow outgoing traffic
-#
-# Configure mail DNS for your host:
+# Configure mail DNS:
 #
 #     - MX
 #     - PTR (IPv4 and IPv6)
 #
-# Add SPF, DMARC and DKIM DNS records whenever you add a mail domain:
+# SPF, DMARC and DKIM DNS records should be created when adding a domain:
 #
-#     - SPF ('IN TXT "v=spf1 mx"' or more)
-#     - DMARC ('_dmarc IN TXT "v=DMARC1; p=reject; rua=mailto:admin@mymaindomain.org; adkim=s; aspf=s;"')
+#     - SPF (IN TXT "v=spf1 mx" or more)
+#     - DMARC (_dmarc IN TXT "v=DMARC1; p=reject; rua=mailto:admin@mymaindomain.org; adkim=s; aspf=s;")
 #     - DKIM (rspamadm dkim_keygen -d mymaindomain.org -s 20190911 -b 4096;
-#             get the DNS entry and also save the private key)
+#             put the DNS entry in your zone file and save the private key
+#             into /var/lib/rspamd/dkim/mymaindomain.org.20190911.key
+#             and
+#                 chown _rspamd /var/lib/rspamd/dkim/*
+#                 chmod 400 /var/lib/rspamd/dkim/*
+#             and enable it by putting a line
+#                 mymaindomain.org 20190911
+#             into /etc/rspamd/dkim_selectors.map
+#             followed by systemctl reload rspamd)
 #
-# Replace the ssl certificates with signed ones.
+# Please open the firewall: open or DNAT tcp ports 25, 143, 587, 4190 to the host (incoming)
+#
+# Replace the dovecot ssl certificates in /etc/dovecot/private with signed ones.
 #
 # Users and domains can be added to the PostgreSQL tables;
 # code for that is not part of this playbook.
-# Mind that if you create a catchall alias, you must also
-# add an alias for each account to the aliases, or you can
-# prepend the following to the SELECT in /etc/postfix/aliases.cf
-#     SELECT u.username || '@' || d.name FROM users u JOIN domains d ON u.domain_id=d.id WHERE d.relay_transport is null AND u.username || '@' || d.name = '%s'
-#     UNION
+#
+#     - put the domain name in table domains
+#     - create a user in table users using `doveadm pw -s PBKDF2`
+#     - create aliases
+#
+# Users should use the following parameters for IMAP and mail submission.
+# Note you will need to use the server_name for which you have installed the ssl certificates.
+# Or you will have to configure dovecot to use multiple certs:
+# https://doc.dovecot.org/configuration_manual/dovecot_ssl_configuration/#with-client-tls-sni-server-name-indication-support
+#
+# IMAP:
+#
+#     - server_name: mail.mydomain.org
+#     - port: 143
+#     - connection_security: starttls
+#     - auth_method: normal password
+#     - username: {user}@{configured_domain}
+#
+# Mail submission:
+#
+#     - server_name: mail.mydomain.org
+#     - port: 587
+#     - connection_security: starttls
+#     - auth_method: normal password
+#     - username: {user}@{configured_domain}
 
 - name: install mail_system
   user: root

mail_system/templates/dovecot/10-auth.conf

@@ -13,7 +13,7 @@
 #disable_plaintext_auth = yes
 
 # 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.
@@ -98,7 +98,7 @@ auth_default_realm = {{ mailserver.dovecot.auth_default_realm }}
 #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
+#   plain login digest-md5 cram-md5 ntlm rpa apop anonymous gssapi otp skey
 #   gss-spnego
 # NOTE: See also disable_plaintext_auth setting.
 auth_mechanisms = plain login
@@ -128,4 +128,6 @@ auth_mechanisms = plain login
 #!include auth-ldap.conf.ext
 #!include auth-passwdfile.conf.ext
 #!include auth-checkpassword.conf.ext
+#!include auth-vpopmail.conf.ext
 #!include auth-static.conf.ext
+

mail_system/templates/dovecot/10-mail.conf

@@ -452,10 +452,10 @@ protocol !indexer-worker {
 # 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.
-#   add-flags - Add the keywords when saving new mails or when fetching can
-#      do it efficiently.
+#   add-flags-on-save - Add the keywords when saving new mails.
 #   content-type=type or !type - Include/exclude content type. Excluding will
 #     never consider the matched MIME part as attachment. Including will only
 #     negate an exclusion (e.g. content-type=!foo/* content-type=foo/bar).
 #   exclude-inlined - Exclude any Content-Disposition=inline MIME part.
 #mail_attachment_detection_options =
+

mail_system/templates/dovecot/10-ssl.conf

@@ -33,15 +33,10 @@ ssl_key = </etc/dovecot/private/dovecot.key
 # when Dovecot needs to act as an SSL client (e.g. imapc backend or
 # submission service). The directory is usually /etc/ssl/certs in
 # Debian-based systems and the file is /etc/pki/tls/cert.pem in
-# RedHat-based systems. Note that ssl_client_ca_file isn't recommended with
-# large CA bundles, because it leads to excessive memory usage.
-#ssl_client_ca_dir =
+# RedHat-based systems.
 ssl_client_ca_dir = /etc/ssl/certs
 #ssl_client_ca_file =
 
-# Require valid cert when connecting to a remote server
-#ssl_client_require_valid_cert = yes
-
 # Request client to send a certificate. If you also want to require it, set
 # auth_ssl_require_client_cert=yes in auth section.
 #ssl_verify_client_cert = no
@@ -59,7 +54,6 @@ ssl_dh = </usr/share/dovecot/dh.pem
 
 # Minimum SSL protocol version to use. Potentially recognized values are SSLv3,
 # TLSv1, TLSv1.1, and TLSv1.2, depending on the OpenSSL version used.
-#ssl_min_protocol = TLSv1
 ssl_min_protocol = TLSv1.2
 
 # SSL ciphers to use, the default is:
@@ -82,3 +76,4 @@ ssl_min_protocol = TLSv1.2
 #   compression - Enable compression.
 #   no_ticket - Disable SSL session tickets.
 #ssl_options =
+

mail_system/templates/dovecot/15-mailboxes.conf

@@ -25,20 +25,18 @@
 #   you want in here, but it's not a good idea to use flags other than the
 #   standard ones specified in the RFC:
 #
-#     \All       - This (virtual) mailbox presents all messages in the
-#                  user's message store.
-#     \Archive   - This mailbox is used to archive messages.
-#     \Drafts    - This mailbox is used to hold draft messages.
-#     \Flagged   - This (virtual) mailbox presents all messages in the
-#                  user's message store marked with the IMAP \Flagged flag.
-#     \Important - This (virtual) mailbox presents all messages in the
-#                  user's message store deemed important to user.
-#     \Junk      - This mailbox is where messages deemed to be junk mail
-#                  are held.
-#     \Sent      - This mailbox is used to hold copies of messages that
-#                  have been sent.
-#     \Trash     - This mailbox is used to hold messages that have been
-#                  deleted.
+#     \All      - This (virtual) mailbox presents all messages in the
+#                 user's message store. 
+#     \Archive  - This mailbox is used to archive messages.
+#     \Drafts   - This mailbox is used to hold draft messages.
+#     \Flagged  - This (virtual) mailbox presents all messages in the
+#                 user's message store marked with the IMAP \Flagged flag.
+#     \Junk     - This mailbox is where messages deemed to be junk mail
+#                 are held.
+#     \Sent     - This mailbox is used to hold copies of messages that
+#                 have been sent.
+#     \Trash    - This mailbox is used to hold messages that have been
+#                 deleted.
 #
 # comment:
 #   Defines a default comment or note associated with the mailbox. This
@@ -84,10 +82,5 @@ namespace inbox {
   #  special_use = \Flagged
   #  comment = All my flagged messages
   #}
-
-  # If you have a virtual "Important" mailbox:
-  #mailbox virtual/Important {
-  #  special_use = \Important
-  #  comment = All my important messages
-  #}
 }
+

mail_system/templates/dovecot/20-imap.conf

@@ -46,8 +46,7 @@
 
 # ID field names and values to send to clients. Using * as the value makes
 # Dovecot use the default value. The following fields have default values
-# currently: name, version, os, os-version, support-url, support-email,
-# revision.
+# currently: name, version, os, os-version, support-url, support-email.
 #imap_id_send = 
 
 # ID fields sent by client to log. * means everything.
@@ -94,10 +93,10 @@
 
 protocol imap {
   # Space separated list of plugins to load (default is global mail_plugins).
-  #mail_plugins = $mail_plugins
   mail_plugins = $mail_plugins imap_sieve imap_acl imap_quota
 
   # Maximum number of IMAP connections allowed for a user from each IP address.
   # NOTE: The username is compared case-sensitively.
   #mail_max_userip_connections = 10
 }
+

mail_system/templates/dovecot/20-lmtp.conf

@@ -16,9 +16,6 @@
 # Verify quota before replying to RCPT TO. This adds a small overhead.
 #lmtp_rcpt_check_quota = no
 
-# Add "Received:" header to mails delivered.
-#lmtp_add_received_header = yes
-
 # Which recipient address to use for Delivered-To: header and Received:
 # header. The default is "final", which is the same as the one given to
 # RCPT TO command. "original" uses the address given in RCPT TO's ORCPT
@@ -26,17 +23,6 @@
 # when a mail has multiple recipients.
 #lmtp_hdr_delivery_address = final
 
-# Workarounds for various client bugs:
-#   whitespace-before-path:
-#     Allow one or more spaces or tabs between `MAIL FROM:' and path and between
-#     `RCPT TO:' and path.
-#   mailbox-for-path:
-#     Allow using bare Mailbox syntax (i.e., without <...>) instead of full path
-#     syntax.
-#
-# The list is space-separated.
-#lmtp_client_workarounds =
-
 protocol lmtp {
   # Space separated list of plugins to load (default is global mail_plugins).
   #mail_plugins = $mail_plugins

mail_system/templates/dovecot/90-quota.conf

@@ -90,7 +90,7 @@ plugin {
   quota_grace = 10%%
   quota_status_success = DUNNO
   quota_status_nouser = DUNNO
-  quota_status_overquota = "552 5.2.2 Mailbox is full"
+  quota_status_overquota = "452 4.2.2 Mailbox is full and cannot receive any more emails"
   quota_exceeded_message = Quota exceeded, please reduce your overall mail volume and/or the number of messages in your inbox.
 
   # https://wiki2.dovecot.org/Quota/Configuration

mail_system/templates/dovecot/90-sieve.conf

@@ -63,7 +63,7 @@ plugin {
   # the "discard" action, and no actions that deliver the message are executed.
   # This "discard script" can prevent discarding the message, by executing
   # alternative actions. If the discard script does nothing, the message is
-	# still discarded as it would be when no discard script is configured.
+    # still discarded as it would be when no discard script is configured.
   #sieve_discard =
 
   # Location Sieve of scripts that need to be executed before the user's