andreas/vanlink
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Spec: record review-driven amendments to the NM WAN design

Browse Source 
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KqhjP7nud5gdBg25zCiRk9
This commit is contained in:
andreas
2026-09-23 19:16:12 -04:00
co-authored by Claude Sonnet 5
parent 8baddceb96
commit 5c18bcdad6
1 changed files with 7 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-09-23-nm-wan-provisioning-design.md
+7
View File
@@ -125,3 +125,10 @@ has none).
- NM installation must not touch AP/LAN ports: mitigated by the install ordering and the unmanaged check. - NM installation must not touch AP/LAN ports: mitigated by the install ordering and the unmanaged check.
- Auto-installing packages changes deploy's contract: only missing required packages are installed and - Auto-installing packages changes deploy's contract: only missing required packages are installed and
a failure aborts with the apt error. a failure aborts with the apt error.
## Amendments made during implementation (review-driven; the code and tests are authoritative)
- **§3/§4 cellular profile** is written as a NetworkManager keyfile from `ap/cellular.nmconnection` (uuid derived in pure bash from the connection name), only if no connection with that id exists (keyfile scan by `id=` plus `nmcli`); `ap/nm-no-auto-default.conf` (`no-auto-default=*`) is installed before the package so NM never auto-creates DHCP "Wired connection" profiles on ports not yet handed to it.
- **§4 `--apply-network`** changes nothing under `/etc/netplan` itself. It validates (NM installed and running, `van-failover` unit present, no apply already running, last status not `running`/`rollback-failed` unless `--force`), no-ops when the netplan already matches and no Armbian file exists (unless `--force`), takes a per-run backup plus a sticky pristine backup `/var/backups/vanlink-netplan-orig`, renders to `/run`, and launches a detached transient unit. The helper installs the file, moves the Armbian file aside, applies, and gates: **stage 1** (≤60 s): apply succeeded, NM device state `100 (connected)` with a `netplan-*` connection, IPv4 address, gateway (`IP4.GATEWAY`, else the DHCP lease's `routers` option, because a never-default profile leaves `IP4.GATEWAY` empty) reachable on-link; **stage 2**: restart `van-failover`, then default route + `ping 1.1.1.1` (≥120 s). Failure → checked rollback (restore, re-apply, connectivity re-check, `ROLLBACK FAILED` if not restored; a last-resort reboot only when the rollback itself failed). Timeouts, a TERM/INT/HUP trap that restores exactly once, budgets derived in one block, log `/var/log/vanlink-apply-network.log`, status file `/var/lib/vanlink/apply-network.status` (`running|ok|rolled-back|rollback-failed <ts> …`). Not built: a boot-time recovery unit (power loss mid-apply boots the new config ungated and leaves status `running`), an arping fallback for gateways that do not answer ICMP.
- **§6 post-check**: the failover-state rule is refined: `present` in `van-failover`'s state means "has an active NM connection", so an unplugged or out-of-range uplink is normal in a van. Post-check warns only when the WAN's device has link (`carrier` 1) but `present` is false; it also reports the last `--apply-network` status (non-`ok` warns) and checks NM/ModemManager, NM-unmanaged AP/LAN ports, the cellular profile and the netplan state.
- Routine deploys also install missing REQUIRED packages via apt (spec §2) and never touch `/etc/netplan`.