felhom-agent/REPORT.md

# REPORT — agent v0.50.0: NAS network storage Part A1 (NFS/SMB automount foundation)

**Date:** 2026-06-30
**Task:** `TASK.md` — NAS network storage Part A1 (agent foundation: automount + bind + liveness).
**Class:** Risky / supervised (creates real network mounts on the Proxmox host). Implemented on `main`,
sim-validated live, sim torn down.

## Baseline (confirmed live)

| | value |
|---|---|
| Agent `main` before | v0.49.0 (commit `7aeb7ca`), live on felhom-pve |
| Agent after | **v0.50.0** (commit `63aa63d`) |
| Deployed binary sha256 (felhom-pve) | `6ddb6ff2efe6b10377e00ff7612f738ff437dfbcbcc35e3fc566e40d139aedf1` |
| Host client tooling | `mount.nfs` (nfs-common) + `mount.cifs` (cifs-utils) present |

## What was built

The agent foundation of `SPIKE-nas-storage-2026-06-29.md` (verdict READY) — a customer NAS can serve
**bulk media** to a media app. The agent mounts a NAS share **host-side** under `/mnt/felhom-drives/<name>`
via a systemd `.automount` (+ `.mount`) pair; it propagates into guest 9201 for free through the existing
shared `mp8` bind. A NAS is a **distinct storage class** — no durable-id, never in the drive
enroll/eject/decommission/wipe/SMART/watchdog machinery. **Bulk-media class only.**

### Files changed (commit `63aa63d`, +1351/-5)
- `internal/storage/netmount.go` (NEW, 511) — `NetworkMountSpec`, the locked NFS/SMB option sets, the
  `+100000` uid recipe, `.mount`/`.automount` rendering, validation, per-share liveness, and the
  `SudoHostOps` `EnsureNetworkMount`/`RemoveNetworkMount`/`ListNetworkMounts` methods.
- `internal/storage/mountunit.go` — drive-machinery guard: `parseFelhomMountUnit` explicitly refuses any
  unit carrying the network marker (Scenario D).
- `internal/localapi/netstorage.go` (NEW, 204) — self-scoped `POST /netstorage/add`, `GET /netstorage`,
  `POST /netstorage/remove`; role gate; out-of-band 0600 SMB creds file.
- `internal/localapi/server.go` — wire `NetStorage` + `SmbCredsDir` into Options + routes.
- `cmd/felhom-agent/main.go` — `newHostOps` returns `*storage.SudoHostOps`; wire `NetStorage`; v0.50.0.
- `internal/config/config.go` — `privileged.smb_creds_dir` (default `/var/lib/felhom-agent/smb-creds`).
- `configs/felhom-agent.sudoers` — new narrow `FELHOM_NETMOUNT` alias (`.automount` install/enable/
  disable/stop + felhom mount-unit removal); `visudo -cf` clean on the live host.

## Tests — `go build ./... && go vet ./... && go test ./...` GREEN (build server, Linux)

Unit tests with **companion red-proofs**:
- **Exact option-set string-asserts** — NFS `vers=4.1,soft,timeo=50,retrans=2,noatime,_netdev` (no `hard`,
  no client uid); SMB `vers=3.0,credentials=…,uid=101000,gid=101000,forceuid,forcegid,file_mode=0664,
  dir_mode=0775,_netdev`.
- **+100000 companion** — container uid 1000 → the SMB unit renders `uid=101000`; a `+0` impl (`uid=1000`)
  FAILS the test (the documented non-writable trap). `dir_mode` must be plain `0775`, never setgid `2775`.
- **Validation matrix** — bad name/traversal/slash/space, bad protocol, server metachar, NFS relative/
  traversal export, uid/gid range, SMB-without-creds, SMB bad share name.
- **Role gate** — under `/mnt/felhom-drives` → user-data; anything else → system (refused).
- **Drive-machinery guard (Scenario D) + companion** — `parseFelhomMountUnit` refuses a network unit even
  when contrived with a by-uuid `What=`; the **same content with the drive marker DOES parse** — proving
  the guard (not luck) is the discriminator.
- **Unit round-trip + health + isNetworkMounted**; **Ensure/Remove command-sequence** (mkdir → install ×2
  → daemon-reload → enable `--now` the `.automount`, never the `.mount`; remove = stop/disable automount →
  stop mount → rm ×2 → daemon-reload); **bad spec → ZERO commands**.
- localapi: add NFS/SMB happy-path; SMB writes a **0600** creds file + no secret in the response; SMB
  missing creds → 400; **role-gate refusal → 403, surface never touched**; list; remove (creds cleaned);
  not-configured → 503; auth required → 401.

(The two `SudoHostOps` command-sequence tests skip on Windows — the systemd-escaped unit filename embeds a
backslash — and run on the Linux build server, where the full suite is green.)

## Live sim validation (Scenarios A–D)

**Isolated sim NAS:** a throwaway **privileged LXC (VMID 9300, `nas-sim`, 192.168.0.114)** on felhom-pve
running `nfs-kernel-server` + `samba` with **its own config** — it did NOT modify any production host's
`/etc/exports` or `smb.conf` (the spike's near-miss avoided). Export squashed to `anonuid/anongid=101000`;
SMB `force user/group = nasguest` (uid/gid 101000). Throwaway creds, out-of-band. **Sim destroyed after.**
Endpoints driven exactly as A2 will (the controller's own local-api token + the real agent server pipeline).

### A — NFS host-side mount → propagates → container read+write (the +100000 recipe) ✅
- `POST /netstorage/add` (nfs) → host automount installed; first access mounted `nfs4` with effective opts
  `vers=4.1,soft,timeo=50,retrans=2,noatime` (exact recipe).
- **Guest 9201 saw the `nfs4` mount with NO restart** (shared-bind propagation); guest view ownership
  `1000:1000` (the +100000 idmap).
- A **uid-1000 Docker container** READ `readme.txt` AND WROTE `ctest.txt` (`WRITE_OK`); the new file landed
  on the NAS as **`nasguest:nasguest` (101000:101000)**.

### B — SMB fallback read+write ✅
- `POST /netstorage/add` (smb) → creds staged **0600** (`felhom-agent`-owned, out-of-band); mounted `cifs`
  with `vers=3.0,uid=101000,forceuid,gid=101000,forcegid,file_mode=0664,dir_mode=0775` (exact recipe).
- uid-1000 container READ + WROTE (`SMB_WRITE_OK`); landed on the NAS as `nasguest` (101000). No secret in
  any response, log, or committed file.

### C — failure isolation (the risk) ✅
- NAS black-holed from felhom-pve (`iptables DROP`, both directions — a dead-NAS black hole).
- **Clean fail-soft:** uncached `stat` → error **`No such device` in 15s**; `cat` data read → error in
  **16s** (≈ the spike's ~16s). It **errors, does not hang**.
- **`df /` did NOT hang** (box-wide health intact); **guest 9201 responsive + `felhom-controller`
  healthy** throughout — blast radius contained to the process touching the mount.
- **Per-share liveness reported `unreachable`** for the affected shares only (never box-wide); the endpoint
  TCP-probe never touched the wedged mount.
- **Automatic recovery** on NAS return: a fresh read succeeded with **no remount**; liveness returned to
  `ok`/`idle`.
- *Note:* a first C run hit a 30s ceiling — it coincided with a concurrent scheduled `vzdump` of 9201
  (load 4.7); the clean re-run after the backup matched the spike (~15–16s). The box-wide isolation held
  **even under that backup load.**

### D — the drive machinery ignores the NAS mount ✅
- `GET /disks` listed only real drives (`felhom-pbs`, `felhom-usb`, `local`, `felhom-flash`, `local-lvm`)
  — **never `media`/`vids`**; the NAS shares carry **no durable-id**.
- The 20 s drive reconcile/`ReassertEnrolledMounts` tick re-bound only the enrolled drives
  (felhom-flash/felhom-usb) and **never touched** the NAS mounts; they remained present and unmodified.

### Lifecycle + teardown
- `POST /netstorage/remove` (both) → units gone, creds file gone, mounts gone, list empty.
- Sim LXC 9300 destroyed; all iptables DROP rules removed; helper scripts removed; `/mnt/felhom-drives`
  back to only `felhom-flash` + `felhom-usb`; agent **v0.50.0 active**; guest 9201 + controller healthy.

## Deploy + clean restart
sudoers (`FELHOM_NETMOUNT`, `visudo -cf` clean) and the v0.50.0 binary installed on felhom-pve (prior
binary backed up `.bak-0.49.0`). Restart: `capabilities self-check ok=46 total=46 degraded=0`,
`local-api server listening 192.168.0.162:8443`, no errors — `ReassertEnrolledMounts` ran without touching
any network mount.

## Operational note (pre-existing, not this feature)
During validation `df /` on felhom-pve showed the **root fs at ~100%** (vzdump output under `/var/lib/vz/
dump` on `pve-root`). Unrelated to network storage (the NAS data lives on the sim, the agent state is
tiny) — flagging it as a host backup-retention/disk-pressure item for follow-up.

## STOP — not yet built (per the task)
- **A2 (controller "network storage" registry kind + UI + per-share health surface)** — NOT built; A2 will
  drive these A1 endpoints.
- **B (restic-over-SFTP NAS backup target, class 2)** — NOT built (separate task).
- **No real customer media app wired to a NAS path** — awaiting A2 + a real app.
- Real-Synology/QNAP (virtual-dsm) GA-fidelity confirmation — out of scope (later pass).

SMB/NFS test credentials were throwaway and out-of-band only. No secrets in any committed file.