SNMP Trap Mapping Reference
This page provides a reference for SNMP trap mapping configuration, parameter mapping options, and trap-related server configuration variables in NetXMS.
For procedures on configuring trap reception and creating mappings, see SNMP Traps.
Default Trap Mappings
NetXMS includes built-in mappings for standard SNMP traps:
| Trap OID | Trap Name | NetXMS Event |
|---|---|---|
|
coldStart |
SNMP_COLD_START |
|
warmStart |
SNMP_WARM_START |
|
linkDown |
SNMP_LINK_DOWN |
|
linkUp |
SNMP_LINK_UP |
|
authenticationFailure |
SNMP_AUTH_FAILURE |
|
egpNeighborLoss |
SNMP_EGP_NEIGHBOR_LOSS |
Parameter Mapping Fields
| Field | Description |
|---|---|
Description |
Human-readable label for the parameter |
Mapping type |
How to find the varbind: By object ID (OID) or By position radio buttons |
OID / Position |
The varbind OID (for by-OID mapping) or position number (for by-position mapping) |
Never convert value to hex string |
Checkbox that prevents automatic hexadecimal conversion for this parameter |
Mapping by OID
When mapping by OID, NetXMS searches through all varbinds in the trap PDU to find one whose OID matches the specified value. This is the recommended method because it works regardless of the order varbinds appear in the trap.
Mapping by Position
When mapping by position, NetXMS extracts the varbind at the specified position in the PDU. Position numbering starts at 1.
For SNMPv2c and SNMPv3, the first two varbinds in the PDU are sysUpTime.0 and the trap OID (snmpTrapOID.0).
These are automatically skipped — position 1 refers to the first user varbind after these two standard entries.
For SNMPv1 traps, position 1 maps directly to the first varbind.
|
Hexadecimal Conversion
By default, an OCTET STRING varbind value is converted to a hexadecimal string if it contains control bytes (codes below 0x1F, excluding CR and LF; a single trailing NUL is allowed). If the MIB defines a DISPLAY-HINT for the object, the hint takes precedence and the value is formatted accordingly.
To prevent automatic hex conversion for a specific parameter, enable the Never convert value to hex string option in the parameter mapping configuration.
To disable automatic hex conversion globally, set SNMP.Traps.AllowVarbindsConversion to 0.
Event Tag
The General page of the trap mapping configuration includes an Event tag field.
Its value is set as the tag of the generated event.
Event tags are expanded in message templates with the %E macro (%u is unrelated — it expands to the source object’s URL-compatible IP address).
From scripts, event tags can be modified with $event→addTag() and $event→removeTag().
Transformation Script Variables
Each trap mapping can have an optional NXSL transformation script with the following global variables:
| Variable | Description |
|---|---|
|
Trap OID as a string |
|
Array of SNMP varbind objects from the trap |
|
The event being generated; tags can be modified with |
|
Source node object; never null — trap mappings are evaluated only after the trap source has been matched to a node |
|
Source object |
|
Boolean, |
|
Related DCI object (set only when a DCI is present in the processing context) |
The script can modify event parameters, set event tags, or perform custom processing before the event is posted.
In the generated event, %1 is always the trap OID; mapped parameters start at %2.
The trap source port is appended as an additional parameter (sourcePort) after the mapped parameters.
Server Configuration Variables
| Variable | Default | Description |
|---|---|---|
|
1 |
Enable automatic hex conversion for OCTET STRING varbinds containing control bytes |
|
1 |
Enable SNMP trap processing (server restart required) |
|
162 |
UDP port for receiving SNMP traps (server restart required) |
|
0 |
Log traps received from addresses not belonging to any known node; controls logging only, never processing |
|
90 |
Number of days to keep trap log entries |
|
0 |
Process traps received from unmanaged nodes |
|
0 |
Number of traps per second that defines a trap flood condition (0 = detection disabled) |
|
15 |
Time period (seconds) during which the rate must stay above the threshold to declare a trap flood |
|
0 |
Search all zones when matching the trap source address to a node (server restart required) |
|
1 |
Generate the default event for traps that do not match any mapping |
|
1 |
Validate the community string (SNMPv1/v2c) or SNMPv3 user of incoming traps against the source node’s credentials; traps that fail validation are dropped. Can be overridden per node with the custom attribute |
Trap rate limiting operates per node.
When traps from a node exceed SNMP.Traps.RateLimit.Threshold per second for SNMP.Traps.RateLimit.Duration seconds, a SNMP_TRAP_FLOOD_DETECTED event is generated and all traps from that node are dropped while the flood condition is active.
When the rate drops back below the threshold, a SNMP_TRAP_FLOOD_ENDED event is generated and processing resumes.