SNMP Traps (xm_snmp)
This module provides support for parsing SNMP v1, v2c, and v3 trap messages. For SNMP v3, the user-based security model (USM) is supported, providing both authentication and encryption functionality. Instead of parsing log files or piping in input from snmptrapd, this module provides convenient and efficient trap variables easily accessible in NXLog fields. There is no need to manually parse the output of external tools, thus it provides a better all-in-one solution for SNMP trap reception.
| To examine the supported platforms, see the list of installer packages in the Available Modules chapter. |
Like the xm_syslog module, the xm_snmp module does not provide support for the network transport layer. Since traps are sent primarily over UDP (typically to port 162), the im_udp module should be used together with this module. This module registers an input reader function under the name "snmp" which can be used in the InputType directive to parse UDP message payloads.
The module supports MIB definitions in order to resolve OID numbers to
names. In addition to the standard xm_snmp module
fields and the im_udp module fields, each variable
in the trap message will be available as an internal NXLog
field. If the OID cannot be resolved to a name, the string OID. will
be prepended to the dotted OID number representation in the field
name. For example, if a trap contains a string variable with OID
1.3.6.1.4.1.311.1.13.1.9999.3.0, this field can be accessed as the
NXLog field $OID.1.3.6.1.4.1.311.1.13.1.9999.3.0. If the
object identifier can be resolved to a name called FIELDNAME, the
value will be available in the NXLog field
$SNMP.FIELDNAME. The SNMP trap variables are also put in the
$raw_event field and are listed as name="value" pairs there in the
order they appear in the trap. The following is an example of the
contents of the $raw_event field (line breaks added):
2011-12-15 18:10:35 192.1.1.114 INFO \
OID.1.3.6.1.4.1.311.1.13.1.9999.1.0="test msg" \
OID.1.3.6.1.4.1.311.1.13.1.9999.2.0="Administrator" \
OID.1.3.6.1.4.1.311.1.13.1.9999.3.0="WIN-OUNNPISDHIG" \
OID.1.3.6.1.4.1.311.1.13.1.9999.4.0="1" \
OID.1.3.6.1.4.1.311.1.13.1.9999.5.0="0" \
OID.1.3.6.1.4.1.311.1.13.1.9999.6.0="test msg"| To convert the output to Syslog format, consider using one of the to_syslog() procedures provided by the xm_syslog module. However, note that the resulting format will not be in accordance with RFC 5675. |
Microsoft Windows can convert and forward EventLog messages as SNMPv1 traps. The evntwin utility can be used to configure which events are sent as traps. See How to Generate SNMP traps from Windows Events for more information about setting up this feature.
The Net-SNMP toolkit (available for Unix/Linux and Windows) provides the snmptrap command line utility which can be used for sending test SNMP traps. Create the following MIB definition file and put it in a directory specified by the MIBDir directive:
TRAP-TEST-MIB DEFINITIONS ::= BEGIN
IMPORTS ucdExperimental FROM UCD-SNMP-MIB;
demotraps OBJECT IDENTIFIER ::= { ucdExperimental 990 }
demo-trap TRAP-TYPE
STATUS current
ENTERPRISE demotraps
VARIABLES { sysLocation }
DESCRIPTION "This is just a demo"
::= 17
ENDHere is an example for invoking the snmptrap utility (line break added):
snmptrap -v 1 -c public localhost TRAP-TEST-MIB::demotraps \
"" 6 17 "" sysLocation s "Test message"The received trap should look like this in the $raw_event field:
2011-12-15 18:21:46 192.168.168.2 INFO SNMP.sysLocation="Test message"If the MIB definition can not be loaded or parsed, the unresolved OID number will be seen in the message:
2011-12-15 19:43:54 192.168.168.2 INFO OID.1.3.6.1.2.1.1.6="Test message"Configuration
The xm_snmp module accepts the following directives in addition to the common module directives.
- AllowAuthenticatedOnly
-
This boolean directive specifies whether only authenticated SNMP v3 traps should be accepted. If set to TRUE, the User block must also be defined, and unauthenticated SNMP traps are not accepted. The default is FALSE: all SNMP traps are accepted.
- MIBDir
-
This optional directive can be used to define a directory which contains MIB definition files. Multiple MIBDir directives can be specified.
- User
-
This directive is specified as a block (see Parsing authenticated and encrypted SNMP traps) and provides the authentication details for an SNMP v3 user. The block must be named with the corresponding user. This block can be specified more than once to provide authentication details for multiple users.
- AuthPasswd
-
This required directive specifies the authentication password.
- AuthProto
-
This optional directive specifies the authentication protocol to use. Supported values are
md5andsha1. If this directive is not specified, the default ismd5. - EncryptPasswd
-
This directive specifies the encryption password to use for encrypted traps.
- EncryptProto
-
This optional directive specifies the encryption protocol to use. Supported values are
desandaes. The default, if encryption is in use and this directive is not specified, isdes.
Fields
The following fields are used by xm_snmp.
$raw_event(type: string)-
A list of event fields in key-value pairs.
$EventTime(type: datetime)-
The reception time of the trap.
$Severity(type: string)-
The severity name: `INFO` (there is no severity in SNMP traps).
$SeverityValue(type: integer)-
The INFO severity level value: `2` (because there is no severity in SNMP traps).
$SNMP.CommunityString(type: string)-
The community string within the SNMP message.
$SNMP.MessageSourceAddress(type: string)-
The IP address of the sender as provided in the trap message. Note that there is a xref:im:udp.adoc#messagesourceaddress[$MessageSourceAddress] field set by the xref:im:udp.adoc[im_udp] module. Available in SNMP v1 only.
$SNMP.RequestID(type: integer)-
An integer associating the SNMP response with a particular SNMP request.
$SNMP.TrapCodeGeneric(type: integer)-
Indicates one of a number of generic trap types. Available in SNMP v1 only.
$SNMP.TrapCodeSpecific(type: integer)-
A code value indicating an implementation-specific trap type. Available in SNMP v1 only.
$SNMP.TrapName(type: string)-
The resolved name of the object identifier in <<snmp-trapoid,SNMP.TrapOID>>. The field will be unset if the OID cannot be resolved. Available in SNMP v1 only.
$SNMP.TrapNameGeneric(type: string)-
The textual representation of <<snmp-trapcodegeneric,SNMP.TrapCodeGeneric>>, one of: `coldStart(0)`, `warmStart(1)`, `linkDown(2)`, `linkUp(3)`, `authenticationFailure(4)`, `egpNeighborLoss(5)`, or `enterpriseSpecific(6)`. Available in SNMP v1 only.
$SNMP.TrapOID(type: string)-
The object identifier of the TRAP message. Available in SNMP v1 only.
$sysUptime(type: integer)-
The amount of time that has elapsed between the last network reinitialization and generation of the trap. This name is chosen in accordance with RFC 5424. Available in SNMP v1 only.
Examples
The InputType snmp directive in the im_udp module block is required to parse the SNMP payload in the UDP message.
<Extension snmp>
Module xm_snmp
MIBDir /usr/share/mibs/iana
MIBDir /usr/share/mibs/ietf
MIBDir /usr/share/mibs/site
</Extension>
<Input udp>
Module im_udp
ListenAddr 0.0.0.0:162
InputType snmp
</Input>This configuration parses SNMP v3 traps.
Only authenticated traps are parsed; a warning is printed for each non-authenticated source that sends a trap.
The User block provides authentication and encryption settings for the switch1 user.
<Extension snmp>
Module xm_snmp
MIBDir /usr/share/mibs/iana
MIBDir /usr/share/mibs/ietf
AllowAuthenticatedOnly TRUE
<User switch1>
AuthPasswd secret
AuthProto sha1
EncryptPasswd secret
EncryptProto aes
</User>
</Extension>
<Input udp>
Module im_udp
Host 0.0.0.0
Port 162
InputType snmp
</Input>
