docs(break-glass): document operator-set FIXED root@pam credential (demo-felhom-01)

§5: add the standing note that a host's root@pam may be pinned to a known
operator-chosen password instead of the random day-0 one — set via chpasswd +
re-vault (PUT /hosts/<id>/recovery-credential, host api_key), guarded by the
break_glass state marker so plain installer re-runs skip it. Caveats: never
--rotate-recovery such a host; a full from-scratch reinstall wipes state.json
and re-randomizes (re-run the set-and-vault). Captures why demo-felhom-01's
root@pam "kept changing" until it was pinned 2026-07-12.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017CDMFpFx84pfviCTVuGGhf
This commit is contained in:
2026-07-12 11:15:07 +02:00
parent 0eb9dc2e9b
commit c322bac21a
+10
View File
@@ -76,6 +76,16 @@ Fix the cause; the three layers are the safety net, not the cure.
- **Rotate the console credential** with `felhom-host-install … --rotate-recovery` (regenerates +
re-vaults; a plain re-run does NOT rotate, to avoid stranding your saved copy). Full auto-rotation is
a future item.
- **Operator-set FIXED credential (e.g. demo-felhom-01, pinned 2026-07-12).** A host's `root@pam` may
be deliberately set to a *known operator-chosen* password instead of the random day-0 one. Do it the
same way step 4b does, just with your password: set it on the box (`printf 'root:<pw>\n' | chpasswd`),
then re-vault with `PUT /api/v1/hosts/<host_id>/recovery-credential` (host `api_key` from
`/etc/felhom-agent/agent.json`; expect HTTP 200), and ensure `break_glass` is in
`/var/lib/felhom-install/state.json`'s `completed[]`. This **survives plain installer re-runs**
(step 4b skips on the marker). Two caveats: (a) **never `--rotate-recovery` such a host** — it
replaces your known copy with a random one; (b) a **full from-scratch reinstall** (uninstall→install)
wipes `state.json`, so step 4b re-randomizes — re-run the set-and-vault afterward. Background: on each
full reinstall this is exactly why `root@pam` "kept changing" until it was pinned.
- **The password is never logged or filed** — it exists only in the hub vault (retrieve as in §3.1).
- **Least-privilege console user** instead of root@pam was probed as a non-blocking observation: PVE
has historically gated the node Shell to `root@pam`, so G1 ships the proven root@pam path. Revisit if