Skip to content

Design: WiFi moves to UniFi access points

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-run MainWireless WPA2 key 2.4 GHz and 5 GHz
    kessel-run-low MainWireless WPA2 key 2.4 GHz only, hidden
    kessel-run-iot IoT WPA2 key 2.4 GHz and 5 GHz
    kessel-run-g Guest open guest portal, client isolation on
  • No WLAN maps to Telework.

  • Every WLAN uses the AP group All APs. The groups ap-24 and ap-5 are empty and unused.

  • The two WLAN groups, Default and Off, 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.py reports 10 gaps for wlanconf. The WLAN struct in go-unifi (unifi/wlan.generated.go) does not model advertise_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_rssi and short_id.
  • The unifi_wlan update 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_sync and setting_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 6g band while the site has no access point with a 6 GHz radio.

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_access site 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-ports already declares them.

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:

  1. go-unifi: the WLAN struct models the 10 keys that the audit names.
  2. Provider: the unifi_wlan update 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_setting already works this way.
  3. Provider: a passphrase_wo_version argument. A change of the number sends passphrase_wo again.

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_ports does. Rejected: unifi_wlan already 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:

  1. 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 passphrase is null after an import.
  2. 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-diff before and after the apply. Every differing line must be a declared change. This is the proof for D1.
  3. 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.

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:

  1. The WLANs exist and are enabled (D2) before the first cable moves.
  2. The operator moves one room and adopts the unit. The room is without WiFi for the adoption and the firmware update.
  3. The operator takes the spec readings on each SSID in that room.
  4. 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.

  • [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/unifi empties All APs after 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 6g without 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_isolation blocks 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.

Each step names its rollback.

  1. Release the fork and move the pin. Rollback: git revert of the pin commit. The release adds no resource, so the plan prints No changes on both versions.
  2. Grant the policy and write the keys. Rollback: git revert of the policy commit, and vault kv metadata delete secret/fzymgc-house/infrastructure/unifi/wlan.
  3. Import the four WLANs. Rollback: git revert. The import blocks leave with it, and terraform -chdir=tf/unifi state rm unifi_wlan.<name> drops each address. The controller does not change.
  4. Reshape and enable the WLANs. Rollback: git revert and merge. The WLANs return to their legacy shape, disabled. The Telework WLAN is destroyed.
  5. Move the first room. Rollback: put the cable back in the Firewalla access point.
  6. Record the first unit in All APs and add 6g to three WLANs. Rollback: git revert and merge, after the unit is back in the group in the UI. The WLANs return to 2.4 GHz and 5 GHz.
  7. Move the other rooms. Rollback: put the cable back in the Firewalla access point.
  8. Record the other units in All APs. Rollback: none needed. The pull request states what the controller already holds.
  9. Turn MLO off on the Telework WLAN. Rollback: git revert and 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.

  • 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-cutover can 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.