two lists for the release of release 4: every reader of a host report in the hub (R-1396 gap 2); how --accept-small-disk reaches a public-image install (the bind form has no such field)

Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
This commit is contained in:
admin committed 2026-11-15 16:03:37 +01:00
1 parent c3fa43a486
commit b8cf6c2417
4 files changed
+118 -297

No files matched your search

@@ -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/<id>/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 <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 <id> --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.
@@ -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 <time of the last full report>”.
5. The answer's new field, and the agent's half (it sends a short report only to a hub that said it understands it).
One test per row of part A that is marked „skip”: a short report changes nothing there. One test for part B as a
whole: after a short report the newest row of the report table is still the last full report.
**Not read for this list:** the pages' templates field by field; the customer page's Host tab (it renders the same
body as the box's page). **The test on a box that settles the design** is in `03` §12a item 8: `pveproxy` stopped for
20 minutes on demo-hp.