How to monitor particular kit with Oversight: which sensor to use, where on the device to set up access, which user function and extraction rows read the response, and how to write the rules that turn it into an alarm. Search for a vendor, a product or an error message, or ask a question in your own words.
Ubiquiti: UniFi, EdgeMAX and airMAX
Ubiquiti makes several quite different product lines, and the way to watch each is different:
| Kit | Best route |
|---|---|
| UniFi gateways, switches and access points, managed from a UniFi OS console (Dream Machine, Dream Router, Cloud Gateway, Cloud Key Gen2 and later, UniFi OS Server) | The console's UniFi Network API, with an API key. SNMP on switches for uplink ports. |
| UniFi on the self-hosted Network application (Windows or Linux, port 8443), or the original Cloud Key (Gen1) | SNMP on the devices only. Neither runs UniFi OS, so there are no API keys, and their API needs a login step a sensor cannot make. |
| EdgeRouter | SNMP |
| EdgeSwitch | SNMP |
| airMAX radios, and anything managed in UISP | SNMP on the radios, or the UISP API |
UniFi: the Network API
From UniFi Network 9.0.108, on a console running UniFi OS 4.1.9 or later, the console answers a documented API with a fixed key, which is exactly what a sensor needs. It reports each device's state as the console sees it, which is what matters: an access point that has lost the controller still answers a ping and SNMP, but the API says it is disconnected.
Making a key
- Network 9: Settings > Control Plane > Integrations, then Create New API Key.
- Network 10: Integrations in the left-hand menu.
The key is shown once; copy it straight away. It carries the rights of the admin who made it, so make it while signed in as a dedicated admin for monitoring, not your own account. Save it in Oversight as an HTTP(S) credential's API key.
Sensor settings
| Setting | Value |
|---|---|
| Scheme and port | https, 443 on a console; 11443 on UniFi OS Server |
| Method | GET |
| Headers | X-API-KEY: {{apikey}}Accept: application/json |
| Verify the certificate | Off, unless the console has been given a proper certificate |
Paths below start /proxy/network/integration. Put the sensors on the console's device in Oversight, since every request goes to the console, and add SV01 not equal to 200 gives CRIT to each.
Finding the IDs
The API names sites and devices by long IDs. Find them once with two temporary sensors with Store raw response ticked, or with curl:
curl -k -H "X-API-KEY: <key>" https://<console>/proxy/network/integration/v1/sites curl -k -H "X-API-KEY: <key>" "https://<console>/proxy/network/integration/v1/sites/<siteId>/devices?limit=200"
The first gives each site's id (the one usually called default in the old interface is the first). The second lists every device with its id, name and model.
Sensors worth having
| What | Path | Extraction | Rules |
|---|---|---|---|
| A device is online | /v1/sites/<siteId>/devices/<deviceId> | SD03, JSON, state | SD03 equal to (OFFLINE,CONNECTION_INTERRUPTED,ISOLATED) gives CRIT |
| An uplink port is up | Same | SD04, JSON, interfaces.ports.<n>.state | SD04 equal to DOWN gives CRIT |
| Power to an access point | Same, on the switch | SD05, JSON, interfaces.ports.<n>.poe.state | Equal to LIMITED gives WARN; equal to DOWN gives CRIT |
| Restarted | /v1/sites/<siteId>/devices/<deviceId>/statistics/latest | SV03, JSON, uptimeSec, unit s | Less than 600 gives WARN |
| Anything offline on the site | /v1/sites/<siteId>/devices?limit=1&filter=state.in(%27OFFLINE%27,%27CONNECTION_INTERRUPTED%27,%27ISOLATED%27) | SV03, JSON, totalCount | Greater than 0 gives CRIT. Network 10 and later only. |
| The console itself | /v1/info | SD03, JSON, applicationVersion | The guard rule alone: no answer, or not 200, is CRIT |
- States that pass.
UPDATINGandGETTING_READYare normal during a firmware update, so they are not in the CRIT list. - Ports are a list, and
<n>counts from 0. Look at the stored response once and check theidxbeside the port you want, since the position in the list is not guaranteed to match the port number. - One sensor for the whole site. On Network 10, the filtered request counts every device that is not online, so one sensor covers a whole site: the alarm says how many, and the UniFi interface says which. On Network 9 the filter is not available; use one sensor per device that matters.
- Firmware updates available are reported too (
firmwareUpdatable), but an update waiting is not a fault. Do not alarm on it.
The controller API you may already know
UniFi has long had a controller API: the one scripts and tools use to change settings, such as a Wi-Fi password, from afar. It is used by logging in first, at /api/login (or /api/auth/login on UniFi OS), and then calling paths such as /api/s/default/rest/wlanconf with the session that login returns. That suits a script, but a sensor makes a single request with nothing carried over from the last one, so it cannot log in first. What that means depends on what the application runs on:
- On a UniFi OS console, including the Cloud Key Gen2 and Gen2 Plus, the same paths also accept the Integrations API key in place of a login. That is what the unofficial sensors below rely on.
- On the self-hosted Network application and the original Cloud Key, there is no API key, so these paths are out of a sensor's reach. Watch the devices by SNMP instead, or move the application onto UniFi OS Server, which brings the API key with it.
Oversight only ever reads. Nothing here changes a setting on the controller.
WAN down and failover: the unofficial route
The official API does not say whether the internet connection is up, or whether a dual-WAN gateway has failed over to its backup. The console's older, undocumented endpoints do, and on UniFi OS they accept the same API key. They are unofficial: Ubiquiti can change them without notice, and some of the field names below come from third-party tools rather than Ubiquiti. Name these sensors so it is clear, and check them after console updates. Paths start /proxy/network/api/s/default, where default is the site's short name:
| What | Path | Extraction | Rules |
|---|---|---|---|
| Internet connection | /stat/health | SD03, REGEX, /"subsystem":\s*"wan".*?"status":\s*"(\w+)"/ | SD03 not equal to ok gives CRIT |
| Access points disconnected | /stat/health | SV03, REGEX, /"subsystem":\s*"wlan".*?"num_disconnected":\s*(\d+)/ | Greater than 0 gives CRIT |
| Switches disconnected | /stat/health | SV04, REGEX, /"subsystem":\s*"lan".*?"num_disconnected":\s*(\d+)/ | Greater than 0 gives CRIT |
| Running on the backup WAN | /stat/device/<gateway-mac> | SD03, JSON, data.0.wan2.is_uplink | SD03 equal to 1 gives WARN |
These use REGEX rather than a JSON path because the order of the subsystems in the reply is not fixed. A true/false value reads as 1 or nothing in a text slot, hence equal to 1. Where these endpoints are not wanted, a Ping of the site's public address from a probe outside is the dependable way to hear that the internet connection has gone.
From the cloud
Ubiquiti's cloud Site Manager API (api.ui.com, key from unifi.ui.com > Settings > API Keys, same X-API-KEY header) reports every console on the account without reaching into the site. Its answers are lists, though, so a JSON path works cleanly only where a key sees one site: /v1/sites, SV03, JSON, data.0.statistics.counts.offlineDevice, greater than 0 gives CRIT. Use a Target override with the whole URL, as the request goes to Ubiquiti rather than the device. A local key and a Site Manager key are different things and are not interchangeable.
UniFi: SNMP
UniFi sets one SNMP community for the whole site: Settings > CyberSecure > Traffic Logging, then SNMP (older versions: Settings > System > Advanced). Turn on v1/v2c, change the community from public, and apply. Every device on the site then uses it. Save it in Oversight as an SNMP credential, version 2c, on the site.
What SNMP is good for in UniFi is the state of a switch's uplink ports. Find the port's number once, because it is not the number on the front panel:
snmpwalk -v2c -c <community> <switch> 1.3.6.1.2.1.31.1.1.1.1
| What | OID | Settings | Rules |
|---|---|---|---|
| Uplink up | 1.3.6.1.2.1.2.2.1.8.<port> | GAUGE | Not equal to 1 gives CRIT |
| Uplink errors | 1.3.6.1.2.1.2.2.1.14.<port> | COUNTER32, change per minute | Greater than 10 gives WARN |
| Restarted | 1.3.6.1.2.1.1.3.0 | GAUGE, multiplier 0.01, unit s | Less than 600 gives WARN |
Limits to know:
- USW Flex and Ultra switches do not support SNMP, in Ubiquiti's own words. Use the API's port state for those.
- Gateways gained SNMP in UniFi OS 4.0.6, but on some versions they answer only the basic system details and no ports. Try a walk of
1.3.6.1.2.1.2.2.1.8first; if nothing comes back, use the API. - SNMP cannot see the controller. A device that has lost its controller still answers SNMP happily. The API's
stateis the reading for that. - If SNMP polls of a UniFi switch start failing after days of working, update the switch: an SNMP memory leak on some switch firmware was fixed from 7.1.16.
EdgeRouter
SNMP, set up from the command line, answering only the probe:
configure set service snmp community <community> authorization ro set service snmp community <community> client <probe-address> commit ; save
EdgeOS has a web API, but it needs a login and a session, which a single-request sensor cannot do, so SNMP is the route. Find the port numbers once, because ethN is not port number N; on one EdgeRouter eth0 was number 6:
snmpwalk -v2c -c <community> <router> 1.3.6.1.2.1.2.2.1.2
| What | OID | Settings | Rules |
|---|---|---|---|
| Each WAN up, and the LAN uplink | 1.3.6.1.2.1.2.2.1.8.<port> | GAUGE | Not equal to 1 gives CRIT |
| Restarted | 1.3.6.1.2.1.1.3.0 | GAUGE, multiplier 0.01, unit s | Less than 600 gives WARN |
| Load, five minutes | 1.3.6.1.4.1.2021.10.1.5.2 | GAUGE, multiplier 0.01 | Optional: greater than the number of cores, sustained, gives WARN |
EdgeRouters do not report their temperatures over SNMP, and there is no reading for load-balancing or failover state: a WAN up sensor on each WAN is how you hear that one has gone.
EdgeSwitch
Add a read-only community under System > Advanced Configuration > SNMP in the web interface (on the ES-10X, snmp community "<name>" ro in configure mode). EdgeSwitches report their hardware health as well as their ports:
| What | OID | Settings | Rules |
|---|---|---|---|
| Uplink up | 1.3.6.1.2.1.2.2.1.8.<port> | GAUGE | Not equal to 1 gives CRIT |
| Temperature state | 1.3.6.1.4.1.4413.1.1.43.1.8.1.4.1.0 | GAUGE; 1 is normal | Equal to 2 gives WARN; equal to (3,4,6) gives CRIT |
| Fan | 1.3.6.1.4.1.4413.1.1.43.1.6.1.3.1.<fan> | GAUGE; 2 is operational | Equal to (3,5,6) gives CRIT |
| Power supply | 1.3.6.1.4.1.4413.1.1.43.1.7.1.3.1.<psu> | GAUGE; 2 is operational | Equal to (3,5,6) gives CRIT |
The 1 before the fan or supply number is the unit, which is 1 on a single switch. Walk 1.3.6.1.4.1.4413.1.1.43.1 once to see which fans and supplies the model has.
airMAX and UISP
On an airMAX radio, turn on SNMP Agent on the Services tab and set a community. Ubiquiti states airMAX supports SNMP v1, so save the credential as version 1. The readings that matter for a point-to-point link:
| What | OID | Settings | Rules |
|---|---|---|---|
| Link connected | 1.3.6.1.4.1.41112.1.4.5.1.15.1 (stations) | GAUGE | On the link's master end: equal to 0 gives CRIT |
| Signal | 1.3.6.1.4.1.41112.1.4.5.1.5.1 | GAUGE, unit dBm | Note the figure when the link is commissioned: 6 dB worse gives WARN, 10 dB worse gives CRIT |
| airMAX capacity | 1.3.6.1.4.1.41112.1.4.6.1.4.1 | GAUGE, unit % | Optional: a sustained drop against its usual figure gives WARN |
Where the radios are managed in UISP, its API gives each device's state in one request. Make a token under Settings > Users, save it as an HTTP(S) credential's API key, and point a sensor at the UISP server: GET /nms/api/v2.1/devices/<id> with the header x-auth-token: {{apikey}}, reading SD03, JSON, overview.status, with equal to disconnected gives CRIT.
A starting set
| Site | Sensors |
|---|---|
| UniFi, Network 10 | Anything offline on the site (one API sensor); the console itself; the gateway restarted; the internet connection and, on dual-WAN sites, running on the backup WAN (unofficial); core switch uplinks by SNMP |
| UniFi, Network 9 | As above, but one device is online sensor per gateway, core switch and important access point in place of the site-wide count |
| EdgeRouter | Each WAN up; the LAN uplink up; restarted |
| EdgeSwitch | Uplinks up; temperature state; fans and power supplies |
| airMAX link | Link connected on the master end; signal on links that matter |
At the default 60 seconds from one probe group, an API sensor costs about £3.46 a month and an SNMP sensor about £1.73.
MIBs
No MIB is needed to poll; every OID above works as a number. To pick objects by name, these can be imported through Files:
- UniFi: the combined UniFi MIB, linked as UI-MIB from Ubiquiti's help article SNMP Monitoring in UniFi Network.
- airMAX: UBNT-MIB and UBNT-AirMAX-MIB, in
dl.ui.com/firmwares/airos-ubnt-mib/ubnt-mib.zip. - EdgeRouter and EdgeSwitch: UBNT-EdgeMAX-MIB and EdgeSwitch-BOXSERVICES-PRIVATE-MIB (with EdgeSwitch-REF-MIB). Ubiquiti does not publish these separately; the LibreNMS project keeps copies.