various improvements in bash comments

setup/dkim.sh

@@ -1,5 +1,5 @@
 # OpenDKIM
-# ========
+# --------
 #
 # OpenDKIM provides a service that puts a DKIM signature on outbound mail.
 #

setup/dns.sh

@@ -39,7 +39,9 @@ mkdir -p /var/run/nsd
 mkdir -p "$STORAGE_ROOT/dns/dnssec";
 
 # TLDs don't all support the same algorithms, so we'll generate keys using a few
-# different algorithms.
+# different algorithms. RSASHA1-NSEC3-SHA1 was possibly the first widely used
+# algorithm that supported NSEC3, which is a security best practice. However TLDs
+# will probably be moving away from it to a a SHA256-based algorithm.
 #
 # Supports `RSASHA1-NSEC3-SHA1` (didn't test with `RSASHA256`):
 #
@@ -58,11 +60,9 @@ if [ ! -f "$STORAGE_ROOT/dns/dnssec/$algo.conf" ]; then
 		FIRST=0 #NODOC
 	fi
 
-	# Create the Key-Signing Key (KSK) (-k) which is the so-called
-	# Secure Entry Point. Use a NSEC3-compatible algorithm (best
-	# practice), and a nice and long keylength. The domain name we
-	# provide ("_domain_") doesn't matter -- we'll use the same
-	# keys for all our domains.
+	# Create the Key-Signing Key (KSK) (with `-k`) which is the so-called
+	# Secure Entry Point. The domain name we provide ("_domain_") doesn't
+	#  matter -- we'll use the same keys for all our domains.
 	#
 	# `ldns-keygen` outputs the new key's filename to stdout, which
 	# we're capturing into the `KSK` variable.
@@ -71,13 +71,13 @@ if [ ! -f "$STORAGE_ROOT/dns/dnssec/$algo.conf" ]; then
 	# Now create a Zone-Signing Key (ZSK) which is expected to be
 	# rotated more often than a KSK, although we have no plans to
 	# rotate it (and doing so would be difficult to do without
-	# disturbing DNS availability.) Omit '-k' and use a shorter key.
+	# disturbing DNS availability.) Omit `-k` and use a shorter key length.
 	ZSK=$(umask 077; cd $STORAGE_ROOT/dns/dnssec; ldns-keygen -a $algo -b 1024 _domain_);
 
 	# These generate two sets of files like:
 	#
-	# * `K_domain_.+007+08882.ds`: DS record normally provided to domain name registrar (but it's actually invalid with "_domain_")
-	# * `K_domain_.+007+08882.key`: public key (goes into DS record & upstream DNS provider like your registrar)
+	# * `K_domain_.+007+08882.ds`: DS record normally provided to domain name registrar (but it's actually invalid with `_domain_`)
+	# * `K_domain_.+007+08882.key`: public key
 	# * `K_domain_.+007+08882.private`: private key (secret!)
 
 	# The filenames are unpredictable and encode the key generation

setup/mail-dovecot.sh

@@ -52,8 +52,9 @@ tools/editconf.py /etc/dovecot/conf.d/10-ssl.conf \
 	"ssl_protocols=!SSLv3 !SSLv2" \
 	"ssl_cipher_list=TLSv1+HIGH !SSLv2 !RC4 !aNULL !eNULL !3DES @STRENGTH"
 
-# Disable in-the-clear IMAP and POP because we're paranoid (we haven't even
-# enabled POP).
+# Disable in-the-clear IMAP because there is no reason for a user to transmit
+# login credentials outside of an encrypted connection. Although we haven't
+# even installed the POP server, ensure it is disabled too.
 sed -i "s/#port = 143/port = 0/" /etc/dovecot/conf.d/10-master.conf
 sed -i "s/#port = 110/port = 0/" /etc/dovecot/conf.d/10-master.conf
 

setup/mail-postfix.sh

@@ -63,7 +63,7 @@ tools/editconf.py /etc/postfix/main.cf \
 # Enable the 'submission' port 587 smtpd server and tweak its settings.
 #
 # * Require the best ciphers for incoming connections per http://baldric.net/2013/12/07/tls-ciphers-in-postfix-and-dovecot/.
-#   but without affecting opportunistic TLS on incoming mail, which will allow any cipher (it's better than none).
+#   By putting this setting here we leave opportunistic TLS on incoming mail at default cipher settings (any cipher is better than none).
 # * Give it a different name in syslog to distinguish it from the port 25 smtpd server.
 # * Add a new cleanup service specific to the submission service ('authclean')
 #   that filters out privacy-sensitive headers on mail being sent out by
@@ -96,9 +96,9 @@ tools/editconf.py /etc/postfix/main.cf \
 # relayed elsewhere. We don't want to be an "open relay". On outbound
 # mail, require one of:
 #
-# * permit_sasl_authenticated: Authenticated users (i.e. on port 587).
-# * permit_mynetworks: Mail that originates locally.
-# * reject_unauth_destination: No one else. (Permits mail whose destination is local and rejects other mail.)
+# * `permit_sasl_authenticated`: Authenticated users (i.e. on port 587).
+# * `permit_mynetworks`: Mail that originates locally.
+# * `reject_unauth_destination`: No one else. (Permits mail whose destination is local and rejects other mail.)
 tools/editconf.py /etc/postfix/main.cf \
 	smtpd_relay_restrictions=permit_sasl_authenticated,permit_mynetworks,reject_unauth_destination
 
@@ -142,20 +142,20 @@ tools/editconf.py /etc/postfix/main.cf virtual_transport=lmtp:[127.0.0.1]:10025
 
 # Who can send mail to us? Some basic filters.
 #
-# * reject_non_fqdn_sender: Reject not-nice-looking return paths.
-# * reject_unknown_sender_domain: Reject return paths with invalid domains.
-# * reject_rhsbl_sender: Reject return paths that use blacklisted domains.
-# * permit_sasl_authenticated: Authenticated users (i.e. on port 587) can skip further checks.
-# * permit_mynetworks: Mail that originates locally can skip further checks.
-# * reject_rbl_client: Reject connections from IP addresses blacklisted in zen.spamhaus.org
-# * reject_unlisted_recipient: Although Postfix will reject mail to unknown recipients, it's nicer to reject such mail ahead of greylisting rather than after.
-# * check_policy_service: Apply greylisting using postgrey.
+# * `reject_non_fqdn_sender`: Reject not-nice-looking return paths.
+# * `reject_unknown_sender_domain`: Reject return paths with invalid domains.
+# * `reject_rhsbl_sender`: Reject return paths that use blacklisted domains.
+# * `permit_sasl_authenticated`: Authenticated users (i.e. on port 587) can skip further checks.
+# * `permit_mynetworks`: Mail that originates locally can skip further checks.
+# * `reject_rbl_client`: Reject connections from IP addresses blacklisted in zen.spamhaus.org
+# * `reject_unlisted_recipient`: Although Postfix will reject mail to unknown recipients, it's nicer to reject such mail ahead of greylisting rather than after.
+# * `check_policy_service`: Apply greylisting using postgrey.
 #
-# Notes:
-# permit_dnswl_client can pass through mail from whitelisted IP addresses, which would be good to put before greylisting
-# so these IPs get mail delivered quickly. But when an IP is not listed in the permit_dnswl_client list (i.e. it is not
-# whitelisted) then postfix does a DEFER_IF_REJECT, which results in all "unknown user" sorts of messages turning into
-# "450 4.7.1 Client host rejected: Service unavailable". This is a retry code, so the mail doesn't properly bounce.
+# Notes: #NODOC
+# permit_dnswl_client can pass through mail from whitelisted IP addresses, which would be good to put before greylisting #NODOC
+# so these IPs get mail delivered quickly. But when an IP is not listed in the permit_dnswl_client list (i.e. it is not #NODOC
+# whitelisted) then postfix does a DEFER_IF_REJECT, which results in all "unknown user" sorts of messages turning into #NODOC
+# "450 4.7.1 Client host rejected: Service unavailable". This is a retry code, so the mail doesn't properly bounce. #NODOC
 tools/editconf.py /etc/postfix/main.cf \
 	smtpd_sender_restrictions="reject_non_fqdn_sender,reject_unknown_sender_domain,reject_rhsbl_sender dbl.spamhaus.org" \
 	smtpd_recipient_restrictions=permit_sasl_authenticated,permit_mynetworks,"reject_rbl_client zen.spamhaus.org",reject_unlisted_recipient,"check_policy_service inet:127.0.0.1:10023"

setup/spamassassin.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Spam filtering with spamassassin via spampd
-# ===========================================
+# -------------------------------------------
 #
 # spampd sits between postfix and dovecot. It takes mail from postfix
 # over the LMTP protocol, runs spamassassin on it, and then passes the