Skip to main content

SNMP and network

Some targets cannot run an agent (routers, switches, UPS and PDU units, printers, appliances) or should not have one. One agent per site takes a collector role and polls those devices over SNMP, forwarding the results up its own outbound WebSocket. No new inbound surface, read-only, low risk.

Setting a device up has exactly two halves, and it helps to know which is which:

  1. The device definition (what to poll, from where) lives server-side and is pushed to the collector, signed. You do not write files on the host for this.
  2. The credential (community string or SNMPv3 user) lives only on the collector host, set by you with wakora secret set. It never travels.

Half 1: the definition​

A device definition names the target, the OIDs, and which hosts may poll it. This is what one looks like (a UPS polled over SNMPv3):

{
  "service": "office-ups",
  "hosts": ["collector-a", "collector-b"],
  "intervalSec": 60,
  "probes": [
    { "type": "snmp", "target": "10.0.20.14", "secret": "snmp-office-ups",
      "v3": true, "authProto": "SHA", "privProto": "AES",
      "get": [
        { "name": "dev.ups.charge_pct",        "oid": "1.3.6.1.2.1.33.1.2.4.0" },
        { "name": "dev.ups.minutes_remaining", "oid": "1.3.6.1.2.1.33.1.2.3.0" },
        { "name": "dev.ups.output_load_pct",   "oid": "1.3.6.1.2.1.33.1.4.4.1.5.1" }
      ] }
  ]
}

The fields that matter to you as the operator:

  • target is the device address. A non-standard SNMP port rides in it ("10.0.20.14:1161").
  • hosts is the collector list in priority order: the first alive host polls, the next is the backup. If the primary dies, the backup takes over within about one poll cycle.
  • secret is the name of the credential the collector resolves locally. This name is the contract between the definition and your host: the secret you create must use exactly this name.
  • v3, authProto, privProto, context are the non-secret SNMPv3 parameters. They are not sensitive, so they ride in the definition. The passphrases do not.
  • get and walk map OIDs to dev.* metric names; walk entries produce one point per table row, tagged with the device's own labels (interface names via a labelOid). sensors: true walks the standard sensor table (temperatures, fans, PSU voltage, optical dBm), poe: true walks the PoE table. deviceFacts (sysDescr, sysName, sysObjectID) fill the device inventory.

Standard MIBs cover most gear (IF-MIB for ports and traffic, UPS-MIB, HOST-RESOURCES-MIB, ENTITY-SENSOR-MIB, PoE tables). Vendor bundles (MikroTik health, APC PowerNet) are just more signed definitions, no new agent code. The resulting metrics are listed in the metrics reference.

You normally do not write this JSON at all: approving a device in the Devices module composes the definition from the device type, signs it for your workspace, and pushes it to the collector. Device definitions ride the same per-workspace signing tier as marketplace templates, in their own namespace, so nothing polls a target your workspace did not explicitly approve. Your part remains the credential below.

Half 2: the credential, on the host​

Create the secret on every host listed in hosts, under exactly the name the definition references. Secrets never transfer between hosts, so a failover to a backup collector that lacks the secret would fail. This is by design and easy to forget.

For SNMP v2c, the community string is entered as the password:

wakora secret set snmp-office-ups
# Password: <community string>

For SNMPv3, --user sets the USM user name and --priv makes the prompt ask twice: first the authentication passphrase, then the privacy passphrase:

wakora secret set snmp-office-ups --user upsmon --priv
# Password: <auth passphrase>
# Privacy passphrase: <priv passphrase>

The security level is derived from what is present: user plus auth passphrase gives authNoPriv, adding the privacy passphrase gives authPriv. The values are stored machine-bound and encrypted, like every secret (see Secrets).

Verifying it works​

Within a poll cycle the device appears in inventory (kind=device, with sysDescr and sysName) and dev.* metrics start flowing. On the collector host, the check result tells you plainly when something is wrong:

  • "run wakora secret set" means the named secret is missing on this collector.
  • "packet is not authentic" means the v3 passphrase is wrong.
  • A timeout usually means the target address, the port, or a firewall between the collector and the device.

Dead targets are cheap by design: before doing real work, the probe fires one short liveness request, so an unreachable device costs one bounded attempt per cycle instead of dragging the whole collector behind serial timeouts. A failed fetch retries within minutes rather than waiting out the full interval.

Traps and syslog​

A collector can also open local listeners for SNMP traps (UDP 162, SNMPv3 informs on their own port) and syslog (UDP 514). The model is: polling is the authoritative state, a trap or syslog line is an immediacy hint. An accepted trap triggers an immediate confirming poll before anything alerts. Traps, syslog and flows are accepted only from the SNMP targets of the collector's active definitions plus an explicit allow list, because UDP is spoofable; an empty list means nobody is accepted, never everybody, so a device has to be approved in Devices (or named in the allow list) before its first packet counts. The source address is checked before the packet is parsed at all, so a stranger's traffic costs the collector a lookup and nothing more. A listener whose port no longer appears in any definition is closed rather than left open. Listener credentials for v3 informs follow the same secret contract as polling.

Device syslog also flows as lines into the logs module (severity mapped to a level, same redaction and volume guards), so a switch's messages are searchable next to everything else.

Topology facts​

A device definition can enable a topology walk. The collector then reads the device's neighbor tables (LLDP, or the MikroTik neighbor table on RouterOS, which does not expose LLDP over SNMP), its chassis identity, port speeds, and its FDB, ARP and VLAN tables (capped, and re-sent only when the content changes). Those facts feed the topology map and address book in the console; the agent side is just more read-only SNMP against the same target with the same credential.

Traffic flows​

A collector can open a NetFlow listener (v5, v9 and IPFIX on one UDP port). Exporters are allowed the same way traps are: the SNMP targets of the collector's active definitions form the allow list, so approving the device is what opens its flows, and spoofed packets from anywhere else are dropped. The collector aggregates locally, one minute at a time, into top talkers and totals per exporter; raw flows never leave your site. Per-exporter byte and flow rates ride the metric stream as dev.flow.*.

Configuration backup​

The configfetch probe fetches a device's running configuration over SSH from the collector. The SSH credential is a named secret on the collector like any other; the device's host key is pinned on first use. Volatile lines (timestamps, rotating counters) are normalized away, and passwords and keys are masked on the collector before anything is sent, with a default pattern set plus whatever the definition adds. A version travels upstream only when the content actually changed. The console keeps the version history and diffs; see Configuration backup.

Device auto-discovery​

An optional subnet scan finds responders and lists them as candidates (kind=candidate). Candidates are not polled automatically. The scanned range lives in a signed definition, so the signature is the approval: a client network is never scanned on the agent's own initiative. A candidate becomes monitored when a device definition is created for it.

Billing​

Each device is one monitored unit, like a site. A 48-port switch is one device; its ports are metrics inside it, never counted per port or per sensor. The collector host itself counts as a host. Flow volume is metered separately in monthly gigabytes.

Planned

sFlow ingestion and STP visibility are planned. Everything else on this page (device metrics, sensors, PoE, traps, syslog, topology, the map, MAC and VLAN views, NetFlow and IPFIX, config backup) is live.