CEDILLE/opnsense-cloudinit
11
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions
Page: Testing New Releases
Pages
Architecture Development Extension Reference Home Testing New Releases Usage
1 Testing New Releases
Louis Raymond edited this page 2026-08-19 13:48:46 -04:00
Table of Contents

Testing against a new (or different) OPNsense release

This project pins a specific OPNsense ISO (iso/fetch-iso.sh, packer/variables.pkr.hcl) and a specific Python package ABI (packer/provisioners/10-install-hook.sh). Both are the kind of thing that silently drifts whenever OPNsense ships a new release. This is the procedure for finding out what changed before it becomes a production surprise.

The current pinned version (26.7) is a snapshots-branch build, not a stable numbered release — the first thing worth doing is running this procedure against an actual stable release (25.7 or 26.1 at the time of writing) to see how much of what's currently pinned is snapshots-specific.

What actually drifts between releases

Area Where it's pinned Symptom if stale
Installer TUI flow packer/opnsense.pkr.hcl boot_command Packer build hangs or misfires partway through; see Development
Python package ABI (py313-*) packer/provisioners/10-install-hook.sh pkg install fails outright — loud, not silent
config.xml schema/defaults base/config.xml Golden-file test mismatches beyond the known UUID/cert noise; possible silent misconfiguration if a transformer assumes a field that moved
rc.syshook early-stage ordering guest hook placement Seed applies too late (after rc.bootup already ran the console wizard)

Procedure

  1. Point the pipeline at the new version.

    • iso/fetch-iso.sh: update ISO and MIRROR to the target release.
    • packer/variables.pkr.hcl: update iso_path/iso_checksum defaults (or pass -var overrides instead of editing defaults, if only testing).
    • Check https://pkg.opnsense.org/FreeBSD:14:amd64/<branch>/latest/All/ for the current py3NN-lxml/py3NN-pyyaml/py3NN-passlib package names; update 10-install-hook.sh if the ABI moved.

  2. Build the image, watching closely.

    make iso
make image

    If the installer TUI changed shape, boot_command will misfire partway through rather than fail cleanly — the build hangs at a <wait> that never gets the screen it expects. There is no monitor socket on a Packer-managed QEMU process to screenshot; if this happens, drive a throwaway VM by hand first (qemu-system-x86_64 -vnc :0 -cdrom <iso>, watch over VNC) to see what actually changed, then adjust boot_command to match and update the walkthrough in Development.

  3. Diff the new base config against the previous one.

    cd opnseed
python3 -m opnseed.cli diff <previous-base.xml> ../base/config.xml

    Keep the previous version's base/config.xml around for this (e.g. git show <previous-tag>:base/config.xml > /tmp/prev-config.xml). Expect noise (assigned UUIDs, a cert reference) — look past that for anything structural: renamed/moved elements, new required fields, changed defaults. If a transformer (opnseed/src/opnseed/transformers/) assumes a field's location or default, this is where that assumption breaks.

  4. Run the test suite against the new base config.

    make test-opnseed

    Golden-file tests (tests/golden/*.xml) will likely fail on the expected UUID/cert noise from a fresh build — delete and let them regenerate if that's the only difference. Anything else is a real regression to investigate before moving on.

  5. Do one real end-to-end boot. Unit tests only check what opnseed would write; they don't confirm OPNsense itself still accepts it. Boot the new image with a seed attached (make seed-example + local QEMU, or a throwaway Proxmox clone — see Development and Usage) and confirm: seed applies, WAN/LAN bind to real devices, config.xml (not rc.conf) holds the result, GUI/SSH reachable, no console wizard, idempotent on reboot.

  6. Record the result in the log below and commit the version bump (ISO pin, package names, base/config.xml) as one change once everything passes.

Scope note

This procedure validates provisioning — that opnseed still correctly turns a seed into a working config.xml on the new release. It deliberately does not cover whether opnseed or its rc.syshook hook survive an in-place opnsense-update on an already-provisioned, already-managed VM: once a VM is seeded and handed off to its normal config-management path (Ansible, etc. — see Architecture), opnseed's job is done, and it's fine if a later major upgrade removes or breaks it.

Verified versions

OPNsense version Branch Date Notes
26.7 snapshots 2026-08 Baseline. Python 3.13 (py313-*); no stable numbered release existed yet at pinning time.

Home