Improve playbook doc

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