unifi-clients

UniFi Clients and Devices

Day-to-day operations, and the two ways they go wrong: partial writes that silently destroy config, and VLAN changes that appear to work and do not.

Full-object PUT discipline

The rule that prevents most damage on this API:

rest/* endpoints replace the object. GET it, modify the one field, PUT the whole thing back.

A partial PUT does not merge. It writes what you sent and drops the rest. The consequences scale with the object:

• rest/networkconf: PUT {"dhcpd_dns_1": "..."} and you can lose the network's DHCP range, domain name, and VLAN assignment.
• rest/wlanconf: you can lose the passphrase, the network binding, the band settings.
• rest/device port_overrides: PUT the complete port_overrides list. Sending one port's override resets every other port on the switch to defaults. On a 24-port switch carrying a segmented network, that is the whole afternoon.

# Correct shape, every time
udm raw GET /proxy/network/api/s/default/rest/networkconf/<NETWORK_ID> > /tmp/net.json
# edit /tmp/net.json, changing only what you mean to change
udm raw PUT /proxy/network/api/s/default/rest/networkconf/<NETWORK_ID> "$(cat /tmp/net.json)"

Then re-read and diff. The PUT response is not proof.

The wired VLAN migration trap

You change a switch port's native VLAN. The controller accepts it. The device behind that port is now stranded, and nothing tells you.

Changing native_networkconf_id in port_overrides does not bounce the link. The device never sees a carrier drop, so it never re-runs DHCP. It keeps its old-subnet lease, sits on a segment where that address has no gateway, and looks completely healthy until it needs to route somewhere. Then it fails in a way that looks like a firewall problem, which is where the afternoon goes.

Completing the move requires the device to issue a fresh DHCP DISCOVER, which means a real reboot. Lease expiry technically works and is useless: 24 hours.