Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
47 KiB
16 — Storage that knows its physical disks
What this is: the design that lets Felhom know, for every storage place, which physical disk(s) it sits on — and use that to make backup tiers honest, to give one-disk boxes a place for household data, and to allow partitions. Operator ruling 2026-10-15: „Felhom must support drives split into parts; the agent and the controller must know whether two storage places sit on the same physical disk." Triggered by the OMV test (
audits/omv-vm-2026-10-15/, R-1068). Spike:audits/storage-identity-2026-10-15/(Part B there). Marks as in01: [FACT] read in a named file or measured; [DESIGN] a proposal. Status: ACCEPTED 2026-10-15 — the operator ruled D1–D6 as recommended (§12). Build A shipped 2026-10-15 (§3, §4, §5's D4 sentence, §8, §10); build B shipped 2026-10-16 (§5's internal place, §6, §7, §9) — what is built, and where the build differs from this text, is §13. Paths: A =felhom-agent/, C =felhom-controller/controller/, E =felhom.eu/.
1. Today, in one table (Part A)
| Place | Found by | Identified by | Mounted | What lives there | The backup page says |
|---|---|---|---|---|---|
Host root / PVE local |
PVE storage local [FACT] A/internal/storage/observe.go:424; never a candidate [FACT] A/internal/storage/role.go:53-79 |
path: / store:local [FACT] A/internal/storage/durableid.go:54-67; role system |
host /, /var/lib/vz |
the local whole-guest copies (vzdump, retention 3) [FACT] E/scripts/felhom-host-install.sh:730-734; 07 §6.1 |
backup.target.degraded „…ugyanazon a lemezen van, mint a rendszer…" [FACT] C/internal/web/backup_target_offer.go:78-100 |
Guest mp0 /var/lib/felhom with folders docker/ and sys_drive/ (bound to /var/lib/docker, /mnt/sys_drive) |
config default system_data_path=/mnt/sys_drive [FACT] C/internal/config/config.go:166 |
path only; „same disk" = st_dev [FACT] C/internal/system/mounts_linux.go:225-245 |
thin LV in local-lvm, backup=1 [FACT] A/configs/build-golden.sh:105, :221-225; measured on all 3 boxes |
app volumes; Tier-1 of apps with no drive [FACT] C/internal/backup/backup.go:429-438; Tier-2 state-only fallback [FACT] C/internal/backup/tier2.go:157-178; inside every whole-guest copy | „Csak egy másolat készül (nincs második meghajtó)…" — corrected 2026-10-24: the i18n keys note.backup.single_copy / note.backup.single_copy_unproven, picked by the agent's verdict [FACT] C/internal/backup/backup.go:1485-1494 |
Enrolled drive (/mnt/<name> on the host → /mnt/felhom-drives/<name>) |
GET /disks/candidates: whole disks, each carrying its nested partition candidates (empty / filesystem / in use; corrected 2026-10-24) [FACT] A/internal/storage/candidates.go:84-90 |
mount: uuid:<fs-uuid>; wipe: byid: wwn > nvme-eui > … [FACT] A/internal/storage/durable_device.go:32-51 |
systemd unit by fs-UUID through FELHOM_MOUNT [FACT] A/internal/storage/mountunit.go:50-65; host bind into mp8 |
HDD_PATH apps, media binds [FACT] C/internal/stacks/media_library.go:24-33; Tier-1/Tier-2; optionally the whole-guest target felhom-backup; not in vzdump (mp8 is a host bind) [FACT] 07:477-480 |
Tier-2 badges; „Nincs 2. (off-drive) másolat" [FACT] C/internal/i18n/locales/hu.json:303 |
| Network share | customer input [FACT] A/internal/localapi/netstorage.go:36-40 | none („no durable-id, no SMART") [FACT] netstorage.go:15-19 | .automount under /mnt/felhom-drives/<name> [FACT] A/internal/storage/netmount.go:18-31 |
browse only; never media, never Tier-2 [FACT] media_library.go:83; tier2.go:141-143 | err.backup.halozati_tarolo_nem_lehet_a_2 [FACT] tier2.go:37-40 |
| USB disk | same as an enrolled drive; transport never decides [FACT] C/internal/settings/settings.go:609-614 | same; the bridge may pass the real identity (N100: yes) [FACT] spike case 4a | same | same | same; SMART may be missing → „Nincs adat" |
[FACT] What compares physical disks today: the controller compares only paths and st_dev (its own comment:
„two partitions on one physical disk look "different" here", mounts_linux.go:240-242). The agent has a whole-disk
compare (SameWholeDisk, role.go:207-216) but uses it only for eject/decommission roles. [FACT] What knows about
partitions: the agent accepts /dev/sdb1 for inspect and mkfs (A/internal/storage/validate.go:28-32) but judges the
whole disk (claim.go:144-163), lists only whole disks, and calls a disk with a partition table or any filesystem
„data-bearing" (candidates.go:66-85). Measured: an empty partition next to another is never offered (spike).
2. The spike in five lines (Part B)
[FACT] A read-only walk (partition → parent; dm/LVM → slaves; loop → backing file → its disk) named the right
physical disk in every case on real devices: one-disk N100 and demo-hp (every system place → the one SSD), two disks
(system vs enrolled drive), two partitions of one disk (both → the same disk), a USB bridge that passes the identity.
Inside a VM (Tester 1) it can only say „unknown": virtual disks on the same host disk and on a different host disk
look identical (QEMU HARDDISK, serial = the slot name drive-scsiN). Not measured: a USB box that hides the serial
(R-1077). Seen: a cheap SSD with a vendor-less WWN (OUI 000000, R-1076). Full table: audits/storage-identity-2026-10-15/README.md.
3. The model
[DESIGN] A storage place is anything Felhom stores on: the system data (mp0), the new internal data place
(§5), an enrolled whole disk, an enrolled partition, a network share. Each place carries:
| Field | Meaning |
|---|---|
kind |
system · internal · disk · partition · network |
physical_disks |
the ids of the whole physical disks under it, e.g. ["serial:ATA:SanDisk_X600:182195804614"] |
identity |
proven — every disk under it has a stable id the agent trusts; unknown — otherwise, with a reason code: vm, no_serial, weak_wwn, usb_bridge, network |
Disk id rule [DESIGN]: serial:<bus>:<model>:<serial> from udev (ID_BUS, ID_MODEL, ID_SERIAL_SHORT); NVMe
eui/nguid when present. A WWN is used only when its NAA OUI is not 000000 (spike case 4c). Model + serial, not WWN,
is the primary key: two disks are „the same" only when the key is equal.
Unknown rule [DESIGN]: systemd-detect-virt ≠ none → every disk is unknown/vm. A disk with no serial → no_serial.
A USB disk whose serial is the bridge's (all the same digit, or equal to a known bridge list) → usb_bridge. A network
share → network, physical_disks: [].
How it is computed [DESIGN]: by the agent, as root, from /sys and udev only (no controller input): the walk
the spike used, built on what exists — walkSlaves/physicalDisksOf (role.go:81-131), parentDisk
(A/internal/storage/hostread.go:183-201) — plus the loop step and the mapping guest path → host mount (/mnt/felhom-drives/<name> →
/mnt/<name> → device; mp0 → its LV).
When [DESIGN]: at agent start, on every disk hot-plug event the agent already reacts to, on enrol/attach, and again right before each Tier-2 run (a disk swapped in the same bay must not inherit the old verdict).
Reported [DESIGN]: GET /disks gains physical_disks + identity per place; the hub report's storage_targets
gains the same two fields (A/internal/hub/report.go:379-438), so the hub sees the agent's verdict directly. The controller
stores nothing of it; it asks.
4. Backup tiers
[DESIGN] The rule: a Tier-2 copy counts as a second copy only when the source place and the target place share
no physical disk and both identities are proven. The decision is the agent's (POST /disks/same-disk with the
two guest paths → {different: bool, proven: bool, reason}), replacing sameDevice/st_dev in tier2.go:83-179 and
hasOffDriveTarget (backup.go:1390-1402).
| Situation | Tier-2 | The one-copy notice | Household sentence (HU / EN) |
|---|---|---|---|
| Different disks, both proven | made, counted | hidden | — |
| Same disk (two partitions, internal place + system) | per decision D1 | shown | „Csak egy helyi másolat készül: nincs második lemez, vagy ugyanazon a lemezen van, mint az adatok. Ez a véletlen törlés ellen véd, lemezhiba ellen nem. Lemezhiba ellen egy másik lemez vagy a távoli mentés véd." / „Only one local copy is made: there is no second disk, or it is on the same disk as the data. This protects against mistakes, not against a disk failure. A different disk or the off-site copy protects against a disk failure." |
| Unknown (VM, hidden serial) | per decision D2 | shown | „A Felhom nem tudja ellenőrizni, hogy a második meghajtó valóban másik lemez-e (virtuális gépben és egyes USB-házakban ez nem látszik), ezért nem számolja második másolatnak." / „Felhom cannot check that the second drive is really a different disk (inside a virtual machine and behind some USB enclosures this is not visible), so it does not count it as a second copy." |
| Network share | never (unchanged) | shown | unchanged |
The notice moves from a Go constant to i18n, in the informal voice (closes R-1072's half). Off-site (Tier-3, PBS) and the local whole-guest copy are unchanged. [FACT] Today Tester 1 counts Tier-2 copies between virtual disks that all sit on one host NVMe (R-1074).
5. One-disk boxes — the internal data place
[FACT] The install button for a data-folder app finds no drive on a one-disk box and refuses with the raw field
name (R-1068). [FACT] The only place on that disk today, sys_drive, is a folder of mp0, which is backup=1:
anything put there rides in every local and off-site whole-guest copy (07 §6.1, §7.5.1). Films there would
overflow the local copy (R-548) and travel to ep0.
[DESIGN] The installer (new installs) creates a second thin LV on local-lvm, the internal data place
(„Belső tárhely"), formats it, and the agent mounts it on the host by fs-UUID at /mnt/belso, bound to
/mnt/felhom-drives/belso — exactly like an enrolled drive. So:
- it is not in vzdump (a host mount, like every drive) and not in PBS;
- the controller registers it as the default drive (
kind: internal), so media andHDD_PATHapps install with no extra step — no sentence at all; the media binds cover it like any drive; - its
physical_disks= the system disk, so a Tier-2 copy between it andsys_drivenever counts (§4); - the agent's format/wipe guard keeps refusing it as a system disk (role system, claim.go:72) — only the installer makes or removes it.
On a one-disk box without an internal place (old boxes, §9), the install of a data-folder app answers in words:
„Ehhez az alkalmazáshoz egy adattároló kell. A Meghajtók oldalon adhatsz hozzá egyet." — never the field name.
Registering sys_drive as a drive (the „way through" R-1068 guessed) is rejected (§10).
6. Partitions
[DESIGN] A place may be one partition. The agent lists, under each whole disk, its partitions as separate candidates with their own state:
| Partition state | Offered as | Who may |
|---|---|---|
| empty (no signature, no children) | „format this part" | the household, self-serve (it holds nothing) |
| a filesystem with no files (agent mounts read-only, counts entries) | „use this part" or „format this part" | the household |
| a filesystem with files | „use this part" (attach) only; format = the customer-confirmed data-bearing path, bound to the partition's durable id | the household with confirmation (today's user-data rule, A/internal/localapi/disks.go:912-946) |
| LVM / RAID / LUKS / swap / mounted elsewhere / on the system disk | not offered | nobody (claim.go:72-103, unchanged) |
The classifier judges the partition (its own signature, children, mounts) and still refuses on the whole disk's
system role and on any sibling that is foreign-mounted or a PV — those siblings make the disk unsafe, not the
partition. A partition's durable id = <disk id>:part<N> + its fs-UUID; the wipe re-resolve (wipe_reresolve.go:53-93)
binds both. Creating or deleting partitions: never from the dashboard in this round — the installer only (D5).
7. The installer
[FACT] Today step_grows gives the guest's one data volume (mp0) 70 / 130 / 250 GiB by the thin pool's free space
(<150 / ≥150 / ≥300 GiB), and nothing above 250 (E/scripts/felhom-host-install.sh step_grows, now at :2475 — line corrected 2026-10-24). Measured pools: 128 GB
disk → 54 GiB, 200 GB → 113 GiB, 512 GB → 349 GiB (PVE default layout; root capped at 96 GiB).
[DESIGN] The rule: mp0 = 70 GiB (pool < 300), 130 (300–800), 250 (≥ 800). Reserve = max(16 GiB, 10 % of the
pool), kept free for thin snapshots during a whole-guest copy, image pulls during updates, and the restore test (which
sizes itself, A19). Internal place = pool − 32 (rootfs) − mp0 − reserve, made only when ≥ 20 GiB. The local
whole-guest copies stay on host local (root), which the data place does not touch — R-548 is not made worse: mp0
does not grow.
| Disk | Thin pool (GiB) | Today: data volume / unused | Proposed mp0 |
Reserve | Internal place |
|---|---|---|---|---|---|
| 256 GB | ≈ 140 (estimate) | 70 / ≈ 38 | 70 | 16 | ≈ 22 (settings and small apps, not a film library) |
| 512 GB | 349 (N100, measured) | 250 / ≈ 67 | 130 | 35 | ≈ 152 |
| 1 TB | ≈ 800 (estimate) | 250 / ≈ 518 | 250 | 80 | ≈ 438 |
| 2 TB | ≈ 1,720 (estimate) | 250 / ≈ 1,438 | 250 | 172 | ≈ 1,266 |
RULED 2026-10-16 (operator, after the build B space check audits/storage-identity-buildB-2026-10-15/SPACE-CHECK.md):
these numbers replace the table above. mp0 = 50 GiB (pool < 300), 100 (300–800), 130 (≥ 800); reserve =
max(16 GiB, 10 %), at most 48 GiB; internal place = pool − 32 − mp0 − reserve, only when ≥ 20 GiB; nothing promised
beyond pool − reserve. Result: ≈ 42 / 182 / 590 / 1,510 GiB for 256 GB / 512 GB / 1 TB / 2 TB. The host root is left as
the Proxmox installer makes it (SPACE-CHECK §3).
8. Virtual machines
[FACT] Inside a VM the agent cannot tell virtual disks apart by host disk (spike cases 5–6). [DESIGN] Every place
on a VM box is identity: unknown/vm; Tier-2 there never counts (D2), and the page says why. The OMV guide tells the
household: a second disk given to the Felhom VM must be a different physical disk on the host, passed whole, on bus
sata (R-1069); otherwise it adds space, not safety. Disk health is OMV's job there (R-1073).
9. Existing boxes
[DESIGN] The agent computes identities on its next update — no migration, no change to what is stored. A box with two real disks keeps every Tier-2 copy and every sentence (both proven, different). A box where two places share a disk (none known in the field; Tester 1 in its VM) shows the honest notice. One-disk boxes get no internal place by themselves; adding one later is a signed operator job (an LV in free thin space), not a household button. Hub: the two new fields appear in reports; nothing is backfilled.
10. Threat note
[DESIGN] „Different disks" is agent-computed evidence, like the data-bearing verdict (03 §6): the controller can
only ask, never assert. A compromised controller could show a false sentence on its own page, but cannot make the agent
call two places different, cannot change the hub's copy of the verdict, and cannot format a partition the agent judges
data-bearing. The agent never trusts a guest path it cannot map to a host mount it made.
11. Rejected options (one line each)
- Register
sys_driveas the media drive — it is insidemp0, so films enter every whole-guest copy, local and off-site. - Grow
mp0without a cap — the same problem, at full size. - Keep
st_devand add a partition check in the controller — the controller cannot see LVM, loop or the host; the agent can. - WWN as the primary disk key — cheap disks ship vendor-less WWNs (N100).
- Ask the hypervisor (OMV/libvirt) which host disk backs a virtual disk — Felhom has no access there, and it would trust a party it does not control.
- Let the dashboard create partitions — a new destructive power for the household with no recovery; not needed for the cases in hand.
12. Decisions for the operator (D1–D6) — RULED 2026-10-15: all six as recommended
| # | Question | Options | Recommendation | If you do nothing |
|---|---|---|---|---|
| D1 | A second copy on the same disk (two partitions, internal place → sys_drive)? |
(a) do not make it; say „only one copy" honestly · (b) make it, label it „same disk: against mistakes, not against a disk failure" | (a) — the first copy already protects against mistakes; (b) spends space and invites a false sense of safety | today's st_dev rule stays: two partitions would count as two disks |
| D2 | Unknown identity (VM, hidden serial)? | (a) never count it; the copy is still made (it may be a real second disk) and the notice stays · (b) the household confirms „these are different disks" once, recorded with the disk ids | (a) for now; revisit (b) when a VM install is a supported shape | VM boxes keep counting same-disk copies as second copies (Tester 1 does today) |
| D3 | The installer's internal place on a one-disk box, and its reserve | (a) §7: mp0 70/130/250, reserve max(16 GiB, 10 %), the rest internal · (b) a larger reserve, 20 % · (c) no internal place; household adds a drive |
(a) | new one-disk boxes keep refusing media apps (R-1068) and leave most of a big disk unused |
| D4 | Media and data-folder apps on a one-disk old box | (a) a plain sentence pointing to Meghajtók; internal place only by a signed operator job · (b) register sys_drive |
(a) — (b) puts films into the whole-guest copies | the raw field error stays (R-1068) |
| D5 | Who creates or deletes partitions | (a) the installer only, this round · (b) also a dashboard wizard | (a) | — (nothing is built either way) |
| D6 | R-1071 — films from a NAS share, read-only, for Jellyfin | (a) a separate decision; this design only labels a NAS place network, never a copy target · (b) fold a read-only media bind kind into this build |
(a) — the model makes it easier (a NAS becomes one more place kind with clear rules), but it is a media decision, not an identity one | stays open as R-1071 |
After the rulings, the build task changes: agent (place identity in /disks and the report, the same-disk call,
partition candidates, the loop step) · controller (Tier-2 and the notice ask the agent; i18n sentences; the install
refusal in words; register the internal place) · installer (step_grows + the internal LV) · hub (store and show the two
fields) · website and guides (the OMV guide's second-disk line; the backup explanation page).
13. Build status
Build A — honest backup copies (D1, D2, D4), shipped 2026-10-15 (agent v0.157.0, controller v0.317.0 with MinAgent
0.157.0, hub v0.154.0; evidence audits/storage-identity-buildA-2026-10-15/):
| Section | Built | Proven |
|---|---|---|
| §3 model | the agent computes kind, physical_disks, identity + reason for every PVE storage and every own mount; GET /disks and the hub report carry them |
live: N100 and demo-hp proven, Tester 1 unknown/vm, the PBS store network; the hub stores and shows them |
| §4 tiers | POST /disks/same-disk; Tier-2 choice, the pre-run guard and the one-copy notice ask it (D1: same disk → no copy; D2: unknown → copy made, not counted); a NAS never counts and never hides the notice (R-1075) |
live: Tester 1 shows the „cannot check" notice and its copies are made, not counted; demo-hp and N100 count theirs, no notice. Unit only: the same-disk skip (no box has two places on one disk), the NAS notice (no box with a NAS can reach the agent, R-1083) |
| §5 D4 | the install of a data-folder app on a box with no drive answers „Ehhez az alkalmazáshoz egy adattároló kell. A Meghajtók oldalon adhatsz hozzá egyet." with a link to the Meghajtók page; never the field name | unit only — no one-disk box was at hand |
| §8 VMs | every place on a VM box is unknown/vm |
live, Tester 1 |
| §10 | the agent maps only paths to mounts it made; an absent drive (its folder on the root disk) is unmapped, never „the system disk" |
unit, and live (unmapped for an absent drive on demo-hp) |
Where the build differs from the text above:
- §3 „When": the identity is computed on every read (each
GET /disks, each report, each same-disk call), not cached at start and on hot-plug. The rule's purpose — a swapped disk never inherits an old verdict — holds with no cache. usb_bridge: built from the spike's rule, never seen on a real device (the N100's USB enclosure passes the real serial).- §4 said the notice closes „R-1072's half": it closed all of R-1072 — the other sentence was already informal.
- An older agent (no same-disk call): the controller keeps the pre-build
st_devrule and logs it once. - §11 rejects
sys_drivefor household data, but the drives page still offers/mnt/sys_driveto attach (R-280) — R-1082.
Build B — the internal place, partitions, the installer (2026-10-16) (agent v0.158.1 — v0.158.0 superseded; controller
v0.318.0; installer 1.33.0; evidence audits/storage-identity-buildB-2026-10-15/; the D3 space check: its SPACE-CHECK.md,
sizes ruled above in §7):
| Section | Built | Where it differs from the text above |
|---|---|---|
| §5 internal place | the root helper felhom-internal-place (bundle) makes pve/felhom-belso by the ruled rule; the installer's step 5b (appliance only) and the signed add_internal_place (an old box) run it; the agent mounts it at /mnt/belso like a drive (kind internal); the controller binds and registers it as the default drive |
the place is made only in appliance mode (a byo host's pool is the owner's); every failing read in the helper refuses (security review of 0.158.0) |
| §6 partitions | each part of a free disk is listed (empty / filesystem / in_use); „format this part", „use this part"; a data-bearing part's wipe id binds disk id + part number + fs-UUID | the „filesystem with no files" state is folded into filesystem (no root read-only mount; the typed confirmation covers both). A part can be formatted only while nothing on its disk is mounted: the root mkfs wrapper refuses any mounted node and deliberately trusts no „it is Felhom's own drive" claim (the agent could fake it — security review of 0.158.0). So a household formats its free parts before using any part; a free part next to an in-use drive can still be USED, not formatted |
| §7 installer | step_grows by the ruled table; step 5b |
the host root is left as Proxmox makes it (SPACE-CHECK §3) |
| §9 old boxes | the signed add_internal_place (no parameters; the size is the rule's) |
— |
Proven live 2026-10-16 (audits/storage-identity-buildB-2026-10-15/README.md): a fresh one-disk install (512 GB VM,
the public installer 1.33.0, agent 0.158.1 and golden 0.318.0 vouched) → data volume 100 GiB, internal place 213 GiB,
registered as the default drive with no press; Jellyfin installed with no extra step onto it; a whole-box copy holds nothing
of it; partitions formatted and used through the wizard; the honest backup offer on a VM. Not as written: an empty part
asks for the typed confirmation (the probe reads the parent's partition table — R-1093) (fixed since in agent v0.160.0:
the parent's PTTYPE is set aside when blkid -p proves the node is a partition of that scheme — git tag --contains f7b7308; noted 2026-10-24); a 200 GB disk gets no internal
place under the ruled sizes (15 GiB < 20).
Also in build B: R-1084 (the whole-box backup offer asks the same-disk question) and R-1082 (/mnt/sys_drive is never
offered to attach, by device). A bundle that adds a path needs a step bundle on boxes with an older wrapper (R16, R-880):
0.158.1 was delivered through 0.158.1-step1.
14. Disk space — every place, its limit, its cleaner, its alarm (D69, decision 288)
What this is. The design of disk space on a box. One line for each place that holds data: what makes it grow, its
limit, what cleans it, and which alarm fires. Written 2026-11-10 from the space list. The evidence is not here — it
is audits/space-list-2026-11-10/ (TABLE.md holds each place with its file:line and its measurement; the place ids
below are the pointers into it). Counts on that day: 45 places; 21 have a name in this folder, 16 a mention, 8 none.
[DESIGN] The rule that keeps this true. A change that adds a place that holds data, or changes the limit, the
cleaner or the alarm of one, changes this section in the same session (PROMPT-TEMPLATE.md §N.5). A place with no
limit is on the list in §14.2 with its ruling, or it has a register row.
14.1 The places [FACT — read and measured 2026-11-10, audits/space-list-2026-11-10/TABLE.md]
The alarms, by short name:
- host disk — the hub's
host_disk_warningat 90 % andhost_disk_criticalat 95 %. To the operator only (D68, decision 287,08-alarm-ladder.md). That is in the hub's source and not in the hub that runs: until the next hub release the household can still get the critical one. - pool — the hub's
storage_fill_warningat 85 % andstorage_fill_criticalat 90 %, on the worse of the pool's data and metadata. To the operator. - data volume — the controller, every 10 minutes: warning at 85 % or under 5 GiB free, critical at 95 % or under 2 GiB. To the household.
- drive — the same watch of the controller, on each registered drive. To the household.
Host system disk (/, the volume pve/root)
| Id | Place | Grows with | Limit | Cleaner | Alarm |
|---|---|---|---|---|---|
| H1 | the system disk as a whole | its parts below (72–82 % of the used bytes) | the size Proxmox gave it; no budget per part (§14.3, R-1370) | each part's own; the whole disk only by the operator's hand (runbooks/disk-full.md) |
host disk |
| H3 | whole-box copies on the current local target | the guest's size (R-1366) | the newest N (default 3) | Proxmox after each good run; the agent removes half-written copies | a skipped run is reported to the hub and shown on the backup page; host disk |
| H4 | whole-box copies on a former target | a move of the target | none (R-1087) | nobody | host disk |
| H5 | guest template archives | each install and re-install | none (R-1368) | nobody; only an uninstall with --remove-golden |
host disk |
| H6 | backup logs and half-written copies | each run | a failed run's log: none (R-1368) | Proxmox; the agent | host disk |
| H7 | the host journal | the agent's sudo calls (R-1367) |
the journald default: 10 % of the disk, at most 4 GB | journald | host disk |
| H8 | other host logs, task logs, graphs | each task | rotation | logrotate, Proxmox |
host disk |
| H9 | old kernels | each approved kernel | the running one, the one before it and the newest: 3 at most, about 3.4 GB (decision 286, 11-os-updates.md §5.11.1) |
the box itself at night, on a ring-0 box (agent v0.174.0); a ring-1 box: nobody yet (needs a ruling) | host disk; a refused or failed clean-up is an operator event |
| H10 | the EFI partition | a boot-loader update | 1.07 GB, 1 % used | none needed | none (R-1371) |
| H11 | the host package cache | each OS update | emptied in each run | the update wrapper | host disk |
| H12 | the agent's self-update folder | each agent update | the running version's binary, and the file of a failed update until the next good one (about 16 MB each; measured 2026-11-10 on three boxes, R-1368) | the agent, at the end of each good update | host disk |
| H13 | old agent binaries | .prev: one file. .bak-*: each re-run of the installer |
none for .bak-* (R-1368) |
nobody | host disk |
| H14 | wrapper state and previous config bundles | each bundle | the last 3 | the wrapper | host disk |
| H15 | host /tmp and /var/tmp |
nothing that lasts | /tmp is in memory: half of memory |
systemd, after 10 and 30 days | none for /tmp (R-1371) |
| H16 | a bare folder under a drive that is not mounted | a write while the drive is away | the write is refused | nothing to clean | storage_disconnected, to the household |
| H18 | swap | fixed | its volume | the kernel | host_swap_short, to the operator |
Thin pool (pve/data)
| Id | Place | Grows with | Limit | Cleaner | Alarm |
|---|---|---|---|---|---|
| H2 | the pool | each block a guest writes | the pool's size; auto-extend is off | the agent's weekly trim (decision 139); a left-over scratch guest: a retry every 10 minutes | pool |
| H17 | the restore test's scratch guest | each restore test | it needs restored size × 1.2 + 5 GiB free, off the tested guest's pool when it can | the agent at the end; a retry every 10 minutes | pool |
Guest root disk (32 GiB; 4–5 % used on three boxes)
| Id | Place | Grows with | Limit | Cleaner | Alarm |
|---|---|---|---|---|---|
| G1 | the root disk as a whole | guest OS updates | 32 GiB; the agent can grow it, never shrink it | the update wrapper, logrotate |
none (R-1371) |
| G13 | app definitions, /opt/docker/stacks |
the catalog's size | under 2 MB measured | an app removal deletes its app.yaml |
none (R-1371) |
| G15 | the guest's system log | each line | the journald default; it is in memory (R-1372) | journald; a restart | none |
| G16 | the guest package cache | each guest OS update | emptied in each run | the wrapper | none (R-1371) |
| G17 | guest /tmp |
nothing that lasts | in memory | systemd; a restart | none |
Guest data volume (mp0, /var/lib/felhom)
| Id | Place | Grows with | Limit | Cleaner | Alarm |
|---|---|---|---|---|---|
| G2 | the data volume as a whole | G3–G12 and G14 | 50 / 100 / 130 GiB (§7; older boxes 70 or 250). A new app is refused under max(5 GB, 10 %) free; a backup is refused at 97 % or under 1 GiB | the three image rules below; the weekly trim | data volume. A box with one volume counts it twice until the next controller release: two warnings for one fill (R-1371) |
| G3 | app images, and one undo image for each app | each install and update | a count: the current and the one before, for each app. No limit in bytes, by ruling (§14.2) | the controller | data volume |
| G4 | old controller images | each controller update | the running one and the one before | the controller | data volume |
| G5 | infrastructure images | a change of the pinned version | the pinned one and the one before | the controller | data volume |
| G6 | helper images (alpine, hello-world) |
pulled once | no version is pinned (R-1372) | nobody | data volume |
| G7 | named app volumes | the app's use | none for each app; the volume's | only an app removal | data volume |
| G8 | volumes with no name | each re-create of a container | none (R-995, R-1267) | nobody | data volume (bytes only) |
| G9 | containers' writable layers; the off-site cache | temporary files; the off-site store's size | none of its own | a re-create drops it | data volume |
| G10 | container logs | each line | 10 MB × 3 for each container | Docker | data volume |
| G11 | the build cache | nothing | empty | — | data volume |
| G12 | the controller's state volume | graph rows; the catalog | rows older than 30 days are deleted | the controller | data volume |
| G14 | backups of apps with no drive (sys_drive) |
dumps | one point for each app; refused at 97 % or under 1 GiB | the nightly replace; moved units are pruned | data volume |
A data drive
| Id | Place | Grows with | Limit | Cleaner | Alarm |
|---|---|---|---|---|---|
| D1 | backups/primary |
dumps | one point for each app. A removed app's kept unit: none, by ruling (§14.2) | the nightly replace; a removal with "delete the backups too" | drive |
| D2 | backups/secondary |
the apps' data | it needs max(2 GB, 20 %) free. A removed app's copy: none, by ruling (§14.2) | the mirror; the household, from the backup page | drive |
| D3 | backups/offsite-restore |
each off-site restore or check | none (R-1372) | the household's delete button | drive |
| D4 | backups/offsite-proof |
one unit a night, for minutes | a headroom check | the proof itself | drive |
| D5 | backups/restore-undo |
each restore | 30 days unused; none under a support hold, by ruling (§14.2) | the controller's sweep | drive; the household is told on a delete |
| D6 | kept |
each "remove, keep my data" | none, by ruling (§14.2) | the household | drive |
| D7 | appdata |
the app's use | the drive | a removal "with data" | drive |
| D8 | userdata |
the household | none, by ruling (§14.2) | the household | drive |
| D9 | shares |
the household's copies | the drive | the household | drive |
| D10 | backups/set-aside |
each re-install that finds a unit | none, by ruling (§14.2) | the household; a removal with "delete its backups too" | drive |
14.2 What can grow without a limit, by ruling [FACT — each line is a ruling, not a defect]
Do not file these as defects (R-370). A change to one is a decision for the operator.
- Undo images: one for each app, no limit in bytes (decision 53).
- The kept data of a removed app: only the household deletes it, with the app's name typed (decision 40).
- The household's own files (decision 67).
- A set-aside backup unit (decision 256).
- A restore's undo copy while a support hold is on it (decision 281).
- The second-drive copy of a removed app (D25).
- The backup unit of a removed app that the household kept (
07-backup-architecture.md§6). - Images in the registry (decision 62). This is not on a box.
14.3 The host system disk — a budget from measured numbers [FACT for the numbers; the smallest disk is RULED, not built — 09 §3 decision 295]
Measured 2026-11-10 (audits/space-list-2026-11-10/evidence/reading-1/, GB = 10⁹ bytes):
| 128 GB disk (demo-hp) | 200 GB disk (Tester 1) | 512 GB disk (N100) | |
|---|---|---|---|
| root volume, as Proxmox made it | 41.4 | 62.9 | 100.9 (the 96 GiB cap) |
| used | 24.0 | 21.6 | 38.1 |
| Proxmox, Debian and all that has no line of its own | 3.3 | 3.2 | 3.4 |
No rule is written here for a size between these three: the Proxmox installer's formula was not read.
What the root needs when the whole-box copies go to a backup drive:
| Part | GB | From |
|---|---|---|
| Proxmox, Debian, small parts | 4 | the last line above |
| kernels: the three the ruling keeps, and one in install | 4.4 | one kernel = 1.02 GB of modules + 0.10 GB in /boot |
| the host journal at its cap | 4.3 | measured on two boxes (H7) |
| one guest template archive | 0.65 | H5 |
| the agent's files, after the self-update fix | 0.1 | H12 (0.75 before the fix) |
| free space an OS update asks for | 0.5 | felhom-os-apply, the free-space check |
| Sum | ≈ 14 |
With the parts nobody cleans today (8 kernels, 49 agent binaries, 4 templates) the same sum is about 21 GB, and it grows by 1.1 GB with each kernel.
What local whole-box copies add. Let C be one packed copy. The copies need keep × C. A new copy also needs
1.25 × C + 1.07 GB free before it starts, because Proxmox prunes only after a good run (A internal/backup/runner.go,
the space check). Measured C: 9.1 GB (demo-hp, 26 containers), 3.15 GB (Tester 1), 1.45 GB (N100).
| Keep | C | Copies + the free space the next one needs | With the 14 GB above |
|---|---|---|---|
| 3 | 3.15 GB | 14.5 GB | 28.5 GB |
| 3 | 9.1 GB | 39.7 GB | 53.7 GB |
| 1 | 9.1 GB | 21.5 GB | 35.5 GB |
What follows from the numbers.
- With a backup drive the root needs about 14 GB. The 41 GB root of a 128 GB disk holds that. The limit is then the pool: a 128 GB disk has a 54 GiB pool, and the guest is promised 32 + 50 GiB of it (§7). That is over-promised by design and it is watched (the pool alarm). The first measured disk whose pool holds 32 + 50 + the 16 GiB reserve is the 200 GB one (113 GiB).
- With no backup drive the root needs 28 to 54 GB at keep 3, by the number of apps. A 128 GB disk holds a small household. It does not hold demo-hp's app set at keep 3. demo-hp keeps 1, and 35.5 GB in a 41.4 GB root leaves little room: a copy that cannot fit is skipped before it starts (R-548). The 63 GB root of a 200 GB disk holds the 54 GB case with 9 GB to spare.
- The installer refuses no disk today, and nothing checks this sum at install time.
Ruled 2026-11-10 (D75, 09 §3 decision 295): the smallest system disk is 200 GB, with or without a backup drive.
One number, because one rule is simpler to promise, and because the pool of a 128 GB disk is smaller than the guest's
promised space even with a backup drive (the first point above). Not built, and not ruled: what the installer does
below 200 GB — refuse, or warn (R-1370). demo-hp (128 GB) stays as a test box.
14.4 Open design points [each has a row]
| Point | Row |
|---|---|
| Nobody watches the guest's root disk (G1, G13, G16). It is 4–5 % used today; app definitions lie on it | R-1371 |
| No alarm for the EFI partition (H10) or for the places in memory (H15, G15, G17) | R-1371 |
A drive in the backup role reports as usb or local-dir. So the household gets the storage_fill mail for a drive it must not clean by hand |
R-1371 |
The hub's first list for a household still holds storage_fill_critical. It is replaced when the box sends its own list. Not measured on the running hub: the release run of 2026-11-10 deployed the hub that blocks the host-disk alarm at send time, but the pages that show a household's list refuse a token („session only"), and no test alarm was made. The proof is the tests and the deployed commit (audits/release-space-fixes-2026-11-10/hub/) |
R-1371 |
| Helper images carry no version; the guest's journal has no stated cap; off-site restores have no limit | R-1372 |
| Old kernels: the clean-up is built for ring-0 boxes (agent v0.174.0); a ring-1 box still keeps every kernel | 11-os-updates.md §5.11.1 |
| The parts of the host disk with no limit and no cleaner (H4, H5, H6, H13) | R-1087, R-1368 |
The smallest disk is ruled (200 GB, 09 §3 decision 295). Nothing enforces it: what the installer does below 200 GB is a written design with a pick (refuse, with one flag for the operator) — §14.5; it waits for the operator's yes |
R-1370 |
| What to do by hand when a disk is full | runbooks/disk-full.md (R-1369) |
14.5 What the installer does on a system disk below 200 GB [FACT — built, not released: installer v1.38.0 on main, not tagged, 2026-11-15] (D75 and D83 = option A, 09 §3 decisions 295 and 308, R-1370; designed 2026-11-14)
The ruling. The smallest system disk is 200 GB, with or without a backup drive. Open: what the installer does below it — refuse, or warn.
Today (read in source, 2026-11-14). The installer reads the free space of the thin pool and WARNS below 120 GiB
(RECOMMENDED_MIN_LVM_GIB, „a recommendation, not a floor”; R-130); the install goes on. It reads no disk size.
A 75 GiB box installed fully on 2026-07-03.
What „the system disk” is, and how its size is read. The disk that holds the pve volume group — the one the
Proxmox installer wrote. Its size is a kernel fact (/sys/block/<disk>/size, in 512-byte sectors), read before
anything is changed. A disk sold as „200 GB” has 200,049,647,616 bytes by the makers' common formula; a virtual disk
made as „200G” has 200 GiB. So the line is 200 × 10⁹ bytes: both pass, a 128 GB or 180 GB disk does not. NOT
MEASURED: no disk's sector count was read for this design; the three test boxes' disks are 128, 200 and 512 GB by
their labels (audits/space-list-2026-11-10/).
The two options.
| A — refuse (CC's pick) | B — warn | |
|---|---|---|
| What the household sees | The install stops before it changes anything: „This machine's system disk is 128 GB. Felhom needs 200 GB.” | The install goes on; one line in the installer's output, and one line on the hub's page for the box |
| What it protects | The promise is one number, and it is true for every box in a household | Nothing by itself: on the public image the installer runs with nobody watching, so a warning in its output is read by nobody |
| What it costs | A household with a 128 GB machine cannot join. That is the ruling's own cost | A 128 GB box gets a pool of 54 GiB for a guest that was promised 82 GiB (16 §14.3); the guest's own space guards read the promise, so only the hub's thin-pool alarm stands before a full pool |
| The way round | One named flag for the operator, --accept-small-disk, that prints the cost and records it (small_disk: true in the install state and on the hub) |
none needed |
CC's pick: A, with the flag. The reasons: the ruling chose one number so that it can be promised; a warning that nobody reads keeps no promise; and the cost of B is paid by the household months later, as a box that stops its local copies. The flag keeps demo-hp (128 GB, a test box by the ruling) and a reinstall of an existing small box possible — by a person who was told.
Edge cases, each with its rule.
| Case | Rule |
|---|---|
| A BYO host (the owner's own Proxmox) | Warn only, never refuse. The disk layout is the owner's; there may be no pve volume group to read. The line names the 200 GB |
| A reinstall of a box that was accepted earlier | The same rule as a new install. The operator's flag is the way |
The size cannot be read (no pve group, an unusual layout, a RAID) |
Appliance: refuse with „cannot read the system disk's size” and name the flag. A refusal that can be explained is better than an install on an unknown disk |
| Two disks: a small system disk and a large second one | The rule reads the SYSTEM disk. The large disk becomes the internal place or a drive; it does not make the system disk larger |
| Exactly 200 GB by the label | Passes (the line is 200 × 10⁹ bytes) |
| A virtual machine (the OMV and test installs) | The same rule on the virtual disk; the tester makes the disk 200 GB |
| The public image, nobody watching | The refusal must reach a person: the box still pairs, and the hub's page for it reads „install refused: system disk 128 GB, needs 200 GB”. Open in the build: today a failed install's reason does not reach the hub's page — to be read before the build |
| The existing 120 GiB pool warning | Stays, as the second check (a 200 GB disk with a small pool is a broken install, not a small disk) |
Where the refusal sits. In the installer's preflight, with the other checks that run before any change, so a
refused machine is exactly as it was. One test per row above in scripts/test_hostinstall.py, the sizes fed through a
seam (no real disk).
Ruled 2026-11-15 (D83): option A, with the flag.
As built (installer v1.38.0, check_system_disk; not tagged, not run on a machine).
| Row of the table above | Built | Test (scripts/test_hostinstall.py) |
|---|---|---|
| An appliance below 200 × 10⁹ bytes | stops, first thing in the preflight; only pvs, lsblk and one /sys/block file were read |
test_small_disk_appliance_is_refused_before_anything_changes, …_check_is_wired_first_in_the_preflight_and_recorded |
| Exactly 200 GB by the label; a virtual disk of 200G | pass; one sector less does not | …_the_line_is_200_times_ten_to_the_nine_bytes |
The flag --accept-small-disk |
goes on, prints the cost, small_disk: true and system_disk_bytes in the install state, "small_disk":true in the enrolment request |
…_flag_goes_on_prints_the_cost_and_marks_it, …_is_told_to_the_hub_at_the_enrolment |
| A BYO host | a warning, never a stop — also when the size cannot be read | …_byo_host_is_warned_never_refused |
| A reinstall of a box that was accepted earlier | the same rule: the check reads no earlier record | the same tests (no state is read by the check) |
The size cannot be read (no pve group, two physical volumes, a RAID, no size) |
appliance: stops and names the flag; with the flag it goes on, recorded as small with size „unknown” | …_size_that_cannot_be_read_refuses_and_names_the_flag |
| A small system disk and a large second one | the system disk decides, in both directions | …_a_large_second_disk_does_not_help |
| The existing 120 GiB pool warning | stays | test_lvm_minimum_is_named_as_what_it_does |
| The public image, nobody watching | NOT built — R-1398. The first-boot unit runs the installer again until it succeeds, so a refused machine prints the refusal on its own screen every 30 seconds; the hub is not told why (R-1398 part 1). The hub's half of the mark is built, not released (2026-11-15 evening): the hub keeps small_disk from the enrolment and the box's page shows „System disk: small — accepted below 200 GB”; the size shows when an installer sends system_disk_bytes (installer 1.38.0 sends only the flag) |
hub TestD83_*, TestSmallDisk_* |
The sentences, as built (the installer's output, English only — the installer has no Hungarian text):
- The refusal: „This machine's system disk is 128 GB. Felhom needs 200 GB. Nothing was changed. (An operator can install a small test box with --accept-small-disk.)”
- The size cannot be read: „Cannot read the system disk's size (no single disk under the 'pve' volume group). Felhom needs a system disk of 200 GB. Nothing was changed. An operator can go on with --accept-small-disk.”
- With the flag: „--accept-small-disk: this machine's system disk (/dev/sda) is 128 GB, below the 200 GB that Felhom needs.” and „The cost: the guest gets less space than a household is promised, and the box's local copies can stop when the disk fills. Recorded as small_disk.”
- A BYO host: „this machine's system disk (/dev/sda) is 128 GB. Felhom needs 200 GB: with less, the local copies of the box can stop when the disk fills. The install goes on (this host is yours).”
For the release session — how the two small machines are installed after this. demo-hp (128 GB): a reinstall
needs --accept-small-disk; the box that runs today is not touched by the rule (the check runs only in an install).
The fresh-install proof VM (64 GiB on 2026-11-15): make its first disk 200G — on a dir storage the file is sparse,
so it costs what is written, not 200 GB — and it then proves the path a household takes, with no flag. One more
proof for that session: the same VM with a 64G disk and --preflight-only must stop with the sentence above, and a
qm config and a disk listing before and after must be equal.
Decisions in code no section records [DESIGN — confirmed by the operator 2026-10-25 (D44 = all picks, R-1265)]
Read at file:line on main by the main session:
systemd-detect-virt --vmis read once per agent process; empty output becomesunknown, which is notnone, so every disk then reads unknown/vm — the fail-closed direction (felhom-agent/internal/storage/identity.go:195-205).- A path the controller cannot read counts as the SAME disk (R-668, v0.269.0): no second copy is ever claimed on
it (
felhom-controller/controller/internal/backup/backup.go:1436-1450). - The internal place („Belső tárhely") refuses eject, decommission and wipe — the controller (
refuseInternalLifecycle) and the agent both — and allows moving its data to another drive (internal/web/internal_place.go:20-26). - The internal place's size subtracts EVERY thin volume already promised in the pool, not only the 32 GiB rootfs and
the data volume (
felhom-agent/configs/felhom-internal-place:11-14).