From 900764cb388a8709dff1f9c1d73c3fc96fcb43ec Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Sat, 12 Nov 2016 20:35:45 -0500 Subject: improve the comments for better docs --- config-box-proton-base.PKGBUILD | 7 +- config-box-winston-base.PKGBUILD | 6 +- config-mgmt-certbot.PKGBUILD | 81 ++++++++++++++++++----- config-mgmt-etckeeper.PKGBUILD | 3 +- config-mgmt-nginx.PKGBUILD | 1 + config-mgmt-pacman-mirrorlist-repomirror.PKGBUILD | 1 + config-mgmt-users-base.PKGBUILD | 1 + config-mgmt-uwsgi.PKGBUILD | 1 + config-service-config.PKGBUILD | 1 + config-service-git.PKGBUILD | 38 ++++++++--- config-service-myhostname.PKGBUILD | 1 + config-service-projects.PKGBUILD | 1 + config-service-repo.PKGBUILD | 1 + config-service-wiki.PKGBUILD | 1 + 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 <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 -# 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 <&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 <