SNMP Trap
Synopsis
Creates a receiver that listens for SNMP trap messages. Supports SNMPv1, SNMPv2c and SNMPv3 with various authentication and privacy protocols, MIB integration, and High-Volume message processing.
Schema
- id: <numeric>
name: <string>
description: <string>
type: snmptrap
tags: <string[]>
pipelines: <pipeline[]>
status: <boolean>
properties:
address: <string>
port: <numeric>
community: <string>
authentication:
status: <boolean>
protocol: <numeric>
password: <string>
privacy:
protocol: <numeric>
passphrase: <string>
username: <string>
Configuration
The following fields are used to define the device:
Device
| Field | Required | Default | Description |
|---|---|---|---|
id | Y | Unique identifier | |
name | Y | Device name | |
description | N | - | Optional description |
type | Y | Must be snmptrap | |
tags | N | - | Optional tags |
pipelines | N | - | Optional pre-processor pipelines |
status | N | true | Enable/disable the device |
Connection
| Field | Required | Default | Description |
|---|---|---|---|
address | N | "0.0.0.0" | Listen address |
port | Y | Listen port for SNMP traps (typically 162) | |
community | Y* | Community string for SNMPv1/v2c authentication. A trap carrying a different community is dropped; leave it empty to accept every v1/v2c trap. Accepts plain text, ${ENV} references, or $secret{...} vault tokens |
* = Required for SNMPv1/v2c in the console, where the field is
Authentication
| Field | Required | Default | Description |
|---|---|---|---|
authentication.status | N | false | Enable SNMPv3 authentication |
authentication.protocol | N | 1 | Authentication protocol ID. See table below |
authentication.password | Y* | Authentication password; required when authentication.status is true and authentication.protocol is above 1 (NoAuth). Unused under NoAuth. Accepts plain text, ${ENV} references, or $secret{...} vault tokens | |
username | Y* | SNMPv3 username; required when authentication.status is true. Accepts plain text, ${ENV} references, or $secret{...} vault tokens |
* = Required when SNMPv3 authentication is enabled (authentication.status: true). authentication.password is required only when authentication.protocol is also above 1 (NoAuth)
A listener configured for SNMPv3 accepts only SNMPv3 traps; v1/v2c traps sent to it are dropped. A listener without SNMPv3 authentication drops SNMPv3 traps in turn, because it has no user to authenticate them with.
In earlier versions the listener accepted every trap on its port, whatever community it carried, and a listener configured for SNMPv3 also took v1/v2c traps. After an upgrade, two kinds of sender are no longer received: senders whose community does not match the configured one, and senders of v1/v2c traps to an SNMPv3 listener.
Dropped traps are counted. Director logs the first drop at once and then at most one line a minute, naming the source IP and the reason, never a community:
Dropped an SNMP trap from 10.0.0.15: its community does not match the configured one. Traps dropped so far: 12.
Dropped an SNMP trap from 10.0.0.15: its SNMP version does not match the listener's. Traps dropped so far: 3.
Authentication Protocols
| ID | Protocol | Description |
|---|---|---|
1 | NoAuth | No authentication |
2 | MD5 | HMAC-MD5-96 authentication |
3 | SHA | HMAC-SHA-96 authentication |
4 | SHA224 | HMAC-SHA-224 authentication |
5 | SHA256 | HMAC-SHA-256 authentication |
6 | SHA384 | HMAC-SHA-384 authentication |
7 | SHA512 | HMAC-SHA-512 authentication |
Privacy
| Field | Required | Default | Description |
|---|---|---|---|
privacy.protocol | N | 1 | Privacy protocol ID. See table below |
privacy.passphrase | Y* | Privacy passphrase; required when authentication.status is true, privacy.protocol is greater than 1, and authentication.protocol is above 1. Privacy applies only to a trap the device also authenticates. Accepts plain text, ${ENV} references, or $secret{...} vault tokens |
* = Required when authentication.status: true, privacy.protocol > 1, and authentication.protocol > 1
Privacy Protocols
| ID | Protocol | Description |
|---|---|---|
1 | NoPriv | No privacy |
2 | DES | DES privacy |
3 | AES | AES-128 privacy |
4 | AES192 | AES-192 privacy |
5 | AES256 | AES-256 privacy |
6 | AES192C | AES-192 with 3DES key padding |
7 | AES256C | AES-256 with 3DES key padding |
MIB Configuration
The SNMP trap receiver automatically loads and integrates Management Information Base (MIB) files for translating SNMP trap messages. MIB files are essential for proper interpretation of vendor-specific or custom SNMP traps.
MIB File Locations
The system looks for MIB files in two locations under <vm_root>:
User directory, i.e. <vm_root>\user\mibs\ (Windows) or <vm_root>/user/mibs/ (Unix): Primary location for custom MIB files. Supports nested directory structure. All user-specific MIB files should be placed here.
Package directory, i.e. <vm_root>\package\mibs\ (Windows) or <vm_root>/package/mibs/ (Unix): Contains default/standard MIB files. Bundled with the installation. Should not be modified directly.
Custom MIB files in the user directory take precedence over similarly named files in the package directory.
MIB Loading Process
The system will recursively scan both MIB directories, load all discovered MIB modules, automatically resolve MIB dependencies, and use loaded MIBs for trap translation.
If MIB loading fails, the system will still receive traps but may not translate vendor-specific OIDs correctly.
Advanced Configuration
To enhance performance and achieve better data handling, the following settings are used:
| Field | Required | Default | Description |
|---|---|---|---|
max_buffer_size | N | 128MB | Ingest buffer admission cap. Also sizes this listener's ingest buffers: 3/8 of this value at start, growing to at most 3x |
This device does not read reuse or workers. It receives traps on one UDP socket with one listener, whatever they are set to. When workers is set to anything other than 1, a Verbose log line says the configured count is set aside. Throughput is not tuned through workers here: received traps are written through the ingest stream's shards, whose count does not depend on it.
In Director versions before v2.4.0, a device whose workers resolved above 1 received no traps at all. That included every device left at the default on a Director with 8 or more CPUs, and any device configured with reuse: true and workers: 4. Such a device now receives traps on one listener, with no change to its configuration. A device created in the web interface sends workers: 1 with reuse off, so it runs one listener on those versions as well.
If the listener's ingest stream cannot be opened, the device stops and logs SNMPTrap stream initialization failed. Error: … instead of reporting connected with nothing listening. When the listener cannot bind its address, the Server is failed to accept requests. log line carries the underlying error, for example the port already being in use.
flush_interval and queue.interval are Director service-level settings configured in vmetric.yml and cannot be overridden per device. max_buffer_size is the exception: it has a service-level default that a device can override.
max_buffer_size is the ingest-buffer admission cap, and is distinct from any buffer_size field above, which sizes the network read buffer. Left unset it is 128MB, whose buffers take 48 MiB of heap per listener worker at start and grow to at most 384 MiB as bursts need the room — and with reuse: true a device runs one worker per listener. Size strings are binary, and 32MB and 32MiB are exact synonyms.
See Listener Memory Sizing for the arithmetic, the sizing table, and what happens when the cap is exhausted.
Examples
The following are commonly used configuration types.
Basic
Minimal SNMPv2c trap receiver with community authentication:
Creating a simple SNMPv2c trap receiver... | |
MIBs
SNMPv2c trap receiver with custom MIB file support:
Basic trap receiver with custom MIB support... | |
Place your custom MIB files in the <vm_root>/user/mibs/ directory before starting the trap receiver. The system will automatically load and use them for trap translation.
Secure
SNMPv3 with SHA-256 authentication and AES-256 privacy encryption:
When using SNMPv3 with privacy, ensure that both the authentication and privacy passwords meet the minimum length requirements for the selected protocols.
SNMPv3 with authentication and privacy... | |