Changelog 2026-07-09 -- opnsense-edge module + prep scripts (DOCFIX-146)

No live infrastructure touched -- unapplied IaC/scripts only. Implements the mechanism identified in the same-day OPNsense deployment research (docs/changelog-20260709-opnsense-research.md).

Items

1. DOCFIX-146 -- scripts/opnsense-prep-image.sh

FILE (new): scripts/opnsense-prep-image.sh + tests/opnsense-prep-image/run-tests.sh.

WHAT: downloads the OPNsense nano image, decompresses it, converts raw -> qcow2, and grows it -- the preprocessing libvirt_volume's create.content.url can't do itself (it almost certainly performs a plain fetch, no decompression). No mirror URL is hardcoded -- OPNSENSE_MIRROR_BASE is a required env var (hard rule 2: never use an inferred value; OPNsense publishes multiple mirrors and a silently-hardcoded one risks going stale unnoticed).

HARNESS: 4/4 green, but only the guard-clause paths this environment can exercise -- qemu-img is genuinely absent here, so that failure path is real, not synthetic; the actual download/convert/resize behavior is UNTESTED (would need qemu-img + network access to a real mirror).

2. DOCFIX-146 (cont.) -- scripts/opnsense-build-config-iso.sh

FILE (new): scripts/opnsense-build-config-iso.sh + tests/opnsense-build-config-iso/run-tests.sh.

WHAT: builds a plain ISO9660 image containing /conf/config.xml, for OPNsense's Configuration Importer (see the OPNsense research changelog -- ISO9660 support was added to the Importer specifically for VM/cloud automation). Uses genisoimage/xorriso, whichever is present.

HARNESS: 3/3 green, same caveat -- neither ISO tool is present in this environment, so the missing-tool guard is exercised for real, but the actual ISO construction and whether OPNsense's Importer picks it up on a real boot are UNTESTED. The exact genisoimage/xorriso invocation is a reasonable, standard construction for a plain ISO9660 volume with one file at a fixed path -- not independently verified.

3. DOCFIX-146 (cont.) -- opentofu/modules/opnsense-edge

FILES (new): opentofu/modules/opnsense-edge/{main,variables,outputs}.tf.

WHAT: one OPNsense edge VM per call. Mechanically identical to modules/cloudinit-vm's shape (a backing_store overlay disk + a secondary volume attached as cdrom), but with the config-seed volume's create.content.url pointing directly at the ISO9660 file built by script 2 above -- no libvirt_cloudinit_disk resource involved (that's NoCloud-format, wrong for this). Two explicit variables, lan_network_name and wan_network_name, rather than a generic ordered list -- OPNsense's own interface-1-is-LAN/interface-2-is-WAN convention makes list-ordering a real silent-mistake risk, so the names are explicit instead. No PXE boot-order attribute used (unlike node-vm): this VM boots from its own pre-installed disk, not over the network, so the field flagged UNVERIFIED in node-vm/main.tf doesn't need touching here at all.

TWO THINGS FLAGGED, NOT PRESENTED AS FACT: (a) whether the Configuration Importer's ISO9660 support behaves as described on a real boot -- the research is well-sourced (a closed, milestone-targeted, core-developer- assigned GitHub issue plus a corroborating later bug report) but not independently tested this session; (b) whether devices.interfaces list order reliably maps to which NIC FreeBSD/OPNsense enumerates first vs. second -- assumed consistent with general libvirt XML ordering, not independently confirmed for this specific guest OS.

config_iso_path has no default and no fallback: the real config.xml content for any site's LAN/WAN/routing role is design work that hasn't happened. Not instantiated in root main.tf.

opentofu/README.md updated: the "Scope of this delivery" and OPNsense research sections both now describe this as BUILT (not just researched), with the schema notes section gaining a new entry on create.content.url accepting local filesystem paths (the mechanism both new scripts' outputs rely on, inferred from examples/alpine_cloudinit.tf's libvirt_cloudinit_disk.path usage, not independently named in the docs pages fetched this session). Workflow doc gap register item 4 and its summary-table row updated to match; companion visual tracker (same Artifact URL) redeployed.

REVERT: git rm -r opentofu/modules/opnsense-edge scripts/opnsense-prep-image.sh scripts/opnsense-build-config-iso.sh tests/opnsense-prep-image tests/opnsense-build-config-iso; revert the opentofu/README.md and workflow-doc sections if reverting fully.

Next actionable step

Same underlying need as DOCFIX-144/145: a machine with the tofu binary, qemu-img, and genisoimage/xorriso to actually run the full chain -- opnsense-prep-image.sh for real, opnsense-build-config-iso.sh for real, then tofu apply the module and boot it, to confirm the Configuration Importer's ISO9660 behavior and the LAN/WAN interface-ordering assumption against a real OPNsense instance rather than sourced-but-unverified research.