# 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/` on the host → `/mnt/felhom-drives/`) | `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:`; 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/` [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:::` 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/` → `/mnt/` → 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 = `:part` + 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. ## 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_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 `[DESIGN — proposed, not built]` (the open point of D75, `09` §3 decision 295, R-1370; written 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//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). **If nothing is decided:** the installer accepts any disk, as today; the 200 GB is a sentence in a document. ## 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`).