SNMP

Pull

Synopsis

Director polls one SNMP agent — a switch, a router, a firewall, a load balancer — and writes what it reads as ECS documents: the device's identity, its interfaces and their traffic, CPU, memory, fans and power supplies, VLANs, hardware, CDP/LLDP neighbors, the manufacturer's own tables, and any OIDs you add. What the device reads is decided by the datasets and profiles assigned to it, as for Windows and Linux devices — see SNMP Datasets.

One device polls one agent. Monitoring forty switches means forty devices. The poller dials out and binds nothing, so every SNMP device on a Director may use port 161.

This device is the poller. Traps the same switches send are received by the SNMP Trap device, which listens; the two are independent and usually run side by side.

note

The SNMP device needs Director 2.2.3 or later. With no Director or cluster at that version selected, the wizard shows SNMP devices are unavailable on directors or clusters below version 2.2.3 and the device cannot be created.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: snmp
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    port: <numeric>
    version: <string>
    community: <string>
    username: <string>
    context_name: <string>
    authentication:
      protocol: <numeric>
      password: <string>
    privacy:
      protocol: <numeric>
      passphrase: <string>
    timeout: <numeric>
    max_retries: <numeric>
    max_repetitions: <numeric>
    vendor: <string>
  definitions: <definition[]>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be snmp
tags	N	-	Optional tags
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device

Connection

Field	Required	Default	Description
address	Y	-	IP address or host name of the agent. A wildcard address (0.0.0.0, ::) is refused.
port	N	161	UDP port the agent answers on
version	N	v2c	v1, v2c, or v3 (also accepted: 1, 2, 2c, 3)
community	Y*	-	The read community (resolvable via ${ENV_VAR} or $secret{...})

* Required for v1 and v2c. Not used with v3.

SNMPv3

Field	Required	Default	Description
username	Y*	-	The SNMPv3 user (resolvable via ${ENV_VAR} or $secret{...})
context_name	N	-	For agents serving several contexts, such as one per VLAN on some Cisco switches
authentication.protocol	N	1	Authentication protocol ID, by number or name. See Authentication Protocols
authentication.password	Y*	-	At least 8 characters. Required when an authentication protocol is set (resolvable via ${ENV_VAR} or $secret{...})
privacy.protocol	N	1	Privacy protocol ID, by number or name. Needs an authentication protocol. See Privacy Protocols
privacy.passphrase	Y*	-	At least 8 characters. Required when a privacy protocol is set (resolvable via ${ENV_VAR} or $secret{...})

* Required for v3, where noted.

The security level follows from the protocols: no authentication is noAuthNoPriv, authentication without privacy is authNoPriv, and both is authPriv.

Datasets

The device's definitions are its datasets, each named after its type, snmp_<dataset>_collector. In the console they are the datasets and profiles assigned to the device. For the dataset types and their properties, see SNMP Datasets.

Nothing assigned is allowed: the device keeps checking that its agent answers, so its connection state stays current, and writes nothing.

Advanced Configuration

Field	Required	Default	Description
timeout	N	10	Seconds to wait for each answer, from 1 to 300
max_retries	N	2	Retries after a timeout, from 0 to 10
max_repetitions	N	10	Rows per GetBulk request, from 1 to 100. v2c and v3 only: v1 walks with GetNext
vendor	N	-	The manufacturer's profile to read the device with, for a device that is not identified on its own. Empty detects it. See Manufacturers

Connection States

• A wrong community looks like a dead agent. An agent drops a request with the wrong community without answering, so the connection state is Connection error, the same as for an agent that is down.
• A refused SNMPv3 user — an unknown user, a wrong password or passphrase, or a level the user does not have — sets Authentication error.
• A configuration error — a missing community, a short password, an unknown protocol or vendor — stops the device at start with Configuration error. The message names the property but never its value.

An agent that stops answering during a reading ends that reading with Connection error; the next reading tries again, and the state returns to Connected when the agent answers.

When Things Are Read

• At start the device reads sysObjectID, sysUpTime, and sysName. No answer stops the device; the Director starts it again later.
• Every dataset on its own interval, all of them once at start. Datasets due at the same moment are read together and share their walks.
• At least every minute the agent is checked, even when nothing is due, so the connection state follows the agent.
• Every hour, and after a reboot, the device is identified again — its manufacturer, model, and OS version — so a firmware upgrade is picked up without an inventory dataset assigned.
• Counters need two readings. Traffic, errors, and other counters are reported as their increase since the dataset's previous reading, so the first reading after a start reports no increase. A counter that goes backwards is a wrap or a reset, and is skipped rather than reported as a spike.
• Reboots. sysUpTime going backwards is reported as a reboot event and clears the remembered counters and statuses.

Records

Every record is one ECS 8.11 document:

• event.module is snmp, and event.dataset is snmp.<dataset> — for example snmp.interface_stats, snmp.f5_pool, or snmp.custom.
• event.kind is metric for a measurement, state for an inventory item, or event for something that happened.
• The device is described under observer.*: observer.name (the device's name in the console), observer.hostname (the agent's sysName), observer.ip, observer.vendor, observer.product, observer.type, observer.serial_number, observer.version, observer.os.*, and observer.geo.name (sysLocation).
• Fields ECS has no name for sit under snmp.<dataset>. Percentages are fractions of 1, sizes are bytes, and rates are per second.

Inventory records carry event.action from a dataset's second reading on: added, changed, unchanged, or removed. A removed item is reported once, as it was last seen.

Each record also carries its dataset's own definition id. For the fields of each dataset, see SNMP Datasets.

Manufacturers

The device identifies the manufacturer from sysObjectID, against the SNMP vendor list of some 8,900 known devices, and otherwise from sysDescr. It then reads the agent with that manufacturer's profile: where it keeps CPU, memory, fans, and power supplies, how its sysDescr names the model and OS version, and which of its own tables it has.

The profiles are Arista, Aruba, Brocade, Check Point, Cisco, Citrix, Dell, F5, Fortinet, HP, Huawei, IBM, Juniper, MikroTik, Palo Alto Networks, pfSense, SonicWall, Sophos, Ubiquiti, and WatchGuard. A device none of them recognizes is read as Generic — the standard MIBs, with CPU and memory from HOST-RESOURCES-MIB — and names no manufacturer.

The SNMP vendor list can be extended and corrected per tenant in Library > SNMP Vendors; see Library. When nothing identifies a device, its vendor property names the profile to read it with, and the choice wins over detection. The Director refuses any name other than the profiles above and Generic.

Console

In the console, go to Fleet Management > Devices > SNMP and click Add new device. The wizard's steps are:

1. General settings, as on every device.
2. Connection settings:
   • Address and Port.
   • SNMP version: SNMPv1, SNMPv2c, or SNMPv3.
   • v1 and v2c: Community string, entered manually or taken from a vault secret.
   • v3, under SNMPv3 user: Username (manual or a vault secret), Context name (Optional), Authentication protocol, and Privacy protocol, shown once an authentication protocol is chosen. Authentication password and Privacy passphrase are shown while their protocol is in use, each manual or a vault secret.
3. Connection check: optional — Next always moves on. See Connection Check.
4. Advanced settings: under Requests, Timeout, Maximum retries, and Maximum repetitions; under Identification, Vendor. The vendor is Automatic detection by default, which writes nothing; otherwise one of the 20 manufacturer profiles, or Generic (standard MIBs only), which writes Generic.
5. Data collection: the datasets or profile the device reads. A device receives datasets or a profile, never both.
6. Review and create.

For SNMPv3 the wizard pre-selects SHA (3) and AES-128 (3). A configuration file that leaves the protocols out means none (1).

The console saves only what the chosen version uses: v3 saves no community, v1 and v2c save no SNMPv3 user, and a password or passphrase is dropped while its protocol is none.

The device's page has the connection check above the Connection settings card, the Vendor under Advanced settings, and a Data collection tab.

Connection Check

The Director the device runs on asks the agent for its system group and identifies the manufacturer the way the running device will, with the tenant's current SNMP vendor list. Click Check connection, and Check again after changing a setting. The result is one of:

Result	Title on screen	Notes
Connected	Connected to <name>	Says how the manufacturer was identified: by its sysObjectID, by its sysDescr, or as chosen under Advanced settings
Manufacturer unknown	Connected to <name>, but its manufacturer is unknown	Shows the sysObjectID. Add to SNMP vendors opens the Library's create dialog; on the wizard, Vendor picks a profile, which is kept under Advanced settings. Either way the check runs again
No response	No response from address:port	A wrong address or port, a firewall, or, for v1 and v2c, a wrong community: an agent ignores a wrong community without answering
Credentials refused	The device refused the credentials	SNMPv3 only
System group hidden	Connected, but the device hides its system group	An SNMPv3 view or context hides it
Invalid settings	The settings are not valid
No answer from the Director	The director did not answer	The console gives up after 45 seconds

Under a connected result, the device's Name, Description, sysObjectID, Location, Uptime, and Response time are listed.

• A self-managed Director takes no console commands, so the check explains that it cannot run there. Orchestrated and serverless Directors run it as managed ones do.
• A Director the platform reports disconnected gets a notice of its own, <director> is offline, instead of a check it cannot answer.
• A Director below 2.2.3 is told to update.
• On a saved device the check uses the stored community, password, and passphrase, which needs the right to edit devices.

Simulation

The SNMP device is not simulated. What it writes is decided by its datasets, each with a record shape of its own, and one generic sample cannot stand in for them.

Not Included

The retired SNMP module could also back up device configurations over SSH or Telnet. That is not SNMP, and is not part of this device.

Examples

SNMPv2c

Polling a switch over SNMPv2c, reading its identity hourly and its interface traffic every minute...

devices: - id: 471209331 name: core-sw01 type: snmp status: true properties: address: "192.0.2.10" port: 161 version: v2c community: "${SNMP_COMMUNITY}" definitions: - name: snmp_system_collector - name: snmp_interface_stats_collector properties: interval: 60

SNMPv3

Polling a firewall over SNMPv3 with authentication and privacy, its credentials taken from a vault...

devices: - id: 471209332 name: edge-fw01 type: snmp status: true properties: address: "192.0.2.20" version: v3 username: "monitor" authentication: protocol: sha256 password: "$secret{store=corp-vault,ref=network/snmp-auth}" privacy: protocol: aes passphrase: "$secret{store=corp-vault,ref=network/snmp-priv}" definitions: - name: snmp_system_collector - name: snmp_cpu_collector - name: snmp_memory_collector