Docs: shared checkout model, /etc/vanlink.conf references

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqhjP7nud5gdBg25zCiRk9
2026-09-23 14:39:22 -04:00
parent 3d117e714c
commit a39fd5a654
8 changed files with 21 additions and 17 deletions
@@ -1,10 +1,12 @@
 # vanlink — campervan router on `wayback`

-> **This clone = the Pi 4 port (host `wan`, branch `wan`).** Onboard `eth0`+`wlan0` are
-> NM-managed WANs (netplan `ap/50-van-wan.yaml`); the AP radios + wired LAN port arrive
-> with the USB hub from wayback (same MAC-derived names, so all configs port verbatim).
-> Dropped here: HA VM, battery/lid (no hardware), heartbeat + ZeroTier (not installed yet).
-> Watchdog is 10s (bcm2835 max 15s); thermal watches `cpu_thermal`.
+> **One checkout, several hosts.** The Pi 5 (`wan`, 10.42.0.1) and the FriendlyElec R5C
+> (`van`, 10.42.1.1) run from this same repo and branch. Everything host-specific
+> (interface names, addressing, which optional services run) lives in
+> `hosts/<hostname>.conf`; `/etc/vanlink.conf` is a symlink to it:
+> `sudo ln -sfn "$PWD/hosts/$(hostname -s).conf" /etc/vanlink.conf`.
+> Edit that file (and commit it), not the individual configs. Before a deploy:
+> `./deploy.sh --check` and `./deploy.sh --diff`. Static checks: `tests/check-templates.sh`.

 Turns **wayback** (Asus ZenBook UX391U, Ubuntu 24.04, zabbly kernel) into a self-contained
 campervan hub/router/AP:
@@ -10,7 +10,7 @@ network:
  version: 2
  ethernets:
    # Starlink dish uplink (RTL8153 USB NIC, MAC-named — travels with the
-    # adapter, see STARLINK_IFACE in deploy.conf). The /32 link route keeps the
+    # adapter, see STARLINK_IFACE in /etc/vanlink.conf). The /32 link route keeps the
    # dish's management address reachable no matter which WAN holds the
    # default route: the dish answers on 192.168.100.1 (gRPC :9200) even while
    # the uplink sits behind CGNAT.
@@ -1,4 +1,4 @@
-# Fixed upstream resolvers for this router — see deploy.conf's DNS_RESOLVERS.
+# Fixed upstream resolvers for this router — see /etc/vanlink.conf's DNS_RESOLVERS.
 # Never the WAN-provided ones: the failover/60-van-wan-dns NM dispatcher
 # strips each WAN's DHCP/RA-provided DNS from resolved as soon as it appears
 # (NM's own ipv4/ipv6.ignore-auto-dns can't be set as a config-file default —
@@ -1,5 +1,5 @@
 [Unit]
-Description=VanLink 2.4GHz AP (hostapd on @WIFI_2G_IFACE@ — see deploy.conf for current hardware)
+Description=VanLink 2.4GHz AP (hostapd on @WIFI_2G_IFACE@ — see /etc/vanlink.conf for current hardware)
 # Same USB re-enumeration hazards as the 5GHz AP (see hostapd-restart.conf for the
 # full story): never stop retrying, and back off a few seconds so the USB device can
 # re-enumerate before the next attempt.
@@ -7,8 +7,8 @@
 // { superuser: "require" } which triggers Cockpit's admin (polkit) escalation.

 // AP radios (MAC-derived iface names, stable) — each runs its own hostapd unit.
-// Interface names/vendor ID below are templated from deploy.conf at deploy
-// time (see deploy.sh's render()) — edit deploy.conf, not the values here.
+// Interface names/vendor ID below are templated from /etc/vanlink.conf at deploy
+// time (see deploy.sh's render()) — edit /etc/vanlink.conf, not the values here.
 const APS = [
    { iface: "@WIFI_5G_IFACE@", unit: "hostapd",    band: "5GHz"   },
    { iface: "@WIFI_2G_IFACE@", unit: "hostapd-2g", band: "2.4GHz" },
@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
-# Deploy vanlink configs/scripts (Pi 4 "wan" port) to their system locations.
+# Deploy vanlink configs/scripts to their system locations. One checkout is
+# shared by every host; host-specific values come from /etc/vanlink.conf
+# (symlink to hosts/<hostname>.conf — see hosts/vanlink.conf.example).
 # Usage:  cd ~/vanlink && sudo ./deploy.sh
-#         sudo ./deploy.sh render <file>   # preview a templated file on stdout
-#         ./deploy.sh --check [conf]        # validate conf + render all templates (no root)
-#         ./deploy.sh --templates           # list templated files
+#         ./deploy.sh --check [conf]       # validate conf + render all templates, no install
+#         ./deploy.sh --diff [conf]        # what would change in /etc
+#         ./deploy.sh render <file>        # preview a templated file on stdout
 # Idempotent. Netplan (wlan0 + Starlink NIC = NM-managed WANs; eth0 is a LAN
 # port on br0) is NOT deployed here — reference copy in ap/50-van-wan.yaml,
 # applied once manually (apply flaps uplinks). We do check it for drift below.
@@ -252,7 +254,7 @@ echo "== dns =="
 # Disable systemd-resolved DNS listener — dnsmasq handles DNS+DHCP on bridge.
 # Even localhost-only listening blocks dnsmasq from binding to port 53.
 install -D -m0644 ap/systemd-resolved-disable.conf /etc/systemd/system/systemd-resolved.service.d/disable.conf
-# Fixed upstream resolvers (deploy.conf's DNS_RESOLVERS), never a WAN's own
+# Fixed upstream resolvers (/etc/vanlink.conf's DNS_RESOLVERS), never a WAN's own
 # DHCP/RA-provided DNS — see the files themselves for the full rationale.
 # (NM's ipv4/ipv6.ignore-auto-dns can't be set as a config-file connection
 # default — NM rejects it there — so 60-van-wan-dns enforces this directly
@@ -3,7 +3,7 @@
 and keep mDNS scoped to the van's own LAN (never a WAN).

 This router only resolves via the fixed servers in
-/etc/systemd/resolved.conf.d/99-van-router-dns.conf (deploy.conf's
+/etc/systemd/resolved.conf.d/99-van-router-dns.conf (/etc/vanlink.conf's
 DNS_RESOLVERS) — never whatever a WAN happens to hand out (Wapana, a
 campsite AP, Starlink, cellular). NetworkManager's own ipv4/ipv6.ignore-auto-
 dns can't be set as a config-file connection default: NM rejects it there
@@ -18,7 +18,7 @@ Pushover credentials shared with van-battery/van-thermal/van-nvme-watch
 state.json (same convention as the other watchdogs). Stdlib only.

 Usage: van-modem-watch [modem-usb-vendor]
-Defaults to 2c7c (Quectel) — see deploy.conf.
+Defaults to 2c7c (Quectel) — see /etc/vanlink.conf.
 """

 import json