module · Networking

Ubiquiti UniFi

Comprehensive Ubiquiti UniFi controller control plane — sites, devices, clients, networks, WLANs, firewall, port forwards, RADIUS, port profiles, static routes, DNS, and more. Full snapshot/diff/apply round-trip for 13 resource kinds.

Namespace: weave unifi Env: UNIFI_API

Commands

State kinds

Networking

Setup

Configure credentials via environment variables. We recommend sourcing them through 1Password or your secrets manager rather than committing them to the shell rc.

Official API reference

weave commands for this module are checked against the vendor's published API.

Site Manager API v1

Variable	Description	Status
UNIFI_API	Required for authentication.	required
UNIFI_USERNAME	Required for authentication.	required
UNIFI_PASSWORD	Required for authentication.	required
UNIFI_API_KEY	Alternative to UNIFI_USERNAME/UNIFI_PASSWORD on Network 9+	optional
UNIFI_SITE	Default site (default: 'default')	optional
UNIFI_OS	Force UniFi OS (1) or legacy controller (0) routing; auto-detected when unset (UDM/Cloud Key login at /api/auth/login + /proxy/network prefix vs legacy /api/login)	optional
UNIFI_VERIFY_TLS	Set to 0 to skip TLS verification on self-signed controllers	optional

Sanity-check the wiring:

weave secrets check
weave unifi --help
weave doctor   # reports UNIFI_API status

Capabilities

What this module can do, by entity and verb. ✓ means a working CLI surface; · means not (yet) wired.

Entity	find	list	show	do	snapshot	diff	apply
alarm	·	✓	·	·	·	·	·
ap-group	·	✓	·	·	·	·	·
client	✓	✓	✓	✓	·	·	·
device	✓	✓	✓	✓	·	·	·
dns-record	·	✓	·	·	✓	✓	·
dynamic-dns	·	✓	·	·	✓	✓	·
event	·	✓	·	·	·	·	·
firewall-group	·	✓	·	·	✓	✓	✓
firewall-rule	✓	✓	·	✓	✓	✓	✓
network	✓	✓	✓	·	✓	✓	✓
port-forward	·	✓	·	✓	✓	✓	✓
port-overrides	·	·	·	·	✓	✓	✓
port-profile	✓	✓	·	·	✓	✓	✓
radius-profile	·	✓	·	·	✓	✓	✓
site	·	✓	✓	·	·	·	·
static-route	·	✓	·	·	✓	✓	✓
user	✓	✓	✓	·	✓	✓	✓
user-group	·	✓	·	·	✓	✓	✓
wlan	✓	✓	✓	·	✓	✓	✓

Commands

Every registered CLI command, grouped by verb. Each example uses placeholder arguments — substitute real values for your environment.

find (7)

find client

read

Find a connected client by MAC, hostname, name, or IP.

weave unifi find client <identifier>

find device

read

Find a UniFi device (AP / switch / gateway) by MAC, name, or serial.

weave unifi find device <identifier>

find firewall-rule

read

Find a firewall rule by name.

weave unifi find firewall-rule <name>

find network

read

Find a network/VLAN by name.

weave unifi find network <name>

find port-profile

read

Find a switch port profile by name.

weave unifi find port-profile <name>

find user

read

Find a saved/known user by MAC, hostname, or name.

weave unifi find user <identifier>

find wlan

read

Find a WLAN/SSID configuration by name.

weave unifi find wlan <ssid>

list (18)

list alarms

read

List alarms on a site.

weave unifi list alarms <arg>

list ap-groups

read

List AP groups on a site (used by WLANs).

weave unifi list ap-groups <arg>

list clients

read

List active wired/wireless clients on a site.

weave unifi list clients <arg>

list devices

read

List UniFi devices (APs, switches, gateways) on a site.

weave unifi list devices <arg>

list dns-records

read

List controller-managed DNS records on a site.

weave unifi list dns-records <arg>

list dynamic-dns

read

List dynamic-DNS configurations on a site.

weave unifi list dynamic-dns <arg>

list events

read

List recent controller events on a site.

weave unifi list events <arg>

list firewall-groups

read

List firewall address / port groups on a site.

weave unifi list firewall-groups <arg>

list firewall-rules

read

List firewall rules on a site.

weave unifi list firewall-rules <arg>

list networks

read

List networks/VLANs/WANs on a site.

weave unifi list networks <arg>

list port-forwards

read

List destination NAT / port-forwarding rules on a site.

weave unifi list port-forwards <arg>

list port-profiles

read

List switch port templates on a site.

weave unifi list port-profiles <arg>

list radius-profiles

read

List RADIUS auth/acct profiles on a site.

weave unifi list radius-profiles <arg>

list sites

read

List sites on the controller.

weave unifi list sites <arg>

list static-routes

read

List static routes on a site.

weave unifi list static-routes <arg>

list user-groups

read

List user (bandwidth/policy) groups on a site.

weave unifi list user-groups <arg>

list users

read

List saved/known users on a site (note, blocked, fixed-IP).

weave unifi list users <arg>

list wlans

read

List WLAN/SSID configurations on a site.

weave unifi list wlans <arg>

show (6)

show client

read

Show full detail for a connected client.

weave unifi show client <mac>

show device

read

Show every detail for one UniFi device.

weave unifi show device <mac>

show network

read

Show full network/VLAN config.

weave unifi show network <identifier>

show site

read

Show site health, counts, and settings summary.

weave unifi show site <name>

show user

read

Show full detail for a saved/known user.

weave unifi show user <mac>

show wlan

read

Show full WLAN configuration.

weave unifi show wlan <identifier>

do (16)

do authorize-guest

write

Authorize a guest client for a duration (minutes).

weave unifi do authorize-guest <client-mac>

do block-client

write

Block a client by MAC.

weave unifi do block-client <client-mac>

do disable-port-forward

write

Disable a port-forward rule by id.

weave unifi do disable-port-forward <pf-id>

do disable-rule

write

Disable a firewall rule by id.

weave unifi do disable-rule <rule-id>

do disconnect-client

write

Force-disconnect (kick) a client from the network.

weave unifi do disconnect-client <client-mac>

do enable-port-forward

write

Enable a port-forward rule by id.

weave unifi do enable-port-forward <pf-id>

do enable-rule

write

Enable a firewall rule by id.

weave unifi do enable-rule <rule-id>

do forget-client

write

Remove a client from the known-users list.

weave unifi do forget-client <client-mac>

do locate

write

Flash a device's locate LED.

weave unifi do locate <device-mac>

do power-cycle

write

Power-cycle a single PoE port on a switch.

weave unifi do power-cycle <device-mac>

do reconnect-client

write

Force a client to reconnect (kick + immediate retry).

weave unifi do reconnect-client <client-mac>

do restart

write

Restart a UniFi device (AP / switch / gateway).

weave unifi do restart <device-mac>

do stop-locate

write

Stop a previously-issued locate.

weave unifi do stop-locate <device-mac>

do unauthorize-guest

write

Revoke a guest authorization.

weave unifi do unauthorize-guest <client-mac>

do unblock-client

write

Unblock a previously-blocked client.

weave unifi do unblock-client <client-mac>

do upgrade

write

Trigger a firmware upgrade on a device.

weave unifi do upgrade <device-mac>

snapshot / diff / apply are generated automatically from the State Kinds declared on this module — see the State kinds section below for per-kind details. Workflow: snapshot → edit YAML → diff → apply --yes (or confirm interactively; apply --dry-run previews the same diff).

State kinds

Resources this module can snapshot and diff; apply where the kind supports live writes (see Round-trip per kind). Always run diff before apply; use --yes in automation after review. Files live under .weave-state/unifi/.

wlans

snapshot diff apply

WLAN/SSID configurations on a site (full apply).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: wlans
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

networks

snapshot diff apply

LAN / VLAN / WAN / VPN networks on a site (full apply).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: networks
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

firewall-rules

snapshot diff apply

Firewall ruleset on a site (full apply).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: firewall-rules
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

firewall-groups

snapshot diff apply

Address / port groups referenced by firewall rules (full apply).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: firewall-groups
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

port-forwards

snapshot diff apply

Destination NAT / port-forwarding rules on a site (full apply).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: port-forwards
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

port-profiles

snapshot diff apply

Switch port templates on a site (full apply).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: port-profiles
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

static-routes

snapshot diff apply

Static routes managed by the gateway (full apply).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: static-routes
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

radius-profiles

snapshot diff apply

RADIUS auth/acct server profiles on a site (full apply).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: radius-profiles
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

user-groups

snapshot diff apply

Bandwidth/policy groups for client users (full apply).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: user-groups
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

port-overrides

snapshot diff apply

Per-device switch port overrides (full apply).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: port-overrides
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

users

snapshot diff apply

Saved clients — note/blocked/fixed-IP/user-group (apply: updates only).

Scope: site
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: unifi
kind: users
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

dns-records

snapshot diff apply

Controller DNS records (snapshot + diff only — write API varies).

Scope: site
Round-trip: Snapshot + diff (apply not wired).

State file skeleton

module: unifi
kind: dns-records
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

dynamic-dns

snapshot diff apply

Dynamic-DNS configurations (snapshot + diff only — credential round-trip unsafe).

Scope: site
Round-trip: Snapshot + diff (apply not wired).

State file skeleton

module: unifi
kind: dynamic-dns
site: <value>
items:
  - # <fields specific to this kind — see snapshot output>

Workflows

End-to-end recipes from operators who already run this module in production. Copy, adapt, and put under change-control.

Bulk-update WLAN passphrase

Edit one YAML file, push to every site.

weave unifi snapshot wlans --site=hq
$EDITOR .weave-state/unifi/wlans-hq.yaml   # change passphrase
weave unifi diff wlans --site=hq
weave unifi apply wlans --site=hq --yes

Migrate misbehaving switch port

Snapshot per-device overrides, edit, re-apply.

weave unifi find device <mac>
weave unifi snapshot port-overrides --site=hq
$EDITOR .weave-state/unifi/port-overrides-hq.yaml
weave unifi apply port-overrides --site=hq --yes

Quarterly firewall audit

Snapshot rules, commit to git, review the next diff.

weave unifi snapshot firewall-rules --site=hq
git add .weave-state/unifi/firewall-rules-hq.yaml && git commit -m 'firewall audit'
# … next quarter …
weave unifi diff firewall-rules --site=hq   # review changes

Quarantine a noisy client

Single command, controller-wide.

weave unifi find client <hostname-or-mac>
weave unifi do block-client <mac> --site=hq --yes

Terraform parity

For each Terraform resource in the canonical provider, here's the equivalent live-API verb in weave. Use this as a migration cheat-sheet, not a 1:1 contract — weave deliberately stays in the live-state lane, not the desired-state lane.

Terraform resource	weave equivalent
unifi_account	weave unifi list radius-profiles / snapshot radius-profiles
unifi_device	weave unifi list/show device + do restart/locate/upgrade + snapshot port-overrides
unifi_dynamic_dns	weave unifi list dynamic-dns / snapshot dynamic-dns
unifi_firewall_group	weave unifi list firewall-groups / snapshot firewall-groups
unifi_firewall_rule	weave unifi list firewall-rules / snapshot firewall-rules + do enable/disable-rule
unifi_network	weave unifi list/find/show network / snapshot networks
unifi_port_forward	weave unifi list port-forwards / snapshot port-forwards + do enable/disable-port-forward
unifi_port_profile	weave unifi list/find port-profile / snapshot port-profiles
unifi_radius_profile	weave unifi list radius-profiles / snapshot radius-profiles
unifi_static_route	weave unifi list static-routes / snapshot static-routes
unifi_user	weave unifi list/find/show user / snapshot users
unifi_user_group	weave unifi list user-groups / snapshot user-groups
unifi_wlan	weave unifi list/find/show wlan / snapshot wlans
unifi_setting_mgmt / setting_radius / setting_usg	Not exposed yet — controller-level settings Planned for v0.2
(events / alarms / locate / power-cycle)	weave unifi list events / list alarms / do locate / do power-cycle Operational verbs unique to weave — no Terraform equivalent

Troubleshooting & source

Missing credentials

Run weave doctor — it reports which env vars (including UNIFI_API) are set and which are blank.

Unexpected behaviour from a state apply

Re-run weave unifi diff <kind> to confirm the controller's current state, then re-snapshot before the next apply. The driver always re-snapshots before diffing.

Open the source

The module lives at https://github.com/andy-broyles/weavewhatever/tree/main/src/weave/modules/unifi. File a bug or feature request at https://github.com/andy-broyles/weavewhatever/issues.