Changelog 2026-07-09 -- OPNsense config.xml design (DOCFIX-149)

No live infrastructure touched. Real design work, not a placeholder -- researched OPNsense's own real, currently-shipped config.xml before drafting, per this session's established discipline.

Item

1. DOCFIX-149 -- opentofu/templates/opnsense-config.xml.tmpl + renderer

FILES (new): opentofu/templates/opnsense-config.xml.tmpl, opentofu/templates/README.md, scripts/opnsense-render-config.sh, tests/opnsense-render-config/run-tests.sh.

WHAT: a {{TOKEN}}-parameterized OPNsense config.xml template (this repo's existing clientdocs token convention, reused rather than inventing a new one), covering system/interfaces/gateway/staticroutes/DNS/NTP and D-107-shaped firewall rules (default-deny WAN egress except NTP + the per-DC mirror's upstream sync -- the two exceptions D-107 names). Paired with scripts/opnsense-render-config.sh, which substitutes tokens from required environment variables (no invented defaults except the NTP pool, which defaults to the exact same public pool OPNsense's own sample ships -- a real, confirmed default, not an invention) and feeds the result to the already-existing scripts/opnsense-build-config-iso.sh -> ISO9660 -> modules/opnsense-edge pipeline.

VERIFICATION: built directly from OPNsense's own real config.xml.sample (opnsense/core's repo, src/etc/config.xml.sample) fetched and read as real content, not summarized -- the same discipline that caught the DOCFIX-142 syntax bug and the DOCFIX-148 LAN/WAN documentation error. This fetch also DIRECTLY CONFIRMED the DOCFIX-148 audit finding: the real sample ships literal placeholder device names (mismatch0/mismatch1) inside each interface's own <if> element, proving LAN/WAN role assignment is exactly the per-block explicit mapping DOCFIX-148 concluded it was, now with a real example rather than research-by-inference. The staticroutes schema was confirmed from opnsense/core's own Route.xml MVC model file (the actual schema-defining source, not a doc page) -- network/gateway/descr/ enabled fields, and gateway must reference a named gateway object (hence the template's own <gateways><gateway_item name="WAN_GW"> addition, which the stock sample doesn't need since it uses DHCP).

TESTED END-TO-END, not just guard clauses: unlike every other opnsense-* script this session, opnsense-render-config.sh needs no external tool (pure bash + template substitution), so its harness (8/8) exercises the real behavior -- happy path, well-formed-XML output (verified with python3 -m xml.dom.minidom), the NTP real-default fallback, one static route rendering while an unset second slot correctly emits nothing, and three failure paths.

A real bug the harness itself caught: the token HOSTNAME collides with bash's own built-in $HOSTNAME variable -- unset HOSTNAME does not actually clear it (bash repopulates it), so a "missing required token" test that should have failed instead silently passed with the shell's own system hostname. Renamed to OPNSENSE_HOSTNAME throughout (template, script, docs, tests) before this shipped, not after.

WHAT'S STILL NOT REAL: opentofu/templates/README.md's token legend marks each token's status precisely -- several cannot be filled with a genuine value yet because the decision they depend on is still PROPOSED (D-100/D-101/D-107's WAN addressing, LAN plane assignment, mirror software choice), and two (WAN_IF/LAN_IF) are only measurable on a real boot (which vtnetN a network becomes). ROOT_PASSWORD_HASH must be freshly generated per deployment -- the stock sample's own shipped hash is a well-known default and must never be reused verbatim.

opentofu/README.md's OPNsense research section and gap register item 4 in docs/dc-dc-deployment-workflow.md (+ its summary table, + the companion visual tracker) updated to reflect this as BUILT (the mechanism and the tested renderer), not just the still-pending final values.

REVERT: git rm -r opentofu/templates scripts/opnsense-render-config.sh tests/opnsense-render-config; revert the opentofu/README.md and workflow-doc sections if reverting fully.

Next actionable step

Two independent things still block a real per-site config.xml: (1) Stage 0 ratification of D-100/D-101/D-107 (WAN addressing, LAN plane assignment, mirror software choice) -- a decision, not a build task; (2) a real boot to measure vtnetN device assignment before setting WAN_IF/LAN_IF. Neither needs more OpenTofu/script work -- the mechanism is done and tested.