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.
Controller
Section titled “Controller”| 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.
Console certificate
Section titled “Console certificate”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:
-
Read the token from Vault:
Terminal window vault kv get -field=cloudflare_api_token secret/fzymgc-house/infrastructure/unifi/acme -
In UniFi OS, open Control Plane, then Console, then Certificates.
-
Add a Let’s Encrypt certificate for
unifi.fzymgc.house. Select Cloudflare as the DNS provider and enter the token. -
Make sure that a client verifies the certificate.
curlmust 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:
echo | openssl s_client -connect unifi.fzymgc.house:443 -servername unifi.fzymgc.house 2>/dev/null | openssl x509 -noout -issuer -enddateunifi.fzymgc.houseresolves to the UCG-Fiber since the cutover of 2026-10-01. dns-control owns the record, as the entryunifi. The entryunifi_ckpholdsunifi-ckp.fzymgc.house,192.168.40.2and 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.
Credentials
Section titled “Credentials”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.
What Terraform manages
Section titled “What Terraform manages”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-unifidoes 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 intf/unififirst. 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.housethat Kea hands out, anddhcp_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 oneipv6object withpdandraobjects inside it, the shape the provider uses from0.60.0-fzymgc.1. - A controller with no UniFi gateway refuses prefix delegation. An update that holds
ipv6.interface_type = "pd"fails withapi.err.GatewayRequiredForPdConfig, and the network keeps every old value. So the legs stateipv6.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 statefalse. - 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 withtagged_vlan_mgmt = "auto"carries it too, so the resolvers see the T-Mobile gateway’s router advertisements. The network statesenabled = true, because the provider reads a missingenabledkey as false, and an update that sends false can disable the backup WAN.- Switch ports are managed only through
unifi_device_ports. Never useunifi_devicewith aport_overrideblock, and never both on one device. Theport_overrideblock is deprecated in the fork. - A port that is not listed in
ports.tfruns 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 inports.tfif 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_profileresources. A port that carries a profile on the controller statesport_profile_id = unifi_port_profile.<name>.idand 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_enabledas null, so those stay unstated. The controller derivesforwardfromtagged_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_settingresource insettings.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,syslogandmgmt. Every other section stays controller-owned, and so do the SSH credentials and keys inmgmt, 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 thatmgmt.auto_upgrade.hoursets. The Device SSH Settings panel of the UI saves the wholemgmtsection, so read the plan after a change in that panel. - AP groups are
unifi_ap_groupresources inap-groups.tf. All three are empty untilunifi-wifi-cutoveradds 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.transitionandpmf_mode = "optional". A WPA2 client still joins, and a WPA3 client gets PMF.kessel-runand IoT run this mode. Sean setkessel-runto 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 = falseandpmf_mode = "required". A client with no WPA3 cannot join. Telework runs this mode. kessel-runruns 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-runand 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_ouion, so a known dual-band client goes tokessel-run. Itsgroup_rekeyis 0, so a sleeping IoT device never misses a group key change. kessel-runalso hasgroup_rekeyat 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
6gband 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 APsmembers inap-groups.tf, by MAC address. Their radios areunifi_deviceresources inaccess-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"withwpa3.supportandpmf_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 nopassphrase_wo, the provider stores the key in the state, and every apply fails with an inconsistent result onpassphrase. No client uses the key. - The Guest WLAN sets
l2_isolation = trueandis_guest = true.is_guestmakes the access point apply the guest policy, which blocks private address ranges. The Guest resolvers.5,.6and.7sit on the Guest subnet, so the pre-authorization allowances of the portal must hold192.168.79.0/24. They also hold192.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.housenever loads. The portal configuration is the site settingguest_access, which Terraform does not manage. - The gateway also runs the portal for a wired client on Guest, because Guest is in the
Hotspotzone. - The keys are fields of
secret/fzymgc-house/infrastructure/unifi/wlanin Vault:mainwireless,iot,guestandtelework. Each WLAN reads its field at apply time into the write-onlypassphrase_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_versionon 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.tfkeeps 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 APsgroup, and the plan showsunifi_ap_group.all_apsas drift. An apply with the oldap-groups.tfempties the group and stops every SSID. So no pull request ontf/unifimerges between an adoption and the pull request that adds that unit’s MAC address toap-groups.tf.
Radios
Section titled “Radios”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.
By tier
Section titled “By tier”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 |
Change a port
Section titled “Change a port”- Edit the port’s entry in
ports.tf. The plan shows the keys you changed, andknown after applyfor keys the controller sets as a side effect, such aslag_idxon a new aggregation lead. - For VLANs, set
native_networkconf_idplustagged_vlan_mgmt. The values areauto(every network tagged),block_all(nothing tagged) orcustomwithexcluded_networkconf_ids. The controller derives the legacyforwardfield and ignores writes to it. Acustomport that excludes every VLAN network is stored asblock_all, so declareblock_allfor that case. - For link aggregation, declare the group on its lead port only, with
op_mode = "aggregate"andaggregate_members. The switch-main groups are 6 with 7, 23 with 24, and 25 with 26. - Removing a setting from
ports.tfleaves its value on the controller. To change a value, state the new one. - 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 } }.
Adopt a UI change
Section titled “Adopt a UI change”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 checkTerraform Cloud/fzymgc-house/main-cluster-unifion the pull request shows the summary of its plan. - The daily drift check of the Temporal worker posts a change for
main-cluster-unifito Discord. - Someone changed a setting in the UI.
- A device adopted. The controller adds a new access point to
All APs, for example.
-
Run a speculative plan from a checkout of
origin/main. It creates no apply:Terminal window terraform -chdir=tf/unifi initterraform -chdir=tf/unifi plan -no-color > /tmp/unifi.plan -
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-> nullon each key, is a port that the UI configured and the files do not declare. -
Ask the operator which changes were intended. Do not decide for the operator.
-
Write the live value of each intended change into the file that owns the object:
ports.tforports-<switch>.tffor a switch port (see Change a port),settings.tf,networks.tf,wlans.tf,ap-groups.tforfirewall-zones.tf. Refer to a network by its resource, for exampleunifi_network.main.id.main.tfmaps each_idto its resource. -
Run the plan again. It must report
No changes. Your infrastructure matches the configuration. -
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 frommain, 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.
Ids after Network 11
Section titled “Ids after Network 11”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:
-
Read the new id from the controller.
scripts/unifi-readonly.sh scripts/unifi-inventory.pywrites each collection to the dump directory, andjq '.[] | {_id, name}'lists the ids. -
Set the new id in the
importblock of the resource intf/unifi/main.tf. Terraform ignores animportblock whose address is in the state, so the block can change before the next step. -
From
tf/unifi, afterterraform login, remove the resource from the state:Terminal window terraform state rm unifi_firewall_zone.telework -
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.
UCG-Fiber gateway
Section titled “UCG-Fiber gateway”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.
The cutover
Section titled “The cutover”| 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/informon it asroot. A switch or a U7 Pro Max takes the same command as the SSH user of the site. The short commandset-informexists 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 1must 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
USR2to theodhcp6cprocess 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.aliasesis on a bridge only whileipv6.interface_typeispd. - 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
::1and the same global/64again, 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.
Network fields
Section titled “Network fields”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.aliasesholds 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
dnsmasqinra-onlymode and no DHCPv6 service. The router advertisement carries every global prefix on the bridge, the ULA prefix included. Thedhcpdv6_dns_*keys set the DNS servers that the advertisement carries as RDNSS (the DNS server option of a router advertisement). dnsmasqanswers DNS on the.1address 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.
Zone firewall
Section titled “Zone firewall”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-zoneandfirewall-policiesare empty, and no network has afirewall_zone_id. - After the upgrade,
firewall-zoneholds six built-in zones: Internal, External, Gateway, Vpn, Hotspot and Dmz.firewall-policiesholds 63 predefined policies, and every network has afirewall_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_templateandexternal_id, and a policy carriesorigin_id. The fork models all three from release0.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 DNSlets through. - A reject policy answers a TCP connection at once. A UDP query still waits for its timeout.
- Guest is in
Hotspotwith two policies.guest-block-gateway-dnsblocks TCP and UDP port 53 to the Gateway zone.guest-block-internalblocks all traffic to theInternalzone, because the built-in policyAllow Public DNSaccepts port 53 fromHotspottoInternal. With no second policy, a Guest client gets internal answers from the resolver of a trusted leg. - Telework is in a custom zone
Teleworkwith one policy,telework-block-gateway: reject all TCP and UDP to the Gateway zone. ICMP stays open on Telework, because neighbor discovery needs it. Internalhas one policy,internal-log-external-dns. It allows TCP and UDP ports 53 and 853 fromInternaltoExternal, 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 to9.9.9.9and149.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, whichsysloginsettings.tfdirects. The UniFi rows gives a query.- The controller puts the rules of
internal-log-external-dnsat the top of the chainUBIOS_LAN_WAN_USERon the gateway. They are above the drop of the object policysmart-tv-block, which the UI holds. So the policy accepts the first packet of a new DNS connection from a device insmart-tv-block. A UDP query of one packet reaches the internet. A TCP or DNS-over-TLS connection fails, because the drop ofsmart-tv-blockmatches every later packet. For every other client, the gateway accepted this traffic before the policy too. - A block policy for DNS from
InternaltoExternalthat someone adds later goes belowinternal-log-external-dnsand does not see a new connection. To make the block policy work, move it aboveinternal-log-external-dnsin the UI. Hotspotruns 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_idsends none, and the controller then chooses the zone. Each leg states its zone innetworks.tf. - The controller gives a network in
Hotspotthe purposeguest. Sotf/unifistatespurpose = "guest"for Guest. If the configuration statescorporate, the next apply moves Guest out ofHotspot, 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 nonetwork_idsand 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
nameandnetwork_idsonly. The controller object also holdsexternal_id, and an update does not send it. Do not rename the zoneTeleworkthrough Terraform until the provider sends that key. - The provider cannot set six keys of a policy:
match_ip_secandmatch_opposite_protocol, and on each sidematch_mac,match_opposite_ips,match_opposite_networksandmatch_opposite_ports. It sendsfalsefor each. A policy that needs one of them astruecannot be managed. - A policy holds
hitsandlast_hitafter 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
maintable before the tables of the WANs, so the blackhole route inmaindrops 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.yamlon 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_hostsinbgp.tflists 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 bgpsection, each block closed withexit. Ubiquiti documents this placement. A prefix list aboverouter bgpnever 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 structBGPConfigmodels every key that the BGP form of the UI writes:frr_bgpd_config,description,enabled,uploaded_file_name,device_mac,redistribute_to_sd_wanandredistribute_to_sd_wan_type. It also modelserror, a status that the controller sets. - Before each write,
unifi_bgpreads the stored object and lays the plan over it. A key thatbgp.tfdoes not declare keeps its stored value. The provider never sendserror, because the UI never sends it. - The provider keeps only the keys that
BGPConfigmodels. If the field audit prints a gap forbgp-config, no change tobgp.tfmerges until the fork models the new key. - The Override WAN Monitors checkbox in the same panel writes
unbind_wan_monitorsto theusgsetting. 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
vtyshon the console, over SSH asroot. The console SSH setting is under Settings, Control Plane, Console.
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 familyssh 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 itssh 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 itssh 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 nothingssh 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 WANsLog export
Section titled “Log export”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:
jq -c .services.systemLog /data/udapi-config/ubios-udapi-server/ubios-udapi-server.stategrep '^syslog\.remote' /tmp/system.cfgKeep 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.
Other answers from the bench
Section titled “Other answers from the bench”| 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 |
Read state off the controller
Section titled “Read state off the controller”Inventory and field audit
Section titled “Inventory and field audit”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.
scripts/unifi-readonly.sh scripts/unifi-inventory.py /tmp/before.unifi-dump > tf/unifi/inventory-summary.jsonThe 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.
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:
rg -n '"firewall_zone_id' /Volumes/Code/github.com/fzymgc-house/go-unifi/unifi/network_encode.goThe 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:
jq -c '.[] | select(has("uplink_identity")) | {name, purpose, wan_networkgroup}' /tmp/before.unifi-dump/networkconf.jsonOnly 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:
scripts/unifi-readonly.sh scripts/unifi-inventory.py /tmp/before.unifi-dump --for-diff > /dev/nullscripts/unifi-readonly.sh scripts/unifi-inventory.py /tmp/after.unifi-dump --for-diff > /dev/nulldiff -r /tmp/before.unifi-dump /tmp/after.unifi-dumpFields and quirks
Section titled “Fields and quirks”- DHCP Guard is
dhcpguard_enabledplus the trusted list indhcpd_ip_1,dhcpd_ip_2anddhcpd_ip_3on eachrest/networkconfobject. There is nodhcpguard_ipkey. Reading one returns nothing, whatever is configured. vlanis 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-activitywith{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_idslist of everycustomport and port profile. So a new network is not tagged on acustomport 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 everycustomlist, and the first apply reportsProvider produced inconsistent resultfor any list it wrote while the network was new. - A
dhcp_v6_serverblock readslease,startandstopfrom the controller, also when the configuration does not state them. A network that wascorporatebefore the block existed holdsdhcpdv6_leasetime,dhcpdv6_startanddhcpdv6_stop. So a new block on such a network must state all three. Without them, the first apply writes the other fields and then reportsProvider 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
Disabledfromport-profiles.tf. To turn the port on again, move it to another profile.