Files
felhom.eu/documentation/architecture/16-storage-physical-identity.md
T

47 KiB
Raw Blame History

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 in 01: [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 and HDD_PATH apps 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 and sys_drive never 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_drive as the media drive — it is inside mp0, so films enter every whole-guest copy, local and off-site.
  • Grow mp0 without a cap — the same problem, at full size.
  • Keep st_dev and 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.
# 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_dev rule and logs it once.
  • §11 rejects sys_drive for household data, but the drives page still offers /mnt/sys_drive to 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_warning at 90 % and host_disk_critical at 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_warning at 85 % and storage_fill_critical at 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.

  1. Undo images: one for each app, no limit in bytes (decision 53).
  2. The kept data of a removed app: only the household deletes it, with the app's name typed (decision 40).
  3. The household's own files (decision 67).
  4. A set-aside backup unit (decision 256).
  5. A restore's undo copy while a support hold is on it (decision 281).
  6. The second-drive copy of a removed app (D25).
  7. The backup unit of a removed app that the household kept (07-backup-architecture.md §6).
  8. 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 --vm is read once per agent process; empty output becomes unknown, which is not none, 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).