"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
-<!-- 2025-06-15 Sun 12:23 -->
+<!-- 2025-06-15 Sun 19:03 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Birchwood Abbey Networks</title>
the <code>abbey-</code> prefix on their names. These roles are applied <i>after</i>
the generic institutional roles (again, documented <a href="Institute/README.html">here</a>).
</p>
-<div id="outline-container-org572973d" class="outline-2">
-<h2 id="org572973d"><span class="section-number-2">1.</span> Overview</h2>
+<div id="outline-container-orga6df532" class="outline-2">
+<h2 id="orga6df532"><span class="section-number-2">1.</span> Overview</h2>
<div class="outline-text-2" id="text-1">
<p>
A Small Institute makes security and privacy top priorities but
philosophy, attitude.
</p>
-<pre class="example" id="org48a6e31">
+<pre class="example" id="org7d85411">
|
=
_|||_
</pre>
</div>
</div>
-<div id="outline-container-org9011e2c" class="outline-2">
-<h2 id="org9011e2c"><span class="section-number-2">2.</span> The Abbey Particulars</h2>
+<div id="outline-container-org79594b3" class="outline-2">
+<h2 id="org79594b3"><span class="section-number-2">2.</span> The Abbey Particulars</h2>
<div class="outline-text-2" id="text-2">
<p>
The abbey's public particulars are included below. They are the
</p>
</div>
</div>
-<div id="outline-container-orgb263070" class="outline-2">
-<h2 id="orgb263070"><span class="section-number-2">3.</span> The Abbey Front Role</h2>
+<div id="outline-container-orgcc08dbd" class="outline-2">
+<h2 id="orgcc08dbd"><span class="section-number-2">3.</span> The Abbey Front Role</h2>
<div class="outline-text-2" id="text-3">
<p>
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™.
</p>
</div>
-<div id="outline-container-orgaa4481a" class="outline-3">
-<h3 id="orgaa4481a"><span class="section-number-3">3.1.</span> Install Emacs</h3>
+<div id="outline-container-orgd6430fd" class="outline-3">
+<h3 id="orgd6430fd"><span class="section-number-3">3.1.</span> Install Emacs</h3>
<div class="outline-text-3" id="text-3-1">
<p>
The monks of the abbey are masters of the staff (bo) and Emacs.
</div>
</div>
</div>
-<div id="outline-container-org67eead8" class="outline-3">
-<h3 id="org67eead8"><span class="section-number-3">3.2.</span> Configure Public Email Aliases</h3>
+<div id="outline-container-org66bcea1" class="outline-3">
+<h3 id="org66bcea1"><span class="section-number-3">3.2.</span> Configure Public Email Aliases</h3>
<div class="outline-text-3" id="text-3-2">
<p>
The abbey uses several additional email aliases. These are the public
</div>
</div>
</div>
-<div id="outline-container-orgee94368" class="outline-3">
-<h3 id="orgee94368"><span class="section-number-3">3.3.</span> Configure Git Daemon on Front</h3>
+<div id="outline-container-orgeda97e9" class="outline-3">
+<h3 id="orgeda97e9"><span class="section-number-3">3.3.</span> Configure Git Daemon on Front</h3>
<div class="outline-text-3" id="text-3-3">
<p>
The abbey publishes member Git repositories with <code>git-daemon</code>. If
</div>
<div class="org-src-container">
-<code>git-tasks</code><pre class="src src-conf" id="orgd72056f"><code>- name: Install git daemon.
+<code>git-tasks</code><pre class="src src-conf" id="org9fbb6b9"><code>- name: Install git daemon.
become: yes
<span class="org-variable-name">apt: pkg</span>=git-daemon-sysvinit
</div>
<div class="org-src-container">
-<code>git-handlers</code><pre class="src src-conf" id="org3f5fdbc"><code>
+<code>git-handlers</code><pre class="src src-conf" id="org5bfdb88"><code>
- name: Restart git daemon.
become: yes
command: systemctl restart git-daemon
</div>
</div>
</div>
-<div id="outline-container-orgf576d82" class="outline-3">
-<h3 id="orgf576d82"><span class="section-number-3">3.4.</span> Configure Gitweb on Front</h3>
+<div id="outline-container-orgd473c7b" class="outline-3">
+<h3 id="orgd473c7b"><span class="section-number-3">3.4.</span> Configure Gitweb on Front</h3>
<div class="outline-text-3" id="text-3-4">
<p>
The abbey provides an HTML interface to members' public Git
</p>
<div class="org-src-container">
-<code>apache-gitweb</code><pre class="src src-conf" id="orgfb77e61"><code>
+<code>apache-gitweb</code><pre class="src src-conf" id="orgba5d06a"><code>
Alias /gitweb-static/ /usr/share/gitweb/static/
<Directory <span class="org-string">"/usr/share/gitweb/static/"</span>>
Options MultiViews
</p>
<div class="org-src-container">
-<code>apache-gitweb-tasks</code><pre class="src src-conf" id="orgeda377f"><code>- name: Enable Apache2 rewrite module for Gitweb.
+<code>apache-gitweb-tasks</code><pre class="src src-conf" id="orgb0b9652"><code>- name: Enable Apache2 rewrite module for Gitweb.
become: yes
<span class="org-variable-name">apache2_module: name</span>=rewrite
notify: Restart Apache2.
</div>
<div class="org-src-container">
-<code>apache-gitweb-handlers</code><pre class="src src-conf" id="org8e422a2"><code>- name: Restart Apache2.
+<code>apache-gitweb-handlers</code><pre class="src src-conf" id="orgaa60cf9"><code>- name: Restart Apache2.
become: yes
systemd:
service: apache2
</div>
</div>
</div>
-<div id="outline-container-org62d9e6f" class="outline-3">
-<h3 id="org62d9e6f"><span class="section-number-3">3.5.</span> Configure Apache for Abbey Documentation</h3>
+<div id="outline-container-orgedf57d5" class="outline-3">
+<h3 id="orgedf57d5"><span class="section-number-3">3.5.</span> Configure Apache for Abbey Documentation</h3>
<div class="outline-text-3" id="text-3-5">
<p>
Some of the directives added to the <q>-vhost.conf</q> file are needed by
</p>
<div class="org-src-container">
-<code>apache-abbey</code><pre class="src src-conf" id="orga762f17"><code><Directory {{ docroot }}/Abbey/>
+<code>apache-abbey</code><pre class="src src-conf" id="org9b93181"><code><Directory {{ docroot }}/Abbey/>
AllowOverride Indexes FileInfo
Options +Indexes +FollowSymLinks
</Directory>
</div>
</div>
</div>
-<div id="outline-container-orga4ac78d" class="outline-3">
-<h3 id="orga4ac78d"><span class="section-number-3">3.6.</span> Configure Photos URLs on Front</h3>
+<div id="outline-container-orgfb00830" class="outline-3">
+<h3 id="orgfb00830"><span class="section-number-3">3.6.</span> Configure Photos URLs on Front</h3>
<div class="outline-text-3" id="text-3-6">
<p>
Some of the directives added to the <q>-vhost.conf</q> file map the abbey's
</p>
<div class="org-src-container">
-<code>apache-photos</code><pre class="src src-conf" id="orgd5dc1aa"><code>
+<code>apache-photos</code><pre class="src src-conf" id="orge3ab136"><code>
RedirectMatch /Photos$ /Photos/
RedirectMatch /Photos/(20[0-9][0-9])_([0-9][0-9])_([0-9][0-9])$ \
/Photos/$1_$2_$3/
</div>
</div>
</div>
-<div id="outline-container-org87f5a8d" class="outline-3">
-<h3 id="org87f5a8d"><span class="section-number-3">3.7.</span> Configure Apache on Front</h3>
+<div id="outline-container-org68934ac" class="outline-3">
+<h3 id="org68934ac"><span class="section-number-3">3.7.</span> Configure Apache on Front</h3>
<div class="outline-text-3" id="text-3-7">
<p>
The abbey needs to add some Apache2 configuration directives to the
</p>
<p>
-The following task adds the <a href="#orga762f17"><code>apache-abbey</code></a>, <a href="#orgd5dc1aa"><code>apache-photos</code></a>, and
-<a href="#orgfb77e61"><code>apache-gitweb</code></a> directives described above to the <q>-vhost.conf</q> file,
+The following task adds the <a href="#org9b93181"><code>apache-abbey</code></a>, <a href="#orge3ab136"><code>apache-photos</code></a>, and
+<a href="#orgba5d06a"><code>apache-gitweb</code></a> directives described above to the <q>-vhost.conf</q> file,
and includes <q>options-ssl-apache.conf</q> from <q>/etc/letsencrypt/</q>. The
rest of the Let's Encrypt configuration is discussed in the following
-<a href="#org8c2a4d3">Install Let's Encrypt</a> section.
+<a href="#org53412cf">Install Let's Encrypt</a> section.
</p>
<div class="org-src-container">
</div>
</div>
</div>
-<div id="outline-container-org75c63c9" class="outline-3">
-<h3 id="org75c63c9"><span class="section-number-3">3.8.</span> Configure Apache Log Archival</h3>
+<div id="outline-container-org09125a0" class="outline-3">
+<h3 id="org09125a0"><span class="section-number-3">3.8.</span> Configure Apache Log Archival</h3>
<div class="outline-text-3" id="text-3-8">
<p>
These tasks hack Apache's <code>logrotate(8)</code> configuration to rotate
</div>
</div>
</div>
-<div id="outline-container-org8c2a4d3" class="outline-3">
-<h3 id="org8c2a4d3"><span class="section-number-3">3.9.</span> Install Let's Encrypt</h3>
+<div id="outline-container-org53412cf" class="outline-3">
+<h3 id="org53412cf"><span class="section-number-3">3.9.</span> Install Let's Encrypt</h3>
<div class="outline-text-3" id="text-3-9">
<p>
The abbey uses a Let's Encrypt certificate to authenticate its public
entered as shown below).
</p>
-<pre class="example" id="orgabcbbd1">
+<pre class="example" id="org0401ab6">
$ sudo apt install python3-certbot-apache
$ sudo certbot --apache -d birchwood-abbey.net
...
</div>
</div>
</div>
-<div id="outline-container-orgc2d4516" class="outline-3">
-<h3 id="orgc2d4516"><span class="section-number-3">3.10.</span> Rotate Let's Encrypt Log</h3>
+<div id="outline-container-org68bbd4b" class="outline-3">
+<h3 id="org68bbd4b"><span class="section-number-3">3.10.</span> Rotate Let's Encrypt Log</h3>
<div class="outline-text-3" id="text-3-10">
<p>
The following task arranges to rotate Certbot's logs files.
</div>
</div>
</div>
-<div id="outline-container-org0ca60d4" class="outline-3">
-<h3 id="org0ca60d4"><span class="section-number-3">3.11.</span> Archive Let's Encrypt Data</h3>
+<div id="outline-container-orgaee4bf6" class="outline-3">
+<h3 id="orgaee4bf6"><span class="section-number-3">3.11.</span> Archive Let's Encrypt Data</h3>
<div class="outline-text-3" id="text-3-11">
<p>
A backup copy of Let's Encrypt's data (<q>/etc/letsencrypt/</q>) is sent to
</div>
</div>
</div>
-<div id="outline-container-orgb0f7e72" class="outline-2">
-<h2 id="orgb0f7e72"><span class="section-number-2">4.</span> The Abbey Core Role</h2>
+<div id="outline-container-org8fe73e2" class="outline-2">
+<h2 id="org8fe73e2"><span class="section-number-2">4.</span> The Abbey Core Role</h2>
<div class="outline-text-2" id="text-4">
<p>
Birchwood Abbey's core is a mini-PC (System76 Meerkat) configured as A
NTP, DNS and DHCP.
</p>
</div>
-<div id="outline-container-org4788112" class="outline-3">
-<h3 id="org4788112"><span class="section-number-3">4.1.</span> Include Abbey Variables</h3>
+<div id="outline-container-orge341d62" class="outline-3">
+<h3 id="orge341d62"><span class="section-number-3">4.1.</span> Include Abbey Variables</h3>
<div class="outline-text-3" id="text-4-1">
<p>
In this abbey specific document, most abbey particulars are not
</div>
</div>
</div>
-<div id="outline-container-org3ee9d8a" class="outline-3">
-<h3 id="org3ee9d8a"><span class="section-number-3">4.2.</span> Install Additional Packages</h3>
+<div id="outline-container-org2531fd3" class="outline-3">
+<h3 id="org2531fd3"><span class="section-number-3">4.2.</span> Install Additional Packages</h3>
<div class="outline-text-3" id="text-4-2">
<p>
The scripts that maintain the abbey's web site use a number of
</div>
</div>
</div>
-<div id="outline-container-org08d805c" class="outline-3">
-<h3 id="org08d805c"><span class="section-number-3">4.3.</span> Configure Private Email Aliases</h3>
+<div id="outline-container-org8570a37" class="outline-3">
+<h3 id="org8570a37"><span class="section-number-3">4.3.</span> Configure Private Email Aliases</h3>
<div class="outline-text-3" id="text-4-3">
<p>
The abbey uses several additional email aliases. These are the campus
</div>
</div>
</div>
-<div id="outline-container-org13e1a3d" class="outline-3">
-<h3 id="org13e1a3d"><span class="section-number-3">4.4.</span> Configure Git Daemon on Core</h3>
+<div id="outline-container-org3db8645" class="outline-3">
+<h3 id="org3db8645"><span class="section-number-3">4.4.</span> Configure Git Daemon on Core</h3>
<div class="outline-text-3" id="text-4-4">
<p>
These tasks are identical to those executed on Front, for similar Git
-services on Front and Core. See <a href="#orgee94368">3.3</a> and
-<a href="#orgf576d82">Configure Gitweb on Front</a> for more information.
+services on Front and Core. See <a href="#orgeda97e9">3.3</a> and
+<a href="#orgd473c7b">Configure Gitweb on Front</a> for more information.
</p>
<div class="org-src-container">
</div>
</div>
</div>
-<div id="outline-container-orgd29bb7e" class="outline-3">
-<h3 id="orgd29bb7e"><span class="section-number-3">4.5.</span> Configure Apache on Core</h3>
+<div id="outline-container-org5d8b13e" class="outline-3">
+<h3 id="org5d8b13e"><span class="section-number-3">4.5.</span> Configure Apache on Core</h3>
<div class="outline-text-3" id="text-4-5">
<p>
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 <a href="#orga762f17"><code>apache-abbey</code></a>,
-<a href="#orgd5dc1aa"><code>apache-photos</code></a>, and <a href="#orgfb77e61"><code>apache-gitweb</code></a> used on Front.
+site on Front. Their configurations include the same <a href="#org9b93181"><code>apache-abbey</code></a>,
+<a href="#orge3ab136"><code>apache-photos</code></a>, and <a href="#orgba5d06a"><code>apache-gitweb</code></a> used on Front.
</p>
<div class="org-src-container">
</div>
</div>
</div>
-<div id="outline-container-org9349add" class="outline-3">
-<h3 id="org9349add"><span class="section-number-3">4.6.</span> Configure Documentation URLs</h3>
+<div id="outline-container-org9eb5aff" class="outline-3">
+<h3 id="org9eb5aff"><span class="section-number-3">4.6.</span> Configure Documentation URLs</h3>
<div class="outline-text-3" id="text-4-6">
<p>
The institute serves its <q>/usr/share/doc/</q> 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 <a href="#orgfb77e61">here</a>).
+directives that enable user Git publishing with Gitweb (defined <a href="#orgba5d06a">here</a>).
</p>
<div class="org-src-container">
</div>
</div>
</div>
-<div id="outline-container-orgb072ede" class="outline-3">
-<h3 id="orgb072ede"><span class="section-number-3">4.7.</span> Install Apt Cacher</h3>
+<div id="outline-container-org528d61f" class="outline-3">
+<h3 id="org528d61f"><span class="section-number-3">4.7.</span> Install Apt Cacher</h3>
<div class="outline-text-3" id="text-4-7">
<p>
The abbey uses the Apt-Cacher:TNG package cache on Core. The
</div>
</div>
</div>
-<div id="outline-container-org4846a56" class="outline-3">
-<h3 id="org4846a56"><span class="section-number-3">4.8.</span> Use Cloister Apt Cache</h3>
+<div id="outline-container-org58e2e8c" class="outline-3">
+<h3 id="org58e2e8c"><span class="section-number-3">4.8.</span> Use Cloister Apt Cache</h3>
<div class="outline-text-3" id="text-4-8">
<p>
Core itself will benefit from using the package cache, but should
</div>
</div>
</div>
-<div id="outline-container-org729dab8" class="outline-3">
-<h3 id="org729dab8"><span class="section-number-3">4.9.</span> Configure NAGIOS</h3>
+<div id="outline-container-org34a50b0" class="outline-3">
+<h3 id="org34a50b0"><span class="section-number-3">4.9.</span> Configure NAGIOS</h3>
<div class="outline-text-3" id="text-4-9">
<p>
A small institute uses <code>nagios4</code> to monitor the health of its network,
</p>
</div>
</div>
-<div id="outline-container-org5b419dc" class="outline-3">
-<h3 id="org5b419dc"><span class="section-number-3">4.10.</span> Monitoring The Home Disk</h3>
+<div id="outline-container-orgb2990be" class="outline-3">
+<h3 id="orgb2990be"><span class="section-number-3">4.10.</span> Monitoring The Home Disk</h3>
<div class="outline-text-3" id="text-4-10">
<p>
The abbey adds monitoring of the space remaining on the volume at
</div>
</div>
</div>
-<div id="outline-container-orga5d786e" class="outline-3">
-<h3 id="orga5d786e"><span class="section-number-3">4.11.</span> Custom NAGIOS Monitor <code>abbey_pisensors</code></h3>
+<div id="outline-container-orgc2b9051" class="outline-3">
+<h3 id="orgc2b9051"><span class="section-number-3">4.11.</span> Custom NAGIOS Monitor <code>abbey_pisensors</code></h3>
<div class="outline-text-3" id="text-4-11">
<p>
The <code>check_sensors</code> plugin is included in the package
</div>
</div>
</div>
-<div id="outline-container-orgbca71e2" class="outline-3">
-<h3 id="orgbca71e2"><span class="section-number-3">4.12.</span> Monitoring The Cloister</h3>
+<div id="outline-container-org642d0e3" class="outline-3">
+<h3 id="org642d0e3"><span class="section-number-3">4.12.</span> Monitoring The Cloister</h3>
<div class="outline-text-3" id="text-4-12">
<p>
The abbey adds monitoring for more servers: Kamino, Kessel, and Ord
Raspberry Pi OS (ARM64) machine, uses the <code>abbey_pisensors</code> monitor.
</p>
</div>
-<div id="outline-container-orgc4822fa" class="outline-4">
-<h4 id="orgc4822fa"><span class="section-number-4">4.12.1.</span> Cloister Network Addresses</h4>
+<div id="outline-container-org6795d73" class="outline-4">
+<h4 id="org6795d73"><span class="section-number-4">4.12.1.</span> Cloister Network Addresses</h4>
<div class="outline-text-4" id="text-4-12-1">
<p>
The IP addresses of all three hosts are nice to use in the NAGIOS
</div>
</div>
</div>
-<div id="outline-container-org3eee260" class="outline-4">
-<h4 id="org3eee260"><span class="section-number-4">4.12.2.</span> Installing NAGIOS Configurations</h4>
+<div id="outline-container-org6668a38" class="outline-4">
+<h4 id="org6668a38"><span class="section-number-4">4.12.2.</span> Installing NAGIOS Configurations</h4>
<div class="outline-text-4" id="text-4-12-2">
<p>
The following task installs each host's NAGIOS configuration. Note
</div>
</div>
</div>
-<div id="outline-container-orgac4edde" class="outline-4">
-<h4 id="orgac4edde"><span class="section-number-4">4.12.3.</span> NAGIOS Monitoring of Ord-Mantell</h4>
+<div id="outline-container-org295bf62" class="outline-4">
+<h4 id="org295bf62"><span class="section-number-4">4.12.3.</span> NAGIOS Monitoring of Ord-Mantell</h4>
<div class="outline-text-4" id="text-4-12-3">
<div class="org-src-container">
<a href="roles_t/abbey-core/templates/nagios-ord-mantell.cfg"><q>roles_t/abbey-core/templates/nagios-ord-mantell.cfg</q></a><pre class="src src-conf"><code><span class="org-type">define host</span> {
</div>
</div>
</div>
-<div id="outline-container-org1489be1" class="outline-4">
-<h4 id="org1489be1"><span class="section-number-4">4.12.4.</span> NAGIOS Monitoring of Kamino</h4>
+<div id="outline-container-org90c4b01" class="outline-4">
+<h4 id="org90c4b01"><span class="section-number-4">4.12.4.</span> NAGIOS Monitoring of Kamino</h4>
<div class="outline-text-4" id="text-4-12-4">
<div class="org-src-container">
<a href="roles_t/abbey-core/templates/nagios-kamino.cfg"><q>roles_t/abbey-core/templates/nagios-kamino.cfg</q></a><pre class="src src-conf"><code><span class="org-type">define host</span> {
</div>
</div>
</div>
-<div id="outline-container-org50e9cd8" class="outline-4">
-<h4 id="org50e9cd8"><span class="section-number-4">4.12.5.</span> NAGIOS Monitoring of Kessel</h4>
+<div id="outline-container-orga2e0dec" class="outline-4">
+<h4 id="orga2e0dec"><span class="section-number-4">4.12.5.</span> NAGIOS Monitoring of Kessel</h4>
<div class="outline-text-4" id="text-4-12-5">
<div class="org-src-container">
<a href="roles_t/abbey-core/templates/nagios-kessel.cfg"><q>roles_t/abbey-core/templates/nagios-kessel.cfg</q></a><pre class="src src-conf"><code><span class="org-type">define host</span> {
</div>
</div>
</div>
-<div id="outline-container-org71f235b" class="outline-3">
-<h3 id="org71f235b"><span class="section-number-3">4.13.</span> Install Munin</h3>
+<div id="outline-container-org1df2352" class="outline-3">
+<h3 id="org1df2352"><span class="section-number-3">4.13.</span> Install Munin</h3>
<div class="outline-text-3" id="text-4-13">
<p>
The abbey is experimenting with Munin. NAGIOS is all about notifying
</div>
</div>
</div>
-<div id="outline-container-org2566a61" class="outline-3">
-<h3 id="org2566a61"><span class="section-number-3">4.14.</span> Install Analog</h3>
+<div id="outline-container-orgda2a76d" class="outline-3">
+<h3 id="orgda2a76d"><span class="section-number-3">4.14.</span> Install Analog</h3>
<div class="outline-text-3" id="text-4-14">
<p>
The abbey's public web site's access and error logs are emailed
</div>
</div>
</div>
-<div id="outline-container-orgc06da74" class="outline-3">
-<h3 id="orgc06da74"><span class="section-number-3">4.15.</span> Add Monkey to Web Server Group</h3>
+<div id="outline-container-orge08fc0f" class="outline-3">
+<h3 id="orge08fc0f"><span class="section-number-3">4.15.</span> Add Monkey to Web Server Group</h3>
<div class="outline-text-3" id="text-4-15">
<p>
Monkey needs to be in <code>www-data</code> so that it can run
</div>
</div>
</div>
-<div id="outline-container-org6f2244e" class="outline-3">
-<h3 id="org6f2244e"><span class="section-number-3">4.16.</span> Install netpbm For Photo Processing</h3>
+<div id="outline-container-org7b13124" class="outline-3">
+<h3 id="org7b13124"><span class="section-number-3">4.16.</span> Install netpbm For Photo Processing</h3>
<div class="outline-text-3" id="text-4-16">
<p>
Monkey's photo processing scripts use <code>netpbm</code> commands like
</div>
</div>
</div>
-<div id="outline-container-org98b415a" class="outline-3">
-<h3 id="org98b415a"><span class="section-number-3">4.17.</span> Install Samba</h3>
+<div id="outline-container-org5e89497" class="outline-3">
+<h3 id="org5e89497"><span class="section-number-3">4.17.</span> Install Samba</h3>
<div class="outline-text-3" id="text-4-17">
<p>
The abbey core provides NAS (Network Attached Storage) service to the
</div>
</div>
</div>
-<div id="outline-container-org388195d" class="outline-2">
-<h2 id="org388195d"><span class="section-number-2">5.</span> The Abbey Gate Role</h2>
+<div id="outline-container-orgf05d620" class="outline-2">
+<h2 id="orgf05d620"><span class="section-number-2">5.</span> The Abbey Gate Role</h2>
<div class="outline-text-2" id="text-5">
<p>
Birchwood Abbey's gate is a $110 µPC configured as A Small Institute
chapter (yet).
</p>
</div>
-<div id="outline-container-orgf3f0dc1" class="outline-3">
-<h3 id="orgf3f0dc1"><span class="section-number-3">5.1.</span> The Abbey Gate's Network Interfaces</h3>
+<div id="outline-container-orgf1ff6da" class="outline-3">
+<h3 id="orgf1ff6da"><span class="section-number-3">5.1.</span> The Abbey Gate's Network Interfaces</h3>
<div class="outline-text-3" id="text-5-1">
<p>
The abbey gate's <code>lan</code> interface is the PC's built-in Ethernet
</p>
</div>
</div>
-<div id="outline-container-orgffd3446" class="outline-3">
-<h3 id="orgffd3446"><span class="section-number-3">5.2.</span> The Abbey's Starlink Configuration</h3>
+<div id="outline-container-orgb6abbb1" class="outline-3">
+<h3 id="orgb6abbb1"><span class="section-number-3">5.2.</span> The Abbey's Starlink Configuration</h3>
<div class="outline-text-3" id="text-5-2">
<p>
The abbey connects to Starlink via Ethernet, and disables Starlink's
</p>
</div>
</div>
-<div id="outline-container-org65cba5d" class="outline-3">
-<h3 id="org65cba5d"><span class="section-number-3">5.3.</span> Alternate ISPs</h3>
+<div id="outline-container-org6994b9d" class="outline-3">
+<h3 id="org6994b9d"><span class="section-number-3">5.3.</span> Alternate ISPs</h3>
<div class="outline-text-3" id="text-5-3">
<p>
The abbey used to use a cell phone on a USB tether to get Internet
</div>
</div>
</div>
-<div id="outline-container-orgdefe312" class="outline-2">
-<h2 id="orgdefe312"><span class="section-number-2">6.</span> The Abbey Cloister Role</h2>
+<div id="outline-container-org77dc2b3" class="outline-2">
+<h2 id="org77dc2b3"><span class="section-number-2">6.</span> The Abbey Cloister Role</h2>
<div class="outline-text-2" id="text-6">
<p>
Birchwood Abbey's cloister is a small institute campus. The <code>campus</code>
<p>
Wireless clients are issued keys for the cloister VPN by the <code>./abbey
client</code> command which is currently identical to the <code>./inst client</code>
-command (described in <a href="Institute/README.html#org69b4800">The Client Command</a>). The wireless, cloistered
+command (described in <a href="Institute/README.html#orgd063a1d">The Client Command</a>). The wireless, cloistered
hosts never roam, are not associated with a member, and so are
"campus" clients, issued keys with commands like this:
</p>
./abbey client campus new-host-name
</pre>
</div>
-<div id="outline-container-org17cd12a" class="outline-3">
-<h3 id="org17cd12a"><span class="section-number-3">6.1.</span> Use Cloister Apt Cache</h3>
+<div id="outline-container-org77767d4" class="outline-3">
+<h3 id="org77767d4"><span class="section-number-3">6.1.</span> Use Cloister Apt Cache</h3>
<div class="outline-text-3" id="text-6-1">
<p>
The Apt-Cacher:TNG program does not work well on the frontier, so is
</div>
</div>
</div>
-<div id="outline-container-org27931e7" class="outline-3">
-<h3 id="org27931e7"><span class="section-number-3">6.2.</span> Configure Cloister NRPE</h3>
+<div id="outline-container-org7df80e3" class="outline-3">
+<h3 id="org7df80e3"><span class="section-number-3">6.2.</span> Configure Cloister NRPE</h3>
<div class="outline-text-3" id="text-6-2">
<p>
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 <code>inst_sensors</code> monitor (described in <a href="Institute/README.html#orgc703c4f">Configure
+server) with a custom <code>inst_sensors</code> monitor (described in <a href="Institute/README.html#org83a4801">Configure
NRPE</a> of <a href="Institute/README.html">A Small Institute</a>). The abbey adds one complication: yet
another <code>check_sensors</code> variant, <code>abbey_pisensors</code>, installed on
Raspberry Pis (architecture <code>aarch64</code>) only.
</div>
</div>
</div>
-<div id="outline-container-orgf92da1d" class="outline-3">
-<h3 id="orgf92da1d"><span class="section-number-3">6.3.</span> Install Munin Node</h3>
+<div id="outline-container-org76e6ceb" class="outline-3">
+<h3 id="org76e6ceb"><span class="section-number-3">6.3.</span> Install Munin Node</h3>
<div class="outline-text-3" id="text-6-3">
<p>
Each cloistered host is a Munin node.
</div>
</div>
</div>
-<div id="outline-container-org06ae4ae" class="outline-3">
-<h3 id="org06ae4ae"><span class="section-number-3">6.4.</span> Install Emacs</h3>
+<div id="outline-container-org63c8ca2" class="outline-3">
+<h3 id="org63c8ca2"><span class="section-number-3">6.4.</span> Install Emacs</h3>
<div class="outline-text-3" id="text-6-4">
<p>
The monks of the abbey are masters of the staff and Emacs.
</div>
</div>
</div>
-<div id="outline-container-orgaca0216" class="outline-2">
-<h2 id="orgaca0216"><span class="section-number-2">7.</span> The Abbey Weather Role</h2>
+<div id="outline-container-org00bce0a" class="outline-2">
+<h2 id="org00bce0a"><span class="section-number-2">7.</span> The Abbey Weather Role</h2>
<div class="outline-text-2" id="text-7">
<p>
Birchwood Abbey now uses Home Assistant to record and display weather
</p>
</div>
</div>
-<div id="outline-container-orge1246d0" class="outline-2">
-<h2 id="orge1246d0"><span class="section-number-2">8.</span> The Abbey DVR Role</h2>
+<div id="outline-container-org0863125" class="outline-2">
+<h2 id="org0863125"><span class="section-number-2">8.</span> The Abbey DVR Role</h2>
<div class="outline-text-2" id="text-8">
<p>
The abbey uses AgentDVR to record video from PoE IP HD security
cameras. It is installed and configured as described here.
</p>
</div>
-<div id="outline-container-orgc5ec7d0" class="outline-3">
-<h3 id="orgc5ec7d0"><span class="section-number-3">8.1.</span> AgentDVR Installation</h3>
+<div id="outline-container-orgc100380" class="outline-3">
+<h3 id="orgc100380"><span class="section-number-3">8.1.</span> AgentDVR Installation</h3>
<div class="outline-text-3" id="text-8-1">
<p>
AgentDVR is installed at the abbey according to the iSpy web site's
preparations.
</p>
</div>
-<div id="outline-container-org2ec288c" class="outline-4">
-<h4 id="org2ec288c"><span class="section-number-4">8.1.1.</span> AgentDVR Installation Preparation</h4>
+<div id="outline-container-org8d95cf0" class="outline-4">
+<h4 id="org8d95cf0"><span class="section-number-4">8.1.1.</span> AgentDVR Installation Preparation</h4>
<div class="outline-text-4" id="text-8-1-1">
<p>
AgentDVR runs in the abbey as a system user, <code>agentdvr</code>, which
</div>
</div>
</div>
-<div id="outline-container-org12e3f20" class="outline-4">
-<h4 id="org12e3f20"><span class="section-number-4">8.1.2.</span> AgentDVR Installation Execution</h4>
+<div id="outline-container-org85f33a0" class="outline-4">
+<h4 id="org85f33a0"><span class="section-number-4">8.1.2.</span> AgentDVR Installation Execution</h4>
<div class="outline-text-4" id="text-8-1-2">
<p>
With the above preparations, the system administrator can get a shell
</p>
</div>
</div>
-<div id="outline-container-orgf4f9004" class="outline-4">
-<h4 id="orgf4f9004"><span class="section-number-4">8.1.3.</span> AgentDVR Installation Completion</h4>
+<div id="outline-container-org710e104" class="outline-4">
+<h4 id="org710e104"><span class="section-number-4">8.1.3.</span> AgentDVR Installation Completion</h4>
<div class="outline-text-4" id="text-8-1-3">
<p>
When Ansible is run a second time, after the installation script, it
</div>
</div>
</div>
-<div id="outline-container-org2cc9a8b" class="outline-3">
-<h3 id="org2cc9a8b"><span class="section-number-3">8.2.</span> Create User <code>agentdvr</code></h3>
+<div id="outline-container-org79332d5" class="outline-3">
+<h3 id="org79332d5"><span class="section-number-3">8.2.</span> Create User <code>agentdvr</code></h3>
<div class="outline-text-3" id="text-8-2">
<p>
AgentDVR runs as the system user <code>agentdvr</code>, which is created here.
</div>
</div>
</div>
-<div id="outline-container-orgd2e6785" class="outline-3">
-<h3 id="orgd2e6785"><span class="section-number-3">8.3.</span> Test For <q>AgentDVR/</q></h3>
+<div id="outline-container-orgee91eeb" class="outline-3">
+<h3 id="orgee91eeb"><span class="section-number-3">8.3.</span> Test For <q>AgentDVR/</q></h3>
<div class="outline-text-3" id="text-8-3">
<p>
The following task probes for the <q>/home/agentdvr/AgentDVR/</q>
</div>
</div>
</div>
-<div id="outline-container-orga6be551" class="outline-3">
-<h3 id="orga6be551"><span class="section-number-3">8.4.</span> Create AgentDVR Service</h3>
+<div id="outline-container-org167a4f4" class="outline-3">
+<h3 id="org167a4f4"><span class="section-number-3">8.4.</span> Create AgentDVR Service</h3>
<div class="outline-text-3" id="text-8-4">
<p>
This service definition came from the template downloaded (from <a href="https://raw.githubusercontent.com/ispysoftware/agent-install-scripts/main/v2/AgentDVR.service">here</a>)
</div>
</div>
</div>
-<div id="outline-container-orgcf2202c" class="outline-3">
-<h3 id="orgcf2202c"><span class="section-number-3">8.5.</span> Create AgentDVR Storage</h3>
+<div id="outline-container-orga2a3821" class="outline-3">
+<h3 id="orga2a3821"><span class="section-number-3">8.5.</span> Create AgentDVR Storage</h3>
<div class="outline-text-3" id="text-8-5">
<p>
The abbey uses a separate volume to store surveillance recordings,
</div>
</div>
</div>
-<div id="outline-container-org80a6047" class="outline-3">
-<h3 id="org80a6047"><span class="section-number-3">8.6.</span> Configure IP Cameras</h3>
+<div id="outline-container-orgaf6ac6d" class="outline-3">
+<h3 id="orgaf6ac6d"><span class="section-number-3">8.6.</span> Configure IP Cameras</h3>
<div class="outline-text-3" id="text-8-6">
<p>
-A new security camera is setup as described in <a href="#org88d6181">Cloistering</a>, after
+A new security camera is setup as described in <a href="#orge54fc33">Cloistering</a>, after
which the camera should be accessible by name on the abbey networks.
Assuming <code>ping -c1 new</code> works, the camera's web interface will be
accessible at <code>http://new/</code>.
</ul>
</div>
</div>
-<div id="outline-container-org474043a" class="outline-3">
-<h3 id="org474043a"><span class="section-number-3">8.7.</span> Configure AgentDVR's Cameras</h3>
+<div id="outline-container-org53206ec" class="outline-3">
+<h3 id="org53206ec"><span class="section-number-3">8.7.</span> Configure AgentDVR's Cameras</h3>
<div class="outline-text-3" id="text-8-7">
<p>
After Ansible has configured and started the AgentDVR service, its web
</p>
</div>
</div>
-<div id="outline-container-org460798c" class="outline-3">
-<h3 id="org460798c"><span class="section-number-3">8.8.</span> Configure AgentDVR's Default Storage</h3>
+<div id="outline-container-org7115391" class="outline-3">
+<h3 id="org7115391"><span class="section-number-3">8.8.</span> Configure AgentDVR's Default Storage</h3>
<div class="outline-text-3" id="text-8-8">
<p>
AgentDVR's web interface is also used to configure a default storage
</p>
</div>
</div>
-<div id="outline-container-org3704d8a" class="outline-3">
-<h3 id="org3704d8a"><span class="section-number-3">8.9.</span> Configure AgentDVR's Recordings</h3>
+<div id="outline-container-orgf7d79ab" class="outline-3">
+<h3 id="orgf7d79ab"><span class="section-number-3">8.9.</span> Configure AgentDVR's Recordings</h3>
<div class="outline-text-3" id="text-8-9">
<p>
After a default storage location has been configured, AgentDVR's
</div>
</div>
</div>
-<div id="outline-container-org8fcc7d5" class="outline-2">
-<h2 id="org8fcc7d5"><span class="section-number-2">9.</span> The Abbey TVR Role</h2>
+<div id="outline-container-orga2af172" class="outline-2">
+<h2 id="orga2af172"><span class="section-number-2">9.</span> The Abbey TVR Role</h2>
<div class="outline-text-2" id="text-9">
<p>
The abbey has a few TV tuners and a subscription to <a href="https://schedulesdirect.org/">Schedules Direct</a>
to serve MythWeb pages at e.g. <code>http://new/mythweb/</code>.
</p>
</div>
-<div id="outline-container-org30eba25" class="outline-3">
-<h3 id="org30eba25"><span class="section-number-3">9.1.</span> Building MythTV and MythWeb</h3>
+<div id="outline-container-org2fb4ef8" class="outline-3">
+<h3 id="org2fb4ef8"><span class="section-number-3">9.1.</span> Building MythTV and MythWeb</h3>
<div class="outline-text-3" id="text-9-1">
<p>
Neither Debian nor the MythTV project provide binary packages of
</p>
</div>
</div>
-<div id="outline-container-org8043294" class="outline-3">
-<h3 id="org8043294"><span class="section-number-3">9.2.</span> TVR Machine Setup</h3>
+<div id="outline-container-org726b88a" class="outline-3">
+<h3 id="org726b88a"><span class="section-number-3">9.2.</span> TVR Machine Setup</h3>
<div class="outline-text-3" id="text-9-2">
<p>
-A new TVR machine needs only <a href="#org88d6181">Cloistering</a> to prepare it for
+A new TVR machine needs only <a href="#orge54fc33">Cloistering</a> to prepare it for
Ansible. As part of that process, it should be added to the <code>tvrs</code>
group in the <q>hosts</q> file. An existing server can become a TVR
machine simply by adding it to the <code>tvrs</code> group.
</p>
</div>
</div>
-<div id="outline-container-org8e63c41" class="outline-3">
-<h3 id="org8e63c41"><span class="section-number-3">9.3.</span> Include Abbey Variables</h3>
+<div id="outline-container-orgc39c4ca" class="outline-3">
+<h3 id="orgc39c4ca"><span class="section-number-3">9.3.</span> Include Abbey Variables</h3>
<div class="outline-text-3" id="text-9-3">
<p>
Private variables in <q>private/vars-abbey.yml</q> are needed, as in the
</div>
</div>
</div>
-<div id="outline-container-org696097f" class="outline-3">
-<h3 id="org696097f"><span class="section-number-3">9.4.</span> Install MythTV Build Requisites</h3>
+<div id="outline-container-org7354ae1" class="outline-3">
+<h3 id="org7354ae1"><span class="section-number-3">9.4.</span> Install MythTV Build Requisites</h3>
<div class="outline-text-3" id="text-9-4">
<p>
A number of developer packages are needed to build MythTV. The wiki
</p>
</div>
</div>
-<div id="outline-container-org36ad0dc" class="outline-3">
-<h3 id="org36ad0dc"><span class="section-number-3">9.5.</span> Build and Install MythTV</h3>
+<div id="outline-container-orgf6b80dc" class="outline-3">
+<h3 id="orgf6b80dc"><span class="section-number-3">9.5.</span> Build and Install MythTV</h3>
<div class="outline-text-3" id="text-9-5">
<p>
After a successful "first" run of e.g. <code>./abbey config new</code>, the
</div>
</div>
</div>
-<div id="outline-container-orga786aa8" class="outline-3">
-<h3 id="orga786aa8"><span class="section-number-3">9.6.</span> Create MythTV User</h3>
+<div id="outline-container-org81a33f9" class="outline-3">
+<h3 id="org81a33f9"><span class="section-number-3">9.6.</span> Create MythTV User</h3>
<div class="outline-text-3" id="text-9-6">
<p>
MythTV Backend needs to run as its own user: <code>mythtv</code>.
</div>
</div>
</div>
-<div id="outline-container-orge24d4fe" class="outline-3">
-<h3 id="orge24d4fe"><span class="section-number-3">9.7.</span> Create MythTV DB</h3>
+<div id="outline-container-orgf93ec30" class="outline-3">
+<h3 id="orgf93ec30"><span class="section-number-3">9.7.</span> Create MythTV DB</h3>
<div class="outline-text-3" id="text-9-7">
<p>
MythTV's MariaDB database is created by the following task, when the
</p>
</div>
</div>
-<div id="outline-container-org6b18a96" class="outline-3">
-<h3 id="org6b18a96"><span class="section-number-3">9.8.</span> Create MythTV DB User</h3>
+<div id="outline-container-org7a9cd2e" class="outline-3">
+<h3 id="org7a9cd2e"><span class="section-number-3">9.8.</span> Create MythTV DB User</h3>
<div class="outline-text-3" id="text-9-8">
<p>
The DB user's password is taken from the <code>mythtv_dbpass</code> variable,
</div>
</div>
</div>
-<div id="outline-container-orgc5bb7c9" class="outline-3">
-<h3 id="orgc5bb7c9"><span class="section-number-3">9.9.</span> Manually Create MythTV DB and DB User</h3>
+<div id="outline-container-orga39e48a" class="outline-3">
+<h3 id="orga39e48a"><span class="section-number-3">9.9.</span> Manually Create MythTV DB and DB User</h3>
<div class="outline-text-3" id="text-9-9">
<p>
The MythTV database and database user are created manually with the
</div>
</div>
</div>
-<div id="outline-container-org087403a" class="outline-3">
-<h3 id="org087403a"><span class="section-number-3">9.10.</span> Load DB Timezone Info</h3>
+<div id="outline-container-org9302b33" class="outline-3">
+<h3 id="org9302b33"><span class="section-number-3">9.10.</span> Load DB Timezone Info</h3>
<div class="outline-text-3" id="text-9-10">
<p>
Starting with MythTV version 0.26, the time zone tables must be loaded
</div>
</div>
</div>
-<div id="outline-container-orge0528f2" class="outline-3">
-<h3 id="orge0528f2"><span class="section-number-3">9.11.</span> Create MythTV Backend Service</h3>
+<div id="outline-container-orgccbba96" class="outline-3">
+<h3 id="orgccbba96"><span class="section-number-3">9.11.</span> Create MythTV Backend Service</h3>
<div class="outline-text-3" id="text-9-11">
<p>
This task installs the <q>mythtv-backend.service</q> file.
</div>
</div>
</div>
-<div id="outline-container-org6b65edf" class="outline-3">
-<h3 id="org6b65edf"><span class="section-number-3">9.12.</span> Set PHP Timezone</h3>
+<div id="outline-container-org3307131" class="outline-3">
+<h3 id="org3307131"><span class="section-number-3">9.12.</span> Set PHP Timezone</h3>
<div class="outline-text-3" id="text-9-12">
<p>
This task checks PHP's timezone. If unset, MythTV's backend logs
</div>
</div>
</div>
-<div id="outline-container-org6b0a2df" class="outline-3">
-<h3 id="org6b0a2df"><span class="section-number-3">9.13.</span> Create MythTV Storage Area</h3>
+<div id="outline-container-org0d2eb5a" class="outline-3">
+<h3 id="org0d2eb5a"><span class="section-number-3">9.13.</span> Create MythTV Storage Area</h3>
<div class="outline-text-3" id="text-9-13">
<p>
The backend does not have a default storage area for its recordings.
</div>
</div>
</div>
-<div id="outline-container-org1d08b3e" class="outline-3">
-<h3 id="org1d08b3e"><span class="section-number-3">9.14.</span> Configure MythTV Backend</h3>
+<div id="outline-container-org0fba7a6" class="outline-3">
+<h3 id="org0fba7a6"><span class="section-number-3">9.14.</span> Configure MythTV Backend</h3>
<div class="outline-text-3" id="text-9-14">
<p>
With MythTV built and installed, and the post-installation tasks
</ul>
</div>
</div>
-<div id="outline-container-orgb3ca848" class="outline-3">
-<h3 id="orgb3ca848"><span class="section-number-3">9.15.</span> Configure Tuner</h3>
+<div id="outline-container-orgfe735ba" class="outline-3">
+<h3 id="orgfe735ba"><span class="section-number-3">9.15.</span> Configure Tuner</h3>
<div class="outline-text-3" id="text-9-15">
<p>
The abbey has a Silicon Dust Homerun HDTV Duo (with two tuners). It
-is setup as described in <a href="#org88d6181">Cloistering</a>, after which the tuner is
+is setup as described in <a href="#orge54fc33">Cloistering</a>, after which the tuner is
accessible by name (e.g. <code>new</code>) on the cloister network. Assuming
<code>ping -c1 new</code> works, the tuner should be accessible via the
<code>hdhomerun_config_gui</code> command, a graphical interface contributed to
</p>
</div>
</div>
-<div id="outline-container-org3b34bee" class="outline-3">
-<h3 id="org3b34bee"><span class="section-number-3">9.16.</span> Add HDHomerun and Mr.Antenna</h3>
+<div id="outline-container-org5f58bcd" class="outline-3">
+<h3 id="org5f58bcd"><span class="section-number-3">9.16.</span> Add HDHomerun and Mr.Antenna</h3>
<div class="outline-text-3" id="text-9-16">
<p>
In MythTV Setup:
</ul>
</div>
</div>
-<div id="outline-container-org9d0a8fc" class="outline-3">
-<h3 id="org9d0a8fc"><span class="section-number-3">9.17.</span> Scan for New Channels</h3>
+<div id="outline-container-org5946f99" class="outline-3">
+<h3 id="org5946f99"><span class="section-number-3">9.17.</span> Scan for New Channels</h3>
<div class="outline-text-3" id="text-9-17">
<p>
In MythTV Setup:
</ul>
</div>
</div>
-<div id="outline-container-orgb063b13" class="outline-3">
-<h3 id="orgb063b13"><span class="section-number-3">9.18.</span> Configure XMLTV</h3>
+<div id="outline-container-org47ed313" class="outline-3">
+<h3 id="org47ed313"><span class="section-number-3">9.18.</span> Configure XMLTV</h3>
<div class="outline-text-3" id="text-9-18">
<p>
The <code>xmltv</code> package, specifically its <code>tv_grab_zz_sdjson</code> program, is
the OTA (over the air) broadcasts.
</p>
-<pre class="example" id="org33f120e">
+<pre class="example" id="orgae6d63c">
$ 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]
</p>
</div>
</div>
-<div id="outline-container-orgfcebc91" class="outline-3">
-<h3 id="orgfcebc91"><span class="section-number-3">9.19.</span> Debug XMLTV</h3>
+<div id="outline-container-org8b7fe65" class="outline-3">
+<h3 id="org8b7fe65"><span class="section-number-3">9.19.</span> Debug XMLTV</h3>
<div class="outline-text-3" id="text-9-19">
<p>
If the <code>mythfilldatabase</code> command fails or expected listings do not
</div>
</div>
</div>
-<div id="outline-container-orge1023bb" class="outline-3">
-<h3 id="orge1023bb"><span class="section-number-3">9.20.</span> Configure MythTV Backend Logging</h3>
+<div id="outline-container-org050202e" class="outline-3">
+<h3 id="org050202e"><span class="section-number-3">9.20.</span> Configure MythTV Backend Logging</h3>
<div class="outline-text-3" id="text-9-20">
<p>
The abbey directs MythTV log messages to <q>/var/log/mythtv.log</q> (and
</div>
</div>
</div>
-<div id="outline-container-orgf05ad64" class="outline-3">
-<h3 id="orgf05ad64"><span class="section-number-3">9.21.</span> Start MythTV Backend</h3>
+<div id="outline-container-org0a560c7" class="outline-3">
+<h3 id="org0a560c7"><span class="section-number-3">9.21.</span> Start MythTV Backend</h3>
<div class="outline-text-3" id="text-9-21">
<p>
After configuring with <code>mythtv-setup</code> as discussed above, start and
</div>
</div>
</div>
-<div id="outline-container-org00c6258" class="outline-3">
-<h3 id="org00c6258"><span class="section-number-3">9.22.</span> Install MythWeb</h3>
+<div id="outline-container-orgc93912e" class="outline-3">
+<h3 id="orgc93912e"><span class="section-number-3">9.22.</span> Install MythWeb</h3>
<div class="outline-text-3" id="text-9-22">
<p>
MythWeb, like MythTV, is installed from a Git repository. The
</div>
</div>
</div>
-<div id="outline-container-orge61fd9f" class="outline-3">
-<h3 id="orge61fd9f"><span class="section-number-3">9.23.</span> Change Broadcast Area</h3>
+<div id="outline-container-org0d2c2da" class="outline-3">
+<h3 id="org0d2c2da"><span class="section-number-3">9.23.</span> Change Broadcast Area</h3>
<div class="outline-text-3" id="text-9-23">
<p>
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 <a href="#org9d0a8fc">Scan for New Channels</a>.
+described in <a href="#org5946f99">Scan for New Channels</a>.
</p>
<p>
<p>
The program will prompt for the zip code and offer a list of "inputs"
-available in that area, as described in <a href="#orgb063b13">Configure XMLTV</a>.
+available in that area, as described in <a href="#org47ed313">Configure XMLTV</a>.
</p>
<p>
</div>
</div>
</div>
-<div id="outline-container-org2b39b3d" class="outline-2">
-<h2 id="org2b39b3d"><span class="section-number-2">10.</span> The Ansible Configuration</h2>
+<div id="outline-container-org1eb02ae" class="outline-2">
+<h2 id="org1eb02ae"><span class="section-number-2">10.</span> The Ansible Configuration</h2>
<div class="outline-text-2" id="text-10">
<p>
The abbey's Ansible configuration, like that of <a href="Institute/README.html">A Small Institute</a>, is
</p>
<p>
-NOTE: if you have not read at least the <a href="Institute/README.html#org
a8e230f">Overview</a> of <a href="Institute/README.html">A Small Institute</a>
+NOTE: if you have not read at least the <a href="Institute/README.html#org
73a9925">Overview</a> of <a href="Institute/README.html">A Small Institute</a>
you are lost.
</p>
<q>README.org</q>, and <a href="Institute/README.html"><q>Institute/README.org</q></a>.
</p>
</div>
-<div id="outline-container-org5569675" class="outline-3">
-<h3 id="org5569675"><span class="section-number-3">10.1.</span> <q>ansible.cfg</q></h3>
+<div id="outline-container-org042b7f9" class="outline-3">
+<h3 id="org042b7f9"><span class="section-number-3">10.1.</span> <q>ansible.cfg</q></h3>
<div class="outline-text-3" id="text-10-1">
<p>
This is much like the example (test) institutional configuration file,
</div>
</div>
</div>
-<div id="outline-container-orgc44db85" class="outline-3">
-<h3 id="orgc44db85"><span class="section-number-3">10.2.</span> <q>hosts</q></h3>
+<div id="outline-container-orgfb630f0" class="outline-3">
+<h3 id="orgfb630f0"><span class="section-number-3">10.2.</span> <q>hosts</q></h3>
<div class="outline-text-3" id="text-10-2">
<div class="org-src-container">
-<a href="hosts"><q>hosts</q></a><pre class="src src-conf" id="org44e6e39"><code>all:
+<a href="hosts"><q>hosts</q></a><pre class="src src-conf" id="org1112b46"><code>all:
vars:
ansible_user: sysadm
ansible_ssh_extra_args: -i Secret/ssh_admin/id_rsa
</div>
</div>
</div>
-<div id="outline-container-orge16edaa" class="outline-3">
-<h3 id="orge16edaa"><span class="section-number-3">10.3.</span> <q>playbooks/site.yml</q></h3>
+<div id="outline-container-org28351e5" class="outline-3">
+<h3 id="org28351e5"><span class="section-number-3">10.3.</span> <q>playbooks/site.yml</q></h3>
<div class="outline-text-3" id="text-10-3">
<p>
This playbook provisions the entire network by applying first the
</div>
</div>
</div>
-<div id="outline-container-orgadc026a" class="outline-2">
-<h2 id="orgadc026a"><span class="section-number-2">11.</span> The Abbey Commands</h2>
+<div id="outline-container-orgc01ecf2" class="outline-2">
+<h2 id="orgc01ecf2"><span class="section-number-2">11.</span> The Abbey Commands</h2>
<div class="outline-text-2" id="text-11">
<p>
The <code>./abbey</code> script encodes the abbey's canonical procedures. It
-includes <a href="Institute/README.html#org1eb4766">The Institute Commands</a> and adds a few abbey-specific
+includes <a href="Institute/README.html#org2c02c67">The Institute Commands</a> and adds a few abbey-specific
sub-commands.
</p>
</div>
-<div id="outline-container-orgcd5a4c6" class="outline-3">
-<h3 id="orgcd5a4c6"><span class="section-number-3">11.1.</span> Abbey Command Overview</h3>
+<div id="outline-container-org7231e49" class="outline-3">
+<h3 id="org7231e49"><span class="section-number-3">11.1.</span> Abbey Command Overview</h3>
<div class="outline-text-3" id="text-11-1">
<p>
Institutional sub-commands:
<dt>new</dt><dd>Create system accounts for a new member.</dd>
<dt>old</dt><dd>Disable system accounts for a former member.</dd>
<dt>pass</dt><dd>Set the password of a current member.</dd>
-<dt>client</dt><dd>Produce an OpenVPN configuration (<q>.ovpn</q>) file for a
-member's device.</dd>
+<dt>client</dt><dd>Register WireGuard™ public keys for a member's device.</dd>
</dl>
<p>
</dl>
</div>
</div>
-<div id="outline-container-orgfdb7b6a" class="outline-3">
-<h3 id="orgfdb7b6a"><span class="section-number-3">11.2.</span> Abbey Command Script</h3>
+<div id="outline-container-orgfeedee0" class="outline-3">
+<h3 id="orgfeedee0"><span class="section-number-3">11.2.</span> Abbey Command Script</h3>
<div class="outline-text-3" id="text-11-2">
<p>
The script begins with the following prefix and trampolines.
The small institute's <code>./inst</code> command expects to be running in
<q>Institute/</q>, not <q>./</q>, but it only references <q>public/</q>, <q>private/</q>,
<q>Secret/</q> and <q>playbooks/check-inst-vars.yml</q>, and will find the abbey
-specific versions of these. The <code>roles_path</code> setting in <a href="#org5569675"><q>ansible.cfg</q></a>
+specific versions of these. The <code>roles_path</code> setting in <a href="#org042b7f9"><q>ansible.cfg</q></a>
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 <q>private/</q>
</div>
</div>
</div>
-<div id="outline-container-orgb5c508c" class="outline-3">
-<h3 id="orgb5c508c"><span class="section-number-3">11.3.</span> The Upgrade Command</h3>
+<div id="outline-container-org1a5942a" class="outline-3">
+<h3 id="org1a5942a"><span class="section-number-3">11.3.</span> The Upgrade Command</h3>
<div class="outline-text-3" id="text-11-3">
<p>
The script implements an <code>upgrade</code> sub-command that runs <code>apt update</code>
</div>
</div>
</div>
-<div id="outline-container-org8de3186" class="outline-3">
-<h3 id="org8de3186"><span class="section-number-3">11.4.</span> The Reboots Command</h3>
+<div id="outline-container-orgd3554de" class="outline-3">
+<h3 id="orgd3554de"><span class="section-number-3">11.4.</span> The Reboots Command</h3>
<div class="outline-text-3" id="text-11-4">
<p>
The script implements a <code>reboots</code> sub-command that looks for
</div>
</div>
</div>
-<div id="outline-container-org772adc2" class="outline-3">
-<h3 id="org772adc2"><span class="section-number-3">11.5.</span> The Versions Command</h3>
+<div id="outline-container-org383f1a9" class="outline-3">
+<h3 id="org383f1a9"><span class="section-number-3">11.5.</span> The Versions Command</h3>
<div class="outline-text-3" id="text-11-5">
<p>
The script implements a <code>versions</code> sub-command that reports the
</div>
</div>
</div>
-<div id="outline-container-orgae2a296" class="outline-3">
-<h3 id="orgae2a296"><span class="section-number-3">11.6.</span> The TZ Command</h3>
+<div id="outline-container-org2ec6e6b" class="outline-3">
+<h3 id="org2ec6e6b"><span class="section-number-3">11.6.</span> The TZ Command</h3>
<div class="outline-text-3" id="text-11-6">
<p>
The abbey changes location almost weekly, so its timezone changes
</div>
</div>
</div>
-<div id="outline-container-org439d72d" class="outline-3">
-<h3 id="org439d72d"><span class="section-number-3">11.7.</span> Abbey Command Help</h3>
+<div id="outline-container-orge534754" class="outline-3">
+<h3 id="orge534754"><span class="section-number-3">11.7.</span> Abbey Command Help</h3>
<div class="outline-text-3" id="text-11-7">
<div class="org-src-container">
<a href="abbey"><q>abbey</q></a><pre class="src src-perl"><code><span class="org-keyword">my</span> $<span class="org-variable-name">ops</span> = <span class="org-string">"config,new,old,pass,client,upgrade,reboots,versions,tz"</span>;
</div>
</div>
</div>
-<div id="outline-container-org88d6181" class="outline-2">
-<h2 id="org88d6181"><span class="section-number-2">12.</span> Cloistering</h2>
+<div id="outline-container-orge54fc33" class="outline-2">
+<h2 id="orge54fc33"><span class="section-number-2">12.</span> Cloistering</h2>
<div class="outline-text-2" id="text-12">
<p>
This is how a new machine is brought into the cloister. The process
Ansible.
</p>
</div>
-<div id="outline-container-org98c58d7" class="outline-3">
-<h3 id="org98c58d7"><span class="section-number-3">12.1.</span> IoT Devices</h3>
+<div id="outline-container-org4d38aa1" class="outline-3">
+<h3 id="org4d38aa1"><span class="section-number-3">12.1.</span> IoT Devices</h3>
<div class="outline-text-3" id="text-12-1">
<p>
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.
</p>
</p>
<ul class="org-ul">
-<li><a href="#org1065e46">Add to Core DHCP</a></li>
-<li><a href="#org5a542f0">Create Wired Domain Name</a></li>
+<li><a href="#orgb616952">Add to Core DHCP</a></li>
+<li><a href="#org37c70cf">Create Wired Domain Name</a></li>
</ul>
<p>
</p>
<ul class="org-ul">
-<li><a href="#orgfa69e17">Create Wireless Domain Name</a></li>
+<li><a href="#orga3c3c7e">Create Wireless Domain Name</a></li>
</ul>
</div>
</div>
-<div id="outline-container-orgdff1f6c" class="outline-3">
-<h3 id="orgdff1f6c"><span class="section-number-3">12.2.</span> Raspberry Pis</h3>
+<div id="outline-container-orgeed6c08" class="outline-3">
+<h3 id="orgeed6c08"><span class="section-number-3">12.2.</span> Raspberry Pis</h3>
<div class="outline-text-3" id="text-12-2">
<p>
The abbey's Raspberry Pi runs the Raspberry Pi OS desktop off an
<li>new username: sysadm</li>
<li>new password: fubar</li>
</ul></li>
-<li><a href="#org1065e46">Add to Core DHCP</a></li>
-<li><a href="#org5a542f0">Create Wired Domain Name</a></li>
+<li><a href="#orgb616952">Add to Core DHCP</a></li>
+<li><a href="#org37c70cf">Create Wired Domain Name</a></li>
<li>Log in as <code>sysadm</code> on the console.</li>
<li>Run <code>sudo raspi-config</code> and use the following menu items.
<ul class="org-ul">
<li>I1 SSH (Enable/disable remote command line access using SSH): enable</li>
<li>A1 Expand Filesystem (Ensures that all of the SD card is available)</li>
</ul></li>
-<li><a href="#org2659b92">Update From Cloister Apt Cache</a></li>
-<li><a href="#orgbae6ece">Authorize Remote Administration</a></li>
-<li><a href="#orgdbf4f10">Configure with Ansible</a></li>
+<li><a href="#org388b5c4">Update From Cloister Apt Cache</a></li>
+<li><a href="#org941d364">Authorize Remote Administration</a></li>
+<li><a href="#orge671fd1">Configure with Ansible</a></li>
</ul>
<p>
</p>
<ul class="org-ul">
-<li><a href="#org1fcb66d">Connect to Cloister Wi-Fi</a></li>
-<li><a href="#org9228440">Connect to Cloister VPN</a></li>
-<li><a href="#orgfa69e17">Create Wireless Domain Name</a></li>
+<li><a href="#orgb16a9f2">Connect to Cloister Wi-Fi</a></li>
+<li><a href="#orgfcc55e8">Connect to Cloister VPN</a></li>
+<li><a href="#orga3c3c7e">Create Wireless Domain Name</a></li>
</ul>
</div>
</div>
-<div id="outline-container-org8e09e5a" class="outline-3">
-<h3 id="org8e09e5a"><span class="section-number-3">12.3.</span> PCs</h3>
+<div id="outline-container-org17e1c80" class="outline-3">
+<h3 id="org17e1c80"><span class="section-number-3">12.3.</span> PCs</h3>
<div class="outline-text-3" id="text-12-3">
<p>
Most of the abbey's machines, like Core and Gate, are general-purpose
<li>new username: sysadm</li>
<li>new password: fubar</li>
</ul></li>
-<li><a href="#org1065e46">Add to Core DHCP</a></li>
-<li><a href="#org5a542f0">Create Wired Domain Name</a></li>
+<li><a href="#orgb616952">Add to Core DHCP</a></li>
+<li><a href="#org37c70cf">Create Wired Domain Name</a></li>
<li>Log in as <code>sysadm</code> on the console.</li>
-<li><a href="#org2659b92">Update From Cloister Apt Cache</a></li>
+<li><a href="#org388b5c4">Update From Cloister Apt Cache</a></li>
<li><p>
Install OpenSSH. Plain Debian does not come with OpenSSH installed.
</p>
<pre class="example">
sudo apt install openssh-server
</pre></li>
-<li><a href="#orgbae6ece">Authorize Remote Administration</a></li>
-<li><a href="#orgdbf4f10">Configure with Ansible</a></li>
+<li><a href="#org941d364">Authorize Remote Administration</a></li>
+<li><a href="#orge671fd1">Configure with Ansible</a></li>
</ul>
<p>
</p>
<ul class="org-ul">
-<li><a href="#org1fcb66d">Connect to Cloister Wi-Fi</a></li>
-<li><a href="#org9228440">Connect to Cloister VPN</a></li>
-<li><a href="#orgfa69e17">Create Wireless Domain Name</a></li>
+<li><a href="#orgb16a9f2">Connect to Cloister Wi-Fi</a></li>
+<li><a href="#orgfcc55e8">Connect to Cloister VPN</a></li>
+<li><a href="#orga3c3c7e">Create Wireless Domain Name</a></li>
</ul>
</div>
</div>
-<div id="outline-container-org1065e46" class="outline-3">
-<h3 id="org1065e46"><span class="section-number-3">12.4.</span> Add to Core DHCP</h3>
+<div id="outline-container-orgb616952" class="outline-3">
+<h3 id="orgb616952"><span class="section-number-3">12.4.</span> Add to Core DHCP</h3>
<div class="outline-text-3" id="text-12-4">
<p>
When a new machine is connected to the cloister Ethernet, its MAC
</div>
</div>
</div>
-<div id="outline-container-org5a542f0" class="outline-3">
-<h3 id="org5a542f0"><span class="section-number-3">12.5.</span> Create Wired Domain Name</h3>
+<div id="outline-container-org37c70cf" class="outline-3">
+<h3 id="org37c70cf"><span class="section-number-3">12.5.</span> Create Wired Domain Name</h3>
<div class="outline-text-3" id="text-12-5">
<p>
A wired device is assigned an IP address when it is added to Core's
-DHCP configuration (as in <a href="#org1065e46">Add to Core DHCP</a>). A private domain name is
+DHCP configuration (as in <a href="#orgb616952">Add to Core DHCP</a>). 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 <code>-w</code>
suffix. Thus <code>new-w.small.private</code> would be the name of the new
</div>
</div>
</div>
-<div id="outline-container-org2659b92" class="outline-3">
-<h3 id="org2659b92"><span class="section-number-3">12.6.</span> Update From Cloister Apt Cache</h3>
+<div id="outline-container-org388b5c4" class="outline-3">
+<h3 id="org388b5c4"><span class="section-number-3">12.6.</span> Update From Cloister Apt Cache</h3>
<div class="outline-text-3" id="text-12-6">
<ul class="org-ul">
<li>Log in as <code>sysadm</code> on the console.</li>
</ul>
</div>
</div>
-<div id="outline-container-orgbae6ece" class="outline-3">
-<h3 id="orgbae6ece"><span class="section-number-3">12.7.</span> Authorize Remote Administration</h3>
+<div id="outline-container-org941d364" class="outline-3">
+<h3 id="org941d364"><span class="section-number-3">12.7.</span> Authorize Remote Administration</h3>
<div class="outline-text-3" id="text-12-7">
<p>
To remotely administer <code>new-w</code>, Ansible must be authorized to login as
</div>
</div>
</div>
-<div id="outline-container-orgdbf4f10" class="outline-3">
-<h3 id="orgdbf4f10"><span class="section-number-3">12.8.</span> Configure with Ansible</h3>
+<div id="outline-container-orge671fd1" class="outline-3">
+<h3 id="orge671fd1"><span class="section-number-3">12.8.</span> Configure with Ansible</h3>
<div class="outline-text-3" id="text-12-8">
<p>
-With remote administration authorized and tested (as in <a href="#orgbae6ece">Authorize
+With remote administration authorized and tested (as in <a href="#org941d364">Authorize
Remote Administration</a>), and the machine connected to the cloister
Ethernet, the configuration of <code>new-w</code> can be completed by Ansible.
Note that if the machine is staying on the cloister Ethernet, its
</p>
<p>
-First <code>new-w</code> is added to Ansible's inventory in <a href="#orgc44db85"><q>hosts</q></a>. A <code>new-w</code>
+First <code>new-w</code> is added to Ansible's inventory in <a href="#orgfb630f0"><q>hosts</q></a>. A <code>new-w</code>
section is added to the list of all hosts, and an empty section of the
same name is added to the list of <code>campus</code> hosts. If the machine uses
the usual privileged account name, <code>sysadm</code>, the <code>ansible_user</code> key in
</div>
</div>
</div>
-<div id="outline-container-org1fcb66d" class="outline-3">
-<h3 id="org1fcb66d"><span class="section-number-3">12.9.</span> Connect to Cloister Wi-Fi</h3>
+<div id="outline-container-orgb16a9f2" class="outline-3">
+<h3 id="orgb16a9f2"><span class="section-number-3">12.9.</span> Connect to Cloister Wi-Fi</h3>
<div class="outline-text-3" id="text-12-9">
<p>
On an IoT device, or a Debian or Android "desktop", the cloister Wi-Fi
</div>
</div>
</div>
-<div id="outline-container-org9228440" class="outline-3">
-<h3 id="org9228440"><span class="section-number-3">12.10.</span> Connect to Cloister VPN</h3>
+<div id="outline-container-orgfcc55e8" class="outline-3">
+<h3 id="orgfcc55e8"><span class="section-number-3">12.10.</span> Connect to Cloister VPN</h3>
<div class="outline-text-3" id="text-12-10">
<p>
Wireless devices (with the cloister Wi-Fi password) can get an IP
</p>
<p>
-Connections to the cloister VPN are authorized by OpenVPN
-configuration (<q>.ovpn</q>) files generated by the <code>./abbey client...</code>
-command (aka <a href="Institute/README.html#org69b4800">The Client Command</a>). These are secret files, kept
-readable only by their owners and are deleted after use. They are
-copied to new OpenVPN clients using secure (<code>ssh</code>) connections.
+Connections to the cloister VPN are authorized by the <code>./abbey
+client...</code> command (aka <a href="Institute/README.html#orgd063a1d">The Client Command</a>), 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
+<q>/etc/wireguard/private-key</q>).
</p>
</div>
-<div id="outline-container-orgbf91881" class="outline-4">
-<h4 id="orgbf91881"><span class="section-number-4">12.10.1.</span> Debian Servers</h4>
+<div id="outline-container-orgf3c5544" class="outline-4">
+<h4 id="orgf3c5544"><span class="section-number-4">12.10.1.</span> Campus Desktops and Servers</h4>
<div class="outline-text-4" id="text-12-10-1">
<p>
-Wireless Debian servers (without NetworkManager) are connected to the
-cloister VPN via the following process.
+Wireless Debian desktops (with NetworkManager) as well as servers
+(<i>without</i> 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 <code>house</code>, 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.
</p>
<ul class="org-ul">
-<li>Create a new client certificate and OpenVPN configuration for the
-new abbey server.</li>
-<li>Copy the <q>campus.ovpn</q> file to the new machine.</li>
-<li>On the new machine:</li>
-<li>Install the <code>openvpn-systemd-resolved</code> package.</li>
-<li>Copy <q>campus.ovpn</q> to <q>/etc/openvpn/cloister.conf</q>.</li>
-<li>Start the OpenVPN service.</li>
-<li>Check that the cloister VPN was connected.</li>
-<li>Logout and unplug the cloister Ethernet.</li>
-<li>Test the cloister VPN connection (and private name resolution)
-with <code>ping -c1 core</code>.</li>
-</ul>
+<li><p>
+The administrator first creates a <q>wifi</q> file like the following
+(in which the wireless network device is named <code>wlan0</code>).
+</p>
+<div class="org-src-container">
+<pre class="src src-conf"><code>auto wlan0
+iface wlan0 inet dhcp
+ wpa-ssid <span class="org-string">"Birchwood Abbey"</span>
+ wpa-psk <span class="org-string">"PASSWORD"</span>
+</code></pre>
+</div></li>
-<p>
-And these are the commands:
+<li><p>
+Then the <q>wifi</q> file is installed and the network interface
+brought up.
</p>
+<div class="org-src-container">
+<pre class="src src-sh"><code>sudo cp wifi /etc/network/interfaces.d/
+sudo ifup wlan0
+</code></pre>
+</div></li>
+<li><p>
+Next, the administrator generates a pair of WireGuard™ keys.
+</p>
<div class="org-src-container">
-<pre class="src src-sh"><code>./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
-<span class="org-keyword">logout</span>
-rm campus.ovpn
+<pre class="src src-sh"><code>sudo apt install wireguard
+wg genkey | sudo tee /etc/wireguard/private-key >/dev/null
+sudo cat /etc/wireguard/private-key | wg pubkey >server.pub
</code></pre>
-</div>
+</div></li>
-<p>
-It may be necessary to reboot before the final tests.
+<li><p>
+The client's name and public key are then registered via the
+<code>./abbey client</code> command, and the resulting details are copied to
+the client.
</p>
+<div class="org-src-container">
+<pre class="src src-sh"><code>scp sysadm@new-w:server.pub ./
+./abbey client campus new <span class="org-sh-quoted-exec">`cat server.pub`</span>
+scp campus.conf sysadm@new-w:
+</code></pre>
+</div></li>
+
+<li><p>
+The details are copied to <q>/etc/wireguard/wg0.conf</q> on the client
+and the service started.
+</p>
+<div class="org-src-container">
+<pre class="src src-sh"><code>sudo cp campus.conf /etc/wireguard/wg0.conf
+sudo systemctl start wg-quick@wg0
+systemctl status wg-quick@wg0
+</code></pre>
+</div></li>
+
+<li>The client can then be unplugged from the cloister Ethernet, and
+connect to the campus Wi-Fi (if not already).</li>
+
+<li><p>
+Finally the connection to the VPN is tested and, if OK, is
+"enabled" (to start at boot time).
+</p>
+<div class="org-src-container">
+<pre class="src src-sh"><code>ping -c1 core
+sudo wg show
+sudo systemctl enable wg-quick@wg0
+</code></pre>
+</div></li>
+</ul>
</div>
</div>
-<div id="outline-container-org3d61cc0" class="outline-4">
-<h4 id="org3d61cc0"><span class="section-number-4">12.10.2.</span> Debian Desktops</h4>
+<div id="outline-container-org447a642" class="outline-4">
+<h4 id="org447a642"><span class="section-number-4">12.10.2.</span> Private Desktops</h4>
<div class="outline-text-4" id="text-12-10-2">
<p>
-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.
</p>
<ul class="org-ul">
-<li>Create a new client certificate and OpenVPN configuration for the
-new abbey desktop, a <q>campus.ovpn</q> file.</li>
+<li>The owner of the Debian desktop machine should have already
+connected to the campus Wi-Fi using the GUI of NetworkManager.</li>
+
<li><p>
-Create a <q>wifi</q> file that looks like this (assuming the wireless
-network device is named <code>wlan0</code>).
+The owner thus begins by generating a pair of WireGuard™ keys on
+the client, sending the public key to the administrator.
</p>
+<div class="org-src-container">
+<pre class="src src-sh"><code>sudo apt install wireguard
+wg genkey | sudo tee /etc/wireguard/private-key >/dev/null
+sudo cat /etc/wireguard/private-key | wg pubkey >dick.pub
+( <span class="org-builtin">echo</span> <span class="org-string">"Subject: new client named dick"</span>
+ <span class="org-builtin">echo</span>
+ cat dick.pub ) | sendmail sysadm@small.example.org
+</code></pre>
+</div></li>
-<pre class="example">
-auto wlan0
-iface wlan0 inet dhcp
- wpa-ssid "Birchwood Abbey"
- wpa-psk "PASSWORD"
-</pre></li>
-
-<li>Copy the <q>wifi</q> and <q>campus.ovpn</q> files to the new machine.</li>
-<li>On the new machine:</li>
-<li>Install the <code>openvpn-systemd-resolved</code> package.</li>
-<li>Copy <q>wifi</q> to <q>/etc/network/interfaces.d/</q>.</li>
-<li>Bring up the Wi-Fi interface.</li>
-<li>Copy <q>campus.ovpn</q> to <q>/etc/openvpn/cloister.conf</q>.</li>
-<li>Start the OpenVPN service.</li>
-<li>Check that the cloister VPN was connected.</li>
-<li>Logout and unplug the cloister Ethernet.</li>
-<li>Test the cloister VPN connection (and private name resolution)
-with <code>ping -c1 core</code>.</li>
-</ul>
+<li><p>
+The administrator runs the <code>./abbey client</code> command and replies
+with the generated configurations.
+</p>
+<div class="org-src-container">
+<pre class="src src-sh"><code>./abbey client debian dick dick <span class="org-sh-quoted-exec">`cat dick.pub`</span>
+( <span class="org-builtin">echo</span> <span class="org-string">"Subject: dick now authorized"</span>
+ <span class="org-builtin">echo</span>
+ cat campus.conf
+ <span class="org-builtin">echo</span> --------
+ cat public.conf
+ ) | sendmail dick
+</code></pre>
+</div></li>
-<p>
-And these are the commands:
+<li><p>
+The owner saves the configuration details in <q>campus.conf</q> and
+<q>public.conf</q>, then installs them and starts the campus VPN
+service.
</p>
+<div class="org-src-container">
+<pre class="src src-sh"><code>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
+</code></pre>
+</div></li>
+<li><p>
+Finally the owner checks that the client has successfully
+connected to the campus VPN and, if it has, enables the service.
+</p>
<div class="org-src-container">
-<pre class="src src-sh"><code>./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
+<pre class="src src-sh"><code>systemctl status wg-quick@wg0
ping -c1 core
-sudo systemctl enable openvpn@cloister
-rm wifi campus.ovpn
-<span class="org-keyword">logout</span>
-rm wifi campus.ovpn
+sudo systemctl enable wg-quick@wg0
</code></pre>
-</div>
+</div></li>
+</ul>
<p>
-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.
</p>
-<p>
-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 <code>house</code>,
-i.e. anyone in the house.
-</p>
-</div>
+<div class="org-src-container">
+<pre class="src src-h"><code>sudo systemctl stop wg-quick@wg0
+sudo systemctl start wg-quick@wg1
+ping -c1 core
+</code></pre>
</div>
-<div id="outline-container-org0cc467a" class="outline-4">
-<h4 id="org0cc467a"><span class="section-number-4">12.10.3.</span> Private Desktops</h4>
-<div class="outline-text-4" id="text-12-10-3">
-<p>
-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:
-</p>
-
-<ul class="org-ul">
-<li>Create a new client certificate and OpenVPN configurations for the
-new abbey desktop, <q>campus.ovpn</q> and <q>public.ovnp</q> files.</li>
-<li>Copy the <q>campus.ovpn</q> and <q>public.ovpn</q> files to the new machine.</li>
-<li>On the new machine:</li>
-<li>Install the <code>openvpn-systemd-resolved</code> and
-<code>network-manager-openvpn-gnome</code> packages.</li>
-<li>Open the desktop Settings > Network > VPN + > Import from
-file… and choose <q>~/campus.ovpn</q>.</li>
-<li>Open the Routes dialogues for both IPv4 and IPv6 and choose
-"Use this connection only for resources on its network.".</li>
-<li>Save the new VPN.</li>
-<li>Do the same with the <q>~/public.ovpn</q> file.</li>
-<li>Connect the appropriate VPN and test it (and private name
-resolution) with <code>ping -c1 core</code>.</li>
-<li>Expunge (delete <i>and</i> empty the trash) the <q>~/campus.ovpn</q> and
-<q>~/public.ovpn</q> files.</li>
-</ul>
<p>
-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 <code>wg-quick@wg0</code> enabled. The campus VPN is re-connected if
+the machine reboots.
</p>
<p>
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 <q>.ovpn</q> files securely,
-e.g. using <code>ssh</code> to any "known host" on the Internet.
+authorized "remotely" simply by copying the <q>.conf</q> text files to the
+machine by whatever means is available.
</p>
<p>
</p>
</div>
</div>
-<div id="outline-container-org1ed2379" class="outline-4">
-<h4 id="org1ed2379"><span class="section-number-4">12.10.4.</span> Android</h4>
-<div class="outline-text-4" id="text-12-10-4">
+<div id="outline-container-orgc4584cc" class="outline-4">
+<h4 id="orgc4584cc"><span class="section-number-4">12.10.3.</span> Android</h4>
+<div class="outline-text-4" id="text-12-10-3">
<p>
-Android phones and tablets are connected to the cloister VPN via the
-following process. Note that they do not appear in the set of
-<code>campus</code> 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 <code>campus</code> hosts, are not configured by Ansible,
+and do not appear in the host inventory.
</p>
<ul class="org-ul">
-<li>Create a new client certificate and campus/public OpenVPN
-configurations for the new abbey Android.</li>
-<li>Copy the <q>campus.ovpn</q> and <q>public.ovpn</q> files to a USB drive.</li>
-<li>On the Android machine:</li>
-<li>Connect to the cloister Wi-Fi.</li>
-<li>Install <a href="https://f-droid.org">F-Droid</a> and use it to install OpenVPN.</li>
-<li>Connect the USB drive, perhaps with an OTG (On The Go) adapter,
-and open the <q>campus.ovpn</q> file. The file should be opened with
-the OpenVPN app, which will appear to ask for confirmation before
-creating the new VPN.</li>
-<li>Open the <q>public.ovpn</q> file and create a second VPN.</li>
-</ul>
+<li>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.</li>
-<p>
-The <q>.ovpn</q> files must be transferred to the Android via a secure
-medium: the <code>scp</code> 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 <code>Transfers</code>. After insertion into the Android,
-its "storage" is viewed with the Files app, which should launch
-OpenVPN when a <q>.ovpn</q> file is opened.
+<li><p>
+The administrator runs the <code>./abbey client</code> command and replies
+with the generated configurations.
</p>
-
<div class="org-src-container">
-<pre class="src src-sh"><code>./abbey client android dicks-tablet dick
-cp campus.ovpn public.ovpn /media/sysadm/Transfers/
-rm campus.ovpn public.ovpn
+<pre class="src src-sh"><code>./abbey client android dicks-razr dick <client public key>
+( <span class="org-builtin">echo</span> <span class="org-string">"Subject: dicks-razr now authorized"</span>
+ <span class="org-builtin">echo</span>
+ cat campus.conf
+ <span class="org-builtin">echo</span> --------
+ cat public.conf
+ ) | sendmail owner
</code></pre>
+</div></li>
+
+<li>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.</li>
+</ul>
</div>
</div>
</div>
-</div>
-<div id="outline-container-orgfa69e17" class="outline-3">
-<h3 id="orgfa69e17"><span class="section-number-3">12.11.</span> Create Wireless Domain Name</h3>
+<div id="outline-container-orga3c3c7e" class="outline-3">
+<h3 id="orga3c3c7e"><span class="section-number-3">12.11.</span> Create Wireless Domain Name</h3>
<div class="outline-text-3" id="text-12-11">
<p>
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 <code>ip addr show
-dev ovpn</code> on the machine, or inspecting <q>/etc/openvpn/ipp.txt</q> on
-Gate. Once discovered, a private domain name,
-e.g. <code>new.small.private</code>, can be associated with the VPN address, e.g
-<code>10.84.138.7</code>. The administrator adds a line like the following to
-<q>private/db.domain</q> 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. <code>new.small.private</code>) can be associated with that host number on
+the cloister VPN subnet, e.g <code>10.84.138.7</code>. The administrator adds a
+line like the following to <q>private/db.domain</q> and increments the
+serial number at the top of the file.
</p>
<div class="org-src-container">
</div>
<p>
-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. <code>new.small.private</code>) associated with the Wi-Fi address
-(e.g. <code>192.168.10.225</code>), but a reverse lookup on a machine connected
-to the Wi-Fi may yield a name like <code>new.lan</code> (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 <q>private/db.campus_vpn</q>.)
+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. <code>thing.small.private</code>) associated with its Wi-Fi
+address (e.g. <code>192.168.10.225</code>), but a reverse lookup on a machine
+connected to the Wi-Fi may yield a name like <code>thing.lan</code> (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 <q>private/db.campus_vpn</q>.)
</p>
</div>
</div>
</div>
<div id="postamble" class="status">
<p class="author">Author: Matt Birkholz</p>
-<p class="date">Created: 2025-06-15 Sun 12:23</p>
+<p class="date">Created: 2025-06-15 Sun 19:03</p>
<p class="validation"><a href="https://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>
projects / Network / commitdiff