From c322bac21a7060b23550ad642416dee76003c290 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sun, 12 Jul 2026 11:15:07 +0200 Subject: [PATCH] docs(break-glass): document operator-set FIXED root@pam credential (demo-felhom-01) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §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//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 Claude-Session: https://claude.ai/code/session_017CDMFpFx84pfviCTVuGGhf --- documentation/runbooks/break-glass.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/documentation/runbooks/break-glass.md b/documentation/runbooks/break-glass.md index 047ff2c..1b65589 100644 --- a/documentation/runbooks/break-glass.md +++ b/documentation/runbooks/break-glass.md @@ -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:\n' | chpasswd`), + then re-vault with `PUT /api/v1/hosts//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