diff --git a/documentation/audits/build-release-4b-2026-11-15/E/small-disk-flag-on-the-public-image.md b/documentation/audits/build-release-4b-2026-11-15/E/small-disk-flag-on-the-public-image.md new file mode 100644 index 00000000..fa09c2b3 --- /dev/null +++ b/documentation/audits/build-release-4b-2026-11-15/E/small-disk-flag-on-the-public-image.md @@ -0,0 +1,48 @@ +# How `--accept-small-disk` reaches an install from the public image — read from source, not tried (2026-11-15) + +For the release session of installer 1.38.0 (D83). The reviewer's reading was: the hub's bind form has an „extra +args” field, the delivery carries it, the first-boot unit appends it. **Two of the three are true. The first is not.** + +| Link | What the source says | Where | +|---|---|---| +| The first-boot unit appends extra arguments to the installer's command line | **TRUE.** `read -ra extra <<< "${FELHOM_EXTRA_ARGS:-}"`, then `bash "$SCRIPT_TMP" "${args[@]}" "${extra[@]}"` — the words are split on spaces and passed as they are | `scripts/iso/felhom-bootstrap.sh:412`–`415` | +| The pairing answer carries them | **TRUE.** The hub's answer to the box's poll holds `extra_args`; the unit writes it into its env file as `FELHOM_EXTRA_ARGS` (shell-quoted), so every later retry has it too | `hub/internal/api/appliance.go:232`; `scripts/iso/felhom-bootstrap.sh:551` | +| The hub's bind handler takes them | **TRUE.** `POST /appliances//bind` reads the form value `extra_args` and stores it with the bind | `hub/internal/web/appliances.go:140`, `:155`; `hub/internal/store/appliance.go:218` | +| **The operator's bind FORM has the field** | **FALSE.** The form on the Hosts page has a household list and the hidden form token, and no input named `extra_args` (searched: no template holds the name) | `hub/internal/web/templates/hosts.html:92`–`97` | +| The household's own bind page (the pairing code) | passes an EMPTY value, always | `hub/internal/web/selfbind.go:276` | + +**So, today:** the flag can reach a public-image install only by a POST that the page does not offer — the operator's +browser session with a hand-made form. CC cannot do it: a bind is a session-only act (no token). + +**One more thing that follows from the unit's retry loop** (R-1398 part 1): without the flag, a small machine that was +bound repeats the refusal every 30 seconds. With the flag in the bind, the first run goes on. + +## The steps for the two small machines + +**demo-hp (128 GB), a reinstall.** It is never installed from the public image in practice; it is installed by the +installer run by hand (the direct shape, as every proof install was): + +``` +./felhom-host-install.sh --customer-id demo-hp --mode appliance --hub-url https://hub.felhom.eu \ + --passphrase-file --accept-small-disk +``` + +Expected: the two „--accept-small-disk” lines with the cost; the install goes on; the install state holds +`small_disk: true`; after the hub release the box's page shows „System disk: small — accepted below 200 GB”. +The box that runs today is not touched by the rule: the check runs only inside an install. + +**The fresh-install proof VM.** Two runs, both by hand in the direct shape (as on 2026-11-14 and 11-15): + +1. *The household's path, no flag:* make the VM's first disk 200G (`qm set --scsi0 nvme-scratch:200,format=raw` + — on a `dir` storage the file is sparse and costs what is written). The install must pass the check with the line + „system disk: /dev/sda, 214 GB (the minimum is 200 GB)”. +2. *The refusal:* the same VM with a 64G disk, `--preflight-only --mode appliance`: it must stop with „This machine's + system disk is 68 GB. Felhom needs 200 GB. Nothing was changed.” Before and after: `qm config`, `pvs`, `lvs`, the + list of `/etc/felhom*` — equal. + +**To prove the public-image path itself** (the unit, the pairing, the flag from the bind) a session needs the +operator: he binds the appliance with a form that holds `extra_args=--accept-small-disk`. That needs the missing +input on the Hosts page first — one line in a template and a render test; **not built** (it was not in the brief; +it is on R-1398, dated line). + +**What is not proven:** all of it. Nothing was run; no hub row was read. diff --git a/documentation/audits/build-release-4b-2026-11-15/F/host-report-readers.md b/documentation/audits/build-release-4b-2026-11-15/F/host-report-readers.md new file mode 100644 index 00000000..2c1c7d24 --- /dev/null +++ b/documentation/audits/build-release-4b-2026-11-15/F/host-report-readers.md @@ -0,0 +1,70 @@ +# Every reader of a host report in the hub — and what a short report would do there (R-1396 gap 2) + +Written 2026-11-15 evening, from source (`hub/` at `c3fa43a4`). **A list, no build.** The design it serves is +`03-host-agent.md` §12a item 8: a box that cannot reach Proxmox sends a *short report* — its id, the times, the agent's +version, the `proxmox_trust` stanza and one `proxmox_unreachable` stanza with the cause, and no other key. + +The column „with a short report” is CC's reading of the code. **Nothing was run.** A row marked WRONG is a reader that +would do harm if it got a short report as it gets a report today. + +## A. The readers on the way in (`internal/api/handler.go`, `handleHostReport`, lines 957–1190) + +| # | Reader | What it reads | With a short report, as the code is today | Needed | +|---|---|---|---|---| +| 1 | the login and the id check | the box's key; `host_id` | works: the id is in the short report | nothing | +| 2 | `store.SaveHostReport` and its summary columns | the whole body, stored as the box's NEWEST report; agent version, CPU, memory, disk percent, guest count, tunnel state into the box's row | **WRONG:** the short report becomes „the newest report”, and the box's row reads disk 0 %, 0 guests, no tunnel. Every reader of part B then sees an empty box | **keep a short report OUT of the report table**: its own columns on the box's row (last seen, unreachable since, cause) | +| 3 | `carryEscrow` (a box's first report) | nothing of the body | harmless | skip | +| 4 | `checkTunnel` | `cloudflared.status` | **WRONG:** an empty state reads as „no tunnel” | skip | +| 5 | `checkHostSwap` | two swap numbers | **WRONG:** zeros can end a real swap alarm | skip | +| 6 | `checkWGTunnel` | the `wireguard` stanza | an absent stanza reads as „feature off” — can end a real alarm | skip | +| 7 | `checkProxmoxTrust` | the `proxmox_trust` stanza | **wanted** — this is one of the two reasons for the short report | run | +| 8 | `checkBoxClock` | `sent_at` | **wanted** | run | +| 9 | `checkGuestPowerGaveUp` | the give-up stanza and the list of guests | **WRONG:** with no guests listed, every give-up mark starts its one-week count to be forgotten | skip | +| 10 | `checkCrash` | the `system` stanza | absent: no change | skip | +| 11 | `checkDeliberateOff` | the power-off stanza | **WRONG:** an absent stanza ends „switched off on purpose” | skip | +| 12 | the guest rows (`UpsertGuestFromReport`) | each guest | no guest, no write: harmless | skip | +| 13 | the storage, backup, restore-test and off-site-verify log lines and warnings | four lists | nothing listed, nothing said: harmless | skip | +| 14 | `noteForeignKeyArchives` | its stanza | absent: no call | skip | +| 15 | the agent's log tail | `log_tail` | absent: the request stays pending | skip | +| 16 | `store.SaveDRRecipeHostHalf` | the recovery recipe's host half | **WRONG, the worst:** an empty recipe is written over the good one — the recipe is what a recovery after a lost box reads | skip | +| 17 | the answer to the box (the control envelope) | nothing of the body: the box's generation, „signed jobs wait”, a pending log request, pending operator actions, „blocked” | **wanted:** a box that cannot reach Proxmox can still take a signed agent update — often the repair | run, and add `accepts_short_report` | +| 18 | `ingestHostOperatorActionResults` | results of operator actions | absent: nothing | run (harmless) | + +## B. The readers of a STORED host report (they read the newest row, or the rows of a time window) + +| # | Reader | Where | What it reads | With a short report stored as the newest row | +|---|---|---|---|---| +| 19 | the OS-update service | `internal/osupdates/service.go:998`, `:1196` | the box's system facts | WRONG: „unknown” facts; a box may be judged „not ready” | +| 20 | the kernel lane | `internal/osupdates/kernel.go:108` | the running and default kernel | WRONG: no kernel known | +| 21 | the restore-test check | `internal/monitor/restoretest.go:195`, `:252`, `:260` | restore tests of the newest report and of a window | WRONG: the newest row shows none | +| 22 | the backup-deadline check | `internal/monitor/deadline.go:356`, `:392`, `:498`, `:514`, `:529` | backups per report, the first report's time | WRONG: the newest row shows none | +| 23 | the „escrow pending” check | `internal/monitor/offsite_escrow_pending.go:53` | the first report's time | harmless | +| 24 | the controller-supervisor check | `internal/monitor/controller_supervisor.go:96` | the supervisor stanza of every box's newest report | WRONG: an absent stanza reads as „agent too old to tell” | +| 25 | the box's page | `internal/web/hosts.go:636`, `:820` | everything shown | WRONG: an empty box | +| 26 | the System page | `internal/web/system.go:547` | the system facts | WRONG: „unknown” cells | +| 27 | the „host stale” check | `internal/monitor/host_staleness.go` (4 reads of the last-report time) | when the box last reported | wanted in part: the box is alive, so not stale — but it must not read as healthy | +| 28 | the host-disk check | `internal/monitor/host_disk.go:77`, `:113` | the disk percent in the box's row | WRONG: 0 % ends a real „disk full” alarm | +| 29 | the Hosts list and the dashboard | `internal/web/hosts.go` (10 reads of the last-report time), the summary columns | state, guests, versions | WRONG: 0 guests, „fine” | + +## What the list changes in the design + +**The short report must not be a report to the hub's store.** If it is kept out of the report table and out of the +summary columns (row 2), then rows 19 to 26, 28 and the guest part of 29 need NO change: they go on reading the last +full report, which is the truth about the box's content as far as anybody knows it. + +What is then left to build, all of it small and in one place each: + +1. `handleHostReport`: a branch at the top for a body that holds `proxmox_unreachable` — it runs rows 1, 7, 8, 17 and + 18, writes three columns on the box's row (last seen, unreachable since, cause), and returns. Nothing else runs. +2. The „host stale” check (row 27) reads „last seen” (a full OR a short report) for liveness. +3. One new operator-only alarm per (box, cause), cleared by the first full report. +4. The box's page, the Hosts list and the System page (rows 25, 26, 29): one line „reports, cannot reach Proxmox since + …; what is shown below is from