diff --git a/docs/design-decisions.md b/docs/design-decisions.md index d5f1924..584a834 100644 --- a/docs/design-decisions.md +++ b/docs/design-decisions.md @@ -2167,9 +2167,53 @@ ## D-112: OPNsense edge config delivery -- the Configuration Importer cannot work on a nano image -**Status:** PROPOSED 2026-07-12. Operator ruling required -- this replaces the config-delivery -mechanism of a BUILT surface (`opentofu/modules/opnsense-edge` + `scripts/opnsense-build-config-iso.sh`). -Options are presented; none is implemented. +**Status:** ADOPTED 2026-07-12 -- **option (c), post-boot network provisioning.** Operator ruling: +"C since it is the way people automate opnsense" -- prefer the mainstream, industry-standard +automation path (the OPNsense REST API, as used by `opn-cli` and the Ansible OPNsense collection) +over a bespoke image-bake or media-import trick. Consistent with the standing "transferable answers +beat quick fixes" constraint: a real Roosevelt edge is provisioned over the network too. + +IMPLEMENTATION NOT STARTED. The BOOTSTRAP sub-problem below is unsolved and is itself unruled -- +"push the config over the API" is not reachable from a factory-default OPNsense without first +solving how we authenticate and how we reach it. Do not start building until B1/B2 are ruled. + +**Bootstrap problem (measured/sourced, must be solved BEFORE any config push):** +1. **No route to it.** Factory-default OPNsense serves LAN on `192.168.1.1/24` on `office1-local`. + `office1-local` is an ISOLATED libvirt network -- the vcloud host has NO leg on `virbr2` + (measured: no IPv4 on the bridge). So nothing can currently talk to the edge's LAN at all. + The WAN side is reachable at the DHCP lease `172.30.1.126`, but OPNsense **blocks all inbound on + WAN by default** -- so the WAN leg is NOT a way in. +2. **No credentialed API.** The OPNsense REST API authenticates with an **API key + secret**, not the + root password. Keys are minted in the GUI -- a chicken-and-egg for a fresh box. SSH is + **DISABLED** in the factory default, so `ssh` is not an entry point either. +3. **Our serial console is write-only.** `modules/opnsense-edge` attaches `` -- + a one-way capture. It CANNOT be typed into, so the console is not currently an entry point + either. Making it interactive means `type='pty'` + `virsh console` (a module change + recreate). + +**Unruled sub-choices (operator, next session):** +- **B1 -- how do we REACH it?** (i) temporarily add a host leg on `virbr2` + (`ip addr add 192.168.1.10/24`) -- reversible, non-persistent, cheapest; or (ii) give + `office1-local` a permanent host address in the OpenTofu network definition (touches D-100's + network design); or (iii) drive it entirely over an interactive serial console and never need IP + reachability for bootstrap. +- **B2 -- how do we AUTHENTICATE the first time?** (i) interactive serial console (`type='pty'`) -> + root login -> enable SSH + install the ed25519 pubkey we already generated in + `~/vr1-office1-creds/`, after which everything is plain SSH/SCP and fully scriptable; or + (ii) authenticated GUI session with the default root credentials (curl + CSRF token) to mint an + API key, then use the REST API proper. + NOTE: (i) is console-driven but is NOT the rejected option (d) -- (d) was rejected for racing the + importer's 7-second timeout. A console *login shell* has no timing race and can be driven at + leisure. These are materially different risks; do not conflate them. + +**Once bootstrapped, the steady-state mechanism is:** push `config.xml` (or the equivalent API +calls) to the edge, reload, and verify. The config we already render (`opnsense-config.xml.tmpl`, +LAN `10.10.0.1/24` + DHCP `.100-.199`, WAN static `172.30.1.2`) is REUSED unchanged -- only the +DELIVERY changes. + +**Consequently RETIRED (do not delete until (c) actually works):** the config-ISO delivery path -- +`scripts/opnsense-build-config-iso.sh` + its harness, and the module's `config_seed` volume + cdrom +disk. They are inert (the Importer never reads them), not harmful. Remove them in the same change +that lands (c), not before. **Finding (MEASURED, not inferred).** The Office1 edge boots (DOCFIX-188 memory + DOCFIX-190 ACPI) but comes up on FACTORY DEFAULTS. The config ISO is well-formed and correctly attached -- verified: diff --git a/docs/session-ledger.md b/docs/session-ledger.md index 11d9b4f..19b77b7 100644 --- a/docs/session-ledger.md +++ b/docs/session-ledger.md @@ -1835,11 +1835,24 @@ - The README research (items 2-3) correctly established the Importer supports ISO9660; it NEVER established the Importer RUNS on a nano. The module's own UNVERIFIED flag was right, and is now discharged NEGATIVE. - - **Options in D-112 (operator picks):** (a) bake config.xml into the image in prep-image - [cleanest; UFS2-write-from-Linux feasibility UNPROVEN -- must verify first]; (b) switch nano -> - installer image [the ISO mechanism then works AS DESIGNED, unchanged]; (c) boot factory-default - then push config via API/SSH over office1-local [most Roosevelt-transferable]; (d) serial expect - scripting [NOT recommended -- 7s timeout, fragile]. + - **D-112 RULED: option (c)** -- post-boot network provisioning (operator: "C since it is the way + people automate opnsense"). The rendered config (`opnsense-config.xml.tmpl`) is REUSED + unchanged; only the DELIVERY changes. IMPLEMENTATION NOT STARTED. + - **SELF-CORRECTION (flagged to operator before the ruling):** I had described option (b) as + making the ISO mechanism "work as designed, unchanged". That was OVER-CLAIMED. Even with a + read-only root the importer prompts "Press any key..." with a 7s timeout and then asks for a + device name -- i.e. it appears INTERACTIVE BY DESIGN, so (b) may have been (d) in disguise. Not + verified either way; recorded so nobody revives (b) on my bad summary. + - **BOOTSTRAP PROBLEM -- UNSOLVED, gates (c), sub-choices B1/B2 UNRULED (see D-112).** "Push the + config over the API" is NOT reachable from a factory-default box: (1) NO ROUTE -- default LAN is + 192.168.1.1/24 on `office1-local`, which is an ISOLATED libvirt net with NO host leg on virbr2 + (measured); WAN is reachable at 172.30.1.126 but OPNsense BLOCKS ALL INBOUND ON WAN by default, + so that is not a way in. (2) NO CREDENTIALED API -- the REST API needs an API key+secret (not + the root password), minted in the GUI; and SSH is DISABLED by default. (3) OUR SERIAL IS + WRITE-ONLY -- the module attaches `` (one-way capture); it cannot be typed + into. Making it interactive = `type='pty'` + `virsh console` (module change + recreate). + NOTE: a console *login shell* is NOT the rejected option (d) -- (d) was rejected for racing the + importer's 7s timeout; a login shell has no timing race. Do not conflate them. - Impacts if not (b): `opnsense-build-config-iso.sh` + harness, the module's config_seed/cdrom, the README research section. ALSO GATES STAGE 3 (per-DC edges use this same module). - **Numbers:** D next-free 113, DOCFIX next-free 191.