Design: WiFi moves to UniFi access points
Context
Section titled “Context”See openspec/changes/unifi-wifi-cutover/proposal.md for the reason and the scope. docs/reference/network.md is the addressing
authority for every leg. This change allocates no address and no prefix.
Sean decided on 2026-09-30 that this change lands before the UCG-Fiber window. The Firewalla
access points work only while the Firewalla runs. The UniFi access points adopt on the Cloud Key
first. In the window they move to the UCG-Fiber with the switches, and ucg-fiber-gateway-cutover
owns that move.
Read from the controller on 2026-09-30 with the View Only account (Network 10.6.106):
-
The controller holds no adopted access point.
-
The controller holds four WLANs from an earlier UniFi WiFi. All four are disabled.
WLAN Network Security Notes kessel-runMainWireless WPA2 key 2.4 GHz and 5 GHz kessel-run-lowMainWireless WPA2 key 2.4 GHz only, hidden kessel-run-iotIoT WPA2 key 2.4 GHz and 5 GHz kessel-run-gGuest open guest portal, client isolation on -
No WLAN maps to Telework.
-
Every WLAN uses the AP group
All APs. The groupsap-24andap-5are empty and unused. -
The two WLAN groups,
DefaultandOff, are built in and cannot be edited. -
switch-main is a USPM24P with a 400 W PoE budget. Ports 17, 18 and 19 link at 2.5G and feed the three live Firewalla access points, 10 W to 15 W each. Port 20 is down.
Read from the provider fork at 0.56.0-fzymgc.8 and its go-unifi commit af901a1:
scripts/unifi-field-audit.pyreports 10 gaps forwlanconf. TheWLANstruct in go-unifi (unifi/wlan.generated.go) does not modeladvertise_device_name_in_beacon,dns_assistance_mode,external_id,iot_channel_lock,iot_dtim_lock,passphrase_autogenerated,roaming_assistant_6e_enabled,roaming_assistant_na_enabled,roaming_assistant_na_rssiandshort_id.- The
unifi_wlanupdate builds the request from the Terraform state, not from the live object. The struct models 13 more live keys that the resource never sets:b_supported,bc_filter_enabled,mdns_proxy_mode,minrate_na_advertising_rates,minrate_ng_advertising_rates,optimize_iot_wifi_connectivity,radius_das_enabled,radius_macacl_format,sae_anti_clogging,sae_groups,sae_psk,sae_syncandsetting_preference. An update sends each one as its zero value or leaves it out. - The resource has
passphrase_wo, a write-only argument that Terraform never stores. It has no version argument, and Terraform does not compare a write-only argument. So a new key in Vault alone never produces an update.
Read from the Firewalla MSP WiFi page on 2026-09-30 (the MSP API behind the MCP has no WiFi endpoint, and the keys are not in the repository):
| Firewalla SSID | Security | Bands | MLO | Microsegments | Devices |
|---|---|---|---|---|---|
kessel-run |
WPA2/WPA3 | 2.4, 5 GHz | off | 4 | 24 |
kessel-run-iot |
WPA2/WPA3 | 2.4, 5 GHz | off | 3 | 18 |
kessel-run-g |
WPA2/WPA3 | 2.4, 5, 6 GHz | off | 1 | 0 |
kessel-run-tw |
WPA3 only | 2.4, 5, 6 GHz | on | 1 | 1 |
A microsegment is a per-group key on one SSID. So kessel-run has four keys today (the groups
Sean, Dorothy, Sophia and Sonos) and kessel-run-iot three (IoT, Eufy and FirstAlertIoT). The
MSP device list shows every wireless device already on the VLAN of its SSID. Nine devices of the
IoT group sit on other legs: six on MainWireless, one on Guest and two wired on Main.
The Firewalla access points isolate devices by VqLAN group: a per-device group that the access point enforces on any SSID and any network. Sean stated on 2026-09-30 that the WiFi uses those groups, that UniFi cannot copy them, and that he converges those devices onto the right SSID. So the move is not seamless for every device, and Sean accepted that clients join a new SSID. Each UniFi WLAN carries one key, which Sean wrote to Vault on 2026-09-30, and a device in another microsegment joins with it.
The U7 Pro Max and the UX7 are WiFi 7 units with a 6 GHz radio. Sean decided on 2026-09-30 that the WLANs use both. Ubiquiti states the limits in its 6 GHz guide and its SSID settings guide:
- A 6 GHz WLAN needs WPA3. The mode WPA2/WPA3 works with 6 GHz: the 6 GHz radio takes WPA3 clients only, and the other two radios take both. PMF (protected management frames) is optional in that mode.
- Ubiquiti says to use WPA3 only with MLO (one client link across several bands).
- The provider fork notes that a controller refuses the
6gband while the site has no access point with a 6 GHz radio.
Goals / Non-Goals
Section titled “Goals / Non-Goals”Goals:
- Every device ends on the VLAN of its role, with the SSID as the only selector.
- A client with a 6 GHz radio uses 6 GHz and the WiFi 7 rates on MainWireless, Guest and Telework.
- Terraform owns the WLANs before the first client depends on them.
- No WLAN update through Terraform removes a field from the controller.
- Every step on a live room has a rollback of one cable move or one revert.
Non-Goals:
- 6 GHz on the IoT WLAN. Its clients are 2.4 GHz and WPA2 devices.
- A WPA3-only mode on MainWireless, IoT or Guest. Those three still take a WPA2 client.
- Radio channels, transmit power and the channel plan. The controller owns them.
- The device records of the access points. Terraform never manages adoption or a device record.
- The guest portal and the
guest_accesssite setting. The field audit reports a gap for that setting, and no WLAN uses the portal after this change. - The move of the access points to the UCG-Fiber, and the zone of each network. Those belong to
ucg-fiber-gateway-cutover. - A change to a switch port that carries an access point.
unifi-access-point-portsalready declares them.
Decisions
Section titled “Decisions”D1: A fork release closes the WLAN gaps before any import
Section titled “D1: A fork release closes the WLAN gaps before any import”The repository rule is that Terraform manages an object behind a full-replace API only after the
wire struct models every live field. wlanconf fails that rule in two layers, so the fork gets
one release, 0.56.0-fzymgc.9, with three changes:
- go-unifi: the
WLANstruct models the 10 keys that the audit names. - Provider: the
unifi_wlanupdate reads the live WLAN first and lays the declared fields over it. The 13 keys that the resource never sets then keep their live values.unifi_settingalready works this way. - Provider: a
passphrase_wo_versionargument. A change of the number sendspassphrase_woagain.
The audit compares struct tags only, so it cannot show the second layer. The dump diff in D2 is the proof for that layer.
Alternatives considered:
- Manage the WLANs in the UI and never in Terraform. Rejected: the proposal requires the WLANs in Terraform, and the WLANs are the only fabric objects that clients see by name.
- Declare all 13 keys in the resource schema. Rejected: most are RADIUS and SAE internals that the estate never sets. Read-then-overlay protects them and every key a later controller adds.
- Send raw JSON, as
unifi_device_portsdoes. Rejected:unifi_wlanalready has a typed schema and a write-only key argument, and a raw document cannot hold a secret safely.
D2: The four disabled WLANs are the proof, and then the production WLANs
Section titled “D2: The four disabled WLANs are the proof, and then the production WLANs”The legacy WLANs are disabled and no access point is adopted, so an update on them reaches no client. The work uses them in three steps:
- Import. One pull request imports the four WLANs as they are, with no key argument. The plan
must report nothing to change. The legacy key of each WLAN stays on the controller, and it
never enters the state, because
passphraseis null after an import. - Reshape. The next pull request changes each WLAN into the Firewalla SSID of its network and
adds the Telework WLAN. The operator takes a dump with
--for-diffbefore and after the apply. Every differing line must be a declared change. This is the proof for D1. - Enable. The same pull request sets
enabled = true. Nothing broadcasts until the first access point adopts. The 6 GHz band joins after that adoption (D4).
The mapping, which the Firewalla export can change:
| Legacy WLAN | Becomes the SSID of | Change |
|---|---|---|
kessel-run |
MainWireless (3001) | keeps its name, WPA2/WPA3, key from Vault |
kessel-run-iot |
IoT (3020) | keeps its name, WPA2/WPA3, key from Vault |
kessel-run-g |
Guest (3100) | keeps its name, WPA2/WPA3 key in place of open, no guest portal |
kessel-run-low |
none | deleted: the Firewalla has no hidden second SSID |
| none | Telework (3200) | created as kessel-run-tw, WPA3 only |
The Terraform names follow the VLAN (unifi_wlan.mainwireless, iot, guest, telework),
with moved blocks from the imported names.
Alternative considered: delete the four WLANs and create new ones. Rejected: that gives up the import at zero change and the update proof on objects that the controller itself wrote.
D3: One Vault path holds the keys, and a version number rotates one
Section titled “D3: One Vault path holds the keys, and a version number rotates one”The keys are fields of one secret at secret/fzymgc-house/infrastructure/unifi/wlan: mainwireless,
iot, guest and telework. The operator writes them with vault kv patch. Terraform never
writes this path.
tf/unifi reads the path with a second ephemeral "vault_kv_secret_v2" block. Each WLAN sets
passphrase_wo from the matching field and passphrase_wo_version as a literal number. tf/CLAUDE.md
requires this route for a secret that flows into a resource. The terraform-unifi policy gains
read on the one path.
To rotate a key, the operator patches the field in Vault, and a pull request raises the version number of that WLAN. Every client of that SSID then needs the new key.
The SSID names and the VLAN map are not secret, and they are in tf/unifi/wlans.tf. The Firewalla
export is encrypted and stays in a scratch directory.
Alternative considered: data "vault_kv_secret_v2" with the plain passphrase argument. Rejected:
tf/CLAUDE.md forbids a new data source read, and the key enters the state.
D4: One SSID per VLAN, and three WLANs gain 6 GHz
Section titled “D4: One SSID per VLAN, and three WLANs gain 6 GHz”A client finds its network by SSID name and key, and on UniFi the SSID is the only thing that
puts a client on a VLAN. So the house gets one SSID per VLAN. Where a Firewalla SSID already maps
to one VLAN, the WLAN keeps its name and key, and those clients join on their own. Where a
Firewalla SSID served several VqLAN groups, the operator maps each group to a VLAN, and the
devices of that group join the SSID of that VLAN by hand. A hidden Firewalla SSID stays hidden.
Every WLAN uses the AP group All APs. The groups ap-24 and ap-5 stay empty.
| WLAN of | Security | Bands | Reason |
|---|---|---|---|
| MainWireless | WPA2/WPA3 | 2.4, 5 and 6 GHz | 6 GHz for the clients that have it, WPA2 for the rest |
| Guest | WPA2/WPA3 | 2.4, 5 and 6 GHz | the same |
| IoT | WPA2/WPA3 | 2.4 and 5 GHz | its devices already join a WPA2/WPA3 SSID on the Firewalla, and none has a 6 GHz radio |
| Telework | WPA3 only | 2.4, 5 and 6 GHz | copies the mode of kessel-run-tw, which its work devices already use |
WPA2/WPA3 is security = "wpapsk", wpa_mode = "wpa2", wpa3_support = true,
wpa3_transition = true and pmf_mode = "optional". Telework is the same with
wpa3_transition = false and pmf_mode = "required". The production pull request sets the mode,
so no client ever joins these WLANs in plain WPA2 and has to join again later.
The 6g band lands in a second step, because the controller refuses it while no 6 GHz access
point is adopted. The pull request that records the first access point in All APs also adds
6g to the three WLANs. A WiFi 7 client gets the WiFi 7 rates on 5 GHz and 6 GHz from that
point, with no MLO.
MLO is off on every WLAN. It went on with Telework’s 6 GHz band on 2026-09-30, and the controller then showed its warning: most WiFi 7 clients use one band, the benefit is limited, and MLO brings interoperability problems. Sean decided the same day to follow that advice, and the measured step on MainWireless is dropped.
WPA3 makes the controller fill the sae_* keys of a WLAN. The resource does not set them, so
the read-then-overlay update of D1 is what keeps them.
Alternatives considered:
- Keep every WLAN on WPA2 and the two old bands. Rejected: Sean decided to use 6 GHz and WiFi 7.
- IoT on WPA2 only. Rejected: its devices already join a WPA2/WPA3 SSID on the Firewalla, so the mode is proven for them, and one mode on every WLAN is simpler.
- A WPA3-only MainWireless with MLO from the first day. Rejected: a WPA2 client on MainWireless loses its network, and IoT devices are not the only WPA2 clients.
- A PPSK WLAN (one SSID, a key per VLAN), which UniFi offers. Rejected: PPSK is WPA2 only and the controller refuses 6 GHz on a PPSK WLAN. Sean chose 6 GHz over one SSID.
- A second SSID for 6 GHz and MLO. Rejected for now: clients need a new network, and the house gets one more SSID. It is the fallback if the MLO step fails and MLO is still wanted.
D5: The Guest WLAN isolates clients and is not a guest-policy WLAN
Section titled “D5: The Guest WLAN isolates clients and is not a guest-policy WLAN”The Guest WLAN sets l2_isolation = true and is_guest = false.
is_guest makes each access point apply the guest policy of the controller: the portal, and a
block of private address ranges. Guest clients have the resolvers .5, .6 and .7 on their own
private subnet, so that policy is the wrong fence. The router already fences the Guest leg. The
Firewalla does it today, and the Hotspot zone of the UCG-Fiber does it after the window.
l2_isolation stops one wireless client from reaching another. The spec requires that the wired
resolvers still answer, and the first access point proves it with two readings on a Guest
client: a lease from Kea, and a DNS answer from 192.168.79.5. Whether isolation holds between
two clients is the access point’s behaviour, and Sean decided on 2026-09-30 not to test it.
Measured on 2026-09-30 from heimdall through the first U7 Pro Max: both readings pass, and the
client reaches the internet.
If the resolvers do not answer with l2_isolation on, a pull request sets it to false on Guest.
The router fence still holds, and the change records the result in the runbook.
Telework sets l2_isolation = false. Its purpose is the least effect on work devices, and the
router fences the leg.
D6: A room moves with one cable
Section titled “D6: A room moves with one cable”The three U7 Pro Max units use the drops of the three live Firewalla access points, on switch-main ports 17, 18 and 19. The ports are already Core native trunks with PoE. So a room moves when the operator takes the cable out of the Firewalla access point and puts it in the U7 Pro Max.
The order is fixed:
- The WLANs exist and are enabled (D2) before the first cable moves.
- The operator moves one room and adopts the unit. The room is without WiFi for the adoption and the firmware update.
- The operator takes the spec readings on each SSID in that room.
- The next room moves only after the readings pass.
The first room is the basement (port 17), the room with the fewest people. It also carries the D5 proof.
The two UX7 units serve rooms that no Firewalla access point serves: the office (switch-office
port 13) and the family room. Sean decided on 2026-09-30 that the family room unit is meshed, with
a wireless uplink to ap-main-floor, so switch-familyroom port 8 stays a free trunk. They adopt in access point mode after the
three U7 Pro Max units. If a UX7 does not adopt on a console without a gateway, it stays unplugged
until the UCG-Fiber holds the site. ucg-fiber-gateway-cutover then gains that adoption as a task
after its window. Measured on 2026-09-30: the office UX7 adopted on the Cloud Key in access point
mode, as device type udm, with its 6 GHz radio serving the three WLANs.
A Firewalla access point stays in the Firewalla app until the Firewalla goes. Until then the rollback of a room is the cable.
D7: The AP group records the adopted units
Section titled “D7: The AP group records the adopted units”ap-groups.tf declares All APs with device_macs = []. The controller adds each adopted access
point to that group. So after an adoption the plan shows drift, and an apply with the old file
empties the group and stops every SSID.
The workspace applies only on a merge that touches tf/unifi. So the rule for the adoption days
is: no pull request on tf/unifi merges between the first adoption and the pull request that adds
the MAC addresses to All APs. The first unit gets its pull request at once, because that pull
request also adds 6 GHz (D4). The other units get one pull request after the last room.
Alternative considered: stop declaring All APs. Rejected: the group is already imported, and a
WLAN refers to it by ID.
D8: The inventory moves wlanconf to the managed tier
Section titled “D8: The inventory moves wlanconf to the managed tier”scripts/unifi-inventory.py lists wlanconf in tier two, the tier for objects that wait for the
UCG-Fiber. The pull request that imports the WLANs moves it to tier one, so the tier-one audit
gates it from then on. wlangroup moves to never: both groups are built in.
Risks / Trade-offs
Section titled “Risks / Trade-offs”- [The read-then-overlay update still loses a field] → The dump diff of D2 runs on disabled WLANs with no access point. A lost field costs nothing, and the fork gets a fix before an SSID is live.
- [A merge on
tf/unifiemptiesAll APsafter an adoption] → The rule of D7. If it happens, the SSIDs stop in every moved room. The fix is the pull request that adds the MAC addresses, or the operator adds the units to the group in the UI. - [A client does not join a WPA2/WPA3 WLAN] → Some old clients fail when PMF is optional. Move
that client to the IoT SSID, which is WPA2. If many clients fail, a pull request sets the WLAN
back to WPA2 and removes
6g. - [The controller drops
6gwithout an error] → The provider fork reports a refused band as an error. The 6 GHz reading of the spec on the first access point is the proof. - [A VqLAN group loses its isolation] → The group becomes a VLAN, and the router fences the VLAN. Devices inside one VLAN reach each other, as the IoT devices need to. A device that must not reach its neighbours goes on Guest, where the WLAN isolates clients.
- [The Guest WLAN changes from open to a key] → The Guest WLAN copies the Firewalla Guest SSID, so a guest who uses the Firewalla SSID today sees no change.
- [
l2_isolationblocks the resolvers on Guest] → D5 has the fallback. - [A U7 Pro Max draws more than the Firewalla unit] → A U7 Pro Max draws up to 25 W. Three units need 75 W of the 400 W budget.
- [The export does not show a key in plain text] → The operator reads the key in the Firewalla app, where each SSID shows it.
- [The UX7 units do not adopt on the Cloud Key] → D6 has the fallback. No room depends on them.
Migration Plan
Section titled “Migration Plan”Each step names its rollback.
- Release the fork and move the pin. Rollback:
git revertof the pin commit. The release adds no resource, so the plan printsNo changeson both versions. - Grant the policy and write the keys. Rollback:
git revertof the policy commit, andvault kv metadata delete secret/fzymgc-house/infrastructure/unifi/wlan. - Import the four WLANs. Rollback:
git revert. The import blocks leave with it, andterraform -chdir=tf/unifi state rm unifi_wlan.<name>drops each address. The controller does not change. - Reshape and enable the WLANs. Rollback:
git revertand merge. The WLANs return to their legacy shape, disabled. The Telework WLAN is destroyed. - Move the first room. Rollback: put the cable back in the Firewalla access point.
- Record the first unit in
All APsand add6gto three WLANs. Rollback:git revertand merge, after the unit is back in the group in the UI. The WLANs return to 2.4 GHz and 5 GHz. - Move the other rooms. Rollback: put the cable back in the Firewalla access point.
- Record the other units in
All APs. Rollback: none needed. The pull request states what the controller already holds. - Turn MLO off on the Telework WLAN. Rollback:
git revertand merge.
The Firewalla access points are not removed from the Firewalla app. Sean decided on 2026-09-30
that the Firewalla itself goes soon, in ucg-fiber-gateway-cutover, and its access points go with
it.
Open Questions
Section titled “Open Questions”- Does a network in the Hotspot zone of the UCG-Fiber change how an access point treats a WLAN on
that network? The bench for
ucg-fiber-gateway-cutovercan read it after one access point is adopted. The answer does not change this change, because the zones do not exist on the Cloud Key.