more work on making the bash scripts readable

setup/dkim.sh

-# OpenDKIM: Sign outgoing mail with DKIM
-########################################
-
-# After this, you'll still need to run dns_update.sh to get the DKIM
-# signature in the DNS zones.
+# OpenDKIM
+# ========
+#
+# OpenDKIM provides a service that puts a DKIM signature on outbound mail.
+#
+# The DNS configuration for DKIM is done in the management daemon.
 
 source setup/functions.sh # load our functions
 
-# Install DKIM
+# Install DKIM...
 apt_install opendkim opendkim-tools
 
 # Make sure configuration directories exist.
@@ -18,9 +19,9 @@ mkdir -p $STORAGE_ROOT/mail/dkim
 echo "127.0.0.1" > /etc/opendkim/TrustedHosts
 
 if grep -q "ExternalIgnoreList" /etc/opendkim.conf; then
-	true; # already done
+	true # already done #NODOC
 else
-	# Add various configuration options to the end.
+	# Add various configuration options to the end of `opendkim.conf`.
 	cat >> /etc/opendkim.conf << EOF;
 MinimumKeyBits          1024
 ExternalIgnoreList      refile:/etc/opendkim/TrustedHosts
@@ -32,7 +33,7 @@ RequireSafeKeys         false
 EOF
 fi
 
-# Create a new DKIM key if we don't have one already. This creates
+# Create a new DKIM key. This creates
 # mail.private and mail.txt in $STORAGE_ROOT/mail/dkim. The former
 # is the actual private key and the latter is the suggested DNS TXT
 # entry which we'll want to include in our DNS setup.
@@ -47,7 +48,7 @@ chmod go-rwx $STORAGE_ROOT/mail/dkim
 
 # Add OpenDKIM as a milter to postfix, which is how it intercepts outgoing
 # mail to perform the signing (by adding a mail header).
-# Be careful. If we add other milters later, it needs to be concatenated on the smtpd_milters line.
+# Be careful. If we add other milters later, it needs to be concatenated on the smtpd_milters line. #NODOC
 tools/editconf.py /etc/postfix/main.cf \
 	smtpd_milters=inet:127.0.0.1:8891 \
 	non_smtpd_milters=\$smtpd_milters \

setup/dns.sh

 #!/bin/bash
-# DNS: Configure a DNS server to host our own DNS
+# DNS
 # -----------------------------------------------
 
 # This script installs packages, but the DNS zone files are only
@@ -14,9 +14,9 @@ source setup/functions.sh # load our functions
 
 # ...but first, we have to create the user because the 
 # current Ubuntu forgets to do so in the .deb
-# see issue #25 and https://bugs.launchpad.net/ubuntu/+source/nsd/+bug/1311886
+# (see issue #25 and https://bugs.launchpad.net/ubuntu/+source/nsd/+bug/1311886)
 if id nsd > /dev/null 2>&1; then
-	true; #echo "nsd user exists... good"; #NODOC
+	true #echo "nsd user exists... good"; #NODOC
 else
 	useradd nsd;
 fi
@@ -40,17 +40,21 @@ mkdir -p "$STORAGE_ROOT/dns/dnssec";
 # TLDs don't all support the same algorithms, so we'll generate keys using a few
 # different algorithms.
 #
-# Supports RSASHA1-NSEC3-SHA1 (didn't test with RSASHA256):
-#   .info and .me.
+# Supports `RSASHA1-NSEC3-SHA1` (didn't test with `RSASHA256`):
 #
-# Requires RSASHA256
-#   .email
-FIRST=1
+#  * .info
+#  * .me
+#
+# Requires `RSASHA256`
+#
+#  * .email
+
+FIRST=1 #NODOC
 for algo in RSASHA1-NSEC3-SHA1 RSASHA256; do
 if [ ! -f "$STORAGE_ROOT/dns/dnssec/$algo.conf" ]; then
 	if [ $FIRST == 1 ]; then
 		echo "Generating DNSSEC signing keys. This may take a few minutes..."
-		FIRST=0
+		FIRST=0 #NODOC
 	fi
 
 	# Create the Key-Signing Key (KSK) (-k) which is the so-called
@@ -58,6 +62,9 @@ if [ ! -f "$STORAGE_ROOT/dns/dnssec/$algo.conf" ]; then
 	# 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.
+	#
+	# `ldns-keygen` outputs the new key's filename to stdout, which
+	# we're capturing into the `KSK` variable.
 	KSK=$(umask 077; cd $STORAGE_ROOT/dns/dnssec; ldns-keygen -a $algo -b 2048 -k _domain_);
 
 	# Now create a Zone-Signing Key (ZSK) which is expected to be
@@ -81,9 +88,13 @@ KSK=$KSK
 ZSK=$ZSK
 EOF
 fi
+
+	# And loop to do the next algorithm...
 done
 
-# Force the dns_update script to be run every day to re-sign zones for DNSSEC.
+# Force the dns_update script to be run every day to re-sign zones for DNSSEC
+# before they expire. When we sign zones (in `dns_update.py`) we specify a
+# 30-day validation window, so we had better re-sign before then.
 cat > /etc/cron.daily/mailinabox-dnssec << EOF;
 #!/bin/bash
 # Mail-in-a-Box

setup/mail-dovecot.sh

@@ -18,15 +18,17 @@
 source setup/functions.sh # load our functions
 source /etc/mailinabox.conf # load global vars
 
-# ### Install packages and basic setup
+# Install packages...
 
 apt_install \
 	dovecot-core dovecot-imapd dovecot-lmtpd dovecot-sqlite sqlite3 \
 	dovecot-sieve dovecot-managesieved
 
-# The dovecot-imapd and dovecot-lmtpd packages automatically enable IMAP and LMTP protocols.
+# The `dovecot-imapd` and `dovecot-lmtpd` packages automatically enable IMAP and LMTP protocols.
 
-# Set the location where we'll store user mailboxes.
+# Set the location where we'll store user mailboxes. '%d' is the domain name and '%n' is the
+# username part of the user's email address. We'll ensure that no bad domains or email addresses
+# are created within the management daemon.
 tools/editconf.py /etc/dovecot/conf.d/10-mail.conf \
 	mail_location=maildir:$STORAGE_ROOT/mail/mailboxes/%d/%n \
 	mail_privileged_group=mail \
@@ -66,7 +68,7 @@ tools/editconf.py /etc/dovecot/conf.d/20-imap.conf \
 # ### LDA (LMTP)
 
 # Enable Dovecot's LDA service with the LMTP protocol. It will listen
-# in port 10026, and Spamassassin will be configured to pass mail there.
+# on port 10026, and Spamassassin will be configured to pass mail there.
 #
 # The disabled unix socket listener is normally how Postfix and Dovecot
 # would communicate (see the Postfix setup script for the corresponding
@@ -91,30 +93,32 @@ protocol imap {
 }
 EOF
 
-# Setting a postmaster_address seems to be required or LMTP won't start.
+# Setting a `postmaster_address` is required or LMTP won't start. An alias
+# will be created automatically by our management daemon.
 tools/editconf.py /etc/dovecot/conf.d/15-lda.conf \
 	postmaster_address=postmaster@$PRIMARY_HOSTNAME
 
 # ### Sieve
 
 # Enable the Dovecot sieve plugin which let's users run scripts that process
-# mail as it comes in. We'll also set a global script that moves mail marked
-# as spam by Spamassassin into the user's Spam folder.
+# mail as it comes in.
 sed -i "s/#mail_plugins = .*/mail_plugins = \$mail_plugins sieve/" /etc/dovecot/conf.d/20-lmtp.conf
 
+# Configure sieve. We'll create a global script that moves mail marked
+# as spam by Spamassassin into the user's Spam folder.
+#
+# * `sieve_before`: The path to our global sieve which handles moving spam to the Spam folder.
+#
+# * `sieve`: The path to the user's main active script. ManageSieve will create a symbolic
+# link here to the actual sieve script. It should not be in the mailbox directory
+# (because then it might appear as a folder) and it should not be in the sieve_dir
+# (because then I suppose it might appear to the user as one of their scripts).
+# * `sieve_dir`: Directory for :personal include scripts for the include extension. This
+# is also where the ManageSieve service stores the user's scripts.
 cat > /etc/dovecot/conf.d/99-local-sieve.conf << EOF;
 plugin {
-  # The path to our global sieve which handles moving spam to the Spam folder.
   sieve_before = /etc/dovecot/sieve-spam.sieve
-
-  # The path to the user's main active script. ManageSieve will create a symbolic
-  # link here to the actual sieve script. It should not be in the mailbox directory
-  # (because then it might appear as a folder) and it should not be in the sieve_dir
-  # (because then I suppose it might appear to the user as one of their scripts).
   sieve = $STORAGE_ROOT/mail/sieve/%d/%n.sieve
-
-  # Directory for :personal include scripts for the include extension. This
-  # is also where the ManageSieve service stores the user's scripts.
   sieve_dir = $STORAGE_ROOT/mail/sieve/%d/%n
 }
 EOF
@@ -122,7 +126,7 @@ EOF
 # Copy the global sieve script into where we've told Dovecot to look for it. Then
 # compile it. Global scripts must be compiled now because Dovecot won't have
 # permission later.
-cp `pwd`/conf/sieve-spam.txt /etc/dovecot/sieve-spam.sieve
+cp conf/sieve-spam.txt /etc/dovecot/sieve-spam.sieve
 sievec /etc/dovecot/sieve-spam.sieve
 
 # PERMISSIONS

setup/mail-postfix.sh

@@ -32,13 +32,26 @@ source /etc/mailinabox.conf # load global vars
 
 # ### Install packages.
 
-apt_install postfix postgrey postfix-pcre ca-certificates
+# Install postfix's packages.
+#
+# * `postfix`: The SMTP server.
+# * `postfix-pcre`: Enables header filtering.
+# * `postgrey`: A mail policy service that soft-rejects mail the first time
+#   it is received. Spammers don't usually try agian. Legitimate mail
+#   always will.
+# * `ca-certificates`: A trust store used to squelch postfix warnings about
+#   untrusted opportunistically-encrypted connections.
+
+apt_install postfix postfix-pcre postgrey ca-certificates
 
 # ### Basic Settings
 
-# Have postfix listen on all network interfaces, set our name (the Debian default seems to be localhost),
-# and set the name of the local machine to localhost for xxx@localhost mail (but I don't think this will have any effect because
-# there is no true local mail delivery). Also set the banner (must have the hostname first, then anything).
+# Set some basic settings...
+#
+# * Have postfix listen on all network interfaces.
+# * Set our name (the Debian default seems to be "localhost" but make it our hostname).
+# * Set the name of the local machine to localhost, which means xxx@localhost is delivered locally, although we don't use it.
+# * Set the SMTP banner (which must have the hostname first, then anything).
 tools/editconf.py /etc/postfix/main.cf \
 	inet_interfaces=all \
 	myhostname=$PRIMARY_HOSTNAME\
@@ -69,7 +82,8 @@ cp conf/postfix_outgoing_mail_header_filters /etc/postfix/outgoing_mail_header_f
 # Enable TLS on these and all other connections (i.e. ports 25 *and* 587) and
 # require TLS before a user is allowed to authenticate. This also makes
 # opportunistic TLS available on *incoming* mail.
-# Set stronger DH parameters, which via openssl tend to default to 1024 bits.
+# Set stronger DH parameters, which via openssl tend to default to 1024 bits
+# (see ssl.sh).
 tools/editconf.py /etc/postfix/main.cf \
 	smtpd_tls_security_level=may\
 	smtpd_tls_auth_only=yes \
@@ -90,25 +104,25 @@ tools/editconf.py /etc/postfix/main.cf \
 
 
 # ### DANE
-#
+
 # When connecting to remote SMTP servers, prefer TLS and use DANE if available.
 #
-# Prefering ("opportunistic") TLS means Postfix will accept whatever SSL certificate the remote
-# end provides, if the remote end offers STARTTLS during the connection. DANE takes this a
-# step further:
+# Prefering ("opportunistic") TLS means Postfix will use TLS if the remote end
+# offers it, otherwise it will transmit the message in the clear. Postfix will
+# accept whatever SSL certificate the remote end provides. Opportunistic TLS
+# protects against passive easvesdropping (but not man-in-the-middle attacks).
+# DANE takes this a step further:
 #
 # Postfix queries DNS for the TLSA record on the destination MX host. If no TLSA records are found,
 # then opportunistic TLS is used. Otherwise the server certificate must match the TLSA records
 # or else the mail bounces. TLSA also requires DNSSEC on the MX host. Postfix doesn't do DNSSEC
 # itself but assumes the system's nameserver does and reports DNSSEC status. Thus this also
-# relies on our local bind9 server being present and smtp_dns_support_level being set to dnssec
-# to use it.
-#
-# The smtp_tls_CAfile is superflous, but it turns warnings in the logs about untrusted certs
-# into notices about trusted certs. Since in these cases Postfix is doing opportunistic TLS,
-# it does not care about whether the remote certificate is trusted. But, looking at the logs,
-# it's nice to be able to see that the connection was in fact encrypted for the right party.
-# The CA file is provided by the package ca-certificates.
+# relies on our local bind9 server being present and `smtp_dns_support_level=dnssec`.
+#
+# The `smtp_tls_CAfile` is superflous, but it eliminates warnings in the logs about untrusted certs,
+# which we don't care about seeing because Postfix is doing opportunistic TLS anyway. Better to encrypt,
+# even if we don't know if it's to the right party, than to not encrypt at all. Instead we'll
+# now see notices about trusted certs. The CA file is provided by the package `ca-certificates`.
 tools/editconf.py /etc/postfix/main.cf \
 	smtp_tls_security_level=dane \
 	smtp_dns_support_level=dnssec \

setup/mail-users.sh

@@ -53,7 +53,6 @@ EOF
 chmod 0600 /etc/dovecot/dovecot-sql.conf.ext # per Dovecot instructions
 
 # Have Dovecot provide an authorization service that Postfix can access & use.
-# Drew Crawford sets the auth-worker process to run as the mail user, but we don't care if it runs as root.
 cat > /etc/dovecot/conf.d/99-local-auth.conf << EOF;
 service auth {
   unix_listener /var/spool/postfix/private/auth {

setup/spamassassin.sh

 #!/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
 # message over LMTP to dovecot for local delivery.
-
+#
 # In order to move spam automatically into the Spam folder we use the dovecot sieve
-# plugin. The tools/mail.py tool creates the necessary sieve script for each mail
-# user when the mail user is created.
+# plugin.
 
 source /etc/mailinabox.conf # get global vars
 source setup/functions.sh # load our functions
@@ -29,13 +28,14 @@ hide_output pyzor discover
 tools/editconf.py /etc/default/spampd DESTPORT=10026
 
 # Enable the Dovecot antispam plugin to detect when a message moves between folders so we can
-# pass it to sa-learn for training. (Be careful if we use multiple plugins later.)
+# pass it to sa-learn for training.
+# (Be careful if we use multiple plugins later.) #NODOC
 sed -i "s/#mail_plugins = .*/mail_plugins = \$mail_plugins antispam/" /etc/dovecot/conf.d/20-imap.conf
 
 # When mail is moved in or out of the Dovecot Spam folder, re-train using this script
 # that sends the mail to spamassassin.
 # from http://wiki2.dovecot.org/Plugins/Antispam
-rm -f /usr/bin/sa-learn-pipe.sh # legacy location
+rm -f /usr/bin/sa-learn-pipe.sh # legacy location #NODOC
 cat > /usr/local/bin/sa-learn-pipe.sh << EOF;
 cat<&0 >> /tmp/sendmail-msg-\$\$.txt
 /usr/bin/sa-learn \$* /tmp/sendmail-msg-\$\$.txt > /dev/null

setup/ssl.sh

@@ -2,7 +2,7 @@
 #
 # SSL Certificate
 # ---------------
-#
+
 # Create a self-signed SSL certificate if one has not yet been created.
 #
 # The certificate is for PRIMARY_HOSTNAME specifically and is used for:
@@ -22,29 +22,31 @@ source /etc/mailinabox.conf # load global vars
 apt_install openssl
 
 mkdir -p $STORAGE_ROOT/ssl
-# Generate a new private key if one doesn't already exist.
+# Generate a new private key.
 # Set the umask so the key file is not world-readable.
 if [ ! -f $STORAGE_ROOT/ssl/ssl_private_key.pem ]; then
 	(umask 077; hide_output \
 		openssl genrsa -out $STORAGE_ROOT/ssl/ssl_private_key.pem 2048)
 fi
 
-# Generate a certificate signing request if one doesn't already exist.
+# Generate a certificate signing request.
 if [ ! -f $STORAGE_ROOT/ssl/ssl_cert_sign_req.csr ]; then
 	hide_output \
 	openssl req -new -key $STORAGE_ROOT/ssl/ssl_private_key.pem -out $STORAGE_ROOT/ssl/ssl_cert_sign_req.csr \
 	  -sha256 -subj "/C=$CSR_COUNTRY/ST=/L=/O=/CN=$PRIMARY_HOSTNAME"
 fi
 
-# Generate a SSL certificate by self-signing if a SSL certificate doesn't yet exist.
+# Generate a SSL certificate by self-signing.
 if [ ! -f $STORAGE_ROOT/ssl/ssl_certificate.pem ]; then
 	hide_output \
 	openssl x509 -req -days 365 \
 	  -in $STORAGE_ROOT/ssl/ssl_cert_sign_req.csr -signkey $STORAGE_ROOT/ssl/ssl_private_key.pem -out $STORAGE_ROOT/ssl/ssl_certificate.pem
 fi
 
-# For nginx and postfix, pre-generate some better DH bits. They seem to
-# each rely on openssl's default of 1024 bits.
+# For nginx and postfix, pre-generate some Diffie-Hellman cipher bits which is
+# used when a Diffie-Hellman cipher is selected during TLS negotiation. Diffie-Hellman
+# provides Perfect Forward Security. openssl's default is 1024 bits, but we'll
+# create 2048.
 if [ ! -f $STORAGE_ROOT/ssl/dh2048.pem ]; then
 	openssl dhparam -out $STORAGE_ROOT/ssl/dh2048.pem 2048
 fi

setup/system.sh

 source setup/functions.sh # load our functions
 
-# Base system configuration
+# Basic System Configuration
 # -------------------------
 
-# ### Base packages
+# ### Install Packages
 
-# Update system packages:
+# Update system packages to make sure we have the latest upstream versions of things from Ubuntu.
 
 echo Updating system packages...
 hide_output apt-get update
@@ -35,8 +35,6 @@ EOF
 
 # ### Firewall
 
-# Turn on the firewall.
-#
 # Various virtualized environments like Docker and some VPSs don't provide #NODOC
 # a kernel that supports iptables. To avoid error-like output in these cases, #NODOC
 # we skip this if the user sets DISABLE_FIREWALL=1. #NODOC
@@ -47,15 +45,15 @@ if [ -z "$DISABLE_FIREWALL" ]; then
 	# Allow incoming connections to SSH.
 	ufw_allow ssh;
 
-	# ssh might be running on an alternate port. Use sshd -T to dump sshd's
-	# settings, find the port it is supposedly running on, and open that port
-	# too.
-	SSH_PORT=$(sshd -T 2>/dev/null | grep "^port " | sed "s/port //")
+	# ssh might be running on an alternate port. Use sshd -T to dump sshd's #NODOC
+	# settings, find the port it is supposedly running on, and open that port #NODOC
+	# too. #NODOC
+	SSH_PORT=$(sshd -T 2>/dev/null | grep "^port " | sed "s/port //") #NODOC
 	if [ ! -z "$SSH_PORT" ]; then
 	if [ "$SSH_PORT" != "22" ]; then
 
-	echo Opening alternate SSH port $SSH_PORT.
-	ufw_allow $SSH_PORT;
+	echo Opening alternate SSH port $SSH_PORT. #NODOC
+	ufw_allow $SSH_PORT #NODOC
 
 	fi
 	fi

setup/web.sh

@@ -5,6 +5,10 @@
 source setup/functions.sh # load our functions
 source /etc/mailinabox.conf # load global vars
 
+# Install nginx and a PHP FastCGI daemon.
+#
+# Turn off nginx's default website.
+
 apt_install nginx php5-fpm
 
 rm -f /etc/nginx/sites-enabled/default
@@ -20,7 +24,7 @@ sed "s#STORAGE_ROOT#$STORAGE_ROOT#" \
 tools/editconf.py /etc/nginx/nginx.conf -s \
 	server_names_hash_bucket_size="64;"
 
-# Bump up max_children to support more concurrent connections
+# Bump up PHP's max_children to support more concurrent connections
 tools/editconf.py /etc/php5/fpm/pool.d/www.conf -c ';' \
 	pm.max_children=8
 
@@ -29,20 +33,20 @@ tools/editconf.py /etc/php5/fpm/pool.d/www.conf -c ';' \
 # until mail accounts have been created.
 
 # make a default homepage
-if [ -d $STORAGE_ROOT/www/static ]; then mv $STORAGE_ROOT/www/static $STORAGE_ROOT/www/default; fi # migration
+if [ -d $STORAGE_ROOT/www/static ]; then mv $STORAGE_ROOT/www/static $STORAGE_ROOT/www/default; fi # migration #NODOC
 mkdir -p $STORAGE_ROOT/www/default
 if [ ! -f $STORAGE_ROOT/www/default/index.html ]; then
 	cp conf/www_default.html $STORAGE_ROOT/www/default/index.html
 fi
 chown -R $STORAGE_USER $STORAGE_ROOT/www
 
-# We previously installed a custom init script to start the PHP FastCGI daemon.
-# Remove it now that we're using php5-fpm.
+# We previously installed a custom init script to start the PHP FastCGI daemon. #NODOC
+# Remove it now that we're using php5-fpm. #NODOC
 if [ -L /etc/init.d/php-fastcgi ]; then
-	echo "Removing /etc/init.d/php-fastcgi, php5-cgi..."
-	rm -f /etc/init.d/php-fastcgi
-	hide_output update-rc.d php-fastcgi remove
-	apt-get -y purge php5-cgi
+	echo "Removing /etc/init.d/php-fastcgi, php5-cgi..." #NODOC
+	rm -f /etc/init.d/php-fastcgi #NODOC
+	hide_output update-rc.d php-fastcgi remove #NODOC
+	apt-get -y purge php5-cgi #NODOC
 fi
 
 # Put our webfinger script into a well-known location.
@@ -51,11 +55,11 @@ for f in webfinger; do
 	chown www-data.www-data /usr/local/bin/mailinabox-$f.php
 done
 
-# Remove obsoleted scripts.
-# exchange-autodiscover is now handled by Z-Push.
-for f in exchange-autodiscover; do
-	rm -f /usr/local/bin/mailinabox-$f.php
-done
+# Remove obsoleted scripts. #NODOC
+# exchange-autodiscover is now handled by Z-Push. #NODOC
+for f in exchange-autodiscover; do #NODOC
+	rm -f /usr/local/bin/mailinabox-$f.php #NODOC
+done #NODOC
 
 # Make some space for users to customize their webfinger responses.
 mkdir -p $STORAGE_ROOT/webfinger/acct;

setup/webmail.sh

@@ -23,16 +23,16 @@ apt_install \
 	php5 php5-sqlite php5-mcrypt php5-intl php5-json php5-common php-auth php-net-smtp php-net-socket php-net-sieve php-mail-mime php-crypt-gpg php5-gd php5-pspell \
 	tinymce libjs-jquery libjs-jquery-mousewheel libmagic1
 
-# We used to install Roundcube from Ubuntu, without triggering the dependencies
-# on Apache and MySQL, by downloading the debs and installing them manually.
-# Now that we're beyond that, get rid of those debs before installing from source.
-apt-get purge -qq -y roundcube*
+# We used to install Roundcube from Ubuntu, without triggering the dependencies #NODOC
+# on Apache and MySQL, by downloading the debs and installing them manually. #NODOC
+# Now that we're beyond that, get rid of those debs before installing from source. #NODOC
+apt-get purge -qq -y roundcube* #NODOC
 
 # Install Roundcube from source if it is not already present or if it is out of date.
 VERSION=1.0.2
 needs_update=0 #NODOC
 if [ ! -f /usr/local/lib/roundcubemail/version ]; then
-	# not installed yet
+	# not installed yet #NODOC
 	needs_update=1 #NODOC
 elif [[ $VERSION != `cat /usr/local/lib/roundcubemail/version` ]]; then
 	# checks if the version is what we want