DOCFIX-188: root-cause the OPNsense boot triple-fault -- libvirt memory_unit (guest had 2 MiB)
The 2026-07-12 triple-fault was never a CPU/nesting/machine/console problem.
dmacvicar/libvirt >=0.9 reinterprets `memory` as raw libvirt units (KiB), not
MiB (the 0.8-era meaning the modules were authored against). With no
`memory_unit`, `memory = 2048` rendered `<memory unit='KiB'>2048</memory>` ->
QEMU `-m size=2048k` = 2 MiB. boot2 fits in 2 MiB and echoes /boot.config;
/boot/loader does not -- hence the deterministic 262-byte fault, immune to every
knob the prior window turned.

Measured every hop: module input -> tofu state -> domain XML -> virsh dominfo
(Max memory: 2048 KiB) -> live QEMU cmdline.

FOUNDATIONAL: the identical defect was latent in all three VM modules --
opnsense-edge (live blocker), cloudinit-vm (MAAS/NetBox/GitBucket, the next
step), node-vm (Stage 3). Every VR1 VM would have gotten 1024x too little RAM.

- memory_unit = "MiB" on all three libvirt_domain resources (memory_mib = 2048
  value untouched -- it now means the 2 GiB always intended).
- Corrected the disproven "svm is ROOT CAUSE" comment in opnsense-edge; the
  setting is retained as legitimate hardening, the false claim is not.
- Guard: opentofu-validate.sh S1 + --check-memory-unit flag. `tofu validate`
  cannot catch this (memory_unit is optional => omitting it is schema-valid,
  which is exactly how it shipped). Harness T3 is a true negative test: the
  fixture IS the shipped defect. Harness 1 -> 4 PASS.
- Incident report gains a READ-THIS-FIRST box so nobody re-chases the CPU theories.

Gauntlet ALL GREEN (52 harnesses); repo-lint 0 fail; tofu fmt/validate clean.
Live boot verification remains a separately-gated operator step.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y117t1F525ba9r1vXSBETk
1 parent f5fd4f5 commit 6ad637f9bd80a7cb3688dfd98f0b4acf25825d3b
@JANeumatrix JANeumatrix authored 1 day ago
Showing 10 changed files
View
docs/changelog-20260712-libvirt-memory-unit-rootcause.md 0 → 100644
View
docs/incident-20260712-opnsense-edge-boot-triplefault.md
View
docs/session-ledger.md
View
opentofu/modules/cloudinit-vm/main.tf
View
opentofu/modules/node-vm/main.tf
View
opentofu/modules/opnsense-edge/main.tf
View
scripts/opentofu-validate.sh
View
tests/opentofu-validate/fixtures/s1-bad/main.tf 0 → 100644
View
tests/opentofu-validate/fixtures/s1-good/main.tf 0 → 100644
View
tests/opentofu-validate/run-tests.sh