diff --git a/docs/design-decisions.md b/docs/design-decisions.md index 05268fa..b5700c3 100644 --- a/docs/design-decisions.md +++ b/docs/design-decisions.md @@ -2462,6 +2462,45 @@ `docs/changelog-20260713-office1-dhcp-apply.md` (the 667-element self-heal, measured), D-112 (the (c) ruling and its stated rationale). +### D-113 -- AMENDMENT (2026-07-14): "interfaces: the REST API" IS FALSE. Base-interface addressing has NO API. + +A factual correction to this decision's own text, not a re-ruling. The (a2) rationale above ends +with: *"everything else -- DHCP, firewall, **interfaces**: the REST API."* **The `interfaces` half +of that claim is wrong**, and it was never measured before being written -- it was inferred from +DHCP and firewall being API-native. + +**MEASURED on the live Office1 edge (2026-07-14), OPNsense 26.1:** + +| Surface | Served by | API? | +|---|---|---| +| Interfaces > [LAN] / [WAN] -- **address, incl. `ipaddrv6`** | `/interfaces.php?if=lan` | **NO -- legacy PHP page, config.xml-backed** | +| Interfaces > Devices (bridge/gif/gre/lagg/loopback/vlan/vxlan) | `/ui/interfaces/*` | yes | +| Interfaces > Virtual IPs | `/api/interfaces/vip_settings/*` | yes (`ipalias`/`carp`/`proxyarp`; iface `wan`/`lan`/`lo0`) | +| Services > Router Advertisements (radvd) | `/api/radvd/settings/*` | yes (`getEntry`/`addEntry`/`searchEntry`) | +| Services > Kea DHCPv4 / DHCPv6 | `/api/kea/*` | yes | + +Only the **Devices** and **Neighbors** sub-trees were migrated to MVC. A base interface's IP +addressing was not. So there is no API call that sets LAN's `ipaddrv6`. + +**What this does and does NOT change:** + +- **It does NOT reopen (a2).** The prohibition D-113 actually adopted is on **hand-authored + `config.xml` and full rendered pushes** -- the clobber path that would wipe the API-managed DHCP. + D-113 also records **"GUI access is a REQUIREMENT"** as the constraint that eliminated VyOS and + plain-Linux. A one-time operator GUI edit is therefore the vendor interface this decision + deliberately PRESERVED. It is not a violation and must not be described as one. +- **It DOES mean the provisioning chain is not 100% API-scriptable** for any surface that needs a + base-interface address -- which is every edge that gets IPv6, i.e. Office1 now and the DC0/DC1 + edges at Stage 3. That is a per-edge manual step unless the VIP path below works. + +**The open question (an EXPERIMENT, not a plan):** the `radvd` entry model has **no prefix field** +-- it derives the advertised prefix from the interface's configured IPv6. Whether an **`ipalias` +VIP** counts as "the interface's configured IPv6" for OPNsense's radvd config generator, or whether +the generator only reads the primary `ipaddrv6`, is **UNKNOWN and must not be assumed**. If the VIP +path works, the whole IPv6 edge build is API-native and reproducible per DC. If it does not, the +LAN GUA is an operator GUI step at every edge. This is cheap and reversible to test on the lab edge +and is gated on an operator ruling. + --- ## D-114: VR1 site containment VMs + MAAS-composed LXD VMs for the non-stack machines