SNMP Trap

Synopsis

Creates a receiver that listens for SNMP trap messages. Supports 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>
    reuse: <boolean>
    workers: <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 SNMPv2c authentication

* = Required for SNMPv2c. Not used when SNMPv3 authentication is configured.

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
username	Y*		SNMPv3 username; required when authentication.status is true

* = Required when SNMPv3 authentication is enabled (authentication.status: true)

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 privacy.protocol is greater than 1

* = Required when privacy.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.

note

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.

warning

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
reuse	N	false	Enable socket address reuse
workers	N	CPU count	Number of worker processes when reuse is enabled. Capped at the number of physical cores.

note

flush_interval and queue.interval are Director service-level settings configured in vmetric.yml and cannot be overridden per device.

Examples

The following are commonly used configuration types.

Basic

Minimal SNMPv2c trap receiver with community authentication:

Creating a simple SNMPv2c trap receiver...

devices: - id: 1 name: basic_trap type: snmptrap properties: port: 162 community: "public"

MIBs

SNMPv2c trap receiver with custom MIB file support:

Basic trap receiver with custom MIB support...

devices: - id: 5 name: mib_enabled_trap type: snmptrap description: "Trap receiver with custom MIB support" properties: port: 162 community: "public"

note

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:

caution

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...

devices: - id: 2 name: secure_trap type: snmptrap properties: port: 162 authentication: status: true protocol: 5 password: "${SNMP_AUTH_PASS}" privacy: protocol: 5 passphrase: "${SNMP_PRIV_PASS}" username: "trapuser"

High-Volume

Optimizing for high trap volumes using multiple workers and SNMPv3 authentication...

devices: - id: 3 name: performant_trap type: snmptrap properties: port: 162 reuse: true workers: 4 authentication: status: true protocol: 3 password: "${SNMP_AUTH_PASS}" username: "trapuser"