SNMP

The snmp plugin polls network devices over SNMP. It knows three kinds of target. Printers report page counts and toner levels. QNAP NAS units report disk health, temperatures and volume fullness. Switches, routers and other devices report uptime, port states, CPU, RAM and per-interface traffic. Turn it on for office and rack gear that speaks SNMP but can't run an agent.

Enable it

Add snmp to the plugins array.

{
  "plugins": ["snmp"],
  "snmp": {
    "refreshInterval": 300000,
    "community": "public",
    "targets": [
      { "name": "office-printer", "ip": "192.0.2.20", "kind": "printer", "tonerWarnPct": 15 },
      { "name": "nas-01", "ip": "192.0.2.30", "kind": "qnap", "tempWarnC": 65, "volumeWarnPct": 85 },
      { "name": "core-switch", "ip": "192.0.2.2", "kind": "switch" },
      { "name": "edge-router", "ip": "192.0.2.1", "kind": "device", "community": "YOUR_COMMUNITY", "wanInterface": "eth0" }
    ]
  }
}

Option	Default	What it does
refreshInterval	300000	Milliseconds between polls.
community	public	Default community for every target.
targets	[]	Targets to poll. Entries without ip are skipped.
targets[].name	the IP	Display name.
targets[].ip	required	Device address.
targets[].kind	printer	printer, qnap, switch or device. switch and device collect the same data and differ only in the card label.
targets[].community	section community	Community string for this target.
targets[].version	2c	1 or 2c. SNMPv3 is not supported.
targets[].tonerWarnPct	10	Printer. A supply at or under this percent is low.
targets[].volumeWarnPct	90	QNAP. A volume at or over this percent is full.
targets[].tempWarnC	70	QNAP. CPU or disk temperature at or over this is too hot.
targets[].wanInterface	none	Switch or device. Interface name, such as eth0, whose traffic is the headline NET figure.

All targets are polled at the same time on each pass.

What it reports

Every payload has name, ip, kind and reachable. A target that answers nothing comes back with reachable: false and nothing else. A collector that throws sends error.

Printers, from the Printer MIB:

• model, serial, pages (lifetime page count) and status (idle, printing, warmup, other, unknown).
• supplies, each with name, level, max and pct. A supply that reports "some remaining" counts as 100%. Unknown levels have a null pct.
• lowSupplies, the supplies at or under tonerWarnPct, and warnPct.

QNAP, from the QNAP NAS MIB and HOST-RESOURCES:

• model, cpuPct, cpuTempC, sysTempC, memPct, memTotalMB, fans and fanRpm (the slowest fan).
• disks, each with slot, descr, model, capacity, tempC, status (0 is healthy) and smart. Empty bays are left out.
• badDisks, disks with a non-zero status, a SMART verdict containing warn, abnormal, fail, error, bad or caution, or a temperature at or over tempWarnC.
• volumes, the CACHEDEVn_DATA mounts with totalGB, usedGB and pct, and fullVolumes.
• tempWarnC, volumeWarnPct.

Switches and other devices, from SNMPv2-MIB, IF-MIB and UCD-SNMP:

• sysDescr, sysName, uptimeSecs.
• portsUp and portsTotal, counting only admin-enabled ports.
• cpuPct, cpuCores, load1, loadavg, memPct, memTotalMB, when the device ships the UCD MIB.
• interfaces, each with name, inBps, outBps, up and adminUp, busiest first. Loopback and pseudo interfaces are dropped. Rates appear from the second poll on.
• netIn, netOut and wanInterface, from the wanInterface link only. Without wanInterface there is no headline figure, because summing every interface on a router counts transit traffic twice.

When it alerts

The server checks these rules in order and the first match sets the status:

Severity	Trigger
error	The payload has error.
error	reachable is false. Reason "SNMP unreachable".
error	badDisks is not empty. The reason names each disk with its SMART verdict and temperature.
warning	fullVolumes is not empty.
warning	cpuTempC is at or over tempWarnC.
warning	memPct is 90 or more. Applies to every kind that reports RAM.
warning	lowSupplies is not empty.
warning	Printer status is anything other than idle, printing or warmup.

Nothing alerts on switch ports or interfaces. A port that drops shows on the card but raises no alert.

SNMP reports do not get their own service. The server folds them into a device entity keyed by IP, dev-<ip>, with any netscan or TP-Link report for the same address. The device status is the worst across its sources. Device alerts go out on the first bad report under source device, and the server does not resolve them when the device recovers.

On the dashboard

The device card takes its name, label and metrics from the SNMP source.

Printer, labelled "Printer · <model>":

• PAGES, uncolored.
• STATUS, red when unreachable.
• SUPPLIES list. A supply is red at or under tonerWarnPct, amber at or under 25%, green above.

QNAP, labelled "NAS · <model>":

• CPU, amber at 90% or more. RAM, amber at 90% or more.
• CPU °C and SYS °C, red at or over tempWarnC, amber within 10 degrees of it.
• FAN, red at 0 rpm.
• A disk bar per volume.
• DISKS list. A disk is red on a non-zero status or a SMART verdict other than good or normal, amber at or over tempWarnC.

Switch or device, labelled "Switch" or "Device" plus the first part of sysDescr:

• CPU, amber at 75%, red at 90%. RAM, amber at 80%, red at 90%.
• NET IN and NET OUT, when wanInterface is set.
• LOAD, or LOAD/CORE on multi-core devices, amber at 0.7 per core, red at 1.0.
• PORTS as up over total, amber when no enabled port is up.
• UPTIME.
• INTERFACES list, up to 16. An admin-disabled port is grey, an enabled port with no link is red with LINK DOWN.

A device with no report from any source for 300 seconds shows OFFLINE.

Requirements

• net-snmp's snmpget and snmpwalk on the agent host. In the Docker client image, add the snmp package.
• UDP 161 open from the agent to each target, and SNMP v1 or v2c enabled on the device with a matching community.
• For QNAP, enable SNMP in the NAS settings.

Gotchas

• The default poll is 300 seconds, and the dashboard marks a device OFFLINE after 300 seconds of silence. A target reported only by SNMP can flicker OFFLINE just before each poll. Set refreshInterval lower, or add the device to netscan too.
• A target without kind is treated as a printer.
• QNAP's SNMP agent drops rows under concurrent requests, so the plugin walks the QNAP tables one at a time. A QNAP poll is slow on purpose.
• If the QNAP disk table comes back empty, or a disk has neither a status nor a SMART reading, the plugin sends error with "SNMP read incomplete" instead of reporting healthy. That shows as an error.
• Each SNMP request uses a 2 second timeout with one retry.