Merge branch 'liw/docs' into 'main'

docs: update `install.md` to match current v-i better

See merge request larswirzenius/puomi!23

7 files changed, 73 insertions, 224 deletions

diff --git a/check b/check
index 2a2e7a7..b997ef3 100755
--- a/check
+++ b/check
@@ -5,5 +5,4 @@
 
 set -euo pipefail
 
-subplot docgen puomi.subplot -o puomi.pdf
 subplot docgen puomi.subplot -o puomi.html
diff --git a/install.md b/install.md
index 483efc6..f0dabaf 100644
--- a/install.md
+++ b/install.md
@@ -12,6 +12,7 @@ To use Puomi you need:
 * A USB drive to hold the installer image.
 * A second machine to provision the router. Below, we call it the
   "laptop", but it can be any machine.
+* Some Ethernet cables.
 
 To install, short version:
 
@@ -19,8 +20,8 @@ To install, short version:
   - v-i is a custom installer for Debian
 * Write the image to a USB drive.
 * Configure the USB drive.
+* Copy the Puomi specification file and playbook to USB drive.
 * Boot your router PC from the USB drive.
-* Copy the Puomi specification file and playbook to installer.
 * Install Puomi on the PC.
 * Boot the PC.
 
@@ -28,101 +29,108 @@ These steps will be covered in more detail below.
 
 ## Get installer image
 
-* Download the 0.2 release image and helper scripts, using any
-  download you like.
-  - <https://files.liw.fi/v-i/0.2/v-i.img.xz>
-  - <https://files.liw.fi/v-i/0.2/write-and-config.sh>
-  - <https://files.liw.fi/v-i/0.2/configure-installer>
+* Download the latest release image and helper scripts, using any
+  download tool you like.
+  - <https://files.liw.fi/v-i/>
+
 * Decompress the image.
+
   - `unxz v-i.img.xz`
-* Create an installer configuration, like the one below. Below, we
-  call it `your.yaml`. The simplest is to set one configuration key to
-  the name of your SSH public key file.
 
-~~~yaml
-authorized_keys_file: mykey.pub
-~~~
+* Create an empty installer configuration file. Below we call it
+  `your.yaml`, but you can call it anything. If you want, you can add
+  content, see [v-i documentation](https://doc.liw.fi/v-i/spec.html)
+  for details.
+
+    ~~~sh
+    touch your.yaml
+    ~~~
 
 * Insert the USB drive to a USB port, and find out the device name.
   (GNOME Disks is a good tool for this. Kernel messages will also tell
   you.) Below, we call it `/dev/sdx`.
+
 * Write the installer to the USB drive and configure it.
 
-~~~sh
-./write-and-config your.yaml /dev/sdx
-~~~
+    ~~~sh
+    ./write-and-config your.yaml /dev/sdx
+    ~~~
+
+* Create a "specification" file to describe the installation you want
+  to do. Below we call it `x220.yaml`. You can pick any host name. The
+  drive must be the drive from which the PC boots. You may want to
+  check what it is called when the installer runs: it may change when
+  the installer USB drive is plugged in.
+
+    ~~~yaml
+    drive: /dev/sda
+    hostname: x220
+    extra_playbooks:
+      - puomi-playbook.yml
+    ansible_vars:
+      user_pub: |
+        YOUR SSH PUBLIC KEY GOES HERE
+    ~~~
+
+* Copy the spec file and the Puomi initial playbook to the installer
+  drive, to `root` user home directory. The drive should still be
+  mounted after the previous steps. Run `df` to see where it is
+  mounted.
+
+    ~~~sh
+    cp x220.yaml puomi-playbook.yml /media/$USER/$SOMETHING/root/
+    ~~~
 
 * Make sure everything is written to the drive, then remove it.
 
-~~~sh
-eject /dev/sdx
-~~~
+    ~~~sh
+    udisksctl power-off -b /dev/sdx
+    ~~~
 
 * You may want to label the physical drive so you remember which one
   is the installer.
 
-## Install on your PC.
+## Install on your router PC.
 
 * Connect the router PC's main Ethernet port to your home Internet
   connection. This can be directly to the external network, or to your
   existing router.
-  - the main port is the one know to Linux as "eth0"
+
+  - the main port is the one known to Linux as `eth0`
   - you may have to boot into the installer and experiment to find out
     which one it is
-* Connect your laptop to any other Ethernet port in the router PC.
+
 * Insert the installer USB to the router PC and boot off it. This may
   involve telling your BIOS which drive to boot from. Every BIOS is
   different about this.
-* Your laptop should get an address 10.1.1.something from the router
-  DHCP. Your laptop won't be able to access the Internet, but you can
-  log into the installer. Check that you can log, then log out again.
-
-~~~sh
-ssh root@v-i
-~~~
-
-* Create a "specification" file to describe the installation you want
-  to do. Below we call it `x220.yaml`. You can pick any host name. The
-  drive must be the drive from which the PC boots. You may want to
-  check what it is called when the installer runs: it may change when
-  the installer USB drive is plugged in.
-
-~~~yaml
-drive: /dev/sda
-hostname: x220
-extra_playbooks:
-  - puomi-playbook.yml
-ansible_vars:
-  user_pub: |
-    YOUR SSH PUBLIC KEY GOES HERE
-~~~
-
-* Copy the spec file and the Puomi initial playbook to the installer.
 
-~~~sh
-scp x220.yaml puomi-playbook.yml root@v-i:
-~~~
+* Log in via the virtual console as `root` (no password required) and
+  run the installer. Note that logging in as root without a password
+  only works on the virtual console, not via SSH.
 
-* Log back into the installer, and do the install. Run the following
-  in the installer:
+    ~~~sh
+    v-i --verbose x220.yaml
+    ~~~
 
-~~~sh
-./v-i --verbose x220.yaml
-~~~
+  This may take several minutes.
 
-* Reboot.
+* Reboot the router PC. Depending on your BIOS, you may need to remove
+  the installer USB drive, but wait until the installer kernel has
+  unmounted it. To be entirely sure, power off, then remove the drive,
+  then power on again.
 
 The router PC should now boot into a Debian system that has been
-configured as an Internet router. Your laptop, still connected to the
-router, should be able to access the Internet normally. DNS should
-work just fine.
+configured as an Internet router. If you connect your laptop to the
+router (any Ethernet port except `eth0`), it should be able to access
+the Internet normally. The router provides hosts on the LAN addresses
+via DHCP.
 
 The router implements NAT, which means that your laptop won't be
 accessible directly from the public side of the router PC: any
 connections must be initiated by the laptop. There is, however, no
 firewall, unless you set it up yourself.
 
-## Configure the installer as you wish
+## Configure the router as you wish
 
 You have root. You can configure the router as you wish. The `puomi`
 Ansible role in the Puomi source tree may be useful, if Ansible is
diff --git a/puomi-installer-playbook.yml b/puomi-installer-playbook.yml
deleted file mode 100644
index eb80b5b..0000000
--- a/puomi-installer-playbook.yml
+++ /dev/null
@@ -1,126 +0,0 @@
-# Ansible playbook for installing a router.
-
-- hosts: image
-  pre_tasks:
-    - name: "add contrib and non-free to APT sources"
-      apt_repository:
-        repo: "deb http://deb.debian.org/debian bullseye contrib non-free"
-
-    - name: "install software"
-      apt:
-        name:
-          - hostapd
-          - firmware-iwlwifi
-          - haveged
-          - bridge-utils
-          - man
-          - ferm
-          - dnsmasq
-          - bind9-dnsutils
-          - locales-all
-
-    - name: "configure dnsmasq for .d support"
-      lineinfile:
-        path: /etc/dnsmasq.conf
-        regexp: ^conf-dir
-        line: "conf-dir=/etc/dnsmasq.d/,*.conf"
-
-    - name: "configure dnsmasq for router"
-      copy:
-        content: |
-          dhcp-range=10.1.1.10,10.1.1.250,255.255.255.0,1h
-          host-record=puomi,10.1.1.1
-          interface=br0
-          interface=lo
-          max-cache-ttl=30
-          neg-ttl=10
-        dest: /etc/dnsmasq.d/router.conf
-
-    - name: "configure hostapd"
-      copy:
-        content: |
-          interface=wlan0
-          bridge=br0
-          driver=nl80211
-          ssid={{ wifi_essid }}
-          country_code={{ wifi_country_code }}
-          hw_mode=g
-          ieee80211n=1
-          channel=2
-          macaddr_acl=0
-          auth_algs=1
-          ignore_broadcast_ssid=0
-          wmm_enabled=1
-          wpa=2
-          wpa_passphrase={{ wifi_passphrase }}
-          wpa_key_mgmt=WPA-PSK WPA-PSK-SHA256
-          wpa_pairwise=TKIP
-          rsn_pairwise=CCMP
-        dest: /etc/hostapd/hostapd.conf
-
-    - name: "configure ferm firewall"
-      copy:
-        content: |
-          table filter {
-              chain INPUT policy ACCEPT;
-              chain OUTPUT policy ACCEPT;
-              chain FORWARD {
-                  policy ACCEPT;
-
-                  # Printer
-                  saddr 10.0.0.73  proto tcp DROP;
-                  saddr 10.0.0.73  proto udp DROP;
-              }
-          }
-
-          table nat {
-             chain POSTROUTING MASQUERADE;
-          }
-        dest: /etc/ferm/ferm.conf
-
-    - name: "configure bridge device br0"
-      copy:
-        content: |
-          [NetDev]
-          Name=br0
-          Kind=bridge
-        dest: /etc/systemd/network/br0.netdev
-
-    - name: "add wired devices to br0"
-      copy:
-        content: |
-          [Match]
-          Name=eth[^0]*
-
-          [Network]
-          Bridge=br0
-        dest: /etc/systemd/network/wired.network
-
-    - name: "configure br0 to provide DHCP and NAT"
-      copy:
-        content: |
-          [Match]
-          Name=br0
-
-          [Network]
-          Address=10.1.1.1/24
-          DHCPServer=false
-          IPMasquerade=true
-          ConfigureWithoutCarrier=true
-        dest: /etc/systemd/network/br0.network
-
-  vars:
-    ansible_python_interpreter: /usr/bin/python3
-
-    sane_debian_system_version: 2
-    sane_debian_system_codename: bullseye
-    sane_debian_system_timezone: Europe/Helsinki
-    sane_debian_system_sources_lists:
-      - repo: |
-          deb http://deb.debian.org/debian bullseye contrib non-free
-
-    unix_users_version: 2
-
-    wifi_essid: Valkama2
-    wifi_country_code: FI
-    wifi_passphrase: Oomam2ah
diff --git a/puomi-playbook.yml b/puomi-playbook.yml
index 0e9cbc3..73b6c30 100644
--- a/puomi-playbook.yml
+++ b/puomi-playbook.yml
@@ -74,8 +74,8 @@
   vars:
     ansible_python_interpreter: /usr/bin/python3
 
-    puomi_lan_ip: 10.3.1.1
-    puomi_dhcp_start: 10.3.1.10
-    puomi_dhcp_end: 10.3.1.250
+    puomi_lan_ip: 10.1.1.1
+    puomi_dhcp_start: 10.1.1.10
+    puomi_dhcp_end: 10.1.1.250
     puomi_dhcp_netmask: 255.255.255.0
     puomi_dhcp_lease: 1h
diff --git a/puomi-qotom.yaml b/puomi-qotom.yaml
deleted file mode 100644
index 70cfe27..0000000
--- a/puomi-qotom.yaml
+++ /dev/null
@@ -1,12 +0,0 @@
-# A target specification file for v-i for Puomi on a Lenovo Thinkpad
-# X220 laptop.
-
-drive: /dev/sda
-hostname: qotom
-extra_playbooks:
-  - puomi-playbook.yml
-ansible_vars:
-  user_pub: |
-   ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPQe6lsTapAxiwhhEeE/ixuK+5N8esCsMWoekQqjtxjP liw personal systems
-ansible_vars_files:
-  - hostid.yml
diff --git a/puomi-x220.yaml b/puomi-x220.yaml
deleted file mode 100644
index 42d27e2..0000000
--- a/puomi-x220.yaml
+++ /dev/null
@@ -1,20 +0,0 @@
-# A target specification file for v-i for Puomi on a Lenovo Thinkpad
-# X220 laptop.
-
-drive: /dev/sdb
-hostname: x220
-extra_playbooks:
-  - puomi-playbook.yml
-ansible_vars:
-  user_ca_pubkey: |
-    sk-ssh-ed25519@openssh.com AAAAGnNrLXNzaC1lZDI1NTE5QG9wZW5zc2guY29tAAAAIAnrswi6ZNElxSgt6ak5hjSNIkVte11ht7BG3qpBJU4hAAAABHNzaDo= 
-  host_key: |
-    -----BEGIN OPENSSH PRIVATE KEY-----
-    b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
-    QyNTUxOQAAACBLyRiXsVpDGLYeaSrqLaQEk9xPGdpaYYln5ZzvCmtTrwAAAIja9k5L2vZO
-    SwAAAAtzc2gtZWQyNTUxOQAAACBLyRiXsVpDGLYeaSrqLaQEk9xPGdpaYYln5ZzvCmtTrw
-    AAAEDWNzJ+c1v8VHN0TezEBADgaaww2RdzHNF9pA+el40MyEvJGJexWkMYth5pKuotpAST
-    3E8Z2lphiWflnO8Ka1OvAAAAAAECAwQF
-    -----END OPENSSH PRIVATE KEY-----
-  host_cert: |
-    ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC1lZDI1NTE5LWNlcnQtdjAxQG9wZW5zc2guY29tAAAAIONCUIfScV7h4bHqDUQ4dnLwxjs22oS8TdQkZzFfVVYkAAAAIEvJGJexWkMYth5pKuotpAST3E8Z2lphiWflnO8Ka1OvAAAAAAAAAAAAAAACAAAAGWNlcnRpZmljYXRlIGZvciBob3N0IHgyMjAAAAAIAAAABHgyMjAAAAAAYxxgIAAAAABjkwdxAAAAAAAAAAAAAAAAAAAAMwAAAAtzc2gtZWQyNTUxOQAAACD7tWzrRUC8C8aZNM0tWvEBW/VJQ2zjjh9THBOYQ07ZxAAAAFMAAAALc3NoLWVkMjU1MTkAAABA1y9CkOOEoocjnaFWw4DCWrl90E5E0/s56Aoz5pCV8GocIlUCkbs9dFC2pQbubMCNw+5RnMWLoA8QJ6/uIsZ3CQ== /tmp/.tmp5sslvF/sub.pub
diff --git a/roles/puomi/defaults/main.yml b/roles/puomi/defaults/main.yml
index f6c8a77..2b0b877 100644
--- a/roles/puomi/defaults/main.yml
+++ b/roles/puomi/defaults/main.yml
@@ -1,6 +1,6 @@
-puomi_lan_ip: 10.2.2.1
-puomi_dhcp_start: 10.2.2.10
-puomi_dhcp_end: 10.2.2.250
+puomi_lan_ip: 10.1.1.1
+puomi_dhcp_start: 10.1.1.10
+puomi_dhcp_end: 10.1.1.250
 puomi_dhcp_netmask: 255.255.255.0
 puomi_dhcp_lease: 1h