felhom.eu/documentation/audits/RUNBOOK-usb-enrollment-3bfix-2026-07-01.md

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.