From: Matt Birkholz Date: Mon, 27 Oct 2025 17:06:19 +0000 (-0700) Subject: Document-smithing: minor edits for consistency or completeness. X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=d8c1215f75bd3dfa6f64ddfe322cc552944805f4;p=Institute Document-smithing: minor edits for consistency or completeness. - Fix ~:tangle-mode~ of private files to include ~g=,o=~. - Get ~:mkdirp yes~ and ~:noweb no-export~ where needed, and not where they are not needed. - Tangle and link to =webupdate= and =gate-wg0.conf=. - Punt nonsense entries in =core-dhcpd.conf=. - Punt capitalization of example submodule directory =Institute/=. - Wordsmithing. --- diff --git a/README.org b/README.org index 59cbd07..fc09898 100644 --- a/README.org +++ b/README.org @@ -269,8 +269,8 @@ Both servers should accept only IMAPS connections. The following configuration keeps them from even listening at the IMAP port (e.g. for ~STARTTLS~ commands). -#+CAPTION: ~dovecot-ports~ #+NAME: dovecot-ports +#+CAPTION: ~dovecot-ports~ #+BEGIN_SRC conf service imap-login { inet_listener imap { @@ -490,7 +490,7 @@ files mentioned in the Nextcloud database dump). #+NAME: backup #+CAPTION: [[file:private/backup][=private/backup=]] -#+BEGIN_SRC sh :tangle private/backup :mkdirp yes :tangle-mode u=rw +#+BEGIN_SRC sh :tangle private/backup :mkdirp yes :tangle-mode u=rwx,g=,o= #!/bin/bash -e # # DO NOT EDIT. @@ -633,7 +633,7 @@ hoped that doing so will increase the chances that some abomination like DNS-over-HTTPS will pass us by. #+CAPTION: [[file:private/vars.yml][=private/vars.yml=]] -#+BEGIN_SRC conf :tangle private/vars.yml :tangle-mode u=rw :mkdirp yes +#+BEGIN_SRC conf :tangle private/vars.yml :tangle-mode u=rw,g=,o= --- domain_priv: small.private #+END_SRC @@ -1212,7 +1212,7 @@ follows these recommendations (and /not/ the suggestion to enable ~systemd~ package). #+CAPTION: [[file:roles_t/all/tasks/main.yml][=roles_t/all/tasks/main.yml=]] -#+BEGIN_SRC conf :tangle roles_t/all/tasks/main.yml :noweb no-export +#+BEGIN_SRC conf :tangle roles_t/all/tasks/main.yml - name: Install systemd-resolved. become: yes @@ -1866,7 +1866,7 @@ used on all of the institute's web sites. #+NAME: apache-userdir-front #+CAPTION: ~apache-userdir-front~ -#+BEGIN_SRC conf :noweb no-export +#+BEGIN_SRC conf UserDir /home/www-users Require all granted @@ -2065,14 +2065,14 @@ Front uses WireGuard™ to provide a public (Internet accessible) VPN service. Core has an interface on this VPN and is expected to forward packets between it and the institute's other private networks. -The following example [[=private/front-wg0.conf=][=private/front-wg0.conf=]] configuration recognizes -Core by its public key and routes the institute's private networks to -it. It also recognizes Dick's notebook and his (replacement) phone, -assigning them host numbers 4 and 6 on the VPN. +The example [[=private/front-wg0.conf=][=private/front-wg0.conf=]] below recognizes Core by its +public key and routes the institute's private networks to it. It also +recognizes Dick's notebook and his (replacement) phone, assigning them +host numbers 4 and 6 on the VPN. #+NAME: =private/front-wg0.conf= -#+CAPTION: =private/front-wg0.conf= -#+BEGIN_SRC conf +#+CAPTION: [[file:private/front-wg0.conf][=private/front-wg0.conf=]] +#+BEGIN_SRC conf :tangle private/front-wg0.conf :tangle-mode u=rw,g=,o= [Interface] Address = 10.177.87.1/24 ListenPort = 39608 @@ -2203,7 +2203,7 @@ starts). The first step is to install Kamailio. #+CAPTION: [[file:roles_t/front/tasks/main.yml][=roles_t/front/tasks/main.yml=]] -#+BEGIN_SRC conf :tangle roles_t/front/tasks/main.yml :noweb no-export +#+BEGIN_SRC conf :tangle roles_t/front/tasks/main.yml - name: Install Kamailio. become: yes @@ -2432,12 +2432,12 @@ The example configuration file, [[file:private/core-dhcpd.conf][=private/core-dh RFC3442's extension to encode a second (non-default) static route. The default route is through the campus ISP at Gate. A second route directs campus traffic to the Front VPN through Core. This is just an -example file, with MAC addresses chosen to (probably?) match -VirtualBox test machines. In actual use =private/core-dhcpd.conf= -refers to a replacement file. +example file, with MAC addresses chosen to match VirtualBox test +machines. In actual use =private/core-dhcpd.conf= refers to a +replacement file. #+CAPTION: [[file:private/core-dhcpd.conf][=private/core-dhcpd.conf=]] -#+BEGIN_SRC conf :tangle private/core-dhcpd.conf :tangle-mode u=rw +#+BEGIN_SRC conf :tangle private/core-dhcpd.conf :tangle-mode u=rw,g=,o= option domain-name "small.private"; option domain-name-servers 192.168.56.1; @@ -2461,12 +2461,8 @@ subnet 192.168.56.0 netmask 255.255.255.0 { 0, 192,168,56,2; } -host core { - hardware ethernet 08:00:27:45:3b:a2; fixed-address 192.168.56.1; } -host gate { - hardware ethernet 08:00:27:e0:79:ab; fixed-address 192.168.56.2; } -host server { - hardware ethernet 08:00:27:f3:41:66; fixed-address 192.168.56.3; } +host dick { + hardware ethernet 08:00:27:dc:54:b5; fixed-address 192.168.56.4; } #+END_SRC The following tasks install ISC's DHCP server and configure it with @@ -2648,7 +2644,7 @@ zone "{{ campus_wg_net_cidr | ansible.utils.ipaddr('revdns') #+END_SRC #+CAPTION: [[file:private/db.domain][=private/db.domain=]] -#+BEGIN_SRC conf :tangle private/db.domain :tangle-mode u=rw +#+BEGIN_SRC conf :tangle private/db.domain :tangle-mode u=rw,g=,o= ; ; BIND data file for a small institute's PRIVATE domain names. ; @@ -2676,7 +2672,7 @@ gate IN A 192.168.56.2 #+END_SRC #+CAPTION: [[file:private/db.private][=private/db.private=]] -#+BEGIN_SRC conf :tangle private/db.private :tangle-mode u=rw +#+BEGIN_SRC conf :tangle private/db.private :tangle-mode u=rw,g=,o= ; ; BIND reverse data file for a small institute's private Ethernet. ; @@ -2695,7 +2691,7 @@ $TTL 7200 #+END_SRC #+CAPTION: [[file:private/db.public_vpn][=private/db.public_vpn=]] -#+BEGIN_SRC conf :tangle private/db.public_vpn :tangle-mode u=rw +#+BEGIN_SRC conf :tangle private/db.public_vpn :tangle-mode u=rw,g=,o= ; ; BIND reverse data file for a small institute's public VPN. ; @@ -2714,7 +2710,7 @@ $TTL 7200 #+END_SRC #+CAPTION: [[file:private/db.campus_vpn][=private/db.campus_vpn=]] -#+BEGIN_SRC conf :tangle private/db.campus_vpn :tangle-mode u=rw +#+BEGIN_SRC conf :tangle private/db.campus_vpn :tangle-mode u=rw,g=,o= ; ; BIND reverse data file for a small institute's campus VPN. ; @@ -2907,7 +2903,7 @@ Core uses Chrony to provide a time synchronization service to the campus. The default daemon's default configuration is fine. #+CAPTION: [[file:roles_t/core/tasks/main.yml][=roles_t/core/tasks/main.yml=]] -#+BEGIN_SRC conf :tangle roles_t/core/tasks/main.yml :noweb no-export +#+BEGIN_SRC conf :tangle roles_t/core/tasks/main.yml - name: Install Chrony. become: yes @@ -2925,7 +2921,7 @@ The default daemon's default configuration is fine. #+END_SRC #+CAPTION: [[file:roles_t/core/handlers/main.yml][=roles_t/core/handlers/main.yml=]] -#+BEGIN_SRC conf :tangle roles_t/core/handlers/main.yml :noweb no-export +#+BEGIN_SRC conf :tangle roles_t/core/handlers/main.yml - name: Restart Chrony. systemd: @@ -3335,7 +3331,7 @@ naming a sub-directory in the member's home directory on Core. The #+NAME: apache-userdir-core #+CAPTION: ~apache-userdir-core~ -#+BEGIN_SRC conf :noweb no-export +#+BEGIN_SRC conf UserDir Public/HTML Require all granted @@ -3530,7 +3526,7 @@ Monkey on Core runs =/usr/local/sbin/webupdate= every 15 minutes via a #+NAME: webupdate #+CAPTION: [[file:private/webupdate][=private/webupdate=]] -#+BEGIN_SRC sh +#+BEGIN_SRC sh :tangle private/webupdate :tangle-mode u=rwx,g=,o= #!/bin/bash -e # # DO NOT EDIT. @@ -3542,7 +3538,7 @@ cd /WWW/live/ rsync -avz --delete --chmod=g-w \ --filter='exclude *~' \ --filter='exclude .git*' \ - ./ {{ domain_name }}:/home/www/ + ./ small.example.org:/home/www/ #+END_SRC The following tasks install the =webupdate= script from [[file:private/][=private/=]], @@ -3577,12 +3573,13 @@ with a route to the campus networks. As described in [[*Configure Public WireGu WireGuard™ Subnet]] for Front, Core is expected to forward packets from/to the private networks. -The following example [[file:private/core-wg0.conf][=private/core-wg0.conf=]] configuration recognizes +The following example [[=private/core-wg0.conf=][=private/core-wg0.conf=]] configuration recognizes Front by its public key, ~S+6HaT~, looking for it at the institute's public IP address and a special port. +#+NAME: =private/core-wg0.conf= #+CAPTION: [[file:private/core-wg0.conf][=private/core-wg0.conf=]] -#+BEGIN_SRC conf :tangle private/core-wg0.conf +#+BEGIN_SRC conf :tangle private/core-wg0.conf :tangle-mode u=rw,g=,o= [Interface] Address = 10.177.87.2 PostUp = wg set %i private-key /etc/wireguard/private-key @@ -3594,10 +3591,9 @@ PublicKey = S+6HaTnOwwhWgUGXjSBcPAvifKw+j8BDTRfq534gNW4= AllowedIPs = 10.177.87.1 AllowedIPs = 10.177.87.0/24 #+END_SRC -# TODO: Make this a template? The following tasks install WireGuard™, configure it with -[[file:private/core-wg0.conf][=private/core-wg0.conf=]], and enable the service. +[[=private/core-wg0.conf=][=private/core-wg0.conf=]], and enable the service. #+CAPTION: [[file:roles_t/core/tasks/main.yml][=roles_t/core/tasks/main.yml=]] #+BEGIN_SRC conf :tangle roles_t/core/tasks/main.yml @@ -5010,8 +5006,8 @@ a wired IoT appliance, Dick's notebook and his replacement phone, assigning them the host numbers 3, 4 and 6 respectively. #+NAME: =private/gate-wg0.conf= -#+CAPTION: =private/gate-wg0.conf= -#+BEGIN_SRC conf +#+CAPTION: [[file:private/gate-wg0.conf][=private/gate-wg0.conf=]] +#+BEGIN_SRC conf :tangle private/gate-wg0.conf :tangle-mode u=rw,g=,o= [Interface] Address = 10.84.139.1/24 ListenPort = 51820 @@ -5463,7 +5459,7 @@ variables defined in [[file:Secret/become.yml][=Secret/become.yml=]], which is l line. #+CAPTION: [[file:Secret/become.yml][=Secret/become.yml=]] -#+BEGIN_SRC conf :tangle Secret/become.yml :tangle-mode u=rw +#+BEGIN_SRC conf :tangle Secret/become.yml :tangle-mode u=rw,g=,o= become_front: !vault | $ANSIBLE_VAULT;1.1;AES256 3563626131333733666466393166323135383838666338666131336335326 @@ -5537,7 +5533,7 @@ example password matches the example encryptions above. #+NAME: vault-password #+CAPTION: [[file:Secret/vault-password][=Secret/vault-password=]] -#+BEGIN_SRC conf :tangle Secret/vault-password :tangle-mode u=r :mkdirp yes +#+BEGIN_SRC conf :tangle Secret/vault-password :mkdirp yes :tangle-mode u=rw,g=,o= alitysortstagess #+END_SRC @@ -5553,37 +5549,37 @@ An institution using the Ansible configuration herein can include this document and its tangle as a Git submodule, e.g. in =institute/=, and thus safely merge updates while keeping public and private particulars separate, in sibling subdirectories =public/= and =private/=. -The following example commands create a new Git repo in =~/net/= -and add an =Institute/= submodule. +The following example commands create a new Git repo in =~/network/= +and add an =institute/= submodule. #+BEGIN_SRC sh cd mkdir network cd network git init -git submodule add git://birchwood-abbey.net/~puck/Institute -git add Institute +git submodule add git://birchwood-abbey.net/~puck/institute +git add institute #+END_SRC An institute administrator would then need to add several more files. - A top-level Ansible configuration file, =ansible.cfg=, would be - created by copying =Institute/ansible.cfg= and changing the - ~roles_path~ to ~roles:Institute/roles~. + created by copying =institute/ansible.cfg= and changing the + ~roles_path~ to ~roles:institute/roles~. - A host inventory, =hosts=, would be created, perhaps by copying - =Institute/hosts= and changing its IP addresses. + =institute/hosts= and changing its IP addresses. - A site playbook, =site.yml=, would be created in a new =playbooks/= - subdirectory by copying =Institute/playbooks/site.yml= with + subdirectory by copying =institute/playbooks/site.yml= with appropriate changes. -- All of the files in =Institute/public/= and =Institute/private/= +- All of the files in =institute/public/= and =institute/private/= would be copied, with appropriate changes, into new subdirectories =public/= and =private/=. -- =~/net/Secret= would be a symbolic link to the (auto-mounted?) +- =~/network/Secret= would be a symbolic link to the (auto-mounted?) location of the administrator's encrypted USB drive, as described in section [[*Keys][Keys]]. -The files in =Institute/roles_t/= were "tangled" from this document -and must be copied to =Institute/roles/= for reasons discussed in the +The files in =institute/roles_t/= were "tangled" from this document +and must be copied to =institute/roles/= for reasons discussed in the next section. This document does not "tangle" /directly/ into =roles/= to avoid clobbering changes to a working (debugged!) configuration. @@ -5591,19 +5587,19 @@ configuration. The =playbooks/= directory must include the institutional playbooks, which find their settings and templates relative to this directory, e.g. in =../private/vars.yml=. Running institutional playbooks from -=~/net/playbooks/= means they will use =~/net/private/= rather than -the example =~/net/Institute/private/=. +=~/network/playbooks/= means they will use =~/network/private/= rather +than the example =~/network/institute/private/=. #+BEGIN_SRC sh -cp -r Institute/roles_t Institute/roles -( cd playbooks; ln -s ../Institute/playbooks/* . ) +cp -r institute/roles_t institute/roles +( cd playbooks; ln -s ../institute/playbooks/* . ) #+END_SRC Given these preparations, the ~inst~ script should work in the super-project's directory. #+BEGIN_SRC sh -./Institute/inst config -n +./institute/inst config -n #+END_SRC ** Maintaining A Working Ansible Configuration @@ -5638,7 +5634,7 @@ appropriate code when it is done. The first code block is the header of the ~./inst~ script. #+CAPTION: [[file:inst][=inst=]] -#+BEGIN_SRC perl :tangle inst :tangle-mode u=rwx,g=rx +#+BEGIN_SRC perl :tangle inst :tangle-mode u=rwx,g=rx,o= #!/usr/bin/perl -w # # DO NOT EDIT. @@ -5775,7 +5771,7 @@ The playbook that updates [[file:private/vars.pl][=private/vars.pl=]]: Most of these settings are already in =private/vars.yml=. The following few provide the servers' public keys and ports. -#+CAPTION: [[file:private/vars.yml][=private/vars.yml]] +#+CAPTION: [[file:private/vars.yml][=private/vars.yml=]] #+BEGIN_SRC conf :tangle private/vars.yml front_wg_pubkey: S+6HaTnOwwhWgUGXjSBcPAvifKw+j8BDTRfq534gNW4= public_wg_port: 39608 @@ -5990,7 +5986,7 @@ during testing). If =members.yml= is not found, =members-empty.yml= is used instead. #+CAPTION: [[file:private/members-empty.yml][=private/members-empty.yml=]] -#+BEGIN_SRC conf :tangle private/members-empty.yml :tangle-mode u=rw +#+BEGIN_SRC conf :tangle private/members-empty.yml :tangle-mode u=rw,g=,o= --- members: usernames: [] @@ -6243,7 +6239,7 @@ from the administrator, but /all/ keys to ~root~ at the institute stay in [[file:Secret/][=Secret/=]]. #+CAPTION: [[file:roles_t/core/templates/passwd][=roles_t/core/templates/passwd=]] -#+BEGIN_SRC perl :tangle roles_t/core/templates/passwd :mkdirp yes +#+BEGIN_SRC perl :tangle roles_t/core/templates/passwd #!/bin/perl -wT use strict; @@ -6538,7 +6534,7 @@ Private keys (and corresponding public keys) should be generated on the client (i.e. by the WireGuard for Android™ app) and never revealed (i.e. sent in email, copied to a network drive, etc.). -The generated configuration vary depending on the type of client, +The generated configurations vary depending on the type of client, which must be given as the first argument to the command. For most types, two configuration files are generated. =campus.conf= contains the client's campus VPN configuration, and =public.conf= the client's @@ -6567,7 +6563,7 @@ run a command like ~systemctl start wg-quick@wg0~. (There may be better support in NetworkManager soon.) #+CAPTION: [[file:inst][=inst=]] -#+BEGIN_SRC perl :tangle inst :noweb no-export +#+BEGIN_SRC perl :tangle inst sub write_wg_server ($$$$$); sub write_wg_client ($$$$$$); sub hostnum_to_ipaddr ($$); @@ -6777,9 +6773,9 @@ as those in [[file:public/][=public/=]] and [[file:private/][=private/=]], along certificate authority and GnuPG key-ring in [[file:Secret/][=Secret/=]] (included in the distribution), can be used to configure three VirtualBox VMs simulating Core, Gate and Front in test networks simulating a private -Ethernet, an untrusted Ethernet, the campus ISP, and a commercial -cloud. With the test networks up and running, a simulated member's -notebook can be created and alternately attached to the untrusted +Ethernet, a wild (untrusted) Ethernet, the campus ISP, and a +commercial cloud. With the test networks up and running, a simulated +member's notebook can be created and alternately attached to the wild Ethernet (as though it were on the campus Wi-Fi) or the Internet (as though it were abroad). The administrator's notebook in this simulation is the VirtualBox host. diff --git a/private/backup b/private/backup old mode 100644 new mode 100755 diff --git a/private/core-dhcpd.conf b/private/core-dhcpd.conf index 88a44a7..f8e6371 100644 --- a/private/core-dhcpd.conf +++ b/private/core-dhcpd.conf @@ -21,9 +21,5 @@ subnet 192.168.56.0 netmask 255.255.255.0 { 0, 192,168,56,2; } -host core { - hardware ethernet 08:00:27:45:3b:a2; fixed-address 192.168.56.1; } -host gate { - hardware ethernet 08:00:27:e0:79:ab; fixed-address 192.168.56.2; } -host server { - hardware ethernet 08:00:27:f3:41:66; fixed-address 192.168.56.3; } +host dick { + hardware ethernet 08:00:27:dc:54:b5; fixed-address 192.168.56.4; } diff --git a/private/webupdate b/private/webupdate old mode 100644 new mode 100755 index 55fc456..6aec86c --- a/private/webupdate +++ b/private/webupdate @@ -1,10 +1,12 @@ #!/bin/bash -e # -# DO NOT EDIT. This file was tangled from institute.org. +# DO NOT EDIT. +# +# This file was tangled from a small institute's README.org. cd /WWW/live/ rsync -avz --delete --chmod=g-w \ --filter='exclude *~' \ --filter='exclude .git*' \ - ./ {{ domain_name }}:/home/www/ + ./ small.example.org:/home/www/