UniFi Network
This content is not available in your language yet.
The UniFi network and what it manages: gateways, switches and access points that are offline, isolated or waiting for adoption, firmware updates waiting, the WAN links and the Internet connection as the gateway sees them, the number of clients, and the alarms UniFi raised. It works with the UniFi Network application of a UniFi OS console (Dream Machine, Cloud Gateway, Cloud Key) and with a self-hosted UniFi Network Server.
DumbMonit reads UniFi with an API key or with a local account holding the View Only role. It never restarts, adopts, upgrades or provisions a device.
The failure worth watching: an access point or a switch drops off quietly. Clients roam to the next access point, the network keeps working, and the coverage hole or the lost uplink is only noticed days later. The same goes for a second WAN link that went down: nothing breaks until the first one fails too.
Network ports to open
Section titled “Network ports to open”From the DumbMonit server (or its relay agent) to the device:
| Port | Protocol | Purpose |
|---|---|---|
| 443 | TCP | API (HTTPS, default) |
| 8443 | TCP | Only with a self-hosted UniFi Network Server |
Two ways in
Section titled “Two ways in”| Credential | API used | What it reads |
|---|---|---|
| API key (UniFi OS console) | The official Integration API, at /proxy/network/integration/v1 on a console and /integration/v1 on a self-hosted server | Version, devices and their state, firmware updates, load, memory and uptime of each online device, number of clients |
| View Only account | The classic API (/api/s/<site>/stat/*), at /proxy/network/api/… on a console | All of the above, plus clients per device and by type, the WAN links, the WAN and Internet status, and alarms |
The WAN, Internet and alarm status only exist in the classic API. With a key, DumbMonit also asks the classic API for the WAN and Internet status with the same key; if the controller refuses it, those series are simply absent, without an error.
Alarms are the entries of UniFi’s “critical” system log over the last 24 hours
(UniFi Network 8 and later), or the unarchived alarms on older versions. That is
the only POST DumbMonit sends, and it only reads.
A session opened with the View Only account is kept from one probe to the next and reopened when it expires: UniFi does not log a new login every minute.
What it watches
Section titled “What it watches”All metrics are prefixed dumbmonit_unifi_. Device series carry device (its
name, or its MAC address when it has none), mac, model and type
(gateway, switch, access_point, other).
| Metric | What | Labels |
|---|---|---|
info | value 1 | version, api (integration or classic) |
devices | devices by state: online, offline, pending, updating, adopting, adoption_failed, isolated, other | state |
devices_upgradable | adopted devices with a firmware update available | |
device_state | 0 online, 1 offline, 2 pending adoption, 3 updating or provisioning, 4 adopting, 5 adoption failed, 6 isolated, 7 other | device labels |
device_up | 1 online or updating, 0 offline, isolated or failed to adopt; absent for a device not adopted yet | device labels |
device_upgradable | 1 when a firmware update is available | device labels, firmware |
device_uptime_seconds, device_cpu_percent, device_memory_percent | online devices only | device labels |
device_clients | clients connected to the device (View Only account) | device labels |
wan_link_up | 1 when a WAN port of the gateway is up; a disabled port has no series | device labels, wan (wan1, wan2) |
wan_up, internet_up | the gateway’s WAN and Internet status; absent without a UniFi gateway | |
internet_latency_seconds | latency measured by the gateway | |
wan_availability_percent | availability of each WAN over the last 24 hours | wan |
subsystem_status | 0 ok, 1 warning, 2 error, 3 unknown, for wlan, wan, www, lan, vpn | subsystem |
clients | clients on the site | |
clients_by_type | wireless, wired, guest, vpn (View Only account) | type |
alarms | critical system log entries of the last 24 hours, or unarchived alarms | |
scrape_errors | calls that failed on the last probe | |
port_enabled, port_up, port_speed_bps, port_full_duplex, port_uplink | ports of each online switch or gateway (View Only account, port_table); port_up is absent for a disabled port | device, mac, port (front-panel number), port_name |
port_poe_enabled, port_poe_watts | PoE of each port | same |
port_rx_bytes_total, port_tx_bytes_total, port_rx_errors_total, port_tx_errors_total | per-port counters, drawn by the switch panel | same |
port_neighbor_info | value 1, LLDP neighbour of the port (lldp_table) | same, remote_chassis, remote_port |
The built-in rules that apply: UniFi device offline, UniFi Internet down, UniFi WAN link down, UniFi gateway CPU high, UniFi device waiting for adoption, UniFi firmware update available, UniFi alarms, plus Monitor unreachable.
Devices
Section titled “Devices”/rest/user (the classic API, read with either credential) lists every
client the controller has ever seen — most of a home network, in practice:
phones passing by, guest Wi-Fi, smart devices that never come back. Tracking
all of them for staleness would bury the alert under devices that simply
never return, not devices that went silent. By default only clients the user
marked one way or another count: named in UniFi, reserved on a fixed IP, or
noted. The Clients to watch besides the marked ones option adds specific
MAC addresses or client names, or all to track every client (not
recommended on anything but a small, mostly-static network).
Tracked clients are published under the generic family shared by every
DumbMonit integration that tracks client devices — dumbmonit_client_device_*,
prefixed without unifi, documented in full under
Client devices:
| Metric | What | Labels |
|---|---|---|
last_seen_timestamp_seconds | Last connection, as /rest/user reports it | device, type (Wired, Wireless or Unknown), os (empty), user (empty), kind |
stale_seconds | Positive once a tracked client has gone past device_stale_days (3 by default) without connecting; drives the Client device stale rule | device, type, os, user, kind, signal (always connection: UniFi has no backup to report) |
The monitor page
Section titled “The monitor page”The panel above the charts reads what the probe stored; opening the page never queries UniFi. It says what is wrong first (devices offline, Internet or a WAN link down, alarms), then the devices by type with their state, firmware and load, and the clients, then the table of tracked clients with their last connection.
How it was validated
Section titled “How it was validated”Login, the View Only role, error answers (refused password, unknown site,
refused key, expired session) and the answers of a controller without devices
were checked against UniFi Network 10.6.106, self-hosted. No device could be
adopted there: the device list, the health of an equipped site, the known
clients (/rest/user) and the Integration API payloads are validated against
the official documentation.
Create a read-only access in UniFi Network
Section titled “Create a read-only access in UniFi Network”-
For an API key on a UniFi OS console: UniFi Network → Settings → Control Plane → Integrations → Create API Key. Name it DumbMonit and copy it: it is shown once.
-
Or create a local account (needed for WAN and alarm status, and on a self-hosted server): Settings → Admins & Users → Create New, local access only.
dumbmonit -
Set that account’s UniFi Network role to View Only.
-
In DumbMonit, enter the address (unifi.lan, or unifi.lan:8443 for a self-hosted server) and paste the key or the account.
-
If the network is not the default site, set the Site option to the short name shown after /manage/ or /network/ in the address bar.
Required permissions
Section titled “Required permissions”- View Only (UniFi Network role) — Reads everything and changes nothing
Keep two-factor authentication off for this local View Only account only, since a monitoring server cannot type a code. A leaked owner or UI.com password would open every console linked to it.
UniFi knows every client that ever connected, most of them phones passing by: only those named, reserved on a fixed IP, or noted in UniFi are watched for staleness by default, to avoid an alert for every visitor’s phone. List more in the Clients to watch option, or enter all.
Controller not set up yet
Section titled “Controller not set up yet”A self-hosted controller whose first-run setup wizard is not finished answers every request with a redirect to /setup. DumbMonit then reports “The UniFi controller is not set up yet” as a configuration error (not a refused password): finish the wizard in the browser, then probe again.
Credentials
Section titled “Credentials”| Credential | Fields |
|---|---|
| API key (UniFi OS console) | A key created in Settings → Control Plane → Integrations, sent as X-API-KEY. |
| View Only account | The user name and password of the local View Only account. |
Address: a host name or IP (unifi.lan), host:port (unifi.lan:8443 for a
self-hosted server), or a full URL; an address copied from the browser, with
/manage/… or /network/…, is accepted. Options: site (default), port (443),
certificate check, request timeout (15 s), clients to watch besides the marked
ones (empty, or all), and device staleness (device_stale_days, 3 days by
default).