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 can take a collector role and poll those devices over SNMP, forwarding the results up its own outbound WebSocket. No new inbound surface, read-only, low risk.

The collector role​

The role is assigned by the server, not configured on the host. A definition lists the hosts that may act as collector, in priority order, which gives you a primary and a backup:

{ "service": "switch-x", "hosts": ["collector-a", "collector-b"], "probes": [ ... ] }

The server computes which listed host is currently alive and ships a roles map. If the primary collector dies, the backup takes over within about one poll cycle, so you do not lose every device at once. The device is one inventory unit (kind=device), not counted per port or per OID.

What a definition contains​

  • target: the device address (non-secret, in the definition).
  • get and walk: the OIDs to read, mapped to dev.* metric names.
  • deviceFacts: sysDescr, sysName, sysObjectID for inventory.
  • secret: the name of a locally stored credential.

Standard MIBs cover most of the ground (IF-MIB for ports and traffic, UPS-MIB, HOST-RESOURCES-MIB, ENTITY-SENSOR-MIB for temperature, voltage, fans and optical DOM, plus PoE tables). Vendor MIBs (MikroTik, APC) ship as signed OID bundles, no new agent code.

Credentials stay local​

The v2c community or the v3 USM user and passphrases are secrets. Set them on the host, and on every listed collector, because secrets are never transferred between hosts:

wakora secret set snmp-switch                        # v2c community
wakora secret set snmp-ups-v3 --user upsmon --priv   # v3 auth + privacy

Non-secret v3 parameters (auth and privacy protocol, context) ride in the signed definition. If you set the secret only on the primary, a failover to the backup will fail because the credential is not there. This is by design (secrets are local) but easy to forget.

Traps and syslog​

A collector can also open local listeners for SNMP traps (UDP 162) 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 are accepted only from the SNMP targets of the collector's active definitions (plus an explicit allow list), because UDP is spoofable. SNMPv3 informs are supported.

Device auto-discovery​

An optional subnet scan finds responders and lists them as candidates (kind=candidate). Candidates are not polled automatically. You approve the IP range (it lives in the signed definition, so the signature is the approval), and a client network is never scanned on its own. A candidate becomes monitored only when you write a full definition for it.

Planned

The full network module (topology via LLDP and CDP, weathermap, MAC tracking, VLAN and STP, IPAM, netflow, config backup) is planned on top of the collector. Device metrics, ports, sensors, PoE, traps and syslog are live today.