From 4041ebf1bc7af83ea65626c08737d9b33bdfffc0 Mon Sep 17 00:00:00 2001 From: Matt Birkholz Date: Wed, 27 Dec 2023 15:22:21 -0700 Subject: [PATCH] Wordsmithing. --- README.org | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/README.org b/README.org index f3f01c7..5476d1f 100644 --- a/README.org +++ b/README.org @@ -111,12 +111,12 @@ month) because of this assumption. * The Services The small institute's network is designed to provide a number of -services. An understanding of how institute hosts co-operate is -essential to understanding the configuration of specific hosts. This -chapter covers institute services from a network wide perspective, and -gets right down in its subsections to the Ansible code that enforces -its policies. On first reading, those subsections should be skipped; -they reference particulars first introduced in the following chapter. +services. Understanding how institute hosts co-operate is essential +to understanding the configuration of specific hosts. This chapter +covers institute services from a network wide perspective, and gets +right down in its subsections to the Ansible code that enforces its +policies. On first reading, those subsections should be skipped; they +reference particulars first introduced in the following chapter. ** The Name Service @@ -172,7 +172,7 @@ declared by the institute's SPF (Sender Policy Framework) DNS record to be the only legitimate sender of institute emails. Thus the Internet sees the institute's outgoing email coming from a server at an address matching the domain's SPF record. The institute does /not/ -sign outgoing emails per DKIM (Domain Keys Identified Mail), yet. +sign outgoing emails per DKIM (Domain Keys Identified Mail) yet. #+CAPTION: Example Small Institute SPF Record #+BEGIN_SRC conf @@ -511,24 +511,26 @@ automatic mount point, e.g. =/media/sysadm/ADE7-F866/=. Unless this volume is mounted (unlocked) at =Secret/=, none of the ~./inst~ commands will work. -Chief among the institute's master secrets is the SSH key to the -privileged accounts on /all/ of the institute servers. It is stored -in =Secret/ssh_admin/id_rsa=. The institute uses several more SSH -keys listed here: +Chief among the institute's master secrets is the SSH key authorized +to access privileged accounts on /all/ of the institute servers. It +is stored in =Secret/ssh_admin/id_rsa=. The complete list of the +institute's SSH keys: - =Secret/ssh_admin/= :: The SSH key pair for A Small Institute Administrator. - =Secret/ssh_monkey/= :: The key pair used by Monkey to update the website on Front (and other unprivileged tasks). - =Secret/ssh_front/= :: The host key pair used by Front to - authenticate itself. + authenticate itself. The automatically generated key pair is + /not/ used. (Thus Core's configuration does not depend on + Front's.) The institute uses a number of X.509 certificates to authenticate VPN clients and servers. They are created by the EasyRSA Certificate Authority stored in =Secret/CA/=. - - =Secret/CA/pki/ca.crt= :: The institute CA (certificate - authority). + - =Secret/CA/pki/ca.crt= :: The institute CA certificate, used to + sign the other certificates. - =Secret/CA/pki/issued/small.example.org.crt= :: The public Apache, Postfix, and OpenVPN servers on Front. @@ -539,7 +541,7 @@ Authority stored in =Secret/CA/=. - =Secret/CA/pki/issued/core.small.private.crt= :: The campus Apache (thus Nextcloud), and Dovecot-IMAPd servers. - - =Secret/CA/pki/issued/core.crt= :: Core's client certificate by + - =Secret/CA/pki/issued/core.crt= :: Core's client certificate, by which it authenticates to Front. The ~./inst client~ command creates client certificates and keys, and @@ -736,8 +738,8 @@ domain_priv: small.private #+END_SRC The private version of the institute's domain name should end with one -of the top-level domains expected for this purpose: =.intranet=, -=.internal=, =.private=, =.corp=, =.home= or =.lan=.[fn:5] +of the top-level domains expected for this purpose: ~.intranet~, +~.internal~, ~.private~, ~.corp~, ~.home~ or ~.lan~.[fn:5] ** Subnets @@ -6574,7 +6576,7 @@ install when "opened". On campus hosts, the system administrator copies the =campus.ovpn= file to =/etc/openvpn/campus.conf=. The OpenVPN configurations generated for Debian hosts specify an ~up~ -script, =update-systemd-resolved=, installed in =/etc/openvpn/= by the +script, ~update-systemd-resolved~, installed in =/etc/openvpn/= by the ~openvpn-systemd-resolved~ package. The following configuration lines instruct the OpenVPN clients to run this script whenever the connection is restarted. @@ -7166,9 +7168,9 @@ or update its configuration files. The administrator will need a desktop system in the test campus networks (using the campus name server). The test Nextcloud configuration requires that it be accessed with the domain name -=core.small.private=. The following sections describe how a client +~core.small.private~. The following sections describe how a client desktop is simulated and connected to the test VPNs (and test campus -name server). Its browser can then connect to =core.small.private= to +name server). Its browser can then connect to ~core.small.private~ to exercise the test Nextcloud. The process starts with enrolling the first member of the institute -- 2.25.1