SNMP Traps
SNMP traps are unsolicited notifications sent by network devices to inform the management system about significant events such as link failures, threshold crossings, authentication failures, and hardware problems. NetXMS receives, processes, and maps SNMP traps to its event system.
Overview
The SNMP trap processing pipeline in NetXMS:
-
Device sends an SNMP trap to the NetXMS server on UDP port 162
-
Server receives and decodes the trap
-
Server matches the trap to a node object based on the source IP address
-
Trap is matched against the trap mapping table to generate a NetXMS event
-
The generated event is processed by the Event Processing Policy
Trap decoding does not require MIB files — trap OIDs are recorded in numeric form.
Loaded MIBs are used only for DISPLAY-HINT formatting of varbind values when varbind conversion is enabled (see SNMP.Traps.AllowVarbindsConversion).
Traps whose source address does not match any known node are discarded, unless the SNMP.Traps.LogAll server configuration variable is enabled.
Trap Reception Configuration
Listening Port
By default, NetXMS listens for SNMP traps on UDP port 162. This can be changed with the server configuration variable:
| Variable | Default | Description |
|---|---|---|
|
162 |
UDP port for receiving SNMP traps. Changing this variable requires a server restart. |
On Linux, binding to port 162 requires root privileges or the CAP_NET_BIND_SERVICE capability.
|
Trap Source Address
When processing a received trap, NetXMS resolves the source IP address to an existing node object.
Traps from addresses that do not match any known node are discarded; enable the SNMP.Traps.LogAll server configuration variable to write such traps to the trap log anyway.
The source address of a received trap can also be used as a network discovery source (see Network Discovery).
SNMP v3 Trap Credentials
SNMPv3 traps are decoded using the credentials of the node they originate from — the security settings configured on the node’s SNMP property page.
If a device sends traps with credentials different from those used for polling, enable Use separate credentials for SNMP trap reception on the node’s SNMP property page and configure the trap credentials there.
The global USM credential list is not used for trap reception.
Per-node trap credentials can also be managed from NXSL scripts using the Node class methods setSNMPTrapCommunity(), setSNMPTrapUSMCredentials(), and clearSNMPTrapCredentials().
Trap Credential Validation
By default, the server validates the credentials of incoming traps: the community string or USM credentials of a trap must match the credentials configured on the source node (the polling credentials, or the separate trap credentials if configured).
Traps that fail validation are dropped, and the SYS_SNMP_TRAP_AUTH_FAILURE event is generated (rate-limited to one event per 24 hours per node).
Validation is skipped when the source node is unknown.
Validation is controlled globally by the SNMP.Traps.ValidateCredentials server configuration variable and can be overridden per node with the SysConfig:SNMP.Traps.ValidateCredentials custom attribute.
| SNMPv3 traps with authentication or privacy are decoded using the node’s keys before this check, so if the keys do not match, the trap is dropped regardless of the validation setting. |
Trap Mapping
Trap mapping defines how incoming SNMP traps are converted to NetXMS events. Each mapping rule matches a specific trap OID and generates a corresponding event.
For default trap mappings, parameter mapping fields, and all trap-related configuration variables, see SNMP Trap Mapping Reference.
Creating Custom Trap Mappings
To map a vendor-specific trap to a NetXMS event:
-
Go to Configuration > SNMP traps
-
Click New…
-
Configure the mapping:
-
Trap OID — the enterprise-specific trap OID (from vendor MIB)
-
Event — the NetXMS event to generate (create a custom event first if needed)
-
Description — human-readable description of the trap
-
-
Define parameter mappings to pass trap variable bindings (varbinds) as event parameters
Trap Parameter Mapping
SNMP traps carry variable bindings (varbinds) containing additional data about the event. These varbinds can be mapped to NetXMS event parameters.
The trap OID itself is always passed as the first event parameter ($1).
Mapped varbinds become parameters $2, $3, $4, and so on.
For parameter mapping fields, OID vs position mapping, hexadecimal conversion, user tags, and transformation scripts, see SNMP Trap Mapping Reference.
Trap Processing Rules
Matching by OID Prefix
Trap mappings can match exact OIDs or OID prefixes. Prefix matching is useful for enterprise traps where the specific trap is encoded in the last OID component.
Mapping Selection
Multiple mappings can exist. When a trap arrives, NetXMS first looks for a mapping whose OID exactly matches the trap OID. If there is no exact match, the mapping with the longest matching OID prefix is used. The order of mappings in the list is irrelevant.
If no mapping matches, no specific event is generated for the trap; instead, the server can generate the SNMP_UNMATCHED_TRAP event when the SNMP.Traps.UnmatchedTrapEvent server configuration variable is set to 1.
Trap Log
NetXMS maintains a trap log that records received SNMP traps.
Trap Processing Configuration Variables
Additional server configuration variables controlling trap processing:
| Variable | Description |
|---|---|
|
When enabled, OCTET STRING varbind values are formatted according to the DISPLAY-HINT from the MIB if one is provided; values containing non-printable characters are rendered as hexadecimal strings |
|
Master switch for SNMP trap processing (enabled by default). Changing this variable requires a server restart. |
|
Log all received traps, including traps from addresses that do not match any known node |
|
Process traps from nodes in unmanaged state |
|
Number of traps per second from a single node that activates flood protection (0 = disabled). Traps from a flooding node are dropped. |
|
Number of consecutive seconds the trap rate must stay above the threshold before flood protection activates |
|
Search for the trap source node in all zones, not only in the zone the trap was received in |
|
Generate the |
|
Validate community strings and USM credentials of incoming traps against the source node’s configured credentials; traps that fail validation are dropped (see Trap Credential Validation above) |
SNMP Trap Proxy
When SNMP devices send traps to a network where the NetXMS server is not directly reachable, you can configure a NetXMS agent to act as an SNMP trap proxy. The agent receives traps from devices and forwards them to the server.
Agent Configuration
Enable the SNMP trap proxy on the agent. See Trap Proxy Agent Parameters for the full list of agent configuration parameters.
Example agent configuration:
EnableSNMPTrapProxy = yes
SNMPTrapListenAddress = *
SNMPTrapPort = 162
On Linux, binding to port 162 requires root privileges or the CAP_NET_BIND_SERVICE capability.
|
Server Configuration
No per-node configuration is required on the server side — trap proxying is enabled entirely on the agent with EnableSNMPTrapProxy.
The agent forwards received traps to the server, which processes them as if they had arrived directly.
By default, traps are accepted only from known nodes.
To log traps from any source, set the SNMP.Traps.LogAll server configuration variable to 1.
Troubleshooting
No Traps Received
-
Verify the server is listening on port 162: check the server log at startup for the SNMP trap receiver initialization message
-
Verify firewall rules allow UDP port 162 inbound
-
On Linux, ensure the server process has permission to bind to port 162
-
Check that the device is configured to send traps to the NetXMS server’s IP address
Traps Received but Not Matched to Node
-
Verify the source IP address of the trap matches a node in NetXMS
-
Some devices send traps from a management interface IP that differs from the node’s primary address — the server matches the trap source against the node’s primary IP address and then against its interface addresses, so make sure an interface with the sending address exists on the node