diff --git a/plinth/modules/email/data/etc/dovecot/conf.d/05-freedombox-auth.conf b/plinth/modules/email/data/etc/dovecot/conf.d/05-freedombox-auth.conf index 6b5c9f746..5371ccc24 100644 --- a/plinth/modules/email/data/etc/dovecot/conf.d/05-freedombox-auth.conf +++ b/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 diff --git a/plinth/modules/email/data/etc/dovecot/conf.d/05-freedombox-mail.conf b/plinth/modules/email/data/etc/dovecot/conf.d/05-freedombox-mail.conf index 4a7326415..70f8996b8 100644 --- a/plinth/modules/email/data/etc/dovecot/conf.d/05-freedombox-mail.conf +++ b/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 diff --git a/plinth/modules/email/data/etc/dovecot/conf.d/15-freedombox-mail.conf b/plinth/modules/email/data/etc/dovecot/conf.d/15-freedombox-mail.conf index d318d4e9f..26d619208 100644 --- a/plinth/modules/email/data/etc/dovecot/conf.d/15-freedombox-mail.conf +++ b/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. diff --git a/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-lmtp.conf b/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-lmtp.conf index 87985dfd3..7c06223c5 100644 --- a/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-lmtp.conf +++ b/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 } diff --git a/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-mailboxes.conf b/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-mailboxes.conf index 0d7635162..df45817c2 100644 --- a/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-mailboxes.conf +++ b/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 diff --git a/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-master.conf b/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-master.conf index 0318bd281..51a5e2964 100644 --- a/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-master.conf +++ b/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 diff --git a/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-tls.conf b/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-tls.conf index 1688123c0..b61e9f6ae 100644 --- a/plinth/modules/email/data/etc/dovecot/conf.d/90-freedombox-tls.conf +++ b/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 diff --git a/plinth/modules/email/data/etc/dovecot/conf.d/95-freedombox-sieve.conf b/plinth/modules/email/data/etc/dovecot/conf.d/95-freedombox-sieve.conf index a16a18857..2b4ec8ccb 100644 --- a/plinth/modules/email/data/etc/dovecot/conf.d/95-freedombox-sieve.conf +++ b/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 } diff --git a/plinth/modules/email/data/etc/dovecot/freedombox-sieve-after/sort-spam.sieve b/plinth/modules/email/data/etc/dovecot/freedombox-sieve-after/sort-spam.sieve index 7a07f1c61..9600ba9b7 100644 --- a/plinth/modules/email/data/etc/dovecot/freedombox-sieve-after/sort-spam.sieve +++ b/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" { diff --git a/plinth/modules/email/data/etc/postfix/freedombox-aliases.cf b/plinth/modules/email/data/etc/postfix/freedombox-aliases.cf index 8ae5d7992..3cd9c0166 100644 --- a/plinth/modules/email/data/etc/postfix/freedombox-aliases.cf +++ b/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' diff --git a/plinth/modules/email/data/etc/rspamd/local.d/freedombox-milter-headers.conf b/plinth/modules/email/data/etc/rspamd/local.d/freedombox-milter-headers.conf index 00110abaf..f42f4ed37 100644 --- a/plinth/modules/email/data/etc/rspamd/local.d/freedombox-milter-headers.conf +++ b/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"]; diff --git a/plinth/modules/email/data/etc/rspamd/local.d/freedombox-redis.conf b/plinth/modules/email/data/etc/rspamd/local.d/freedombox-redis.conf index cf59cfc22..72200cd99 100644 --- a/plinth/modules/email/data/etc/rspamd/local.d/freedombox-redis.conf +++ b/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 diff --git a/plinth/modules/email/dns.py b/plinth/modules/email/dns.py index c84c59051..c6df85abe 100644 --- a/plinth/modules/email/dns.py +++ b/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 diff --git a/plinth/modules/email/postfix.py b/plinth/modules/email/postfix.py index c5e652e3a..a23c3153a 100644 --- a/plinth/modules/email/postfix.py +++ b/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 diff --git a/plinth/modules/email/privileged/dkim.py b/plinth/modules/email/privileged/dkim.py index 711882f91..95a413e8e 100644 --- a/plinth/modules/email/privileged/dkim.py +++ b/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 diff --git a/plinth/modules/email/privileged/domain.py b/plinth/modules/email/privileged/domain.py index 062b24917..404949aac 100644 --- a/plinth/modules/email/privileged/domain.py +++ b/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 diff --git a/plinth/modules/email/privileged/home.py b/plinth/modules/email/privileged/home.py index 886c6ed22..37d9ff2b4 100644 --- a/plinth/modules/email/privileged/home.py +++ b/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 diff --git a/plinth/modules/email/privileged/postfix.py b/plinth/modules/email/privileged/postfix.py index 9d47c0037..9b42d6a50 100644 --- a/plinth/modules/email/privileged/postfix.py +++ b/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 diff --git a/plinth/modules/email/privileged/spam.py b/plinth/modules/email/privileged/spam.py index e5597d070..f2ba735e8 100644 --- a/plinth/modules/email/privileged/spam.py +++ b/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 diff --git a/plinth/modules/email/privileged/tls.py b/plinth/modules/email/privileged/tls.py index fa8645345..2ad57e4d9 100644 --- a/plinth/modules/email/privileged/tls.py +++ b/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