# Changelog 2026-07-09 -- OPNsense deployment research

Research delivery, not a script/code change -- no live infrastructure touched,
no DOCFIX number assigned (matches the `changelog-20260709-dc-dc-design.md`
precedent for design/research-only deliveries).

## Item

### 1. OPNsense deployment mechanism researched against OPNsense's own docs/forum/GitHub
FILES: `opentofu/README.md` (new dedicated section, sourced),
`docs/dc-dc-deployment-workflow.md` (gap register item 4, summary table).

WHAT: closes the open question from DOCFIX-145 -- whether `modules/
cloudinit-vm` applies to OPNsense. It does not (confirmed, not just hedged):
OPNsense's own forum consensus is that FreeBSD's cloud-init support "is not
great yet." But there IS a real, officially documented alternative that uses
the exact same mechanical shape already built:

- The **Configuration Importer** (official docs) runs in a 2-3 second
  boot-time window, scanning an attached volume for `/conf/config.xml`.
  Supported filesystems: GPT, MBR, ZFS pool, msdosfs (FAT).
- **ISO9660 support was added to the Importer specifically for VM/cloud
  automation** -- a closed, milestone-targeted, core-developer-assigned
  GitHub issue requested it explicitly so a config ISO could be attached as
  a secondary CD-ROM ("shared one to many"). A later bug report confirms the
  behavior is live in current code (exact shipped version not pinned from
  the 22.7 changelog text directly -- the later bug report is the stronger
  signal; confirm on a real boot before relying on it).
  This means: same mechanical pattern as `cloudinit-vm` (a secondary volume
  attached as a `cdrom` disk), different payload (a plain ISO9660 image with
  `/conf/config.xml`, not a NoCloud seed).
- A deeper `autorun` hook (`/usr/local/etc/rc.syshook.d/import/`) exists for
  more advanced provisioning beyond a static config.xml.
- **Use the nano image for KVM**, not the vga/serial/dvd installer images --
  pre-installed, serial-console-ready, auto-expands on first boot. Confirmed
  real-world workflow: download `.img.bz2` -> `bunzip2` -> `qemu-img convert
  -f raw -O qcow2` -> `qemu-img resize` -> boot via libvirt with a FreeBSD
  os-variant, serial console, no graphics.
- Network convention: interface 1 = LAN (default 192.168.1.1), interface 2 =
  WAN -- order matters, same instinct as `node-vm`'s PXE-boot-priority design.

All findings sourced with URLs in `opentofu/README.md`'s dedicated section
(docs.opnsense.org, the OPNsense forum, opnsense/core GitHub issues, and one
independent KVM how-to + one community VM-image-building project used for
cross-corroboration).

WHAT STILL NEEDS BUILDING (not done this delivery, itemized so it's a
punch-list not a vague "TODO"):
1. A preprocessing script for the nano image's decompress+convert step --
   `libvirt_volume`'s `create.content.url` almost certainly does a plain HTTP
   fetch with no decompression, so the `.img.bz2` can't be consumed directly;
   the qcow2 needs to exist before OpenTofu sees it.
2. A way to build a plain ISO9660 image containing `/conf/config.xml`
   (`genisoimage`/`xorriso` -- exact tool/flags not yet verified against a
   real build) to feed a `libvirt_volume`'s `create.content.url`, the same
   way `libvirt_cloudinit_disk.path` feeds `cloudinit-vm`'s seed volume today.
3. The actual `config.xml` content for OPNsense's LAN/WAN/routing role at
   each site -- real design work, not started.

REVERT: `git checkout HEAD~ -- opentofu/README.md docs/dc-dc-deployment-workflow.md`.

## Next actionable step

Build the OPNsense-specific module (working name: `modules/opnsense-edge`)
once items 1-3 above are ready, following the now-confirmed pattern. Verify
the ISO9660 Importer behavior on a real boot as part of that work, not before
-- this research pins down the mechanism with reasonable confidence but the
module build is where it gets tested for real.