From 900764cb388a8709dff1f9c1d73c3fc96fcb43ec Mon Sep 17 00:00:00 2001
From: Luke Shumaker <lukeshu@sbcglobal.net>
Date: Sat, 12 Nov 2016 20:35:45 -0500
Subject: improve the comments for better docs

---
 config-mgmt-certbot.PKGBUILD | 81 ++++++++++++++++++++++++++++++++++++--------
 1 file changed, 66 insertions(+), 15 deletions(-)

(limited to 'config-mgmt-certbot.PKGBUILD')

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
 }
-- 
cgit v1.2.3