SNMP

SNMP (Simple Network Management Protocol) is a polling-based protocol that retrieves device data via OID-addressed MIB variables. Prelude Collector uses SNMP when a device does not support streaming telemetry — older boxes, appliances, environmental sensors, optical line systems — or when the metric you need only lives in a MIB. After the first mention, this page refers to Prelude Collector as "the collector".

When to use

Pick SNMP when the device speaks it cleanly and the data is exposed in a standard or vendor MIB. SNMP is the broadest-support protocol in the network: nearly every router, switch, firewall, UPS, and optical platform answers SNMP.

Connection settings

An SNMP Protocol record carries the device-side transport settings:

For the exact field names accepted by the API, see the API reference for Protocols.

The collector-wide SNMP defaults apply to every SNMP Protocol record and are set via COLLECTOR_SNMP_* environment variables (see the Configuration reference):

The collector's SNMP session uses UDP transport. Requests for one device are serialized so the collector never overlaps SNMP RPCs on the same target. Table walks use the GETBULK operation (not GETNEXT); tune max-repetitions down for devices whose SNMP engine struggles with large bulk PDUs.

Authentication options

SNMPv2c (community string)

The simplest option. Set version: "v2c" and provide a community value. The community string is encrypted at rest. Use only on a trusted management VLAN.

SNMPv3 USM

The full security model. sec_level controls how much of the USM stack is active:

For authPriv, set both auth_proto / auth_key and priv_proto / priv_key. SHA + AES is the recommended combination.

Walk profiles

A walk profile is a named SNMP table walk plus the metadata the collector needs to label its rows. Profiles tell the collector which columns are numeric metrics and which are string labels. They are how SNMP table data lands in your output backends with the right Prometheus labels or InfluxDB tags.

A profile looks like this:

{
  "name": "ifTable",
  "oid": "1.3.6.1.2.1.2.2",
  "mib_module": "IF-MIB",
  "description": "Interface table",
  "netos": [],
  "metrics": ["ifInOctets", "ifOutOctets", "ifOperStatus"],
  "labels": ["ifDescr", "ifIndex"]
}

A standard set of IETF and common vendor profiles ships in the collector image. Drop additional profiles into storage/mibs/profiles/ as .json files and they will be loaded at startup alongside the built-ins.

The collector also exposes a built-in SNMP browser in the web UI for interactively walking MIBs and trying OIDs against a device.

Examples

v2c Device + Protocol

export BASE="https://collector.example.com"
export TOKEN="<your-api-token>"

curl -s -X POST "$BASE/api/v1/devices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "edge-switch-04",
    "ip": "192.0.2.40",
    "active": true
  }'

curl -s -X POST "$BASE/api/v1/protocols" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 4,
    "type": "snmp",
    "address": "192.0.2.40:161",
    "version": "v2c",
    "community": "<community-string-placeholder>"
  }'

Bruno: 02 Devices / Create device, 03 Protocols / Create gNMI protocol

v3 Device + Protocol

curl -s -X POST "$BASE/api/v1/protocols" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 4,
    "type": "snmp",
    "address": "192.0.2.40:161",
    "version": "v3",
    "username": "prelude-monitor",
    "sec_level": "authPriv",
    "auth_proto": "SHA",
    "auth_key": "<auth-key-placeholder>",
    "priv_proto": "AES",
    "priv_key": "<priv-key-placeholder>"
  }'

Bruno: 03 Protocols / Create gNMI protocol

Subscription

Bind any SNMP Model to the Device with a Subscription. interval is the poll interval in seconds:

device_id: 4
model: ietf-interfaces
interval: 60
enabled: true

Limitations

• SNMP v1 is not supported. The minimum version is v2c.
• SNMP traps are out of scope for this version of the collector. Trap receivers and informs are handled outside the collection pipeline.
• Walking very large tables (chassis with 1000+ ports) can pressure the device's SNMP engine. Pick conservative intervals and split subscriptions across multiple collectors when you scale out.
• Polling is bound by the collector's worker-pool-size (see Configuration) and by the device's own SNMP engine. Plan on intervals of 30 seconds or longer on busy devices.
• A vendor MIB you load yourself only resolves names if the underlying file is reachable to the collector at startup; missing files do not break collection but leave OIDs unnamed in the UI.

Troubleshooting

Test Connection from the device UI

Open the device's Protocols tab in the web UI and click Test Connection on the SNMP Protocol row. The collector issues a small GET against the device using the credentials stored on the Protocol record and reports success, failure, or the SNMP error returned. Use this first whenever a Subscription stops producing Snapshots — it proves community / USM credentials and reachability are healthy and narrows the problem to OIDs.

One-shot OID test

The test-path endpoint runs a one-shot walk against an existing Device without needing a Model or Mapping, and returns the raw updates the device sends back:

curl -s -X POST "$BASE/api/v1/protocols/test-path" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device-id": 4,
    "protocol": "snmp",
    "paths": ["1.3.6.1.2.1.2.2"]
  }'

Bruno: 03 Protocols / Test path (gNMI)

paths for SNMP is a list of root OIDs to walk. Use it to confirm an OID actually returns rows on the target before wiring it into a profile.

See also

• Collection protocols
• Choosing a protocol
• Polling intervals
• API: Protocols