email: Add various documentation links for future readability

Signed-off-by: Sunil Mohan Adapa <sunil@medhas.org>
Reviewed-by: James Valleroy <jvalleroy@mailbox.org>

plinth/modules/email/data/etc/dovecot/conf.d/05-freedombox-auth.conf

@@ -1,5 +1,7 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
+# See: https://doc.dovecot.org/settings/core/
+
 # Outlook and Windows Mail works only with LOGIN mechanism, not the standard
 # PLAIN:
 auth_mechanisms = plain login

plinth/modules/email/data/etc/dovecot/conf.d/05-freedombox-mail.conf

@@ -1,5 +1,8 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
+# See:
+# https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb/
+#
 # Users in FreedomBox are not expected to access mail by logging into the
 # system. Storing the mail in single location instead of home directories and
 # with single UID/GID simplifies security reasoning and backup/restore

plinth/modules/email/data/etc/dovecot/conf.d/15-freedombox-mail.conf

@@ -1,5 +1,8 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
+# See: https://doc.dovecot.org/configuration_manual/mail_location/
+# See: https://doc.dovecot.org/settings/core/
+
 # Use sdbox, a format specific to dovecot, for storing mails. The format allows
 # better performance with some IMAP queries. When this is combined with Full
 # Text Search (FTS), users will get optimal web and desktop mail experience.

plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-lmtp.conf

@@ -1,5 +1,8 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
+# See: https://doc.dovecot.org/configuration_manual/sieve/configuration/
+
+# Enable the sieve plugin to sort mail during delivery using sieve scripts.
 protocol lmtp {
   mail_plugins = $mail_plugins sieve
 }

plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-mailboxes.conf

@@ -2,6 +2,7 @@
 
 # Mark various mailboxes with special use flags (RFC 6154). Various names used
 # in mail clients for mailboxes: https://www.imapwiki.org/SpecialUse
+# See: https://doc.dovecot.org/configuration_manual/namespace/
 
 namespace inbox {
   # Archive

plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-master.conf

@@ -1,5 +1,9 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
+# Listen on Unix domain sockets for postfix to use dovecot SASL authentication
+# and for postfix to deliver mail using dovecot to local mailboxes. See:
+# https://doc.dovecot.org/configuration_manual/howto/postfix_and_dovecot_sasl/
+
 service auth {
   unix_listener /var/spool/postfix/private/auth {
       mode = 0600

plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-tls.conf

@@ -1,8 +1,8 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
-# Mozilla Guideline v5.6, Dovecot 2.3.9, OpenSSL 1.1.1d, intermediate
-# Generated 2021-08
-# https://ssl-config.mozilla.org/
+# Mozilla Guideline v5.6, Dovecot 2.3.9, OpenSSL 1.1.1d, intermediate.
+# Generated 2021-08: https://ssl-config.mozilla.org/
+# See: https://doc.dovecot.org/configuration_manual/dovecot_ssl_configuration/
 ssl = required
 
 ssl_min_protocol = TLSv1.2

plinth/modules/email/data/etc/dovecot/conf.d/95-freedombox-sieve.conf

@@ -1,5 +1,9 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
+# Default sieve scripts applied for delivery to all users. To move mail to Junk
+# folder based on classification headers set by rspamd. See:
+# https://doc.dovecot.org/settings/pigeonhole/
+
 plugin {
   sieve_after = /etc/dovecot/freedombox-sieve-after
 }

plinth/modules/email/data/etc/dovecot/freedombox-sieve-after/sort-spam.sieve

@@ -1,5 +1,9 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
+# A simple sieve script that applies to all users. Moves mail to Junk folder
+# based on classification header set by rspamd.
+# See: https://docs.gandi.net/en/gandimail/sieve/sieve_tutorial.html
+
 require ["fileinto", "mailbox"];
 
 if header :is "X-Spam" "Yes" {

plinth/modules/email/data/etc/postfix/freedombox-aliases.cf

@@ -1,4 +1,7 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
+# Configuration for sqlite based postfix lookup table for aliases. See:
+# https://www.postfix.org/SQLITE_README.html
+
 dbpath = /var/lib/postfix/freedombox-aliases/aliases.sqlite3
 query = SELECT value FROM alias WHERE name='%s'

plinth/modules/email/data/etc/rspamd/local.d/freedombox-milter-headers.conf

@@ -1,5 +1,8 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
+# Configure which/how headers are added by rspamd before returning mail to
+# postfix. See: https://rspamd.com/doc/modules/milter_headers.html
+
 use = ["authentication-results", "x-spam-level", "x-spam-status",
        "x-spamd-bar", "x-spamd-result"];
 

plinth/modules/email/data/etc/rspamd/local.d/freedombox-redis.conf

@@ -1,4 +1,8 @@
 # Do not edit this file. Manage your settings on FreedomBox.
 
+# Many modules such as bayes classifier require redis. Default configuration
+# does not connect to a local redis server. See:
+# https://rspamd.com/doc/configuration/redis.html
+
 servers = "127.0.0.1";
 db = "7";  # Use database number 8 not to clash with other clients

plinth/modules/email/dns.py

@@ -1,6 +1,12 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 """
 Manage DNS entries needed for an email server.
+
+See: https://en.wikipedia.org/wiki/MX_record
+See: https://dmarcguide.globalcyberalliance.org/
+See: https://support.google.com/a/answer/2466580
+See: https://datatracker.ietf.org/doc/html/rfc6186
+See: https://rspamd.com/doc/modules/dkim_signing.html
 """
 
 from dataclasses import dataclass

plinth/modules/email/postfix.py

@@ -1,6 +1,10 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 """
 Set and get postfix configuration using postconf.
+
+See: http://www.postfix.org/postconf.1.html
+See: http://www.postfix.org/master.5.html
+See: http://www.postfix.org/postconf.5.html
 """
 
 import re

plinth/modules/email/privileged/dkim.py

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 """
 Generate DKIM keys for signing outgoing messages.
+
+See: https://rspamd.com/doc/modules/dkim_signing.html
 """
 
 import pathlib

plinth/modules/email/privileged/domain.py

@@ -1,6 +1,10 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 """
 Configure domains accepted by postfix.
+
+See: http://www.postfix.org/postconf.5.html#mydestination
+See: http://www.postfix.org/postconf.5.html#mydomain
+See: http://www.postfix.org/postconf.5.html#myhostname
 """
 
 import pathlib

plinth/modules/email/privileged/home.py

@@ -1,5 +1,10 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
-"""Privileged actions to setup users' dovecot mail home directory."""
+"""
+Privileged actions to setup users' dovecot mail home directory.
+
+See:
+https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb/
+"""
 
 import subprocess
 

plinth/modules/email/privileged/postfix.py

@@ -2,6 +2,11 @@
 """
 Configure postfix to use auth and local delivery with dovecot. Start smtps and
 submission services. Setup aliases database.
+
+See:
+https://doc.dovecot.org/configuration_manual/howto/postfix_and_dovecot_sasl/
+See: https://doc.dovecot.org/configuration_manual/howto/postfix_dovecot_lmtp/
+See: http://www.postfix.org/TLS_README.html
 """
 
 from plinth import actions

plinth/modules/email/privileged/spam.py

@@ -1,6 +1,9 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 """
 Configures rspamd to handle incoming and outgoing spam.
+
+See: http://www.postfix.org/MILTER_README.html
+See: https://rspamd.com/doc/configuration/ucl.html
 """
 
 import pathlib

plinth/modules/email/privileged/tls.py

@@ -1,6 +1,10 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 """
 TLS certificate configuration for postfix and dovecot.
+
+See: https://ssl-config.mozilla.org/
+See: http://www.postfix.org/TLS_README.html
+See: https://doc.dovecot.org/configuration_manual/dovecot_ssl_configuration/
 """
 
 import pathlib