# opentofu/templates/ -- the OPNsense config.xml template is DELETED (2026-07-13)

`opnsense-config.xml.tmpl` **no longer exists.** Neither do `scripts/opnsense-render-config.sh`
(the renderer) or `scripts/opnsense-build-config-iso.sh` (the config-seed ISO builder). If you
came here looking for them, this is why -- and what to use instead.

## Why they are gone

**Hand-authoring the appliance's GUI-owned `config.xml` was the single root cause of every
OPNsense-specific bug this project has had:**

| bug | what hand-authored XML did |
|---|---|
| DOCFIX-191 | the rendered config had no sshd and no key -- it would have **locked management out** |
| DOCFIX-192 | the rendered config silenced the edge's **only console** (no serial, no video) |
| DOCFIX-193 | LAN DHCP was never implemented -- and an old-style ISC `<dhcpd>` block would have been **inert**, because OPNsense 26.1 uses **Kea** |
| 2026-07-13 | a full-config push **drops ~667 migration-populated elements**, including the only 2 firewall pass rules on the box. It survives only because OPNsense silently regenerates them -- an undocumented self-heal we were depending on |

**None of those is expressible through the REST API,** where sshd, DHCP and firewall rules are
typed resources with defaults. You cannot forget to enable sshd in a format where sshd is a typed
field.

**And the config-seed ISO never worked at all.** Per **D-112**, the OPNsense Configuration
Importer can NEVER fire on a pre-installed nano image: `opnsense-importer -b` probes for a
read-only root, finds a writable one with a factory `/conf/config.xml` already present, and exits
without enumerating a single device. Nothing was ever going to read that ISO. It cost a full
session on 2026-07-12 to discover.

## What to use instead (D-113(a2), ADOPTED + PROVEN 2026-07-13)

Edge configuration is done over the **OPNsense REST API**. The provisioning chain has **no
`config.xml` in it anywhere**:

    boot the factory nano image
      -> D-112(c) console bootstrap             (enable SSH + install the service key)
      -> scripts/opnsense-bootstrap-apikey.sh   (mints an API key via OPNsense's OWN model --
                                                 no GUI click, no re-implemented crypto)
      -> scripts/opnsense-api.sh                (DHCP, firewall, interfaces -- everything else)

Proven end to end against the live Office1 edge on 2026-07-13, read AND write:
`docs/changelog-20260713-opnsense-api-proven.md`,
`docs/changelog-20260713-opnsense-api-write-proven.md`,
`docs/changelog-20260713-opnsense-apikey-bootstrap.md`.

## If you are tempted to bring the template back

Don't. A `config.xml` renderer is not a safety net -- it is a loaded gun pointed at a live
router. On 2026-07-13 the repo still contained runbook steps telling an operator to render a
config and push it to the edge, which by then would have **clobbered live API-managed DHCP**
(see `docs/changelog-20260713-config-xml-danger-sweep.md`).

The governing decision is **D-113** (`docs/design-decisions.md`). If you believe the API cannot
express something the edge needs, that is a finding worth raising against D-113 -- not a reason
to hand-write XML.

Deleted in: `docs/changelog-20260713-config-xml-path-deleted.md`. The files remain in git history.