improve the comments for better docs

14 files changed, 111 insertions, 33 deletions

diff --git a/config-box-proton-base.PKGBUILD b/config-box-proton-base.PKGBUILD
index 751b70f..4c91978 100644
--- a/config-box-proton-base.PKGBUILD
+++ b/config-box-proton-base.PKGBUILD
@@ -3,8 +3,7 @@ pkgver=20161111.10
 
 package() {
 preamble
-
-# ## Base setup
+# #### base setup
 
 depends+=(linux-libre-lts grub haveged systemd-swap)
 conflicts+=(linux-libre)
@@ -33,14 +32,14 @@ ln -s ../../ca-certificates/extracted/tls-ca-bundle.pem etc/ssl/certs/ca-certifi
 install -d etc/ssl/private
 ln -s ../../letsencrypt/live/$(cat etc/hostname) etc/ssl/private/myhostname
 
-# ### timedate
+# ##### timedate
 
 ln -s ../usr/share/zoneinfo/Europe/London etc/localtime
 
 # Use timesyncd NTP client daemon.
 add-unit etc/systemd/system/sysinit.target.wants/systemd-timesyncd.service
 
-# ### networking
+# ##### networking
 
 depends+=(netctl)
 
diff --git a/config-box-winston-base.PKGBUILD b/config-box-winston-base.PKGBUILD
index c82b78f..d882c1a 100644
--- a/config-box-winston-base.PKGBUILD
+++ b/config-box-winston-base.PKGBUILD
@@ -3,8 +3,8 @@ pkgver=20161111.4
 
 package() {
 preamble
+# #### base setup
 
-# ## Base setup
 depends+=(linux-libre-lts grub haveged irqbalance systemd-swap)
 conflicts+=(linux-libre)
 
@@ -39,14 +39,14 @@ ln -s ../../ca-certificates/extracted/tls-ca-bundle.pem etc/ssl/certs/ca-certifi
 install -d etc/ssl/private
 ln -s ../../letsencrypt/live/$(cat etc/hostname) etc/ssl/private/myhostname
 
-# ### timedate
+# ##### timedate
 
 ln -s ../usr/share/zoneinfo/Iceland etc/localtime
 
 # Use timesyncd NTP client daemon.
 add-unit etc/systemd/system/sysinit.target.wants/systemd-timesyncd.service
 
-# ### networking
+# ##### networking
 
 depends+=(netctl)
 
diff --git a/config-mgmt-certbot.PKGBUILD b/config-mgmt-certbot.PKGBUILD
index 7546242..4e06f72 100644
--- a/config-mgmt-certbot.PKGBUILD
+++ b/config-mgmt-certbot.PKGBUILD
@@ -3,6 +3,7 @@ pkgver=20161111.1
 
 package() {
 preamble
+# #### SSL
 
 # Use the [certbot][] ACME client to get certificates from
 # [Let's Encrypt][].
@@ -16,7 +17,29 @@ depends+=(certbot)
 # Alternative Names in a single certificate. This makes configuring
 # nginx easier.
 
-# ## issuance, renewal, and installation
+# ##### keys user and group
+
+# Files affected manually:
+#
+# * `/etc/passwd`
+# * `/etc/shadow`
+# * `/etc/group`
+# * `/etc/gshadow`
+# * `/etc/letsencrypt`
+# * `/var/lib/letsencrypt`
+# * `/var/log/letsencrypt`
+#
+# In order to run certbot as a non-root user, the keys user and group
+# have been created:
+#
+#     useradd --system --user-group --no-create-home --home-dir /etc/ssl --shell /usr/bin/nologin keys
+#     chown -R keys:keys /etc/letsencrypt /var/log/letsencrypt /var/lib/letsencrypt
+#     chmod 750 /etc/letsencrypt/archive /etc/letsencrypt/live
+#
+# The associated keys group allows users to read the (private) keys in
+# /etc/letsencrypt/live.
+
+# ##### issuance, renewal, and installation
 
 # Unlike acmetool, certbot doesn't have an easy way of saying "please
 # add this domain as a Subject Alternative Name".  You have to re-run
@@ -98,10 +121,41 @@ UMask=0027
 EOF
 add-unit etc/systemd/system/timers.target.wants/certbot-renew.timer
 
-# Both `certbot-get` and `certbot-renew.serviceq prove ownership of
+# Both `certbot-get` and `certbot-renew.service` prove ownership of
 # the domain via the `http-01` challenge. `/etc/nginx/nginx.conf`
 # includes `/etc/nginx/snippets/ssl.conf`, which has a `server{}`
 # block that handles ACME http-01 challenges.
+
+# Both `certbot-get` and `certbot-renew.service` have been written to
+# run `sudo /etc/ssl/misc/certbot-hook` after certificates have been
+# updated, and `sudo` has been configured to allow the keys user to do
+# this without a password.  Right now `certbot-hook` just runs
+# `systemctl reload nginx.service`.
+add-file -m755 etc/ssl/misc/certbot-hook <<EOF
+#!/bin/bash
+systemctl reload nginx.service
+EOF
+install -dm750 etc/sudoers.d
+add-file etc/sudoers.d/10-certbot <<EOF
+keys ALL=(ALL) NOPASSWD: /etc/ssl/misc/certbot-hook
+EOF
+
+# ##### other
+
+# Files affected manually:
+#
+# * `/etc/nginx/nginx.conf`
+# * `/etc/ssl/private/dhparam-2048.pem`
+
+# `nginx.conf` includes `snippets/ssl.conf`, which is primarily based
+# on the output of [Mozilla Security's recommended web server
+# configuration generator][0]. It has had the main SSL information
+# promoted to be directly into the `http{}` block, instead of having
+# to be in each `server{}` block. The HTTP->HTTPS redirector has had
+# an exception added to it to have it respond to ACME http-01
+# challenges.
+#
+# [0]: https://mozilla.github.io/server-side-tls/ssl-config-generator/
 add-file etc/nginx/snippets/ssl.conf <<EOF
 # -*- Mode: nginx; nginx-indent-level: 8; indent-tabs-mode: t -*-
 
@@ -167,19 +221,16 @@ ssl_stapling_verify on;
 #resolver <IP DNS resolver>;
 EOF
 
-# Both `certbot-get` and `certbot-renew.service` have been written to
-# run `sudo /etc/ssl/misc/certbot-hook` after certificates have been
-# updated, and `sudo` has been configured to allow the keys user to do
-# this without a password.  Right now `certbot-hook` just runs
-# `systemctl reload nginx.service`.
-add-file -m755 etc/ssl/misc/certbot-hook <<EOF
-#!/bin/bash
-systemctl reload nginx.service
-EOF
-install -dm750 etc/sudoers.d
-add-file etc/sudoers.d/10-certbot <<EOF
-keys ALL=(ALL) NOPASSWD: /etc/ssl/misc/certbot-hook
-EOF
+# Because certbot is only configured to use http-01 challenges, the
+# all challenges happen over pain HTTP, which means that the
+# configurations for each subdomain (which only serve over
+# HTTPS/HTTP2) do not need to include anything about ACME or SSL
+# (other than mentioning `ssl` in the `listen` directive).
+
+# `ssl.conf` needs to refer to a dhparam PEM file. This has been
+# generated with the command
+#
+#    openssl dhparam -out /etc/ssl/private/dhparam-2048.pem 2048
 
 postamble
 }
diff --git a/config-mgmt-etckeeper.PKGBUILD b/config-mgmt-etckeeper.PKGBUILD
index 589e323..9895ded 100644
--- a/config-mgmt-etckeeper.PKGBUILD
+++ b/config-mgmt-etckeeper.PKGBUILD
@@ -3,6 +3,7 @@ pkgver=20161111.5
 
 package() {
 preamble
+# #### etckeeper
 
 depends+=(etckeeper pristine-etc-keeper)
 
@@ -33,7 +34,7 @@ git ls-files --ignored --exclude-standard -z|xargs -0r git rm --cached --
 EOF
 
 # etckeeper has been configured to run the pre-commit hook at exta
-# times, to work around a bug[0].
+# times, to work around [a bug][0].
 #
 # [0]: https://etckeeper.branchable.com/todo/metadata_changes_don__39__t_cause_a_new_commit/
 add-file -m755 etc/etckeeper/unclean.d/20pre-commit <<EOF
diff --git a/config-mgmt-nginx.PKGBUILD b/config-mgmt-nginx.PKGBUILD
index cb52e65..e88ae1f 100644
--- a/config-mgmt-nginx.PKGBUILD
+++ b/config-mgmt-nginx.PKGBUILD
@@ -3,6 +3,7 @@ pkgver=20161111.3
 
 package() {
 preamble
+# #### Nginx
 
 depends+=(nginx)
 
diff --git a/config-mgmt-pacman-mirrorlist-repomirror.PKGBUILD b/config-mgmt-pacman-mirrorlist-repomirror.PKGBUILD
index 0318946..0776c9d 100644
--- a/config-mgmt-pacman-mirrorlist-repomirror.PKGBUILD
+++ b/config-mgmt-pacman-mirrorlist-repomirror.PKGBUILD
@@ -6,6 +6,7 @@ conflicts=(pacman-mirrorlist)
 
 package() {
 preamble
+# #### pacman
 
 add-file etc/pacman.d/mirrorlist <<EOF
 Server = https://repomirror.parabola.nu/\$repo/os/\$arch
diff --git a/config-mgmt-users-base.PKGBUILD b/config-mgmt-users-base.PKGBUILD
index b0dd54b..1b7de4e 100644
--- a/config-mgmt-users-base.PKGBUILD
+++ b/config-mgmt-users-base.PKGBUILD
@@ -3,6 +3,7 @@ pkgver=20161111.4
 
 package() {
 preamble
+# #### users
 
 install -d etc
 install -dm750 etc/sudoers.d
diff --git a/config-mgmt-uwsgi.PKGBUILD b/config-mgmt-uwsgi.PKGBUILD
index 9c997b3..5bd3fad 100644
--- a/config-mgmt-uwsgi.PKGBUILD
+++ b/config-mgmt-uwsgi.PKGBUILD
@@ -3,6 +3,7 @@ pkgver=20161111.5
 
 package() {
 preamble
+# #### process management
 
 # Wherever possible, we should use uWSGI for process management of our
 # HTTP services.  This allows for much more consistent management and
diff --git a/config-service-config.PKGBUILD b/config-service-config.PKGBUILD
index ee11c5f..8e8fbc5 100644
--- a/config-service-config.PKGBUILD
+++ b/config-service-config.PKGBUILD
@@ -3,6 +3,7 @@ pkgver=20161111.4
 
 package() {
 preamble
+# #### Config
 
 depends+=(
 	config-mgmt-nginx
diff --git a/config-service-git.PKGBUILD b/config-service-git.PKGBUILD
index 48bd74c..b074cec 100644
--- a/config-service-git.PKGBUILD
+++ b/config-service-git.PKGBUILD
@@ -3,16 +3,10 @@ pkgver=20161111.2
 
 package() {
 preamble
-
-depends+=(config-mgmt-certbot)
-
-add-file -m755 etc/ssl/misc/certbot-get.d/10-git <<EOF
-#!/bin/bash
-echo git.{parabola.nu,parabolagnulinux.org}
-EOF
+# #### Git
 
 depends+=(
-	git # for the 'git' user
+	git # for the 'git' user, and obviously git itself.
 	cronie
 	moreutils # for chronic
 )
@@ -28,19 +22,43 @@ PATH=/srv/git/.local/bin:/bin
 0	*	*	*	*	chronic bash -c "update-gitmeta 'Update from cron' 2>&1"
 EOF
 
-# ## transport: git protocol
+# ##### transport: git protocol
 
 add-unit etc/systemd/system/sockets.target.wants/git-daemon.socket
 
-# ## transport: HTTPS
+# ##### transport: SSH
+
+# Files affected manually:
+#
+# * `/srv/git/git-shell-commands/`
+#
+# This is the only method for which push is enabled. Only the git@
+# user may push; even though if you have access to git, you probably
+# have access to ssh into yourname@winston, you can't push from that
+# account. As far as git is concerned, all users are equal (TODO:
+# perhaps we should implement some more granular access
+# control. Safety rails and all that). Access to git@ is based on
+# membership in the "git" group in hackers.git (see
+# [#Parabola_hackers](#Parabola_hackers)).
+#
+# If you need to set up custom git hooks, then ssh in to your user,
+# and use `sudo -u git` to do it.
+
+# ##### transport: HTTPS
 
 depends+=(
 	cgit
+	config-mgmt-certbot
 	config-mgmt-nginx
 	config-mgmt-uwsgi
 	uwsgi-plugin-cgi
 )
 
+add-file -m755 etc/ssl/misc/certbot-get.d/10-git <<EOF
+#!/bin/bash
+echo git.{parabola.nu,parabolagnulinux.org}
+EOF
+
 # The git web interface is cgit, which is managed by uWSGI speaking
 # uwsgi/modifier1=9, which is the variant of the uwsgi protocol for
 # CGI requests.
diff --git a/config-service-myhostname.PKGBUILD b/config-service-myhostname.PKGBUILD
index e83d2cd..2afb390 100644
--- a/config-service-myhostname.PKGBUILD
+++ b/config-service-myhostname.PKGBUILD
@@ -3,6 +3,7 @@ pkgver=20161111.10
 
 package() {
 preamble
+# #### Host information
 
 depends+=(
 	config-mgmt-nginx
diff --git a/config-service-projects.PKGBUILD b/config-service-projects.PKGBUILD
index 480eeb8..105c67a 100644
--- a/config-service-projects.PKGBUILD
+++ b/config-service-projects.PKGBUILD
@@ -3,6 +3,7 @@ pkgver=20161111.2
 
 package() {
 preamble
+# #### Projects
 
 depends+=(
 	config-mgmt-nginx
diff --git a/config-service-repo.PKGBUILD b/config-service-repo.PKGBUILD
index be63367..3341bb7 100644
--- a/config-service-repo.PKGBUILD
+++ b/config-service-repo.PKGBUILD
@@ -6,6 +6,7 @@ conflicts=(pacman-mirrorlist)
 
 package() {
 preamble
+# #### Repo
 
 depends+=(
 	rsync
diff --git a/config-service-wiki.PKGBUILD b/config-service-wiki.PKGBUILD
index ddb086c..dce36e5 100644
--- a/config-service-wiki.PKGBUILD
+++ b/config-service-wiki.PKGBUILD
@@ -3,6 +3,7 @@ pkgver=20161111.4
 
 package() {
 preamble
+# #### Wiki
 
 depends+=(
 	# PHP