RFC: Settings Profile — configuration that survives major upgrades (export intent, flash clean, regenerate)

[ispyisail]

Status: Ready for review · companion to #62 (signed OTA upgrade) · Updated: cross-hardware portability promoted to a first-class goal — the board.json capability check and the Applied/Adapted/Deferred/Dropped import report (see "Cross-hardware: the capability check and the import report"). Earlier updates: fleet-scaling argument, role-based hardware mapping, legacy converter, fixed-point testing.

The problem

Every major Gargoyle upgrade today effectively means reconfiguring the router from scratch — and moving your settings to a different router model means the same thing. Backup/restore and sysupgrade's keep-config path both preserve the raw /etc/config files, and raw config varies along three independent axes that a raw restore silently assumes all match:

1. Hardware topology — LAN might be br-lan over eth1 eth2 eth3 with WAN on eth0.10 on one box; on an MT6000 the same roles are lan1..lan4/wan. Restore across models and those device names don't exist → no LAN → unreachable router (the same class as the live LAN2-vs-lan2 VLAN lockout).
2. Firmware schema — across a major OpenWrt bump: swconfig→DSA, iptables→fw4, ipset→nft sets, scalar ipaddr→CIDR list, hwmode→band.
3. Capability / feature set — the source router may have tri-band wifi + QoS + Tor + OpenVPN; the target may have none of them.

So the safe advice becomes "don't keep settings," and users pay for every major upgrade — or every new router — with their entire configuration. That is a real adoption blocker: a router you must re-program twice a year loses to stock firmware that upgrades in one click.

The idea: preserve intent, not files

The raw UCI files are an implementation detail of one firmware version on one box. What the user owns is their intent: "LAN is 192.168.12.1/24, SSID is X with key Y, these six port forwards, this QoS shape." Every release already contains code that renders that intent into its own native config — the GUI's save paths. This RFC gives that intent a stable, versioned file (gargoyle-profile.json) with zero hardware facts in it, and makes upgrades regenerate config from it instead of carrying files forward:

check → download → verify → EXPORT PROFILE → sysupgrade (clean config)
      → first boot: import profile → boot already configured

Because the profile is hardware-free, the same mechanism that survives a version bump also carries a config onto a different model — cross-version and cross-hardware are one design, not two. This is the model pfSense/OPNsense, FRITZ!Box and MikroTik all use — none carry raw backend state across versions.

Why not chained migration scripts?

The obvious alternative (preserve raw config + migrations/NNN.sh transforming it version-by-version) was considered and rejected: every upstream schema change must be modeled twice forever, chains break on skipped versions, and it's untestable against configs nobody anticipated. With the profile approach, each release maintains only its own generators (code that must exist anyway for the GUI) plus tolerant JSON readers — and version skipping is free by construction, because importers translate intent to the running schema, never old-schema to new-schema. 1.13→1.15 is exactly the same code path as 1.14→1.15.

Cross-hardware: the capability check and the import report

"Restore on any compatible router as if native" is achievable — but only honest if the importer can tell what the target can actually do, and report what it couldn't. Two pieces make that work.

The capability oracle already ships. Every OpenWrt device carries /etc/board.json — a machine-readable model of that exact box: the port topology (which named roles physically exist) and, per radio, the supported bands (2G/5G/6G), the PHY modes (ht/vht/he/eht), the max channel width, and the legal channel list. On import, each fragment is checked against board.json before it's applied — so the importer knows, per target, whether it can do 6 GHz, 160 MHz, WPA3, or a given port, rather than writing config that silently fails. We read the abstraction OpenWrt maintains per-model; we don't replicate it (the same O(features) property the fleet-scaling argument relies on).

Every field has a portability tier — the spec for what each importer does on a mismatched target:

Tier	Examples	On a mismatched target
1 · Portable verbatim	hostname, timezone, admin password hash, DHCP ranges + leases, port forwards, firewall/restriction/quota rules keyed by IP/MAC, DDNS, SSID + passphrase	applies identically everywhere — most of a typical config
2 · Role-mappable	LAN/WAN assignment, per-port VLAN membership by role name (lan2)	mapped through the target's own port inventory; degrades when port count differs (VLANs on lan3/lan4 → 2-port router drops them)
3 · Capability-gated	6 GHz band, 160 MHz width, WPA3/SAE, DFS/regulatory channels	checked vs board.json; degrades to nearest-valid — the SSID + key always survive ("6 GHz SSID → 5 GHz"; "160 → 80 MHz")
4 · Feature-gated	QoS, Tor, OpenVPN, WireGuard, USB/DLNA	if the plugin is absent, held aside, not dropped ("config saved — install the plugin, then Apply")
5 · Never carried	device names, phy paths, MACs, safe_apply snapshots, lease file, counters	regenerated fresh; carrying these is what bricks — excluded from export

The import is a report, not a silent best-effort. Every fragment resolves to exactly one of four outcomes, assembled into a reviewable checklist (persisted to /etc/gargoyle/import-report.json, surfaced in the pending-import banner below):

• Applied — landed natively, unchanged.
• Adapted — applied with a capability-forced change (with the reason).
• Deferred — correct, but the target lacks the software; held for a later install.
• Dropped — physically impossible on this target (with the reason).

Applied needs no attention; the other three are the warnings. Design rule: an importer must classify into one of the four — never half-apply-and-move-on. "The backend applied it" and "the setting survived, or the user was told it couldn't" are different claims; the report enforces the second. This is the honest core — "as if native" is literally true only for Tiers 1–2. You cannot restore a 6 GHz SSID onto a dual-band router; the truthful outcomes are adapt or tell the user, and the report makes each one a line item instead of a silent failure. (pfSense does exactly this: a cross-hardware restore drops you into an interface-assignment screen — that prompt is precisely the Tier-2 report.)

Scaling to the real fleet (hundreds of models, memory classes, ancient installs)

The design's central scaling property: per-model knowledge lives in code that already exists and that someone else already maintains per-model.

• The profile contains zero hardware facts — no device names, no partition info, no radio paths — so the profile layer is O(features) work, not O(models × versions). The rejected migration-chain approach scales O(models × versions) and would genuinely collapse under a real fleet; this is exactly why it was rejected.
• Importers run on the target device, under the new firmware, using the same logic the GUI uses — which already knows the hardware through OpenWrt's board layer (board.json, ubus call system board). OpenWrt maintains that abstraction across all its boards; we ride it rather than replicate it.
• Hardware references are role-based, and mapping is the importer's job (Tier 2 above). The profile says "lan2" or "the 5 GHz radio," and the importer maps that through the current firmware's own port/radio inventory. This matters even for a same-device upgrade: swconfig's eth0.1 became DSA's lan1, and interface names are case-sensitive (the LAN2 vs lan2 live bug). Anything unmappable becomes a Dropped line in the report, never a guess.
• Hardware floors, EOL policy and the upgrade allowlist live in RFC: Signed OTA firmware upgrade (usign/fwtool/sysupgrade + signed manifest) #62's manifest (min_ram_kb / min_flash_kb / eol / final_version): devices below the floor are never offered an upgrade, EOL devices are told honestly they are at their final version. This RFC's job is that for every device that does upgrade or reflash, the configuration survives.
• Installs older than this system can't export a profile — no code retro-fixes the past, and that limit is stated rather than papered over. The mitigation is the legacy converter (P2): a script that reads the old raw backup tarball users already have and emits a best-effort profile — wifi credentials, LAN addressing, static leases, port forwards are all extractable from old configs even where the schema changed. Even 80% recovery turns "reprogram from scratch" into "review a checklist," for the one unavoidable manual flash onto the first profile-aware release.

Fleet tiers (shared with #62): Tier A validated boards get full OTA + profile survival; Tier B (buildable, not yet OTA-validated) get profile survival with a manual flash — P1 delivers this with zero OTA infrastructure; Tier C (EOL/below floor) are frozen at their final version and told so.

Design in brief

1. Profile format — one human-readable JSON of feature-level intent (system, LAN/DHCP, wifi, known devices, port forwards, VLANs, restrictions, quotas, QoS...). No device names, no firewall syntax, nothing board-specific; ports/radios by role. Unknown keys are ignored with a warning; absent features get defaults; profile_version bumps only on breaking semantic changes.
2. Per-feature exporters/importers — /usr/lib/gargoyle/profile.d/NN-<feature>.sh export|import, independent and idempotent; a thin gargoyle_profile.sh orchestrator assembles/splits the JSON (jshn is already on every image). Each importer performs its Tier classification and (for Tiers 2–4) its board.json / plugin-presence check, emitting an entry to the import report for every fragment it touches. Each importer lives next to the page code it mirrors, with a shared round-trip test (below) so page evolution can't silently orphan its importer.
3. Upgrade wiring — the profile (a few KB) is stashed in a minimal conf tarball (profile + dropbear host keys only) passed via sysupgrade -f (the archive defines the preserved set, so no -n is needed — -f overrides it in sysupgrade's own source anyway); a shipped /etc/uci-defaults/99-gargoyle-profile-import imports it once on first boot before network/wireless start (stock OpenWrt run-once mechanism, no new plumbing). The RFC: Signed OTA firmware upgrade (usign/fwtool/sysupgrade + signed manifest) #62 manifest's min_profile_version lets the upgrade page state before flashing what will carry over. All three flash entry points share this wiring: OTA (RFC: Signed OTA firmware upgrade (usign/fwtool/sysupgrade + signed manifest) #62), the existing manual upload page (its "preserve settings" checkbox routes cross-major saves through the profile stash instead of raw keep-config), and CLI. A successful import also marks the router as provisioned (the password came from the profile), so the firstboot wizard doesn't re-prompt a user whose router just upgraded itself.
4. Safety net (never a brick, never a blank slate) — the safe_apply philosophy applied to upgrades. Importers fail per-feature: a bad one leaves that feature at defaults and the rest proceed; the profile is preserved at /etc/gargoyle/pending-import.json (alongside the import-report.json above) with a GUI banner ("N of M settings groups need review") and per-feature retry. Wholesale failure still boots clean defaults, reachable at the default LAN IP, profile intact. Worst case today: unreachable router, full manual rebuild. Worst case with this: one login and a guided re-import. One further contract, imposed by RFC: Signed OTA firmware upgrade (usign/fwtool/sysupgrade + signed manifest) #62's downgrade design: when a profile is newer than the running firmware (a downgrade), the importer applies the readable subset but preserves the newer profile file intact on disk — this is what makes downgrade→re-upgrade a lossless round-trip.

Free wins

• Cross-device moves: the profile contains no board specifics, so it imports on a different router model — the capability check and import report do the honest work of flagging what adapts, defers, or doesn't fit. New-router migration becomes export → flash → import. Raw tarballs can never do this.
• Provisioning: drop a profile into an image and a fresh router comes up configured.
• Support: export --redacted beats "describe your settings."

Honest limits

Physical impossibility is real, and stated rather than hidden: tri-band → dual-band loses a radio, 4 VLAN'd ports → a 2-port router loses two — each is a Dropped/Adapted line in the report, by design. Features removed upstream can't import (the report says so rather than pretending). Firmware older than this system can't export — the legacy converter recovers most of it, not all. The profile covers what the GUI manages; hand-edited raw UCI stays the raw tarball's job (the raw-backup side — divergent keep lists, missing manifest, blind restore — is owned by companion RFC #98, whose restore pre-flight routes cross-major tarballs to this profile path). Single-partition targets still can't auto-rollback a bad flash (#62's scope) — this removes the config half of the risk, not the flash half.

Phases

1. P1 — profile core + the big eight features (system/password, LAN/DHCP, wifi, known devices, port forwards, restrictions, QoS, VLANs; ~95% of real-world config surface), each with its Tier classification, board.json/plugin capability check, and import-report entries. Export/Import on the Backup page. Ships value with zero OTA infrastructure (Tier B: manual flash + settings survival) — and cross-device moves work at P1 because the profile is already hardware-free.
2. P2 — upgrade wiring: stash-through-sysupgrade, first-boot import, pending-import banner/retry surfacing the import report with per-outcome fix affordances (install-and-apply for Deferred), manifest min_profile_version, integration with ota_upgrade.sh (RFC: Signed OTA firmware upgrade (usign/fwtool/sysupgrade + signed manifest) #62 phase 3), legacy converter (old raw backup tarball → best-effort profile, exposed as "Import legacy backup" on the Backup page).
3. P3 — long tail (DDNS, tor, exportable VPN config), cross-device support matrix, redacted export, and a --dry-run that emits the import report without applying — so the GUI can state, before committing, exactly what will carry / adapt / defer / drop onto a named target (pairs with RFC: Signed OTA firmware upgrade (usign/fwtool/sysupgrade + signed manifest) #62's pre-flight, which already refuses combinations it can't honor before flashing).

Testing

New vnet phase NN-settings_profile.test.sh:

• T-PROF-01: export on a richly configured VM is schema-valid and complete.
• T-PROF-02: import onto a factory-reset VM reproduces the wire behavior (DHCP range, SSID, forwards actually work — asserted on the wire, not by diffing UCI).
• T-PROF-03: full loop — old image, configure via the real browser (the phase-38 journey layer), OTA-style flash to new image, assert every profile setting survived on the wire.
• T-PROF-04: corrupt profile at first boot boots clean defaults, reachable, banner present, pending-import file preserved.
• T-PROF-05: profile with unknown future keys imports the known subset, logs the rest, and preserves the original newer profile file intact (the RFC: Signed OTA firmware upgrade (usign/fwtool/sysupgrade + signed manifest) #62 downgrade round-trip contract).
• T-PROF-06: fixed-point round-trip — export → import → export must yield an identical profile on every feature. This is the drift alarm: it runs in CI against every page change, so an evolved save path that orphans its importer fails loudly instead of rotting silently.
• T-PROF-07: cross-hardware map — import a profile assigning VLANs to lan3/lan4 onto a target modeled with 2 LAN ports; assert lan1/lan2 apply on the wire and lan3/lan4 appear as Dropped in the report.
• T-PROF-08: capability degrade — import a 6 GHz + 160 MHz + WPA3 wifi block against a board.json advertising only 2G/5G, 80 MHz, WPA2; assert SSID+key are live on 5 GHz and the report shows the three Adapted lines with reasons.
• T-PROF-09: feature-gated defer — import an OpenVPN-bearing profile onto a VM without the plugin; assert the fragment is preserved, no OpenVPN UCI is written, and the report shows Deferred with the install affordance.
• T-PROF-10: report exhaustiveness — every fragment in a rich fixture resolves to exactly one of {Applied, Adapted, Deferred, Dropped}; no fragment silently vanishes (the classifier's drift alarm, analogue of T-PROF-06).
• Legacy-converter cases: representative old-version config tarballs (swconfig-era network, fw3-era firewall) convert to profiles that import clean.
• Fills the reserved upgrade-path TODO slots (T-UPG-09/10) with real teeth.

T-PROF-07..10 use a synthetic-board.json swap (feed the importer a constrained capability model) so a single x86 VM can stand in for dual-band / low-port-count targets without needing that physical hardware in the sim. The browser-journey requirement in T-PROF-03 is deliberate: recent VLAN-save debugging proved "the backend applied it" and "the user's settings actually survived" are different claims, and only the second counts.

Full design docs: docs/settings-profile-upgrade-plan.md and docs/settings-profile-cross-hardware-amendment.md in ispyisail/gargoyle-tools.

Feedback welcome — especially on the profile schema's feature list for P1, which old versions the legacy converter should target first, and whether the Backup page should default to profile export (with the raw tarball as the "advanced" option) once this lands.

[ispyisail]

Companion RFC posted: #98 (backup coverage overhaul). It fixes the raw-backup side this RFC deliberately leaves in place for same-version snapshots. An audit found the web backup and sysupgrade.conf keep lists have silently diverged (an in-place sysupgrade loses /etc/openvpn keys; backup/restore loses /etc/tor; neither preserves the web TLS cert), plus restore has no manifest/version/board checks at all. #98 adds a declarative keep.d registry, a backup manifest, and a restore pre-flight that routes cross-major tarballs to this RFC's profile path.

[ispyisail]

Amendment: cross-hardware portability + the capability-negotiated import report

A concrete requirement pushes on this RFC: "a backup restorable on any compatible Gargoyle router — whatever the version or hardware, restoring as if native — with warnings for features the target can't cope with."

This RFC already makes that possible (a profile with zero hardware facts can be replayed anywhere), but it treats cross-hardware as a side effect of the cross-version design rather than a feature to build. This amendment promotes it to co-equal and specifies the two things the RFC under-designs for it to actually work and be honest.

1. Cross-hardware is co-equal with cross-version

Raw config varies along three independent axes, not two — verified against a real running config:

1. Hardware topology — LAN is br-lan over eth1 eth2 eth3, WAN is eth0.10; on an MT6000 the same roles are lan1..lan4/wan. Restore across models and the device names don't exist → unreachable router (same class as the LAN2-vs-lan2 lockout bug).
2. Firmware schema — swconfig→DSA, fw3→fw4, etc. (the axis this RFC already owns.)
3. Capability / feature set — source has tri-band wifi + QoS + Tor + OpenVPN; target may have none.

2. The capability oracle already ships: board.json

Every OpenWrt device carries /etc/board.json — a machine-readable capability model of that exact box: the port topology and per-radio band support (2G/5G/6G, ht/vht/he/eht, max_width, legal channel modes). So on import each fragment can be checked against what the target can physically do before it's applied. We read the abstraction OpenWrt already maintains per-model; we don't replicate it — same O(features) scaling property this RFC relies on.

3. Five-tier taxonomy → what each importer does on a mismatched target

Tier	Examples	On a mismatched target
1 Portable verbatim	hostname, password hash, DHCP ranges, leases, port-forwards, firewall/restriction/quota by IP/MAC, SSID+key	applies identically everywhere
2 Role-mappable	LAN/WAN assignment, per-port VLAN by role name	mapped via target's own switchinfo; degrades when port count differs
3 Capability-gated	6 GHz, 160 MHz, WPA3, DFS channels	checked vs board.json; degrades to nearest-valid, credential always survives
4 Feature-gated	QoS, Tor, OpenVPN, WireGuard, USB/DLNA	if plugin absent → held aside, not dropped ("install + Apply")
5 Never carried	device names, phy paths, MACs, safe_apply snapshots, lease file, counters	regenerated fresh; carrying these is what bricks

4. The import report — this is the "warnings"

Every fragment resolves to exactly one of Applied / Adapted / Deferred / Dropped, each with a one-line human reason, assembled into a reviewable checklist (persisted to /etc/gargoyle/import-report.json, surfaced in the pending-import banner this RFC already specifies). Applied needs no attention; the other three are the warnings. Design rule: an importer must classify into one of the four — never half-apply-and-move-on. "The backend applied it" and "the setting survived, or the user was told it couldn't" are different claims; the report enforces the second.

This is the honest core: "restore as if native" is literally true only for Tiers 1–2. You cannot restore a 6 GHz SSID onto a dual-band router — the only truthful outcomes are adapt it or tell the user, and the report is what makes that a line item instead of a silent failure.

Prior art

pfSense/OPNsense do exactly this — restore onto different hardware drops you into an interface-assignment screen ("saved config had 4 interfaces, this box has 2, map them"), which is precisely the Tier-2 report. UniFi/Omada push off-device intent to any adopted model. MikroTik /export is the counter-example (port names physical, not hardware-abstracted) — the reason role-mapping is load-bearing.

Fits the existing phases (additions, not new phases)

• P1 — each importer gains its Tier classification + board.json check + report assembly. Exporters unchanged (a profile is already hardware-free).
• P2 — surface the report in the pending-import banner; add fix affordances (install-and-apply for Deferred).
• P3 — cross-device matrix + a --dry-run that emits the report without applying, so the GUI can say before committing exactly what will carry/adapt/defer/drop onto a named target (pairs with RFC: Signed OTA firmware upgrade (usign/fwtool/sysupgrade + signed manifest) #62 pre-flight).

New vnet cases T-PROF-07..10 cover cross-hardware port mapping, capability degrade, feature-gated defer, and report exhaustiveness — using a synthetic-board.json swap so one x86 VM can stand in for dual-band / low-port-count targets.

Full write-up with the verified config evidence lives in docs/settings-profile-cross-hardware-amendment.md (gargoyle-tools). Happy to fold this straight into the RFC body if the direction lands.

[ispyisail]

P1 skeleton scope

Scoped the smallest buildable slice that proves the whole architecture end-to-end, grounded in the real tree (switchinfo.sh's jshn+board.json idiom, set_time_zone.sh/restore.sh write paths, www/backup.sh). Full write-up: docs/settings-profile-p1-skeleton.md (gargoyle-tools).

Three contracts:

• part-script profile.d/NN-<feature>.sh export|import — export prints its jshn JSON fragment under its own key; import reads the whole profile, self-selects its key, writes native UCI, and calls profile_report_add once per field.
• the report — profile_report_add <feature> <field> applied|adapted|deferred|dropped <reason> accumulates to /etc/gargoyle/import-report.json. Enforced rule: classify every field into exactly one outcome, never half-apply silently (T-PROF-10 is the CI alarm).
• capability queries — cap_band_supported / cap_max_width_for / cap_mode_supported / cap_lan_port_count etc., thin reads of the target's own board.json (switchinfo's idiom generalized).

Reference feature = 10-system (Tier 1, fully built): hostname, timezone, password_shadow. One real subtlety worth flagging — the GUI sets passwords by piping plaintext to passwd root (access.js:207, firstboot.js:30), which a profile must never carry, so 10-system carries the shadow hash and splices it in like restore.sh:238-240. This is also what makes export --redacted (P3) clean.

30-wifi stub proves the Tier-3 capability hook (real export; import writes SSID+key and fires adapted/dropped report lines via cap_*, defers full htmode reconstruction).

Build order — first PR = frame + 10-system: profile_lib.sh (report + cap_* queries) → gargoyle_profile.sh (orchestrator) → 10-system.sh → host-side round-trip test (proves it with no router) → CGI endpoints + Backup-page panel → 30-wifi hook. Steps 1–4 are the testable heart; T-PROF-01/02/10 become real the moment 10-system lands.