From 87b4bee5642312b93e6a5ef01bfbfe003165e99e Mon Sep 17 00:00:00 2001 From: Matt Birkholz Date: Sun, 15 Jun 2025 19:34:19 -0600 Subject: [PATCH] Update README.html. --- README.html | 904 ++++++++++++++++++++++++++-------------------------- 1 file changed, 458 insertions(+), 446 deletions(-) diff --git a/README.html b/README.html index fca9741..cd63406 100644 --- a/README.html +++ b/README.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Birchwood Abbey Networks @@ -24,8 +24,8 @@ idiosyncrasies. The roles herein are abbey specific, emphasized by the abbey- prefix on their names. These roles are applied after the generic institutional roles (again, documented here).

-
-

1. Overview

+
+

1. Overview

A Small Institute makes security and privacy top priorities but @@ -64,7 +64,7 @@ map is very similar, with differences mainly in terminology, philosophy, attitude.

-
+
                 |                                                   
                 =                                                   
               _|||_                                                 
@@ -103,8 +103,8 @@ philosophy, attitude.
-
-

2. The Abbey Particulars

+
+

2. The Abbey Particulars

The abbey's public particulars are included below. They are the @@ -134,18 +134,18 @@ into private_ex/vars-abbey.yml.

-
-

3. The Abbey Front Role

+
+

3. The Abbey Front Role

Birchwood Abbey's front door is a Digital Ocean Droplet configured as A Small Institute Front. Thus it is already serving a public web site with Apache2, spooling email with Postfix and serving it with -Dovecot-IMAPd, and hosting a VPN with OpenVPN. +Dovecot-IMAPd, and hosting a VPN with WireGuard™.

-
-

3.1. Install Emacs

+
+

3.1. Install Emacs

The monks of the abbey are masters of the staff (bo) and Emacs. @@ -160,8 +160,8 @@ The monks of the abbey are masters of the staff (bo) and Emacs.

-
-

3.2. Configure Public Email Aliases

+
+

3.2. Configure Public Email Aliases

The abbey uses several additional email aliases. These are the public @@ -200,8 +200,8 @@ from there, forwarding sysadm to a real person.

-
-

3.3. Configure Git Daemon on Front

+
+

3.3. Configure Git Daemon on Front

The abbey publishes member Git repositories with git-daemon. If @@ -276,7 +276,7 @@ like git-tasks and git-handlers.

-git-tasks
- name: Install git daemon.
+git-tasks
- name: Install git daemon.
   become: yes
   apt: pkg=git-daemon-sysvinit
 
@@ -314,7 +314,7 @@ like git-tasks and git-handlers.
-git-handlers

+git-handlers

 - name: Restart git daemon.
   become: yes
   command: systemctl restart git-daemon
@@ -322,8 +322,8 @@ like git-tasks and git-handlers.
-
-

3.4. Configure Gitweb on Front

+
+

3.4. Configure Gitweb on Front

The abbey provides an HTML interface to members' public Git @@ -350,7 +350,7 @@ lists the repositories found in /var/www/git/.

-apache-gitweb

+apache-gitweb

 Alias /gitweb-static/ /usr/share/gitweb/static/
 <Directory "/usr/share/gitweb/static/">
     Options MultiViews
@@ -408,7 +408,7 @@ web site /favicon.ico.
 

 
 

-apache-gitweb-tasks
- name: Enable Apache2 rewrite module for Gitweb.
+apache-gitweb-tasks
- name: Enable Apache2 rewrite module for Gitweb.
   become: yes
   apache2_module: name=rewrite
   notify: Restart Apache2.
@@ -445,7 +445,7 @@ web site /favicon.ico.
 

 
 

-apache-gitweb-handlers
- name: Restart Apache2.
+apache-gitweb-handlers
- name: Restart Apache2.
   become: yes
   systemd:
     service: apache2
@@ -454,8 +454,8 @@ web site /favicon.ico.
-
-

3.5. Configure Apache for Abbey Documentation

+
+

3.5. Configure Apache for Abbey Documentation

Some of the directives added to the -vhost.conf file are needed by @@ -473,7 +473,7 @@ filename suffixes.

-apache-abbey
<Directory {{ docroot }}/Abbey/>
+apache-abbey
<Directory {{ docroot }}/Abbey/>
     AllowOverride Indexes FileInfo
     Options +Indexes +FollowSymLinks
 </Directory>
@@ -496,8 +496,8 @@ AddType text/plain private pub public_vpn req rev sample txt yml
-
-

3.6. Configure Photos URLs on Front

+
+

3.6. Configure Photos URLs on Front

Some of the directives added to the -vhost.conf file map the abbey's @@ -509,7 +509,7 @@ matching configurations for accurate previews and tests.

-apache-photos

+apache-photos

 RedirectMatch /Photos$ /Photos/
 RedirectMatch /Photos/(20[0-9][0-9])_([0-9][0-9])_([0-9][0-9])$ \
               /Photos/$1_$2_$3/
@@ -522,8 +522,8 @@ AliasMatch /Photos/$ {{ docroot }}/Photos/index.html
-
-

3.7. Configure Apache on Front

+
+

3.7. Configure Apache on Front

The abbey needs to add some Apache2 configuration directives to the @@ -534,11 +534,11 @@ The abbey simply creates a birchwood-abbey.net-vhost.conf file in

-The following task adds the apache-abbey, apache-photos, and -apache-gitweb directives described above to the -vhost.conf file, +The following task adds the apache-abbey, apache-photos, and +apache-gitweb directives described above to the -vhost.conf file, and includes options-ssl-apache.conf from /etc/letsencrypt/. The rest of the Let's Encrypt configuration is discussed in the following -Install Let's Encrypt section. +Install Let's Encrypt section.

@@ -568,8 +568,8 @@ rest of the Let's Encrypt configuration is discussed in the following
-
-

3.8. Configure Apache Log Archival

+
+

3.8. Configure Apache Log Archival

These tasks hack Apache's logrotate(8) configuration to rotate @@ -701,8 +701,8 @@ encrypting and sending to sendmail.

-
-

3.9. Install Let's Encrypt

+
+

3.9. Install Let's Encrypt

The abbey uses a Let's Encrypt certificate to authenticate its public @@ -711,7 +711,7 @@ certificate is a terminal session affair (with prompts and lines entered as shown below).

-
+
 $ sudo apt install python3-certbot-apache
 $ sudo certbot --apache -d birchwood-abbey.net
 ...
@@ -821,8 +821,8 @@ restarted manually.
-
-

3.10. Rotate Let's Encrypt Log

+
+

3.10. Rotate Let's Encrypt Log

The following task arranges to rotate Certbot's logs files. @@ -850,8 +850,8 @@ The following task arranges to rotate Certbot's logs files.

-
-

3.11. Archive Let's Encrypt Data

+
+

3.11. Archive Let's Encrypt Data

A backup copy of Let's Encrypt's data (/etc/letsencrypt/) is sent to @@ -930,8 +930,8 @@ imported into root@front's GnuPG key file.

-
-

4. The Abbey Core Role

+
+

4. The Abbey Core Role

Birchwood Abbey's core is a mini-PC (System76 Meerkat) configured as A @@ -941,8 +941,8 @@ with Postfix and Dovecot, and providing essential localnet services: NTP, DNS and DHCP.

-
-

4.1. Include Abbey Variables

+
+

4.1. Include Abbey Variables

In this abbey specific document, most abbey particulars are not @@ -961,8 +961,8 @@ directory, playbooks/.

-
-

4.2. Install Additional Packages

+
+

4.2. Install Additional Packages

The scripts that maintain the abbey's web site use a number of @@ -980,8 +980,8 @@ The house task list uses JQuery.

-
-

4.3. Configure Private Email Aliases

+
+

4.3. Configure Private Email Aliases

The abbey uses several additional email aliases. These are the campus @@ -1021,13 +1021,13 @@ e.g. mythtv@mythtv.birchwood.private, locally.)

-
-

4.4. Configure Git Daemon on Core

+
+

4.4. Configure Git Daemon on Core

These tasks are identical to those executed on Front, for similar Git -services on Front and Core. See 3.3 and -Configure Gitweb on Front for more information. +services on Front and Core. See 3.3 and +Configure Gitweb on Front for more information.

@@ -1043,14 +1043,14 @@ services on Front and Core. See 3.3 and
-
-

4.5. Configure Apache on Core

+
+

4.5. Configure Apache on Core

The Apache2 configuration on Core specifies three web sites (live, test, and campus). The live and test sites must operate just like the -site on Front. Their configurations include the same apache-abbey, -apache-photos, and apache-gitweb used on Front. +site on Front. Their configurations include the same apache-abbey, +apache-photos, and apache-gitweb used on Front.

@@ -1092,15 +1092,15 @@ site on Front. Their configurations include the same
-
-

4.6. Configure Documentation URLs

+
+

4.6. Configure Documentation URLs

The institute serves its /usr/share/doc/ on the house (campus) web site. This is a debugging convenience, making some HTML documentation more accessible, especially the documentation of software installed on Core and not on typical desktop clients. Also included: the Apache2 -directives that enable user Git publishing with Gitweb (defined here). +directives that enable user Git publishing with Gitweb (defined here).

@@ -1121,8 +1121,8 @@ directives that enable user Git publishing with Gitweb (defined -

4.7. Install Apt Cacher

+
+

4.7. Install Apt Cacher

The abbey uses the Apt-Cacher:TNG package cache on Core. The @@ -1138,8 +1138,8 @@ The abbey uses the Apt-Cacher:TNG package cache on Core. The

-
-

4.8. Use Cloister Apt Cache

+
+

4.8. Use Cloister Apt Cache

Core itself will benefit from using the package cache, but should @@ -1163,8 +1163,8 @@ so caching their packages is not a priority.)

-
-

4.9. Configure NAGIOS

+
+

4.9. Configure NAGIOS

A small institute uses nagios4 to monitor the health of its network, @@ -1178,8 +1178,8 @@ customized check_sensors plugin (abbey_pisensors) in

-
-

4.10. Monitoring The Home Disk

+
+

4.10. Monitoring The Home Disk

The abbey adds monitoring of the space remaining on the volume at @@ -1215,8 +1215,8 @@ remaining on roots.)

-
-

4.11. Custom NAGIOS Monitor abbey_pisensors

+
+

4.11. Custom NAGIOS Monitor abbey_pisensors

The check_sensors plugin is included in the package @@ -1311,8 +1311,8 @@ recognizable temperature in the sensors output.

-
-

4.12. Monitoring The Cloister

+
+

4.12. Monitoring The Cloister

The abbey adds monitoring for more servers: Kamino, Kessel, and Ord @@ -1329,8 +1329,8 @@ Kessel is a wireless host while Kamino is wired. Ord Mantell, the Raspberry Pi OS (ARM64) machine, uses the abbey_pisensors monitor.

-
-

4.12.1. Cloister Network Addresses

+
+

4.12.1. Cloister Network Addresses

The IP addresses of all three hosts are nice to use in the NAGIOS @@ -1347,8 +1347,8 @@ ord_mantell_addr: 10.84.138.10

-
-

4.12.2. Installing NAGIOS Configurations

+
+

4.12.2. Installing NAGIOS Configurations

The following task installs each host's NAGIOS configuration. Note @@ -1369,8 +1369,8 @@ rarely powered up.

-
-

4.12.3. NAGIOS Monitoring of Ord-Mantell

+ -
-

4.12.4. NAGIOS Monitoring of Kamino

+
+

4.12.4. NAGIOS Monitoring of Kamino

roles_t/abbey-core/templates/nagios-kamino.cfg
define host {
@@ -1479,8 +1479,8 @@ rarely powered up.
-
-

4.12.5. NAGIOS Monitoring of Kessel

+
+

4.12.5. NAGIOS Monitoring of Kessel

roles_t/abbey-core/templates/nagios-kessel.cfg
define host {
@@ -1535,8 +1535,8 @@ rarely powered up.
-
-

4.13. Install Munin

+
+

4.13. Install Munin

The abbey is experimenting with Munin. NAGIOS is all about notifying @@ -1623,8 +1623,8 @@ next task configures libsensors to ignore them.

-
-

4.14. Install Analog

+
+

4.14. Install Analog

The abbey's public web site's access and error logs are emailed @@ -1678,8 +1678,8 @@ the campus as http://www/analog.html.

-
-

4.15. Add Monkey to Web Server Group

+
+

4.15. Add Monkey to Web Server Group

Monkey needs to be in www-data so that it can run @@ -1701,8 +1701,8 @@ user cloud accounts, found in files owned by www-data, files like

-
-

4.16. Install netpbm For Photo Processing

+
+

4.16. Install netpbm For Photo Processing

Monkey's photo processing scripts use netpbm commands like @@ -1718,8 +1718,8 @@ Monkey's photo processing scripts use netpbm commands like

-
-

4.17. Install Samba

+
+

4.17. Install Samba

The abbey core provides NAS (Network Attached Storage) service to the @@ -1797,8 +1797,8 @@ permissions.

-
-

5. The Abbey Gate Role

+
+

5. The Abbey Gate Role

Birchwood Abbey's gate is a $110 µPC configured as A Small Institute @@ -1809,8 +1809,8 @@ of its gate, so there is no additional Ansible configuration in this chapter (yet).

-
-

5.1. The Abbey Gate's Network Interfaces

+
+

5.1. The Abbey Gate's Network Interfaces

The abbey gate's lan interface is the PC's built-in Ethernet @@ -1831,8 +1831,8 @@ The MAC address of each interface is set in private/vars.yml (see

-
-

5.2. The Abbey's Starlink Configuration

+
+

5.2. The Abbey's Starlink Configuration

The abbey connects to Starlink via Ethernet, and disables Starlink's @@ -1880,8 +1880,8 @@ at least our local network traffic out of view of our ISPs.

-
-

5.3. Alternate ISPs

+
+

5.3. Alternate ISPs

The abbey used to use a cell phone on a USB tether to get Internet @@ -1926,8 +1926,8 @@ service, using a 60-isp.yaml file similar to the lines below.

-
-

6. The Abbey Cloister Role

+
+

6. The Abbey Cloister Role

Birchwood Abbey's cloister is a small institute campus. The campus @@ -1942,7 +1942,7 @@ tasks, namely configuration required on Raspberry Pi OS machines.

Wireless clients are issued keys for the cloister VPN by the ./abbey client command which is currently identical to the ./inst client -command (described in The Client Command). The wireless, cloistered +command (described in The Client Command). The wireless, cloistered hosts never roam, are not associated with a member, and so are "campus" clients, issued keys with commands like this:

@@ -1951,8 +1951,8 @@ hosts never roam, are not associated with a member, and so are ./abbey client campus new-host-name
-
-

6.1. Use Cloister Apt Cache

+
+

6.1. Use Cloister Apt Cache

The Apt-Cacher:TNG program does not work well on the frontier, so is @@ -1986,13 +1986,13 @@ local host.

-
-

6.2. Configure Cloister NRPE

+
+

6.2. Configure Cloister NRPE

Each cloistered host is a small institute campus host and thus is already running an NRPE server (a NAGIOS Remote Plugin Executor -server) with a custom inst_sensors monitor (described in Configure +server) with a custom inst_sensors monitor (described in Configure NRPE of A Small Institute). The abbey adds one complication: yet another check_sensors variant, abbey_pisensors, installed on Raspberry Pis (architecture aarch64) only. @@ -2030,8 +2030,8 @@ Raspberry Pis (architecture aarch64) only.

-
-

6.3. Install Munin Node

+
+

6.3. Install Munin Node

Each cloistered host is a Munin node. @@ -2074,8 +2074,8 @@ them.

-
-

6.4. Install Emacs

+
+

6.4. Install Emacs

The monks of the abbey are masters of the staff and Emacs. @@ -2091,8 +2091,8 @@ The monks of the abbey are masters of the staff and Emacs.

-
-

7. The Abbey Weather Role

+
+

7. The Abbey Weather Role

Birchwood Abbey now uses Home Assistant to record and display weather @@ -2119,16 +2119,16 @@ entities. These were labeled and organized on an "Abbey" dashboard.

-
-

8. The Abbey DVR Role

+
+

8. The Abbey DVR Role

The abbey uses AgentDVR to record video from PoE IP HD security cameras. It is installed and configured as described here.

-
-

8.1. AgentDVR Installation

+
+

8.1. AgentDVR Installation

AgentDVR is installed at the abbey according to the iSpy web site's @@ -2151,8 +2151,8 @@ bash <(curl -s "https://raw.githubusercontent.com/\< preparations.

-
-

8.1.1. AgentDVR Installation Preparation

+
+

8.1.1. AgentDVR Installation Preparation

AgentDVR runs in the abbey as a system user, agentdvr, which @@ -2187,8 +2187,8 @@ sudo mv ~/01agentdvr /etc/sudoers.d/

-
-

8.1.2. AgentDVR Installation Execution

+
+

8.1.2. AgentDVR Installation Execution

With the above preparations, the system administrator can get a shell @@ -2209,8 +2209,8 @@ Ansible is run again.

-
-

8.1.3. AgentDVR Installation Completion

+
+

8.1.3. AgentDVR Installation Completion

When Ansible is run a second time, after the installation script, it @@ -2233,8 +2233,8 @@ sudo rm /etc/sudoers.d/01agentdvr

-
-

8.2. Create User agentdvr

+
+

8.2. Create User agentdvr

AgentDVR runs as the system user agentdvr, which is created here. @@ -2271,8 +2271,8 @@ AgentDVR runs as the system user agentdvr, which is created here.

-
-

8.3. Test For AgentDVR/

+
+

8.3. Test For AgentDVR/

The following task probes for the /home/agentdvr/AgentDVR/ @@ -2295,8 +2295,8 @@ remaining installation steps are skipped unless

-
-

8.4. Create AgentDVR Service

+
+

8.4. Create AgentDVR Service

This service definition came from the template downloaded (from here) @@ -2346,8 +2346,8 @@ by install.sh.

-
-

8.5. Create AgentDVR Storage

+
+

8.5. Create AgentDVR Storage

The abbey uses a separate volume to store surveillance recordings, @@ -2381,11 +2381,11 @@ location do not fail.

-
-

8.6. Configure IP Cameras

+
+

8.6. Configure IP Cameras

-A new security camera is setup as described in Cloistering, after +A new security camera is setup as described in Cloistering, after which the camera should be accessible by name on the abbey networks. Assuming ping -c1 new works, the camera's web interface will be accessible at http://new/. @@ -2404,8 +2404,8 @@ long duration logs, thus fewer frames per second.

-
-

8.7. Configure AgentDVR's Cameras

+
+

8.7. Configure AgentDVR's Cameras

After Ansible has configured and started the AgentDVR service, its web @@ -2442,8 +2442,8 @@ AgentDVR's Live View.

-
-

8.8. Configure AgentDVR's Default Storage

+
+

8.8. Configure AgentDVR's Default Storage

AgentDVR's web interface is also used to configure a default storage @@ -2455,8 +2455,8 @@ pressed before the task is complete.

-
-

8.9. Configure AgentDVR's Recordings

+
+

8.9. Configure AgentDVR's Recordings

After a default storage location has been configured, AgentDVR's @@ -2488,8 +2488,8 @@ parameters are set (in the Recording and Storage tabs).

-
-

9. The Abbey TVR Role

+
+

9. The Abbey TVR Role

The abbey has a few TV tuners and a subscription to Schedules Direct @@ -2504,8 +2504,8 @@ interface on the master server. It configures the Apache web server to serve MythWeb pages at e.g. http://new/mythweb/.

-
-

9.1. Building MythTV and MythWeb

+
+

9.1. Building MythTV and MythWeb

Neither Debian nor the MythTV project provide binary packages of @@ -2536,19 +2536,19 @@ video source and capture card, after which the backend can be started.

-
-

9.2. TVR Machine Setup

+
+

9.2. TVR Machine Setup

-A new TVR machine needs only Cloistering to prepare it for +A new TVR machine needs only Cloistering to prepare it for Ansible. As part of that process, it should be added to the tvrs group in the hosts file. An existing server can become a TVR machine simply by adding it to the tvrs group.

-
-

9.3. Include Abbey Variables

+
+

9.3. Include Abbey Variables

Private variables in private/vars-abbey.yml are needed, as in the @@ -2564,8 +2564,8 @@ directory, playbooks/.

-
-

9.4. Install MythTV Build Requisites

+
+

9.4. Install MythTV Build Requisites

A number of developer packages are needed to build MythTV. The wiki @@ -2651,8 +2651,8 @@ MythTV is built and installed.

-
-

9.5. Build and Install MythTV

+
+

9.5. Build and Install MythTV

After a successful "first" run of e.g. ./abbey config new, the @@ -2700,8 +2700,8 @@ Several of the remaining installation steps are skipped unless

-
-

9.6. Create MythTV User

+
+

9.6. Create MythTV User

MythTV Backend needs to run as its own user: mythtv. @@ -2718,8 +2718,8 @@ MythTV Backend needs to run as its own user: mythtv.

-
-

9.7. Create MythTV DB

+
+

9.7. Create MythTV DB

MythTV's MariaDB database is created by the following task, when the @@ -2746,8 +2746,8 @@ privileged DB user, the mythconverg database is created manually

-
-

9.8. Create MythTV DB User

+
+

9.8. Create MythTV DB User

The DB user's password is taken from the mythtv_dbpass variable, @@ -2779,8 +2779,8 @@ created above.

-
-

9.9. Manually Create MythTV DB and DB User

+
+

9.9. Manually Create MythTV DB and DB User

The MythTV database and database user are created manually with the @@ -2805,8 +2805,8 @@ exit;

-
-

9.10. Load DB Timezone Info

+
+

9.10. Load DB Timezone Info

Starting with MythTV version 0.26, the time zone tables must be loaded @@ -2830,8 +2830,8 @@ e.g. 2022-09-13 20:15:41.

-
-

9.11. Create MythTV Backend Service

+
+

9.11. Create MythTV Backend Service

This task installs the mythtv-backend.service file. @@ -2875,8 +2875,8 @@ This task installs the mythtv-backend.service file.

-
-

9.12. Set PHP Timezone

+
+

9.12. Set PHP Timezone

This task checks PHP's timezone. If unset, MythTV's backend logs @@ -2917,8 +2917,8 @@ bitter complaints.

-
-

9.13. Create MythTV Storage Area

+
+

9.13. Create MythTV Storage Area

The backend does not have a default storage area for its recordings. @@ -2942,8 +2942,8 @@ creates that directory and ensures it has appropriate permissions.

-
-

9.14. Configure MythTV Backend

+
+

9.14. Configure MythTV Backend

With MythTV built and installed, and the post-installation tasks @@ -2983,12 +2983,12 @@ directory: /home/mythtv/Recordings.

-
-

9.15. Configure Tuner

+
+

9.15. Configure Tuner

The abbey has a Silicon Dust Homerun HDTV Duo (with two tuners). It -is setup as described in Cloistering, after which the tuner is +is setup as described in Cloistering, after which the tuner is accessible by name (e.g. new) on the cloister network. Assuming ping -c1 new works, the tuner should be accessible via the hdhomerun_config_gui command, a graphical interface contributed to @@ -2999,8 +2999,8 @@ tuner's domain name or IP address can also be entered.

-
-

9.16. Add HDHomerun and Mr.Antenna

+
+

9.16. Add HDHomerun and Mr.Antenna

In MythTV Setup: @@ -3043,8 +3043,8 @@ any case, do not run mythfilldatabase.

-
-

9.17. Scan for New Channels

+
+

9.17. Scan for New Channels

In MythTV Setup: @@ -3065,8 +3065,8 @@ channels is presented. Delete All unused transports.

-
-

9.18. Configure XMLTV

+
+

9.18. Configure XMLTV

The xmltv package, specifically its tv_grab_zz_sdjson program, is @@ -3101,7 +3101,7 @@ the list of "inputs" available in a postal code typically ends with the OTA (over the air) broadcasts.

-
+
 $ tv_grab_zz_sdjson --configure --config-file .mythtv/Mr.Antenna.xml
 Cache file for lineups, schedules and programs.
 Cache file: [/home/mythtv/.xmltv/tv_grab_zz_sdjson.cache]
@@ -3151,8 +3151,8 @@ backend is running, so it is not run until then.
-
-

9.19. Debug XMLTV

+
+

9.19. Debug XMLTV

If the mythfilldatabase command fails or expected listings do not @@ -3191,8 +3191,8 @@ Running a similar command (without --quiet) might be more revealing

-
-

9.20. Configure MythTV Backend Logging

+
+

9.20. Configure MythTV Backend Logging

The abbey directs MythTV log messages to /var/log/mythtv.log (and @@ -3229,8 +3229,8 @@ away from /var/log/syslog) and rotates the log file.

-
-

9.21. Start MythTV Backend

+
+

9.21. Start MythTV Backend

After configuring with mythtv-setup as discussed above, start and @@ -3246,8 +3246,8 @@ sudo -u mythtv mythfilldatabase

-
-

9.22. Install MythWeb

+
+

9.22. Install MythWeb

MythWeb, like MythTV, is installed from a Git repository. The @@ -3363,14 +3363,14 @@ The following tasks take care of the rest of the installation.

-
-

9.23. Change Broadcast Area

+
+

9.23. Change Broadcast Area

The abbey changes location almost weekly, so its HDTV broadcast area changes frequently. At the start of a long stay the administrator uses the MythTV Setup program to scan for the new area's channels, as -described in Scan for New Channels. +described in Scan for New Channels.

@@ -3388,7 +3388,7 @@ program as user mythtv.

The program will prompt for the zip code and offer a list of "inputs" -available in that area, as described in Configure XMLTV. +available in that area, as described in Configure XMLTV.

@@ -3411,8 +3411,8 @@ And the mythtv account can run mythfilldatabase.

-
-

10. The Ansible Configuration

+
+

10. The Ansible Configuration

The abbey's Ansible configuration, like that of A Small Institute, is @@ -3439,7 +3439,7 @@ specific versions.

-NOTE: if you have not read at least the Overview of A Small Institute +NOTE: if you have not read at least the Overview of A Small Institute you are lost.

@@ -3469,8 +3469,8 @@ rest are built up piecemeal by (tangled from) this document, README.org, and Institute/README.org.

-
-

10.1. ansible.cfg

+
+

10.1. ansible.cfg

This is much like the example (test) institutional configuration file, @@ -3487,11 +3487,11 @@ except the roles are found in Institute/roles/ as well as roles/.

-
-

10.2. hosts

+
+

10.2. hosts

-hosts
all:
+hosts
all:
   vars:
     ansible_user: sysadm
     ansible_ssh_extra_args: -i Secret/ssh_admin/id_rsa
@@ -3562,8 +3562,8 @@ except the roles are found in Institute/roles/ as well as roles/.
-
-

10.3. playbooks/site.yml

+
+

10.3. playbooks/site.yml

This playbook provisions the entire network by applying first the @@ -3604,17 +3604,17 @@ institutional roles, then the liturgical roles.

-
-

11. The Abbey Commands

+
+

11. The Abbey Commands

The ./abbey script encodes the abbey's canonical procedures. It -includes The Institute Commands and adds a few abbey-specific +includes The Institute Commands and adds a few abbey-specific sub-commands.

-
-

11.1. Abbey Command Overview

+
+

11.1. Abbey Command Overview

Institutional sub-commands: @@ -3625,8 +3625,7 @@ Institutional sub-commands:

new
Create system accounts for a new member.
old
Disable system accounts for a former member.
pass
Set the password of a current member.
-
client
Produce an OpenVPN configuration (.ovpn) file for a -member's device.
+
client
Register WireGuard™ public keys for a member's device.

@@ -3643,8 +3642,8 @@ and _architecture for all hosts.

-
-

11.2. Abbey Command Script

+
+

11.2. Abbey Command Script

The script begins with the following prefix and trampolines. @@ -3667,7 +3666,7 @@ The script begins with the following prefix and trampolines. The small institute's ./inst command expects to be running in Institute/, not ./, but it only references public/, private/, Secret/ and playbooks/check-inst-vars.yml, and will find the abbey -specific versions of these. The roles_path setting in ansible.cfg +specific versions of these. The roles_path setting in ansible.cfg effectively merges the institutional roles into the distinctly named abbey specific roles. The roles likewise reference files with relative names, and will find the abbey specific private/ @@ -3686,8 +3685,8 @@ code block "duplicates" the action of the institute's

-
-

11.3. The Upgrade Command

+
+

11.3. The Upgrade Command

The script implements an upgrade sub-command that runs apt update @@ -3752,8 +3751,8 @@ a limit pattern. For example:

-
-

11.4. The Reboots Command

+
+

11.4. The Reboots Command

The script implements a reboots sub-command that looks for @@ -3784,8 +3783,8 @@ The script implements a reboots sub-command that looks for

-
-

11.5. The Versions Command

+
+

11.5. The Versions Command

The script implements a versions sub-command that reports the @@ -3812,8 +3811,8 @@ operating system version of all abbey managed machines.

-
-

11.6. The TZ Command

+
+

11.6. The TZ Command

The abbey changes location almost weekly, so its timezone changes @@ -3911,8 +3910,8 @@ last host in the previous play.

-
-

11.7. Abbey Command Help

+
+

11.7. Abbey Command Help

abbey
my $ops = "config,new,old,pass,client,upgrade,reboots,versions,tz";
@@ -3922,8 +3921,8 @@ last host in the previous play.
-
-

12. Cloistering

+
+

12. Cloistering

This is how a new machine is brought into the cloister. The process @@ -3932,13 +3931,13 @@ narrows down to the common preparation of all machines administered by Ansible.

-
-

12.1. IoT Devices

+
+

12.1. IoT Devices

A wireless IoT device (smart TV, Blu-ray deck, etc.) cannot install -Debian nor even an OpenVPN app from F-Droid. And it shouldn't. As an -untrustworthy bit of kit, it should have no access to the cloister, +Debian nor even the WireGuard™ For Android app. And it shouldn't. As +an untrustworthy bit of kit, it should have no access to the cloister, merely the Internet. It need not appear in the Ansible inventory.

@@ -3949,8 +3948,8 @@ given a private domain name as described in the following steps.

@@ -3960,12 +3959,12 @@ last step:

-
-

12.2. Raspberry Pis

+
+

12.2. Raspberry Pis

The abbey's Raspberry Pi runs the Raspberry Pi OS desktop off an @@ -3984,8 +3983,8 @@ Ethernet, and power up.

  • new username: sysadm
  • new password: fubar
    • -
  • Add to Core DHCP
    • -
  • Create Wired Domain Name
    • +
  • Add to Core DHCP
    • +
  • Create Wired Domain Name
  • Log in as sysadm on the console.
  • Run sudo raspi-config and use the following menu items.
      @@ -3993,9 +3992,9 @@ Ethernet, and power up.
    • I1 SSH (Enable/disable remote command line access using SSH): enable
    • A1 Expand Filesystem (Ensures that all of the SD card is available)
    • -
  • Update From Cloister Apt Cache
    • -
  • Authorize Remote Administration
    • -
  • Configure with Ansible
    • +
  • Update From Cloister Apt Cache
    • +
  • Authorize Remote Administration
    • +
  • Configure with Ansible

    • @@ -4004,14 +4003,14 @@ steps are taken.

    -
    -

    12.3. PCs

    +
    +

    12.3. PCs

    Most of the abbey's machines, like Core and Gate, are general-purpose @@ -4031,18 +4030,18 @@ Ethernet, and power up. Choose to boot from the USB drive.

  • new username: sysadm
  • new password: fubar
    • -
  • Add to Core DHCP
    • -
  • Create Wired Domain Name
    • +
  • Add to Core DHCP
    • +
  • Create Wired Domain Name
  • Log in as sysadm on the console.
    • -
  • Update From Cloister Apt Cache
    • +
  • Update From Cloister Apt Cache

  • Install OpenSSH. Plain Debian does not come with OpenSSH installed. 

     sudo apt install openssh-server
    • -
  • Authorize Remote Administration
    • -
  • Configure with Ansible
    • +
  • Authorize Remote Administration
    • +
  • Configure with Ansible

    • @@ -4051,14 +4050,14 @@ steps are taken.

    -
    -

    12.4. Add to Core DHCP

    +
    +

    12.4. Add to Core DHCP

    When a new machine is connected to the cloister Ethernet, its MAC @@ -4119,12 +4118,12 @@ reporting 1 packets transmitted, 1 received, 0% packet loss....

    -
    -

    12.5. Create Wired Domain Name

    +
    +

    12.5. Create Wired Domain Name

    A wired device is assigned an IP address when it is added to Core's -DHCP configuration (as in Add to Core DHCP). A private domain name is +DHCP configuration (as in Add to Core DHCP). A private domain name is then associated with this address. If the device is intended to operate wirelessly, the name for its address is modified with a -w suffix. Thus new-w.small.private would be the name of the new @@ -4167,8 +4166,8 @@ resolvectl query 192.168.56.4

    -
    -

    12.6. Update From Cloister Apt Cache

    +
    +

    12.6. Update From Cloister Apt Cache

    • Log in as sysadm on the console.
      • @@ -4191,8 +4190,8 @@ sudo reboot
    -
    -

    12.7. Authorize Remote Administration

    +
    +

    12.7. Authorize Remote Administration

    To remotely administer new-w, Ansible must be authorized to login as @@ -4226,11 +4225,11 @@ key.

    -
    -

    12.8. Configure with Ansible

    +
    +

    12.8. Configure with Ansible

    -With remote administration authorized and tested (as in Authorize +With remote administration authorized and tested (as in Authorize Remote Administration), and the machine connected to the cloister Ethernet, the configuration of new-w can be completed by Ansible. Note that if the machine is staying on the cloister Ethernet, its @@ -4238,7 +4237,7 @@ domain name will be new (having had no -w suffix added

    -First new-w is added to Ansible's inventory in hosts. A new-w +First new-w is added to Ansible's inventory in hosts. A new-w section is added to the list of all hosts, and an empty section of the same name is added to the list of campus hosts. If the machine uses the usual privileged account name, sysadm, the ansible_user key in @@ -4286,8 +4285,8 @@ configuration files.

    -
    -

    12.9. Connect to Cloister Wi-Fi

    +
    +

    12.9. Connect to Cloister Wi-Fi

    On an IoT device, or a Debian or Android "desktop", the cloister Wi-Fi @@ -4328,8 +4327,8 @@ desktop connected to the Wi-Fi using the following ping command.

    -
    -

    12.10. Connect to Cloister VPN

    +
    +

    12.10. Connect to Cloister VPN

    Wireless devices (with the cloister Wi-Fi password) can get an IP @@ -4341,173 +4340,192 @@ however, are not accessible except via the cloister VPN.

    -Connections to the cloister VPN are authorized by OpenVPN -configuration (.ovpn) files generated by the ./abbey client... -command (aka The Client Command). These are secret files, kept -readable only by their owners and are deleted after use. They are -copied to new OpenVPN clients using secure (ssh) connections. +Connections to the cloister VPN are authorized by the ./abbey +client... command (aka The Client Command), which registers a new +client's public key and installs new WireGuard™ configurations on the +servers. Private keys are kept on the clients (e.g. in +/etc/wireguard/private-key).

    -
    -

    12.10.1. Debian Servers

    +
    +

    12.10.1. Campus Desktops and Servers

    -Wireless Debian servers (without NetworkManager) are connected to the -cloister VPN via the following process. +Wireless Debian desktops (with NetworkManager) as well as servers +(without NetworkManager) are configured to automatically connect to +the cloister Wi-Fi and VPN, and so can be used much like a wired +desktop machine. They are typically connected to a large TV and +auto-login to an unprivileged account named house, i.e. anyone in +the house. Our campus desktops include an 8GB Core i3 NUC (Intel®'s +Next Unit of Computing) and an 8GB Raspberry Pi 4 with SSD storage +running Pop!_OS and Raspberry Pi OS desktops, respectively. They are +authorized to connect to the campus VPN via the following process.

      -
    • Create a new client certificate and OpenVPN configuration for the -new abbey server.
      • -
    • Copy the campus.ovpn file to the new machine.
      • -
    • On the new machine:
      • -
    • Install the openvpn-systemd-resolved package.
      • -
    • Copy campus.ovpn to /etc/openvpn/cloister.conf.
      • -
    • Start the OpenVPN service.
      • -
    • Check that the cloister VPN was connected.
      • -
    • Logout and unplug the cloister Ethernet.
      • -
    • Test the cloister VPN connection (and private name resolution) -with ping -c1 core.
      • -
    +

  • +The administrator first creates a wifi file like the following +(in which the wireless network device is named wlan0). +

    +
    +
    auto wlan0
+iface wlan0 inet dhcp
+    wpa-ssid "Birchwood Abbey"
+    wpa-psk "PASSWORD"
+
    +
    • -

    -And these are the commands: +

  • +Then the wifi file is installed and the network interface +brought up.

    +
    +
    sudo cp wifi /etc/network/interfaces.d/
+sudo ifup wlan0
+
    +
    • +

  • +Next, the administrator generates a pair of WireGuard™ keys. +

    -
    ./abbey client campus new
-scp campus.ovpn sysadm@new-w:
-ssh sysadm@new-w
-sudo apt install openvpn-systemd-resolved
-sudo cp campus.ovpn /etc/openvpn/cloister.conf
-sudo systemctl start openvpn@cloister
-systemctl status openvpn@cloister
-ping -c1 core
-sudo systemctl enable openvpn@cloister
-rm campus.ovpn
-logout
-rm campus.ovpn
+
    sudo apt install wireguard
+wg genkey | sudo tee /etc/wireguard/private-key >/dev/null
+sudo cat /etc/wireguard/private-key | wg pubkey >server.pub
 
    
-
    +
    • -

    -It may be necessary to reboot before the final tests. +

  • +The client's name and public key are then registered via the +./abbey client command, and the resulting details are copied to +the client.

    +
    +
    scp sysadm@new-w:server.pub ./
+./abbey client campus new `cat server.pub`
+scp campus.conf sysadm@new-w:
+
    +
    • + +

  • +The details are copied to /etc/wireguard/wg0.conf on the client +and the service started. +

    +
    +
    sudo cp campus.conf /etc/wireguard/wg0.conf
+sudo systemctl start wg-quick@wg0
+systemctl status wg-quick@wg0
+
    +
    • + +
  • The client can then be unplugged from the cloister Ethernet, and +connect to the campus Wi-Fi (if not already).
    • + +

  • +Finally the connection to the VPN is tested and, if OK, is +"enabled" (to start at boot time). +

    +
    +
    ping -c1 core
+sudo wg show
+sudo systemctl enable wg-quick@wg0
+
    +
    • +
    -
    -

    12.10.2. Debian Desktops

    +
    +

    12.10.2. Private Desktops

    -Wireless Debian desktops (with NetworkManager) include our 8GB Core i3 -NUC (Intel®'s Next Unit of Computing) and our 8GB Raspberry Pi 4. -They run the Pop!_OS and Raspberry Pi OS desktops respectively. They -are connected to the cloister VPN via the following process. +Member notebooks are private machines not remotely administered by the +abbey. These machines roam, and so are authorized to connect both to +the cloister VPN or to the public VPN. They are authorized to do so +via the following process.

      -
    • Create a new client certificate and OpenVPN configuration for the -new abbey desktop, a campus.ovpn file.
      • +
    • The owner of the Debian desktop machine should have already +connected to the campus Wi-Fi using the GUI of NetworkManager.
      • +

    • -Create a wifi file that looks like this (assuming the wireless -network device is named wlan0). +The owner thus begins by generating a pair of WireGuard™ keys on +the client, sending the public key to the administrator.

      +
      +
      sudo apt install wireguard
+wg genkey | sudo tee /etc/wireguard/private-key >/dev/null
+sudo cat /etc/wireguard/private-key | wg pubkey >dick.pub
+( echo "Subject: new client named dick"
+  echo
+  cat dick.pub ) | sendmail sysadm@small.example.org
+
      +
      • -
      -auto wlan0
-iface wlan0 inet dhcp
-    wpa-ssid "Birchwood Abbey"
-    wpa-psk "PASSWORD"
-
      - -
    • Copy the wifi and campus.ovpn files to the new machine.
      • -
    • On the new machine:
      • -
    • Install the openvpn-systemd-resolved package.
      • -
    • Copy wifi to /etc/network/interfaces.d/.
      • -
    • Bring up the Wi-Fi interface.
      • -
    • Copy campus.ovpn to /etc/openvpn/cloister.conf.
      • -
    • Start the OpenVPN service.
      • -
    • Check that the cloister VPN was connected.
      • -
    • Logout and unplug the cloister Ethernet.
      • -
    • Test the cloister VPN connection (and private name resolution) -with ping -c1 core.
      • -
    +

  • +The administrator runs the ./abbey client command and replies +with the generated configurations. +

    +
    +
    ./abbey client debian dick dick `cat dick.pub`
+( echo "Subject: dick now authorized"
+  echo
+  cat campus.conf
+  echo --------
+  cat public.conf
+  ) | sendmail dick
+
    +
    • -

    -And these are the commands: +

  • +The owner saves the configuration details in campus.conf and +public.conf, then installs them and starts the campus VPN +service.

    +
    +
    sudo cp campus.conf /etc/wireguard/wg0.conf
+sudo vp public.conf /etc/wireguard/wg1.conf
+sudo systemctl start wg-quick@wg0
+systemctl status wg-quick@wg0
+
    +
    • +

  • +Finally the owner checks that the client has successfully +connected to the campus VPN and, if it has, enables the service. +

    -
    ./abbey client campus new
-scp wifi campus.ovpn sysadm@new-w:
-ssh sysadm@new-w
-sudo apt install openvpn-systemd-resolved
-sudo cp wifi /etc/network/interfaces.d/
-sudo ifup wlan0
-sudo cp campus.ovpn /etc/openvpn/cloister.conf
-sudo systemctl start openvpn@cloister
-systemctl status openvpn@cloister
+
    systemctl status wg-quick@wg0
 ping -c1 core
-sudo systemctl enable openvpn@cloister
-rm wifi campus.ovpn
-logout
-rm wifi campus.ovpn
+sudo systemctl enable wg-quick@wg0
 
    
-
    +
    • +

    -It may be necessary to reboot before the final tests. +The owner will want to test the public VPN connection as well by +taking the Debian desktop off the campus Wi-Fi and getting it Internet +access some other way (perhaps tethered to a cell phone). Then the +following commands will switch to the public VPN and test it.

    -

    -As configured above, the wireless Debian desktops make automatic, -persistent connections to the cloister Wi-Fi and VPN, and so can be -used much like a wired desktop machine. They are typically connected -to a large TV and auto-login to an unprivileged account named house, -i.e. anyone in the house. -

    -
    +
    +
    sudo systemctl stop wg-quick@wg0
+sudo systemctl start wg-quick@wg1
+ping -c1 core
+
    -
    -

    12.10.3. Private Desktops

    -
    -

    -Member notebooks are private machines not remotely administered by the -abbey. These machines roam, and so are authorized to connect to the -cloister VPN or the public VPN. This is how they are connected to the -VPNs: -

    - -
      -
    • Create a new client certificate and OpenVPN configurations for the -new abbey desktop, campus.ovpn and public.ovnp files.
      • -
    • Copy the campus.ovpn and public.ovpn files to the new machine.
      • -
    • On the new machine:
      • -
    • Install the openvpn-systemd-resolved and -network-manager-openvpn-gnome packages.
      • -
    • Open the desktop Settings > Network > VPN + > Import from -file… and choose ~/campus.ovpn.
      • -
    • Open the Routes dialogues for both IPv4 and IPv6 and choose -"Use this connection only for resources on its network.".
      • -
    • Save the new VPN.
      • -
    • Do the same with the ~/public.ovpn file.
      • -
    • Connect the appropriate VPN and test it (and private name -resolution) with ping -c1 core.
      • -
    • Expunge (delete and empty the trash) the ~/campus.ovpn and -~/public.ovpn files.
      • -

    -We assume the desktop is running NetworkManager, which is the case in -all our Debian desktops from Pop!_OS and Ubuntu to Mint and Raspberry -Pi OS. +This leaves wg-quick@wg0 enabled. The campus VPN is re-connected if +the machine reboots.

    Note that a new member's notebook does not need to be patched to the cloister Ethernet nor connected to the cloister Wi-Fi. It can be -authorized "remotely" simply by copying the .ovpn files securely, -e.g. using ssh to any "known host" on the Internet. +authorized "remotely" simply by copying the .conf text files to the +machine by whatever means is available.

    @@ -4529,61 +4547,55 @@ password is included in Secret/become.yml.

    -
    -

    12.10.4. Android

    -
    +
    +

    12.10.3. Android

    +

    -Android phones and tablets are connected to the cloister VPN via the -following process. Note that they do not appear in the set of -campus hosts, are not configured by Ansible, and do not appear in -the host inventory. +Android phones and tablets are authorized to connect to the cloister +and public VPNs via the following process. Note that they do not +appear in the set of campus hosts, are not configured by Ansible, +and do not appear in the host inventory.

      -
    • Create a new client certificate and campus/public OpenVPN -configurations for the new abbey Android.
      • -
    • Copy the campus.ovpn and public.ovpn files to a USB drive.
      • -
    • On the Android machine:
      • -
    • Connect to the cloister Wi-Fi.
      • -
    • Install F-Droid and use it to install OpenVPN.
      • -
    • Connect the USB drive, perhaps with an OTG (On The Go) adapter, -and open the campus.ovpn file. The file should be opened with -the OpenVPN app, which will appear to ask for confirmation before -creating the new VPN.
      • -
    • Open the public.ovpn file and create a second VPN.
      • -
    +
  • The owner of the Android device creates a WireGuard™ key pair with +the WireGuard™ for Android app, and texts the public key to the +administrator.
    • -

    -The .ovpn files must be transferred to the Android via a secure -medium: the scp command, a USB drive, a cloud download, or perhaps -an encrypted email. In the following commands, the files are copied -to a USB drive labeled Transfers. After insertion into the Android, -its "storage" is viewed with the Files app, which should launch -OpenVPN when a .ovpn file is opened. +

  • +The administrator runs the ./abbey client command and replies +with the generated configurations.

    -
    -
    ./abbey client android dicks-tablet dick
-cp campus.ovpn public.ovpn /media/sysadm/Transfers/
-rm campus.ovpn public.ovpn
+
    ./abbey client android dicks-razr dick <client public key>
+( echo "Subject: dicks-razr now authorized"
+  echo
+  cat campus.conf
+  echo --------
+  cat public.conf
+  ) | sendmail owner
 
    
+
    • + +
  • The owner enters the details of the two WireGuard™ subnets into +the app, creating two tunnels. These are turned on and off +depending on whether the Android is connecting to the campus or +public VPN.
    • +
    -
    -
    -

    12.11. Create Wireless Domain Name

    +
    +

    12.11. Create Wireless Domain Name

    A wireless machine is assigned a Wi-Fi address when it connects to the -cloister Wi-Fi, and a "VPN address" when it connects to Gate's OpenVPN -server. The VPN address can be discovered by running ip addr show -dev ovpn on the machine, or inspecting /etc/openvpn/ipp.txt on -Gate. Once discovered, a private domain name, -e.g. new.small.private, can be associated with the VPN address, e.g -10.84.138.7. The administrator adds a line like the following to -private/db.domain and increments the serial number at the top of the -file. +cloister Wi-Fi, and a host number when it is registered. Given the +host number (e.g. 7), a private domain name +(e.g. new.small.private) can be associated with that host number on +the cloister VPN subnet, e.g 10.84.138.7. The administrator adds a +line like the following to private/db.domain and increments the +serial number at the top of the file.

    @@ -4614,14 +4626,14 @@ resolvectl query 10.84.138.7

    -A wireless device with no Ethernet interface and unable to run OpenVPN -gets just a Wi-Fi address. It can be given a private domain name -(e.g. new.small.private) associated with the Wi-Fi address -(e.g. 192.168.10.225), but a reverse lookup on a machine connected -to the Wi-Fi may yield a name like new.lan (provided by the access -point) while elsewhere (e.g. on the cloister Ethernet) the IP address -will not resolve at all. (There is no "reverse mapping" to be added -to private/db.campus_vpn.) +A wireless device with no Ethernet interface and unable to run +WireGuard™ gets just a Wi-Fi address. It can be given a private +domain name (e.g. thing.small.private) associated with its Wi-Fi +address (e.g. 192.168.10.225), but a reverse lookup on a machine +connected to the Wi-Fi may yield a name like thing.lan (provided by +the access point) while elsewhere (e.g. on the cloister Ethernet) the +IP address will not resolve at all. (There is no "reverse mapping" to +be added to private/db.campus_vpn.)

    @@ -4629,7 +4641,7 @@ to private/db.campus_vpn.)

    Author: Matt Birkholz

    -

    Created: 2025-06-15 Sun 12:23

    +

    Created: 2025-06-15 Sun 19:03

    Validate

    -- 2.25.1