Netscan

The netscan plugin pings a list of devices on the local network and reports whether each one answers and how fast. It needs no credentials. Turn it on for the gear in an office or rack that can't run an agent: switches, printers, access points, the router, a NAS, phones.

For deeper numbers from the same devices, such as toner levels or port states, add the SNMP or TP-Link plugin. Reports for the same IP merge into one device on the dashboard.

Enable it

Add netscan to the plugins array.

{
  "plugins": ["netscan"],
  "netscan": {
    "refreshInterval": 30000,
    "pingCount": 2,
    "pingTimeout": 2,
    "devices": [
      { "name": "core-switch", "ip": "192.0.2.2", "type": "switch" },
      { "name": "office-printer", "ip": "192.0.2.20", "type": "printer" },
      { "name": "nas-01", "ip": "192.0.2.30", "type": "nas", "warnMs": 50 },
      { "name": "upstairs-ap", "ip": "192.0.2.40", "type": "ap", "mac": "00:00:5e:00:53:01" }
    ]
  }
}

Option	Default	What it does
refreshInterval	30000	Milliseconds between scans.
pingCount	2	Echo requests per device.
pingTimeout	2	Seconds to wait for each reply, passed to ping -W.
devices	[]	Devices to ping. Entries without ip are skipped.
devices[].name	the IP	Display name.
devices[].ip	required	Address to ping.
devices[].type	host	Free-form label such as switch, printer, ap, nas. Stored in the payload, not used for alerting.
devices[].mac	none	Stored with the device.
devices[].warnMs	200	Average round trip in milliseconds above which the device is slow.

All devices are pinged at the same time on each pass.

What it reports

One payload per device: name, ip, type, mac, up, latency (average round trip in ms, one decimal), loss (packet loss percent) and warnMs.

A device with 100% loss is reported down even if ping exited cleanly.

When it alerts

Severity	Trigger	Reason text
error	up is false	<name> (<ip>) unreachable
warning	latency is above warnMs	<name>: high latency <n>ms

Packet loss below 100% does not alert.

Netscan reports do not get their own service. The server folds them into a device entity keyed by IP, dev-<ip>, together with any SNMP or TP-Link report for the same address. Each plugin's payload sits under data.sources.<plugin>, and the device status is the worst status across its sources.

Device alerts go out on the first bad report, with no one-report wait, under source device. While an alert for that device is open, further bad reports don't send another. The server never resolves device alerts when the device recovers, so after the first one, the device does not page again until someone resolves the alert by hand.

On the dashboard

Netscan adds a PING metric to the front of the device card. It shows DOWN in red when the device is down, the latency in amber when it is above warnMs, and the latency in green otherwise.

A device with only a netscan source shows as "Device · <ip>". When SNMP or TP-Link also reports for that IP, their metrics fill the rest of the card and their name for the device replaces the netscan name.

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

Requirements

• A ping binary on the agent host. It runs ping -c <count> -W <timeout> <ip>.
• The agent must reach the devices over ICMP. In a container, use host networking.

Gotchas

• -W means seconds in Linux iputils ping. BSD and macOS ping read it differently.
• Some devices drop ICMP but answer SNMP. For those, the SNMP plugin's reachability is the better signal.