diff --git a/documentation/audits/RUNBOOK-usb-enrollment-3bfix-2026-07-01.md b/documentation/audits/RUNBOOK-usb-enrollment-3bfix-2026-07-01.md new file mode 100644 index 0000000..7d4232d --- /dev/null +++ b/documentation/audits/RUNBOOK-usb-enrollment-3bfix-2026-07-01.md @@ -0,0 +1,74 @@ +# RUNBOOK result — physical USB enrollment validation on the pool-scoped ACL (3b-fix closure) + +**Date:** 2026-07-01 · **Host:** felhom-pve (192.168.0.162, node demo-felhom) · **Class:** live +supervised validation, **no code change, no version bump**. Baseline: script v1.7.0, agent v0.53.0, +controller v0.94.0 — all reconfirmed. + +## Verdict + +**The ACL residual is CLOSED: drive enrollment / management needs NO `Datastore.Allocate` and hits NO +403 under the pool-scoped token.** The v1.7.0 layout (`Datastore.Audit` box-wide in Base; write privs +`Datastore.Allocate`/`AllocateSpace` per-storage) is complete for storage/drive operations. + +A full physical wizard enrollment could **not be completed**, but for a reason that is **ACL-independent +and not a permission failure**: the plugged-in test device is an SD-card reader that does not surface as +a wizard candidate (details below). Per the runbook's own decision branch, that is a "note it — separate +follow-up, NOT a permission issue" outcome, not the STOP condition (which is a 403). + +## What was validated + +- **Baseline (reconfirmed):** roles `Base=Sys.Audit SDN.Use Datastore.Audit`, `Store=Datastore.Allocate + Datastore.AllocateSpace`, `Guest=VM.* + Pool.Allocate`. Agent v0.53.0 active. felhom-usb + felhom-flash + enrolled, mounted, untouched. +- **New device identified unambiguously:** `/dev/sdd`, 59.5 GiB, `SD/MMC/MS PRO` card reader, by-id + `usb-Generic-_SD_MMC_MS_PRO_20120926571200000-0:0`, ntfs factory partition, **unmounted**. Distinct + from felhom-usb (sdc) + felhom-flash (sdb). Nothing was formatted (the wizard never offered it). +- **S1 (drive visibility — the 3b-fix) — PASS, in the real UI:** the controller agent-view (Meghajtók + ügynök nézet) shows both felhom-usb + felhom-flash as **Regisztrálva** with full metadata and **no + "Meghajtó leválasztva" (detached) alert**. `felhom-agent --selftest=read` sees all **5** storages. +- **No 403 anywhere:** the agent log across the whole interaction window (13:44→) shows zero pve-token + permission failures. (The only "permission denied" is the PRE-EXISTING, unrelated non-root PBS + key-file read — `/etc/pve/priv/storage/felhom-pbs.pw` — used for PBS *datastore metrics*, not for + backup; a known root→non-root fs-permission gap, see [[bundle-slice-day0-selfinstall]].) +- **Write-containment intact (re-confirmed):** vzdump→felhom-usb → 403 (`Datastore.AllocateSpace` + per-storage); out-of-pool guest ops → 403. + +## Why the new drive did not appear in the wizard (root cause; ACL-independent) + +Confirmed at agent source: +- The controller's drive list (`/settings/storage/init` wizard + agent-view) is served by the agent's + `GET /disks` (`internal/localapi/disks.go` `handleDisks`), which iterates **`storage.Observe()`**. +- `Observe()` (`internal/storage/observe.go` `snapshot()`) enumerates **only PVE storages** via + `ListStorage`/`NodeStorage` (both `Datastore.Audit` — now granted box-wide). It does **not** enumerate + raw/unregistered block devices. +- The agent has **no storage-registration path at all**: its disk endpoints are `assign` (host mount), + `eject`, `decommission`, `format` (mkfs), `guest-attach` (bind), `netstorage` (host mount) — all + **host-ops via sudo**. There is **no `pvesm add` / `POST /storage` / storage.cfg writer** anywhere in + the agent. So the agent never creates a PVE dir-storage (which is exactly why enrollment needs no + `Datastore.Allocate` — confirming the fix). + +Consequence: a **brand-new raw device that is not yet a registered PVE dir-storage never surfaces in the +init wizard** — regardless of the token ACL (it would be equally absent under the old broad token). The +existing `dir: felhom-usb` / `dir: felhom-flash` entries in `storage.cfg` were created out-of-band +(operator/manual during initial setup), not by the agent. The SD-card reader used here (HOTPLUG=0, an +ntfs partition) is simply one instance of "raw device with no PVE-storage entry." + +## Follow-up flagged (NOT a permission issue, NOT this task) + +**New-drive registration gap:** there is no self-serve path to turn a freshly-plugged raw drive into a +Felhom-managed dir-storage — the init wizard only offers drives that are *already* PVE dir-storages. A +colleague plugging in a genuinely new USB would need the operator to `pvesm add dir …` first (or a new +controller/agent feature to register a raw device). Worth a design decision: +- Option A: agent gains a `register-raw-drive` step (host-op `pvesm add` via sudo → still no token priv; + keeps the ACL as-is), fed by a raw-block-device candidate list (host-ops `lsblk`, not `Observe()`). +- Option B: document that new-drive registration is an operator step. + +This is independent of the pool-scoped ACL and does not block it. + +## NOT done + +- A completed physical format→mount→enroll of a genuinely new drive (blocked by the registration gap + above, not the ACL). If desired, provide a drive that is already a PVE dir-storage (or add the entry + out-of-band) and re-run the wizard — the ACL will not block it (host-ops + Datastore.Audit only). +- Cleanup: the SD-card stick was never touched (no format); it can be unplugged. felhom-usb/felhom-flash + + guest 9201 untouched and healthy throughout.