Skip to content

UniFi

The UniFi controller runs on the UCG-Fiber, which is also the gateway. It runs the switching fabric (VLANs on switch ports, DHCP Guard, IGMP snooping and mDNS scope) and routes every leg. Its DHCPv4 server is off on every network, and it runs no DHCPv6 service. The Kea pair on the resolvers serves DHCPv4 on every network. A setting on the controller can still veto work on that layer: DHCP Guard on a network drops every offer from a server that is not on its trusted list.

URL https://unifi.fzymgc.house (192.168.40.1, Core, the UCG-Fiber). Use the hostname. The certificate does not cover the address.
API UniFi OS login POST /api/auth/login. Network API under /proxy/network/api/s/default/.

Read the application version on the controller. It is not pinned in this repository. The UCG-Fiber runs Network 11.0.89 since 2026-10-18. Network 11 moved the application database to PostgreSQL and re-keyed every object to a UUID. See Ids after Network 11.

The UCG-Fiber serves a Let’s Encrypt certificate for unifi.fzymgc.house. UniFi OS issues and renews it with a DNS-01 challenge through Cloudflare, so no ACME client runs on the console. Every client verifies the certificate with the system trust store.

The challenge uses the Cloudflare token unifi-acme-dns01. tf/cloudflare/unifi_acme.tf creates the token and writes it to Vault. The token can edit DNS records and read the zone of fzymgc.house, and nothing else.

To issue the certificate on a console that has none:

  1. Read the token from Vault:

    Terminal window
    vault kv get -field=cloudflare_api_token secret/fzymgc-house/infrastructure/unifi/acme
  2. In UniFi OS, open Control Plane, then Console, then Certificates.

  3. Add a Let’s Encrypt certificate for unifi.fzymgc.house. Select Cloudflare as the DNS provider and enter the token.

  4. Make sure that a client verifies the certificate. curl must print an HTTP status and no certificate error:

    Terminal window
    curl -sS -o /dev/null -w '%{http_code}\n' https://unifi.fzymgc.house/

To read the issuer and the expiry date of the certificate in service:

Terminal window
echo | openssl s_client -connect unifi.fzymgc.house:443 -servername unifi.fzymgc.house 2>/dev/null | openssl x509 -noout -issuer -enddate
  • unifi.fzymgc.house resolves to the UCG-Fiber since the cutover of 2026-10-01. dns-control owns the record, as the entry unifi. The entry unifi_ckp holds unifi-ckp.fzymgc.house, 192.168.40.2 and the DHCP reservation of the Cloud Key.
  • The certificate belongs to UniFi OS, not to the Network application. A restore of a Network backup keeps it.
  • The Cloud Key serves a ZeroSSL certificate that expires on 2026-10-23. Nothing in this repository issues or renews it.
Path under secret/fzymgc-house/ Account Role Reader
infrastructure/unifi/readonly automation-readonly Network: View Only scripts/unifi-readonly.sh, which runs the inventory and ad-hoc probes from a workstation, and the unifi-mcp Deployment in the cluster, through the copy on cluster/unifi-mcp (see MCP Gateway Clients). The controller rejects writes from it.
infrastructure/unifi/admin automation-admin Network: Full Management the main-cluster-unifi workspace only, through the terraform-unifi policy
cluster/dns-control, fields unifi_writer_username and unifi_writer_password dns-control-writer Network Admin dns-control, through the dns-control ExternalSecret. It writes only the name and the note of a client. The console offers no narrower role that can rename a client, so dns-control confines the account to that one write. The admin activity log names the account for each change
infrastructure/unifi/wlan the WLAN keys, one field per SSID: mainwireless, iot, guest, telework none the main-cluster-unifi workspace only, through the terraform-unifi policy. Terraform reads a key at apply time into the write-only passphrase_wo of a unifi_wlan, so no key enters the state. The operator writes a key with vault kv patch secret/fzymgc-house/infrastructure/unifi/wlan <field>=<key>
infrastructure/unifi/acme the Cloudflare token unifi-acme-dns01, in the field cloudflare_api_token none the operator, who enters it in UniFi OS for the console certificate. tf/cloudflare/unifi_acme.tf writes it

Humans use their own logins. The local admin credential is in 1Password.

The UCG-Fiber holds the same two automation accounts with the same passwords and roles, so the cutover changes no credential. A write as automation-readonly returns 403 api.err.NoPermission there.

Both automation accounts sign in with a password. An API key carries the rights of the admin who creates it, and a Network admin cannot create one. A key of an owner login has rights over the whole console, so the workspace does not use one.

If you change the password of automation-readonly, write it to infrastructure/unifi/readonly and to cluster/unifi-mcp. The ExternalSecrets policy reads only cluster/*, so the second path is a copy that the unifi-mcp Deployment reads.

tf/unifi (workspace main-cluster-unifi, agent mode, auto-apply on merge) declares every network on the controller as a unifi_network in networks.tf, every port profile as a unifi_port_profile in port-profiles.tf, and the ports of each adopted switch as one unifi_device_ports resource per switch: switch-main in ports.tf, and the others in ports-<switch>.tf. One resource per switch is the rule, because two resources on one MAC overwrite each other. The radios of each access point are one unifi_device resource per unit in access-points.tf, imported by MAC address in main.tf. firewall-zones.tf declares the custom firewall zone and every user policy of the zone firewall. static-routes.tf declares the blackhole route of each VIP prefix (BGP). The provider is the fork at app.terraform.io/fzymgc-house/unifi (runbook), pinned to an exact version in versions.tf.

  • Change the fabric through a pull request, not the UI. A UI change shows as drift on the next plan, and an apply sets it back. main-cluster-unifi does not apply by itself: after a merge, read the plan of the run in HCP and confirm it only if it changes what the pull request changed. If the plan also changes another object, discard the run and adopt the UI change in tf/unifi first. The drift check of the Temporal worker plans this workspace each day and posts a change to Discord. There, Reject keeps the UI change for adoption, and Approve sets it back. See Adopt a UI change and HCP Terraform.
  • DHCP Guard is dhcp_guarding = { enabled, servers }, with at most three servers. A cut that brings a new DHCP server onto a guarded VLAN adds its address first.
  • The seven legs are Core, Guest, IoT, Lab, Main, MainWireless and Telework. Each states the subnet and gateway of the network reference, the domain fzymgc.house that Kea hands out, and dhcp_server = { enabled = false }. UniFi serves DHCP nowhere, and a UI change that turns it on shows as drift.
  • Each leg also states the IPv6 fields that the UCG-Fiber acts on: SLAAC, the ULA gateway address of the leg in ipv6.aliases, and the ULA resolver VIP of the leg as the only DNS server of the router advertisement. The ULA index of each leg comes from the network reference. The IPv6 fields are one ipv6 object with pd and ra objects inside it, the shape the provider uses from 0.60.0-fzymgc.1.
  • A controller with no UniFi gateway refuses prefix delegation. An update that holds ipv6.interface_type = "pd" fails with api.err.GatewayRequiredForPdConfig, and the network keeps every old value. So the legs state ipv6.interface_type = "none" until the UCG-Fiber holds the site, and the prefix delegation values apply after the cutover.
  • Main, MainWireless and IoT state multicast_dns = true, so the gateway repeats mDNS between these three legs. Core, Lab, Guest and Telework state false.
  • The controller UI hides the subnet, IPv6 and purpose fields while no UniFi gateway is adopted. It offers only the VLAN ID and DHCP Guarding. A field that no form shows is not declared until the UCG-Fiber UI shows how the controller stores it. Network fields lists the keys that the UCG-Fiber UI writes.
  • WAN2 (VLAN 2000) is not a LAN. It carries the T-Mobile gateway on switch-masterbedroom port 8 (tmobile-gateway) across the switch uplinks to the gateway’s WAN2 port on switch-main port 21 (wan2-gateway). The uplinks between those two ports must carry VLAN 2000. A trunk with tagged_vlan_mgmt = "auto" carries it too, so the resolvers see the T-Mobile gateway’s router advertisements. The network states enabled = true, because the provider reads a missing enabled key as false, and an update that sends false can disable the backup WAN.
  • Switch ports are managed only through unifi_device_ports. Never use unifi_device with a port_override block, and never both on one device. The port_override block is deprecated in the fork.
  • A port that is not listed in ports.tf runs the controller’s default configuration, so a port changed in the UI shows as drift. Each listed port states only the settings that differ from port to port: name, VLANs, link aggregation, PoE and a few per-port ones. Settings the UI stamps identically everywhere (port security, isolation, storm control, LLDP-MED, STP mode, keepalive, egress rate limiting, autoneg) are left out. The controller keeps them, and Terraform does not assert them, so a UI change to one of those is not drift. State one in ports.tf if it has to be asserted.
  • The resolver trunks are port 12 (sandiego) and port 13 (portland): Core native, every VLAN tagged (tagged_vlan_mgmt = "auto").
  • Port profiles are unifi_port_profile resources. A port that carries a profile on the controller states port_profile_id = unifi_port_profile.<name>.id and no network keys, so the intent the ports share lives in one place. A port with no profile states its network keys. The controller lets a declared port setting win over the profile, so the rule is a convention here, not a provider check.
  • A profile states the settings the controller holds that differ from the provider defaults. The provider reads the egress and storm control rates as null while their feature is off, and a false lldpmed.notify_enabled as null, so those stay unstated. The controller derives forward from tagged_vlan_mgmt. Settings the provider does not declare (STP edge state, PTP, EEE, the QoS profile) stay on the controller, and the fork’s go-unifi tags them, so an update keeps them.
  • Every switch is adopted: switch-main, switch-agg-main, switch-office, switch-kitchen, switch-library, switch-familyroom, switch-recroom and switch-masterbedroom.
  • Site settings are one unifi_setting resource in settings.tf, with the sections the fabric and the resolvers depend on: global_switch (switch-wide DHCP snooping, which DHCP Guard needs), igmp_snooping, radio_ai, ntp, syslog and mgmt. Every other section stays controller-owned, and so do the SSH credentials and keys in mgmt, which the controller stores as secrets. A section is replaced whole on write, so the provider reads it first and writes every undeclared field back as it was.
  • Device Auto-Update is on (mgmt.auto_upgrade.enabled = true). The controller updates the firmware of each switch and access point in the hour that mgmt.auto_upgrade.hour sets. The Device SSH Settings panel of the UI saves the whole mgmt section, so read the plan after a change in that panel.
  • AP groups are unifi_ap_group resources in ap-groups.tf. All three are empty until unifi-wifi-cutover adds the access points.
  • A link aggregation group is declared on its lead port only. The controller keeps an override entry on some member ports (switch-agg-main ports 2 and 4). The provider reads past them and drops them on the first update, and the switch ignores a member’s own settings while the group exists.
Network Purpose VLAN DHCP Guard
Core corporate untagged off
Lab corporate 1000 off
WAN2 vlan-only, T-Mobile WAN transport 2000 off
Main corporate 3000 on: 192.168.20.6, 192.168.20.7, 192.168.20.5
MainWireless corporate 3001 off
IoT corporate 3020 off
Guest guest 3100 on: 192.168.79.6, 192.168.79.7, 192.168.79.5
Telework corporate 3200 on: 192.168.217.6, 192.168.217.7, 192.168.217.5

Every WLAN is a unifi_wlan resource in wlans.tf, one per VLAN, with the SSID name the access points broadcast. A client joins a VLAN by SSID and by nothing else.

SSID VLAN Security Bands Client isolation
kessel-run Main (3000) WPA2/WPA3, PMF optional, 802.11r 2.4, 5 and 6 GHz off
kessel-run-iot IoT (3020) WPA2/WPA3, PMF optional 2.4 GHz off
kessel-run-g Guest (3100) Enhanced Open (OWE), captive portal 2.4, 5 and 6 GHz on
kessel-run-tw Telework (3200) WPA3 only 2.4, 5 and 6 GHz off
  • WPA2/WPA3 is wpa3.support, wpa3.transition and pmf_mode = "optional". A WPA2 client still joins, and a WPA3 client gets PMF. kessel-run and IoT run this mode. Sean set kessel-run to WPA3 only in the UI on 2026-10-13 and back to this mode on 2026-10-14. The files adopted each change.
  • WPA3 only is wpa3.support, wpa3.transition = false and pmf_mode = "required". A client with no WPA3 cannot join. Telework runs this mode.
  • kessel-run runs 802.11r fast roaming (fast_roaming_enabled), proxy ARP and multicast enhancement. A client that moves to another access point carries its key over instead of a full handshake. The access points answer ARP for their clients and send multicast as unicast, so the air carries fewer broadcast frames.
  • Every WLAN states rrm_enabled (802.11k neighbour reports), off as the controller holds it.
  • kessel-run and Guest run the roaming assistant, at -75 dBm on 5 GHz and -88 dBm on 6 GHz. Below the threshold, the access point sends the client a BSS transition request (802.11v) that warns it of the drop, and then drops it. The client has time to move to a closer radio first. Ubiquiti calls this a soft drop and the minimum RSSI a hard drop.
  • The 5 GHz threshold of the roaming assistant is above the -78 dBm minimum RSSI of the 5 GHz radios, so the warning comes before the hard drop. The 6 GHz radios have no minimum RSSI (see Radios). The 6 GHz threshold stays low, because a higher one drops a client that holds a weak but working 6 GHz link over and over.
  • IoT keeps the roaming assistant off. Telework holds no roaming assistant keys, so they stay unstated there.
  • IoT serves 2.4 GHz only, with no2ghz_oui on, so a known dual-band client goes to kessel-run. Its group_rekey is 0, so a sleeping IoT device never misses a group key change.
  • kessel-run also has group_rekey at 0. With the periodic rekey on, a Sonos player and a Mac on the upstairs access point dropped at every rekey, at the same minute of each hour. The controller logs such a drop as a plain wireless disconnect, with no reason, so the fixed minute is the only mark of a rekey drop. Guest and Telework keep the periodic rekey.
  • MLO (one client link across several bands) is off on every WLAN. The controller warns that most WiFi 7 clients use one band and that MLO brings interoperability problems, and Sean decided on 2026-09-30 to follow that advice.
  • The controller refuses the 6g band while the site has no access point with a 6 GHz radio. On a fresh site, declare the WLANs without it, adopt one access point, then add it.
  • The access points are All APs members in ap-groups.tf, by MAC address. Their radios are unifi_device resources in access-points.tf. See Radios.
  • The Guest WLAN has no key. A guest signs in on the captive portal of the gateway with a voucher code. security = "open" with wpa3.support and pmf_mode = "required" is Enhanced Open (OWE), which encrypts the link of each client with no key. A client with no OWE support cannot join.
  • The Guest WLAN still states passphrase_wo, with the key of the earlier WLAN. The controller keeps that key on an open WLAN and returns it on every read. With no passphrase_wo, the provider stores the key in the state, and every apply fails with an inconsistent result on passphrase. No client uses the key.
  • The Guest WLAN sets l2_isolation = true and is_guest = true. is_guest makes the access point apply the guest policy, which blocks private address ranges. The Guest resolvers .5, .6 and .7 sit on the Guest subnet, so the pre-authorization allowances of the portal must hold 192.168.79.0/24. They also hold 192.168.40.1, the address of the portal.
  • The portal is plain HTTP on port 8880 of the gateway, with no domain. A Guest client cannot resolve an internal name, so a portal that redirects to unifi.fzymgc.house never loads. The portal configuration is the site setting guest_access, which Terraform does not manage.
  • The gateway also runs the portal for a wired client on Guest, because Guest is in the Hotspot zone.
  • The keys are fields of secret/fzymgc-house/infrastructure/unifi/wlan in Vault: mainwireless, iot, guest and telework. Each WLAN reads its field at apply time into the write-only passphrase_wo, so no key is in the repository, the state or a plan.
  • To rotate a key, patch the field in Vault and raise passphrase_wo_version on that WLAN in a pull request. Terraform does not compare a write-only value, so the version is what makes the apply send the new key. Every client of that SSID then needs the new key.
  • The provider reads the live WLAN before an update and lays the declared fields over it, so a field left out of wlans.tf keeps the value the controller holds.
Access point Model Switch port Link
ap-basement U7 Pro Max switch-main 17 2.5G, PoE
ap-main-floor U7 Pro Max switch-main 18 2.5G, PoE
ap-upstairs U7 Pro Max switch-main 19 2.5G, PoE
ap-office UniFi Express 7, access point mode switch-office 13 2.5G, own power supply
ap-bedroom4 UniFi Express 7, access point mode switch-main 20 2.5G, own power supply
ap-garage U6 Mesh none, wireless uplink to ap-main-floor or ap-upstairs mesh

A UniFi Express 7 adopts in access point mode on a console with no gateway. It reports as device type udm, not uap, so a dump filter for access points takes both. ap-bedroom4 stands on a desk and serves one bedroom. Until 2026-10-16 it was ap-family-room, meshed to ap-main-floor. A meshed unit has to use the channel of its parent, so in that bedroom it shared the channels of ap-upstairs until its cable was in. The family room has no access point now.

The garage unit is meshed, and the controller picks its parent: it moved between ap-main-floor and ap-upstairs six times in the week before 2026-10-14, and each move drops its clients. The provider has no field for a fixed parent. The unit has 2.4 GHz and 5 GHz radios and no 6 GHz radio.

The pre-wired drops with no access point are switch-familyroom port 8 (ap-familyroom, a Core trunk), switch-library port 2, switch-masterbedroom port 7 and switch-recroom port 7.

  • After an access point adopts, the controller adds it to the All APs group, and the plan shows unifi_ap_group.all_aps as drift. An apply with the old ap-groups.tf empties the group and stops every SSID. So no pull request on tf/unifi merges between an adoption and the pull request that adds that unit’s MAC address to ap-groups.tf.

access-points.tf states three things per unit, and nothing else about the radio table: the 2.4 GHz channel, the 2.4 GHz transmit power, and the minimum RSSI of the 5 GHz and 6 GHz radios. The provider reads the live radio table before an update and lays the declared fields over it, so the channel widths, the 5 GHz and 6 GHz channels and every other radio field stay as the controller holds them. ap-bedroom4 is the exception: it also states its 5 GHz and 6 GHz channels, widths and transmit power. Every radio of a unit has an entry, even a 2.4 GHz radio that is off, as on ap-office and ap-bedroom4. An entry left out plans the removal of that radio on every run.

Access point 2.4 GHz channel 2.4 GHz power 5 GHz minimum RSSI 6 GHz minimum RSSI
ap-basement 1 medium -78 dBm off
ap-main-floor 6 medium -78 dBm off
ap-upstairs 11 medium -78 dBm off
ap-bedroom4 radio off none -78 dBm off
ap-office radio off none -78 dBm off
ap-garage 11 low -78 dBm no 6 GHz radio

ap-bedroom4 is a low-power cell for one bedroom. Its cell overlaps the cell of ap-upstairs, so its 5 GHz and 6 GHz channels are planned and kept apart from those of ap-upstairs:

Band Channel Width Power Why this channel
5 GHz 60 80 MHz low 52 to 64 overlaps only ap-basement, two floors down, on its primary channel
6 GHz 101 160 MHz low 97 to 125 overlaps only the 320 MHz channel of ap-basement, two floors down

The other 5 GHz radios use 36 to 48 (ap-main-floor), 52 to 64 (ap-basement), 100 to 112 (ap-upstairs) and 132 to 144 (ap-office). The T-Mobile gateway uses 149 to 161. Channel 101 is a preferred scanning channel (PSC), one of the 6 GHz channels that a client scans first, so a client finds the radio by its own scan. Low power keeps the clients of ap-upstairs on ap-upstairs.

No 5 GHz radio uses 120 to 128. These channels cover 5600 to 5650 MHz, the band of the airport weather radars (TDWR). A radio on a DFS channel (a 5 GHz channel shared with radar) listens for radar. When it detects radar, it moves itself to another channel and stays off the old one for at least 30 minutes. ap-bedroom4 first had 5 GHz 116 at 80 MHz, which covers 116 to 128. It detected radar on 2026-10-16, four minutes after it came up on 116, and moved to 56. The event log of the 30 days before holds no other radar event.

A radar move changes the channel that the radio runs on, not its configuration. So the plan still shows No changes. To find a move, look for the AP_DETECTED_RADAR_V2 event, or compare channel with current_channel in unifi_get_device_radio on the unifi_ro MCP route.

The 2.4 GHz plan is a vertical 1, 6, 11 stack. Before this plan, automatic selection had put ap-basement, ap-upstairs and ap-garage on channel 6 at full power, and the neighbour scan of 2026-10-14 showed channel 6 as the most crowded channel at every unit, with the cars and the Powerwall gateway on it in the garage. Channel 1 was the cleanest channel at the three stacked units. Medium power shrinks each cell, so two radios on one channel hear less of each other.

The nightly channel optimizer of the controller rewrites a manual channel. On the first night of the plan it moved ap-main-floor to 1 and ap-upstairs to 6, which put three radios on channel 1, and the family room radio read 97% busy the next morning. The speculative plan showed the two moves as drift, and the next apply set the channels back. The UI toggle for the optimizer did not hold: the site setting still read enabled = true after the toggle was set off, and the optimizer moved the same two channels again on the second night. settings.tf now holds it off in the radio_ai section of unifi_setting, and a UI change to it shows up in the plan. With it on, every night is drift, and the daily drift check posts it to Discord. The optimizer logs no event when it moves the channel of a wired unit, so the plan is the only record of that move. An apply and a radar move log AP_CHANGED_CHANNELS on a wired unit too.

Minimum RSSI drops a client whose signal falls below the threshold, so it looks for a closer radio instead of holding a weak link. Only the 5 GHz radios have a threshold. 2.4 GHz has no threshold, because its clients are IoT devices with one radio and nowhere better to go.

The 6 GHz radios had a -75 dBm threshold from 2026-10-15 to 2026-10-16. Before it, a Mac upstairs held the 6 GHz radio of ap-upstairs at -78 to -84 dBm, with sessions of one to eight days. With it on, the Mac ran on 5 GHz at -55 to -69 dBm and dropped about 30 times a day. It came back about 16 seconds after each drop, and some sessions passed no data.

The pattern matches a client that leaves 5 GHz to try 6 GHz and is refused there each time. The controller logs no failed association, so that cause is an inference. A dropped client picks its next radio itself, and an Apple device prefers 6 GHz. The roaming assistant of kessel-run and Guest acts on a weak 6 GHz link instead, at -88 dBm. See WiFi.

Two radios that are not ours sit inside the house and shape the plan. A hidden WPA2 network on channel 11 is heard at -30 dBm from ap-basement and above -42 dBm from three other units. A hidden dual-band WPA2/WPA3 network on channel 2 and channel 153 is heard at -34 dBm from ap-upstairs, which matches the Wi-Fi of the T-Mobile gateway in the master bedroom. Turning those two radios off is the larger gain, and it needs no pull request. The neighbour scan is unifi_list_rogue_aps on the unifi_ro MCP route, or Insights, Neighboring Access Points in the UI.

The WLAN settings that shape roaming are in wlans.tf: rrm_enabled (802.11k neighbour reports), the roaming assistant per band, and the minimum data rate per band as minimum_data_rate_2g_kbps and minimum_data_rate_5g_kbps, which sets how much airtime the beacons of a WLAN take. One setting of the plan has no field in the provider: the fixed mesh parent of a meshed unit, which the UI calls Uplink. The garage unit flips between two parents until the provider fork gains the field.

One row per controller collection in tf/unifi/inventory-summary.json. now is managed. after the cutover is a collection that only a gateway uses and that holds no object yet. Terraform manages it from its first object. never names the owner or the reason. scripts/unifi-field-audit.py gates each tier: a collection is imported only after it prints no gap for it.

Collection Objects Managed Where, or why not
account 0 never RADIUS accounts
apgroups 3 now ap-groups.tf
bgp-config 0 now bgp.tf. See BGP
channelplan 3 never radio channel plan, controller-owned
device-tags 0 never UI labels
dhcpoption 0 never UniFi serves no DHCP
dpiapp 0 never DPI catalogue, controller-owned
dpigroup 1 never DPI catalogue, controller-owned
dynamicdns 0 never Cloudflare owns dynamic DNS
firewall-policies 104 now firewall-zones.tf: the user policies. The 101 predefined policies stay controller-owned
firewall-zone 7 now firewall-zones.tf: the custom zone Telework. The six built-in zones are read by name and stay controller-owned
firewallgroup 0 after the cutover address and port groups for policies
firewallrule 0 after the cutover legacy rules, if any survive the classification
hotspotop 0 never hotspot operators, unused
hotspotpackage 0 never hotspot packages, unused
nat 0 after the cutover NAT rules
network-members-groups 0 never UI grouping
networkconf 10 now networks.tf. The two WAN networks of the gateway stay controller-owned
ospf-router 0 never no OSPF in the estate
portconf 4 now port-profiles.tf
portforward 0 after the cutover port forwards. The rule classification of the cutover keeps none
power-supervisors 10 never PoE power state, controller-owned
radiusprofile 1 never no RADIUS in the estate
routing 0 after the cutover static routes
scheduletask 1 never controller maintenance schedule
setting 32 now settings.tf: global_switch, igmp_snooping, ntp, rsyslogd, mgmt. Other sections stay controller-owned
spatialrecord 0 never map data
stat-device 14 now ports.tf and ports-<switch>.tf manage port_overrides only, through raw JSON. Adoption, radios and the rest of the device record are never managed
static-dns 0 never the resolver pair owns names
trafficroutes 0 after the cutover traffic routes
user 187 never clients. Kea owns addressing and the resolver pair owns names. When unifi_alias.enabled is true, dns-control writes the name and the note of each client whose MAC a curated entry holds
usergroup 2 never client bandwidth groups, UI-only
wlanconf 4 now wlans.tf
wlangroup 2 never the built-in Default and Off groups, which the controller does not let anyone edit
the site 1 never one site, created by the console
  1. Edit the port’s entry in ports.tf. The plan shows the keys you changed, and known after apply for keys the controller sets as a side effect, such as lag_idx on a new aggregation lead.
  2. For VLANs, set native_networkconf_id plus tagged_vlan_mgmt. The values are auto (every network tagged), block_all (nothing tagged) or custom with excluded_networkconf_ids. The controller derives the legacy forward field and ignores writes to it. A custom port that excludes every VLAN network is stored as block_all, so declare block_all for that case.
  3. For link aggregation, declare the group on its lead port only, with op_mode = "aggregate" and aggregate_members. The switch-main groups are 6 with 7, 23 with 24, and 25 with 26.
  4. Removing a setting from ports.tf leaves its value on the controller. To change a value, state the new one.
  5. To end a link aggregation group, remove the whole entry of its lead port. The provider then drops the entry on the controller, and the lead and its members run the default configuration. An entry that stays keeps the member list that the controller holds.

Never destroy the resource. Destroying it resets every port on the switch, uplinks included, and prevent_destroy blocks that plan. To stop managing the switch, use removed { from = unifi_device_ports.switch_main; lifecycle { destroy = false } }.

The controller UI writes the same objects that tf/unifi declares. An apply of main-cluster-unifi sets each object back to what the files state, so a UI change that the files do not hold is lost on the next confirmed apply. Run this procedure in four cases:

  • A pull request touches tf/unifi, and its plan changes an object that the pull request does not change. The check Terraform Cloud/fzymgc-house/main-cluster-unifi on the pull request shows the summary of its plan.
  • The daily drift check of the Temporal worker posts a change for main-cluster-unifi to Discord.
  • Someone changed a setting in the UI.
  • A device adopted. The controller adds a new access point to All APs, for example.
  1. Run a speculative plan from a checkout of origin/main. It creates no apply:

    Terminal window
    terraform -chdir=tf/unifi init
    terraform -chdir=tf/unifi plan -no-color > /tmp/unifi.plan
  2. List each object that the plan changes. On a changed line, the value on the left of -> is the live value, and the value on the right is the declared value. On a changed port, ignore the keys that read (known after apply). A port that the plan removes, with -> null on each key, is a port that the UI configured and the files do not declare.

  3. Ask the operator which changes were intended. Do not decide for the operator.

  4. Write the live value of each intended change into the file that owns the object: ports.tf or ports-<switch>.tf for a switch port (see Change a port), settings.tf, networks.tf, wlans.tf, ap-groups.tf or firewall-zones.tf. Refer to a network by its resource, for example unifi_network.main.id. main.tf maps each _id to its resource.

  5. Run the plan again. It must report No changes. Your infrastructure matches the configuration.

  6. Open the adoption as its own pull request, and merge it before any other pull request on tf/unifi. Then update the other pull request from main, and read its plan again.

After the merge, the run of main-cluster-unifi plans no changes and finishes with no confirmation. A change that the operator did not intend needs no code: the next confirmed apply sets it back. To set it back at once, change it back in the UI. On a Discord drift post, choose Reject for a change that you adopt. Approve applies the plan and sets the UI change back.

Network 11 re-keyed every object to a UUID. The v1 API resolves the old id of a network, a WLAN or a port profile through legacy_id, so those resources refresh their id on the next plan. A firewall zone, an AP group or a firewall policy is read from its list, and nothing in the list carries the old id. The provider stops a read of one by an id of the old form that finds nothing, with the message not found by its pre-Network 11 id, because a silent removal plans a second object with the same name. To move such a resource to its new id:

  1. Read the new id from the controller. scripts/unifi-readonly.sh scripts/unifi-inventory.py writes each collection to the dump directory, and jq '.[] | {_id, name}' lists the ids.

  2. Set the new id in the import block of the resource in tf/unifi/main.tf. Terraform ignores an import block whose address is in the state, so the block can change before the next step.

  3. From tf/unifi, after terraform login, remove the resource from the state:

    Terminal window
    terraform state rm unifi_firewall_zone.telework
  4. The next plan imports the resource by its new id and shows no other change for it.

Client groups (usergroup) have no data source in the provider, so wlans.tf names their ids in locals. Those are UUIDs since Network 11 too.

The upgrade to Network 11 also set mgmt.auto_upgrade to false. No admin did that, so the plan after the upgrade sets it back to the stated true.

The UCG-Fiber is the gateway and the controller since the cutover of 2026-10-01. The facts in this section are measurements on UniFi OS 5.1.33 and Network 10.6.106, on the bench and in the cutover window.

The bench WAN was the T-Mobile gateway, which delegates no IPv6 prefix. So the bench showed the keys for prefix delegation, and the window proved the delegated /64 on FiOS.

Port Role Link
4 (2.5 GbE) Internet 2, T-Mobile, failover only switch-main port 21
5 (10 GbE RJ45) Internet 1, FiOS the ONT
6 (SFP+) LAN switch-agg-main port 6
  • The Cloud Key is powered off, and it must stay off. The two UniFi Express 7 access points do not follow the inform override of a controller. After the first configuration push from the UCG-Fiber, they went back to the Cloud Key, which gave them its old WLAN configuration.
  • To move an Express 7 access point to a controller, run mca-cli-op set-inform http://192.168.40.1:8080/inform on it as root. A switch or a U7 Pro Max takes the same command as the SSH user of the site. The short command set-inform exists only at the prompt of a device.
  • switch-kitchen accepts no SSH connection. Only the inform override can move it.
  • FiOS answers a DHCPv6 request for a prefix only. The IPv6 connection type of Internet 1 must be SLAAC with prefix delegation of size 56. With the type DHCPv6, the gateway also asks for an address, and FiOS sends no reply.
  • FiOS gives a new router no prefix until the lease of the old router ends. A lease is two hours long. To make the gateway ask again, send USR2 to the odhcp6c process of the WAN port.
  • The gateway does not use ipv6.pd.prefixid. It numbers the legs itself, and the UI states that a later release adds a manual prefix ID. The assignment is in /data/udapi-config/pd.leases.
  • The ULA address of ipv6.aliases is on a bridge only while ipv6.interface_type is pd.
  • WAN failover moves a client to T-Mobile in about 3 seconds, and back to FiOS in about 4 seconds.
  • A restart of the gateway stops the internet for about 80 seconds. Each bridge then holds its ULA ::1 and the same global /64 again, and FiOS gives the prefix back at once.
  • A host that holds the gateway as its DNS server by hand can fail after a gateway change. The NAS held two addresses of the old gateway, and it now uses the Main VIP of the resolver pair.

Each row names one field of the network form in the UI and the keys that the controller writes to the networkconf object.

UI field Keys the controller writes
New network with a subnet purpose = corporate, ip_subnet, vlan, firewall_zone_id, dhcpguard_enabled with dhcpd_ip_1. lte_lan_enabled and mdns_enabled are on by default
IPv6 interface type, prefix delegation ipv6_interface_type = pd, ipv6_pd_interface = wan, ipv6_pd_auto_prefixid_enabled, ipv6_pd_start, ipv6_pd_stop, ipv6_client_address_assignment = slaac, ipv6_ra_enabled, ipv6_ra_priority, dhcpdv6_allow_slaac = true, dhcpdv6_dns_auto. The network also holds ipv6_setting_preference = manual
A DNS server in place of Auto dhcpdv6_dns_1 to dhcpdv6_dns_4, dhcpdv6_dns_auto = false
IPv6 Additional IPs ipv6_aliases = ["<ula>::1/64"]

The provider fork models every key in the table. From 0.60.0-fzymgc.1 the IPv6 keys are the ipv6 object: dhcpdv6_allow_slaac is dhcp_v6_server.allow_slaac, ipv6_setting_preference is ipv6.setting_preference, and ipv6_aliases is ipv6.aliases. The provider sends allow_slaac and setting_preference only when the configuration states them, and it keeps the live alias list when the configuration states none.

  • ipv6.aliases holds the ULA (unique local IPv6 address) gateway address of a leg. The gateway puts the address on the bridge of the network, beside the delegated prefix, with a connected route. It routes ULA traffic between two legs in both directions.
  • The gateway runs dnsmasq in ra-only mode and no DHCPv6 service. The router advertisement carries every global prefix on the bridge, the ULA prefix included. The dhcpdv6_dns_* keys set the DNS servers that the advertisement carries as RDNSS (the DNS server option of a router advertisement).
  • dnsmasq answers DNS on the .1 address of every network, and SSH and the web UI listen on every address. So a zone policy must block them from an untrusted leg.
  • The DHCP Guard keys stay on a network while the DHCP server of the gateway is off, and the switches enforce them.
  • A WAN network carries routing_table_id. The fork models it from the same release.

The zone-based firewall puts each network in a zone and filters traffic between zones with policies. The upgrade from the legacy firewall is one-way.

  • To read the mode, dump the controller. In legacy mode, firewall-zone and firewall-policies are empty, and no network has a firewall_zone_id.
  • After the upgrade, firewall-zone holds six built-in zones: Internal, External, Gateway, Vpn, Hotspot and Dmz. firewall-policies holds 63 predefined policies, and every network has a firewall_zone_id.
  • The Zone field of a network offers Internal, Hotspot, DMZ and each custom zone. So any network can join Hotspot.
  • A zone carries cloud_template and external_id, and a policy carries origin_id. The fork models all three from release 0.56.0-fzymgc.8.

The table shows what a client reaches when its leg is in Hotspot or in a new custom zone, with no user policy:

Probe from the leg Hotspot Custom zone
A host on an internal leg blocked blocked
The other untrusted zone blocked blocked
Gateway DNS allowed over IPv4 by the locked policy Allow DNS, blocked over IPv6 allowed
Gateway SSH and HTTPS blocked allowed
Neighbor discovery to the gateway allowed allowed
A host on the same leg reachable reachable
  • The controller puts a user policy above the locked policies, so the user policy takes precedence. A user policy that blocks port 53 to the Gateway zone stops the DNS that Allow DNS lets through.
  • A reject policy answers a TCP connection at once. A UDP query still waits for its timeout.
  • Guest is in Hotspot with two policies. guest-block-gateway-dns blocks TCP and UDP port 53 to the Gateway zone. guest-block-internal blocks all traffic to the Internal zone, because the built-in policy Allow Public DNS accepts port 53 from Hotspot to Internal. With no second policy, a Guest client gets internal answers from the resolver of a trusted leg.
  • Telework is in a custom zone Telework with one policy, telework-block-gateway: reject all TCP and UDP to the Gateway zone. ICMP stays open on Telework, because neighbor discovery needs it.
  • Internal has one policy, internal-log-external-dns. It allows TCP and UDP ports 53 and 853 from Internal to External, and it logs each new connection. The resolvers send their queries upstream through dnscrypt-proxy, so a log line names a client that bypasses them. The one expected exception is the bootstrap queries of dnscrypt-proxy to 9.9.9.9 and 149.112.112.112. The policy matches new connections only, so a long DNS-over-TLS session gives one line. The lines go out with the syslog of the gateway, which syslog in settings.tf directs. The UniFi rows gives a query.
  • The controller puts the rules of internal-log-external-dns at the top of the chain UBIOS_LAN_WAN_USER on the gateway. They are above the drop of the object policy smart-tv-block, which the UI holds. So the policy accepts the first packet of a new DNS connection from a device in smart-tv-block. A UDP query of one packet reaches the internet. A TCP or DNS-over-TLS connection fails, because the drop of smart-tv-block matches every later packet. For every other client, the gateway accepted this traffic before the policy too.
  • A block policy for DNS from Internal to External that someone adds later goes below internal-log-external-dns and does not see a new connection. To make the block policy work, move it above internal-log-external-dns in the UI.
  • Hotspot runs the captive portal of the site on every network in the zone, for a wired client too. The portal authorizes a client over IPv4 only, and the gateway drops IPv6 from a guest to the internet. So a Guest client has no IPv6 path to the internet.
  • A network update that states no firewall_zone_id sends none, and the controller then chooses the zone. Each leg states its zone in networks.tf.
  • The controller gives a network in Hotspot the purpose guest. So tf/unifi states purpose = "guest" for Guest. If the configuration states corporate, the next apply moves Guest out of Hotspot, and the fence of Guest opens.
  • No policy names an address outside the estate. Such an address belongs to a third party and can change, so the repository does not hold one.

tf/unifi/firewall-zones.tf declares the zone Telework as a unifi_firewall_zone and each user policy as a unifi_firewall_policy. It reads the built-in zones by name with the unifi_firewall_zone data source, because the controller creates and owns them.

  • Add a policy through a pull request. The controller puts a new user policy last in its zone pair, and the provider cannot change the order. To change the order, use the UI.
  • The network is the one writer of zone membership, through firewall_zone_id. The zone resource states no network_ids and ignores a change to the list. When the provider does not know the list, it sends an empty one, and an empty list takes Telework out of its zone.
  • The provider builds a zone update from name and network_ids only. The controller object also holds external_id, and an update does not send it. Do not rename the zone Telework through Terraform until the provider sends that key.
  • The provider cannot set six keys of a policy: match_ip_sec and match_opposite_protocol, and on each side match_mac, match_opposite_ips, match_opposite_networks and match_opposite_ports. It sends false for each. A policy that needs one of them as true cannot be managed.
  • A policy holds hits and last_hit after its first match. They are traffic counters that the controller computes, and the field audit does not count them as a gap.

The UCG-Fiber peers with every node of the cluster and learns a host route for each routed LoadBalancer VIP, in 192.168.250.0/24 and fddb:f665:73f7:250::/64. The site holds one BGP configuration: an FRR file. In Network 10.6, the UI shows it under Settings, Policy Engine, Routing. Select the BGP filter, then select Manage under Configuration. tf/unifi/bgp.tf declares it as the unifi_bgp resource site, in raw mode.

Item Value
Gateway AS 65000, router ID 192.168.200.1
Cluster AS 65001, one session per node and family, from the Lab leg of the node
IPv4 peers peer group CILIUM4: the Lab address 192.168.200.<host> of each node, passive
IPv6 peers peer group CILIUM6: the Lab ULA fddb:f665:73f7:4:aaaa::<host> of each node, passive
Timers keepalive 3 seconds, hold 9 seconds, graceful restart
Import host routes inside the VIP prefixes, nothing else
Export nothing
Fallback a blackhole route for each VIP prefix, distance 250, in tf/unifi/static-routes.tf
  • A VIP that no node announces has no host route. Without the fallback, the gateway sends its traffic out of the default route to the WAN. The policy rule 32000 of the gateway reads the main table before the tables of the WANs, so the blackhole route in main drops that traffic. An announced VIP keeps its BGP host route, because a host route is longer than the prefix.
  • The file must agree with argocd/app-configs/cilium-lb/bgp.yaml on the ASNs, the peer addresses and the timers.
  • The gateway peers with the node addresses and with no other host, so a Lab host cannot peer from a free address. bgp_node_hosts in bgp.tf lists the host octets, and a new node needs its octet there. A node that is down still shows in the summary, as a neighbor that is not established.
  • The gateway loads the route-maps and the prefix lists only when they come after the router bgp section, each block closed with exit. Ubiquiti documents this placement. A prefix list above router bgp never reaches FRR, so the route-map matches nothing and the import filter drops every route.
  • An update posts the whole object to v2/api/site/default/bgp/config. The go-unifi struct BGPConfig models every key that the BGP form of the UI writes: frr_bgpd_config, description, enabled, uploaded_file_name, device_mac, redistribute_to_sd_wan and redistribute_to_sd_wan_type. It also models error, a status that the controller sets.
  • Before each write, unifi_bgp reads the stored object and lays the plan over it. A key that bgp.tf does not declare keeps its stored value. The provider never sends error, because the UI never sends it.
  • The provider keeps only the keys that BGPConfig models. If the field audit prints a gap for bgp-config, no change to bgp.tf merges until the fork models the new key.
  • The Override WAN Monitors checkbox in the same panel writes unbind_wan_monitors to the usg setting. It does not change the BGP object.
  • Guest and Telework cannot reach the VIP prefixes in either family. The zone policies block them, and no policy names the prefixes. A probe from Guest needs a client that holds a voucher on the captive portal. An unauthorized client reaches nothing past the portal, so its failure proves nothing about the fence.
  • The UI lists each neighbor with its state, but its route counts lag the gateway. Read the current state with vtysh on the console, over SSH as root. The console SSH setting is under Settings, Control Plane, Console.
Terminal window
ssh root@192.168.40.1 "vtysh -c 'show bgp ipv4 unicast summary' -c 'show bgp ipv6 unicast summary'"
# one established neighbor per node in each family
ssh root@192.168.40.1 "vtysh -c 'show ip route bgp' -c 'show ipv6 route bgp'"
# one host route per VIP, with next hops at the Lab addresses of the nodes that serve it
ssh root@192.168.40.1 "vtysh -c 'show bgp ipv4 unicast neighbors 192.168.200.142 received-routes'"
# what one node announces, before the import filter. A node announces only the VIPs of the
# Services that have a ready endpoint on it
ssh root@192.168.40.1 "vtysh -c 'show ip prefix-list' -c 'show ipv6 prefix-list'"
# LB-VIPS and LB-VIPS6, one entry each. If either is missing, the gateway imports nothing
ssh root@192.168.40.1 "ip route get 192.168.250.149; ip route get 192.168.250.200"
# the announced VIP goes via the Lab address of a node on br1000. The free address returns an
# error or a blackhole route, and never a route via eth4 or eth3, the WANs

The gateway, the switches and the APs send their syslog to the network collector otel-network on the VIP 192.168.250.150 (The UniFi rows). syslog.ip and syslog.port in settings.tf set the target, UDP 514, for every device. To make sure that rows arrive, run this query in ClickStack: SELECT LogAttributes['hostname'] AS device, count() FROM default.otel_logs WHERE ServiceName = 'unifi' AND Timestamp > now() - INTERVAL 10 MINUTE GROUP BY device.

Three replicas of the collector keep the VIP announced while one restarts. If no node announces it, the blackhole route of the VIP prefix drops the stream (BGP), so it does not leave through the default route to the WAN.

unifi_setting.syslog owns four controls of the Traffic Logging page (Settings, CyberSecure, Traffic Logging). Do not change them in the UI, because the change becomes drift:

UI control Field of syslog
Activity Logging, Off enabled
Activity Logging, Internally Stored this_controller.enabled = true
Activity Logging, SIEM Server this_controller.enabled = false, with ip and port
Debug Logs debug

Internally Stored and SIEM Server are one choice. The API keeps this_controller and ip as separate fields, but the controller sends the logs to one target only. While this_controller is on, the controller ignores ip. It then sets syslog.remote.ip=127.0.0.1 and syslog.remote.port=5514 in /tmp/system.cfg on the gateway, and the Network application receives the logs itself. services.systemLog in the state of ubios-udapi-server stays "enabled": false. To read which target the gateway has, run this as root on the gateway:

Terminal window
jq -c .services.systemLog /data/udapi-config/ubios-udapi-server/ubios-udapi-server.state
grep '^syslog\.remote' /tmp/system.cfg

Keep NetFlow (IPFIX) off. The gateway meters IPFIX in the kernel module ipt_NETFLOW, which sees only the packets that pass through the CPU. While IPFIX export is on, the gateway turns off its hardware offload, and every forwarded packet goes through the CPU. Both WAN links run at 10 Gb.

Flow Logging is a UI setting (the setting traffic_flow), and tf/unifi does not manage it. It feeds the flow store of Insights, not the syslog. All Traffic adds an NFLOG rule with --nflog-group 1 for the new connections of every zone pair, and ulogd writes group 1 to /run/.fw_mq.socket for Insights (/run/mq-ulogd.conf). Without a drive in the console, the store holds about 10,000 records. All Traffic logs about 10 new connections per second from Internal to External alone, so it replaces every record, the blocked ones too, in about 15 minutes. Flow Logging stays at Blocked Traffic Only until the console has an NVMe drive.

To get allowed traffic into ClickStack, set logging = true on a zone policy that matches it, as internal-log-external-dns does. Its rule writes to NFLOG group 0, and ulogd sends group 0 to the syslog. A save of the Traffic Logging page reloads the firewall of the gateway. The table of offloaded connections then empties and fills again in a few minutes.

Question Answer
Does the UCG-Fiber take a BGP configuration? Yes. It takes an FRR configuration file, under Settings, Policy Engine, Routing in Network 10.6. The fork manages it with unifi_bgp
Does the WireGuard server take an existing private key? Not in the UI, which generates a new key pair. The fork does: unifi_vpn_server takes wireguard.private_key and sends it as x_wireguard_private_key. The attribute has no write-only variant, so the key is in the workspace state
Can an automation account create its own API key? No. A key is created under Settings, Control Plane, Integrations, and it carries the rights of the admin who creates it. A Network Full Management admin does not see that page. So automation-admin and automation-readonly stay on a password. The View Only account was not tested
What does a restore of a Cloud Key backup keep? The site, with the WAN networks of the UCG-Fiber added. UniFi OS is untouched, so the automation accounts, their roles and the certificate stay. The firewall returns in legacy mode, so upgrade it again after a restore

scripts/unifi-inventory.py dumps every collection the controller holds, one JSON file per collection, with every x_ key removed. Those keys are controller-side secrets. The dump holds household device names, so it goes to a scratch directory whose name ends in .unifi-dump, which Git ignores. Standard output gets a summary that is safe to commit: per collection, the object count and the sorted key names, and no value. The committed copy is tf/unifi/inventory-summary.json.

Terminal window
scripts/unifi-readonly.sh scripts/unifi-inventory.py /tmp/before.unifi-dump > tf/unifi/inventory-summary.json

The wrapper reads the View Only credential from Vault, so vault login first. A collection the controller refuses is named on standard error, the other collections are still written, and the exit code is 1. Network 11.0.89 refuses none of the listed collections. It returns the frr_bgpd_config of the BGP configuration only to an admin account, so the dump lacks it.

scripts/unifi-field-audit.py compares each dumped collection with the JSON tags of the struct that models it in the go-unifi fork, and prints the fields the fork does not model. The UniFi API replaces a whole object on update, so a field the fork does not model is deleted by the first Terraform update, and no plan shows it. A collection is imported into Terraform only after the audit prints no gap for it at the go-unifi commit the provider release was built from.

Terminal window
scripts/unifi-field-audit.py /tmp/before.unifi-dump --go-unifi /Volumes/Code/github.com/fzymgc-house/go-unifi --tier one

--tier one gates the objects adopted on the current controller: networks, port profiles, AP groups and the setting sections mgmt, ntp, igmp_snooping, rsyslogd and global_switch. --tier two gates the objects adopted at or after the gateway cutover. --tier all audits every collection that has a struct. The exit code is 1 when a collection in the requested tier has a gap. The output names the go-unifi commit it read.

The audit reads struct tags only. For a network, go-unifi builds each request with one encoder struct per purpose in unifi/network_encode.go, and an encoder that lacks a key drops it on update. The audit printed no gap for firewall_zone_id while no encoder sent it. The provider is a third layer: it must set the struct field, or the key never leaves Terraform. The audit printed no gap for dhcpdv6_allow_slaac while the provider had no attribute for it. For a network key, also make sure that the encoder of each purpose that uses the key carries it, and that unifi/network_resource.go in the provider sets the field:

Terminal window
rg -n '"firewall_zone_id' /Volumes/Code/github.com/fzymgc-house/go-unifi/unifi/network_encode.go

The audit counts every object in a collection. It does not know which objects Terraform manages. Before you state the risk of a gap, find the objects that hold the key:

Terminal window
jq -c '.[] | select(has("uplink_identity")) | {name, purpose, wan_networkgroup}' /tmp/before.unifi-dump/networkconf.json

Only the two WAN networks, Internet 1 and Internet 2, hold is_wifi_tethering and uplink_identity, and tf/unifi manages neither network. Internet 2 is not the network that unifi_network.wan2 manages. That resource manages the vlan-only network named WAN2 on VLAN 2000, and WAN2 is also the network group (wan_networkgroup) of Internet 2.

A WAN network in tf/unifi needs provider 0.56.0-fzymgc.14 or later. From that release, the update of unifi_wan reads the live network and lays the plan over it, and go-unifi sends every key that the two WAN networks hold. An earlier release sends only the keys that the resource declares, and an update with it deletes at least 15 keys of a WAN network.

No WAN network is in tf/unifi yet. An update of unifi_wan also sends three keys that the live network does not hold, and no test shows what the controller does with them:

Key Sent value
ipv6_enabled true when wan_type_v6 is not disabled
wan_vlan 0 when the network has no VLAN id
attr_hidden_id the network group. Internet 2 holds no such key

Before the first update of an adopted WAN network, dump the controller. After the update, dump it again and compare the WAN network in the two dumps.

To prove that a controller move kept every object, dump before the backup and after the restore with --for-diff, which drops ids, timestamps and device state, then diff the two directories:

Terminal window
scripts/unifi-readonly.sh scripts/unifi-inventory.py /tmp/before.unifi-dump --for-diff > /dev/null
scripts/unifi-readonly.sh scripts/unifi-inventory.py /tmp/after.unifi-dump --for-diff > /dev/null
diff -r /tmp/before.unifi-dump /tmp/after.unifi-dump
  • DHCP Guard is dhcpguard_enabled plus the trusted list in dhcpd_ip_1, dhcpd_ip_2 and dhcpd_ip_3 on each rest/networkconf object. There is no dhcpguard_ip key. Reading one returns nothing, whatever is configured.
  • vlan is an integer on most networks, a string on some, and absent on the untagged one.
  • The admin activity log answers who changed which field, when, from which app, with the old and new values: POST /proxy/network/v2/api/site/default/system-log/admin-activity with {timestampFrom, timestampTo, pageSize, pageNumber}. The View Only account can run it. The mobile app writes DHCP Guard fields too, so read this log first when the fabric behaves unexpectedly.
  • When the controller creates a network, it adds the network to the excluded_networkconf_ids list of every custom port and port profile. So a new network is not tagged on a custom port at first. The next apply of each list removes the network from it again, unless the list names it. A pull request that adds a network therefore plans a second change on every custom list, and the first apply reports Provider produced inconsistent result for any list it wrote while the network was new.
  • A dhcp_v6_server block reads lease, start and stop from the controller, also when the configuration does not state them. A network that was corporate before the block existed holds dhcpdv6_leasetime, dhcpdv6_start and dhcpdv6_stop. So a new block on such a network must state all three. Without them, the first apply writes the other fields and then reports Provider produced inconsistent result after apply, and each later plan shows the three values going to null.
  • About eight UniFi OS logins in a few minutes return HTTP 429. Leave time between dumps.
  • A port profile leaves in two changes. The controller refuses to delete a profile that a port holds, with api.err.ObjectReferredByDevice. Terraform deletes a removed profile before it updates the port that held it, so one change that does both fails at the apply. Move the port to another profile in the first change, and remove the profile in the second one.
  • The provider cannot move a port from a port profile to its own network keys. It does not clear portconf_id, so the controller keeps the profile and ignores the keys. Move a port to another profile instead. The reverse move, from a port’s own keys to a profile, works. Read the port back after an apply that changes the kind of configuration a port holds, and make sure that the port is the one the device hangs on: the client table of the controller names the switch and the port of every client.
  • The provider has no field for the state of a port. To turn a port off, give it the profile Disabled from port-profiles.tf. To turn the port on again, move it to another profile.