From 789bbd1c8f62ac6fa0c14298caad8a239f5daab4 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sat, 11 Jul 2026 10:33:24 +0200 Subject: [PATCH] docs: REPORT + CONTEXT for the NAS verify-before-commit share (host-install v1.13.0) Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6 --- CONTEXT.md | 10 +++++++++ REPORT.md | 62 ++++++++++++++++++------------------------------------ 2 files changed, 30 insertions(+), 42 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index 2d470f2..1784461 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -3,6 +3,16 @@ > Created with the REUSE.md rollout (2026-07-03). Authoritative history: `hub/CHANGELOG.md` (hub), > `website/CHANGELOG.md`, `scripts/CHANGELOG.md`; end-of-task detail in `REPORT.md`. +- **2026-07-11 — NAS verify-before-commit SHIPPED (agent v0.81.0 + controller v0.113.0 LIVE on demo; + host-install v1.13.0).** The spike's production task landed same-day: add = agent verify (retry=0 + unit, journal-classified, auto-rollback) → controller uid-1000 write probe (--netprobe re-exec) → + register LAST; full rollback on any failure; §3.2 Hungarian error map (nfs_export merged); + storage_network.html redesigned (SMB-first, Route-A guidance); orphan rows; systemd-journal group + (NO sudoers). Live A–E validated vs an isolated sim NAS, Route A proven in production (alien-uid + 1060 server-side). Feature doc: `documentation/controller/network-storage-nas.md`. NOT published + (no Gitea/Day-0 bump; Peti pending with the usermod one-liner). Record: + `felhom-controller/REPORT.md`. + - **2026-07-11 — SPIKE: NAS verify mechanisms + NFS squash matrix — ALL FIVE QUESTIONS ANSWERED, no blocker.** Record: `documentation/audits/SPIKE-nas-verify-2026-07-11.md`. Q1 in-guest access DOES wake the host automount (make-or-break PASS; container bind-mount too); Q2 controller drops to uid diff --git a/REPORT.md b/REPORT.md index ffa753f..6a29aa7 100644 --- a/REPORT.md +++ b/REPORT.md @@ -2,48 +2,26 @@ > **Overwrite** this file with a summary of the most recent task only (uniform with the other repos; not cumulative). The cumulative hub history lives in [hub/CHANGELOG.md](hub/CHANGELOG.md); the scripts history lives in [scripts/CHANGELOG.md](scripts/CHANGELOG.md). -## SPIKE — NAS verify mechanisms + NFS squash matrix — 2026-07-11 +## NAS verify-before-commit — felhom.eu share (host-install v1.13.0 + feature doc) — 2026-07-11 -**Class:** spike (findings doc is the only artifact; no production code touched). -**Record:** `documentation/audits/SPIKE-nas-verify-2026-07-11.md`. -**Baselines (read-only):** felhom-agent `300f06722b` (v0.80.0, `netmount.go` = recipe under test), -felhom-controller `3db9126121` (v0.112.0, the probe container), felhom.eu `8ca1272db6`. +Part of the cross-repo task (agent **v0.81.0** + controller **v0.113.0**, both LIVE on the demo; +full task-wide record incl. red-proofs + the A–E live-validation transcripts: +`felhom-controller/REPORT.md`). This repo's commit: `27e2fb0`. -### Verdicts (all five questions answered live, evidence in the record) +- **`scripts/felhom-host-install.sh` v1.13.0** — the agent-user setup adds `felhom-agent` to the + **`systemd-journal` group** (idempotent `usermod -aG`): the verify pipeline classifies mount + failures from an UNPRIVILEGED `journalctl` read; group membership instead of a sudoers grant. + Existing installs: `usermod -aG systemd-journal felhom-agent && systemctl restart felhom-agent` + — **applied to the demo host (felhom-pve) during this task's live validation**; Peti's box gets + it only when the NAS feature reaches him. Also fixed: the header still said v1.11.0 while + `SCRIPT_VERSION` was 1.12.0 (the 1.12.0 bump had no changelog entry either) — both now 1.13.0. +- **NEW `documentation/controller/network-storage-nas.md`** — the authoritative network-storage + feature doc (none existed; the knowledge lived only in the two spike docs): the locked recipes + (incl. `retry=0` + its evidence), the verify pipeline, the §8 mount-truth table, the Q4 error + taxonomy (with the merged `nfs_export` honesty rule), the protocol-honest NAS-side recipes + (SMB plain-user; NFS map-all-users vs full-fidelity `anonuid=`), Route A caveats + incl. the operator-facing "chmod succeeds and persists" nuance, and the open items (Q1c + restart-window test, appliance pass). -- **Q1 — in-guest automount trigger: PASS (make-or-break).** A `pct exec` ls AND a docker - bind-mount access from inside guest 9201 both wake the host systemd automount (~1 s); content - correct, nfs4 propagates host→guest; idle-unmount + re-trigger proven. Q1c open item: whether a - trigger installed BEFORE guest start carries through at boot needs a restart-window test (no - restart permitted this spike). -- **Q2 — controller uid-1000 probe: PASS.** `docker exec -u 1000:1000` chain proof + `setpriv - --reuid 1000` mechanism proof (same syscalls as `syscall.Credential`); CapEff `a80425fb` has - SETUID/SETGID; server-side files land `101000:101000`. -- **Q3 — Route A: ACCEPTED-with-caveats.** `all_squash` to an arbitrary server uid (1050) gives the - guest-uid-1000 app full read/create/rename/**hardlink**/delete. Caveats: guest sees - `nobody:nogroup`; `chown` fails immediate-clean EPERM; `chmod` SUCCEEDS and persists server-side. - q3c pinned the June WRONG case: `anonuid` without `all_squash` never applies to non-root traffic — - wire uid 101000 fails on others-perms. Consumer guidance must require the "map/squash ALL users" - mode, not just an anon-uid field. -- **Q4 — error taxonomy + timing:** full table in the record. Headlines: NFSv4 returns the IDENTICAL - `No such file or directory` for nonexistent vs not-permitted exports (merge those error - categories); dead server = systemd `timeout` at **90 s** (systemd kills mount.nfs before its 2-min - retry — no diagnostic string); **`retry=0` recommended for the PRODUCTION unit** (dead-server - verify 90 s→3.1 s with clean `No route to host`; guest on-demand access 91 s→3.8 s ENODEV; happy - path untouched; autofs retries fresh per access). SMB splits cleanly: `error(13)`=credentials, - `error(2)`=share name. **Budget (Q4-vii):** verify cannot ride the agentapi global 15 s timeout - (`client.go:87`) — worst case is systemd's 90 s; give AddNetStorage its own longer-lived path or - async status-poll, ~120 s end-to-end, agent-side `systemctl start` bounded at ~95 s. -- **Q5 — plain-user SMB: PASS.** Stock user + rw share, zero server-side uid config, all 8 probe - steps pass INCLUDING hardlink (on Debian Samba/ext4 — re-verify on a real appliance); server-side - ownership = the authenticated account; guest sees forced `1000:1000/0664`. - -### Safety rails held -Isolated scratch root `/srv/nas-spike2/` on 180 (backups `.bak-nasspike2`); no iptables/network -manipulation (unreachable case = verified-unused 192.168.0.199); no guest restart; spike mounts only -under `/mnt/felhom-drives/spike2-*`. **Teardown verified:** exports back to pre-count 2, smb.conf -sections 6, spike users/scratch/units/creds/mountpoints all gone, 0 spike2 mounts on host and in -guest, controller 0.112.0 healthy, spike-pulled alpine image removed. - -**Next:** the production "NAS verify-before-commit + UI redesign" TASK is written by the operator -side on these findings (STOP honored — no production work started). +No hub/website/manifest changes; nothing to deploy from this repo (the script ships via the Day-0 +supply chain on the operator's publish decision — NOT triggered by this task).