UniFi (SNMP)

The UniFi (SNMP), UniFi Access Point (SNMP), and UniFi Switch (SNMP) checks monitor Ubiquiti UniFi hardware over SNMP. They read different parts of the hardware, so which one you pick matters more than any threshold you set. By default, UniFi (SNMP) runs every 15 minutes, and UniFi Access Point (SNMP) and UniFi Switch (SNMP) every 5 minutes. The work splits in two — turning SNMP on in the UniFi Network application, and pointing the right check at the right device.

Pick the right check

Pointing the wrong check at a device does not fail loudly. The generic UniFi (SNMP) check on a switch stays green and shows no CPU, RAM, or temperature — those values live in a MIB it does not read. UniFi Access Point (SNMP) on anything that is not an access point sits at Warning with No radio data (enable SNMP / UBNT-UniFi-MIB), because the radio table it walks comes back empty. Look at the tiles on the first result: if the numbers you expected are missing, you are on the wrong check.

The two switch-facing checks do not fully overlap. UniFi Switch (SNMP) covers the hardware — CPU, RAM, temperature, fans — and counts ports up and down. UniFi (SNMP) covers the PoE budget, with warning and critical thresholds on consumption as a percentage of that budget, and it adds per-port detail rows — but only for the ports that matter: ports that are administratively up yet operationally down, plus any port you select under Interfaces that must be up, capped at 50 rows. With nothing selected, a healthy switch shows the summary line and no detail rows at all — but every port you select keeps a row of its own, whether it is up or down. On a PoE switch you can run both checks against the same address if you want each set of signals. If a device does not answer the PoE MIB, octoja leaves the PoE section out of the result rather than raising an alarm.

Prerequisites

• You need the Monitoring Check Management permission (monitoring-checks.manage). Permissions are granted per group under Administration → Groups.
• An octoja agent — or an agentless network device with a monitoring asset — that can reach the UniFi hardware over the network.
• SNMP enabled on the UniFi side, with the community string or SNMPv3 credentials to hand.

Where the check runs

UniFi switches, access points, and gateways cannot run an octoja agent. All three checks are agent-side: they run on an octoja-managed device and query the UniFi hardware across the network on UDP port 161. You have two ways to place them.

• On an existing agent. Add the check to any device with the octoja agent installed that can reach the UniFi hardware — typically a server or workstation on the same network. The check then lives on that device's Checks tab.
• On the UniFi device itself, registered without an agent. Add the switch, access point, or gateway as a network device and give it a monitoring asset; the check is listed on the UniFi device and the monitoring asset does the probing. octoja runs the check against that network device's own IP address, so the host follows the device instead of whatever the check has stored. If SNMP is enabled on the network device, the check also takes over its SNMP connection settings (version, port, community or SNMPv3 credentials); they take precedence over the connection fields in the check. See Add a Network Device Without an Agent.

Either way, the probing host needs a clear path to the UniFi device's LAN or management address on UDP 161. Point the check at that address, not at a gateway's public WAN address.

Enable SNMP in the UniFi Network application

SNMP on UniFi is a central setting, not a per-device one. You turn it on once in the UniFi Network application and the controller pushes it to every adopted device — there is nothing to configure on the switch or access point itself.

1. Sign in to the UniFi Network application that adopted the hardware — your UniFi OS console, Cloud Key, or self-hosted controller.
2. Open Settings and find the SNMP section. octoja's own field help points at Settings → System → SNMP, which is where recent Network versions keep it. If your version files it somewhere else, search the settings for SNMP — you are looking for the section that carries the enable switch and the credentials for the SNMP versions your controller supports.
3. Enable the version your controller offers:
   • Community-based SNMP, labelled v1/v2c. This is the option octoja's own check descriptions point at. Enable it and set the community string — treat it as a password and move it off public.
   • SNMPv3, with a username and password. Availability varies by UniFi Network version and hardware generation. Use it if your controller offers it: it authenticates and encrypts, where a v2c community string travels in the clear.
4. Save, then give the devices a moment. UniFi applies the setting when each adopted device next provisions — until then it will not answer. If one device stays silent while its neighbours reply, force a provision on it.
5. Note the address of each device you want to monitor. That is the device's own LAN address, not the controller's — each check is pointed at the switch, access point, or gateway itself.

UniFi controller layouts move between releases. If the wording above does not match what you see, search the settings for SNMP. Whatever the layout, you are configuring SNMP once for the whole Network application, not on the individual switch or access point.

Cloud-hosted controller? Nothing changes for octoja

Whether the UniFi Network application runs on local hardware or is hosted in the cloud (for example a console reached through unifi.ui.com) makes no difference to the checks — there is nothing to "add" or connect for the controller itself. Two things follow from that:

• Enable SNMP the same way. Open your cloud-hosted Network application in the browser, enable SNMP under Settings → System → SNMP as described above, and the setting is pushed to every adopted device on site — exactly as with a local controller.
• The checks still poll locally. Each check queries the switch, access point, or gateway at its LAN address, from an octoja-managed device on the same network. Do not point a check at the cloud console's address or a public URL — the controller does not answer SNMP, and the UniFi devices are not reachable on UDP 161 across the internet.

The only hard requirement is therefore the same as always: one online device with the octoja agent in the same network as the UniFi hardware. The cloud console itself is not a monitorable device in octoja.

Steps

1. Go to Devices and open the device the check will run from — your agent-managed device, or the agentless UniFi device itself.
2. Click the Checks tab → Add Check, then pick UniFi (SNMP), UniFi Access Point (SNMP), or UniFi Switch (SNMP).
3. Fill in the connection block. Everything else has a working default.
4. Click Add Check.

Add one check per device. Each check queries a single address, so a site with a gateway, three switches, and eight access points needs one check per box.

Settings

All three checks share the same connection block — only the label of the host field differs. Which fields appear below it depends on the check.

The v3 fields build on each other, because encryption requires authentication: with Auth protocol (v3) on None, octoja hides the privacy fields altogether. Pick an auth protocol and its password first, and the privacy pair appears underneath.

Warning and critical thresholds are ordered for you: if you enter a warning value above the critical one, octoja swaps them rather than producing an alarm that can never fire.

Three fields need more than a default value to use well.

• Interfaces that must be up, on UniFi (SNMP), is a picker fed by the ports discovered on the previous run — so it is empty the first time. Save the check, let it run once, then reopen it and select your uplinks and business-critical ports.
• Warn if any interface down, on UniFi (SNMP), is off by default, and on a UniFi switch you should leave it off. It warns about labelled ports that are administratively up but operationally down — and UniFi labels every port on a switch, so unused ports get flagged alongside a genuinely dead uplink. Use Interfaces that must be up for targeted alarms instead.
• Client warning per radio (0 = off), on UniFi Access Point (SNMP), is off out of the box. Set it to the client count at which you consider a radio saturated, and the check warns as soon as any radio reaches it.

Results

After the first check interval, the result appears in the device's Checks tab with online state, model, and the measurement tiles for that check.

When the result is not what you expected

Tips

• Rolling the same check out across a fleet is what configuration packages are for — see Assign Checks with Configuration Packages.
• Prefer SNMPv3 wherever your UniFi Network version offers it. A v2c community string is sent unencrypted on the wire.
• Pick a probing device that stays online and sits close to the UniFi hardware on the network. If it goes offline, every UniFi check running from it goes with it.

See also: Checks