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 Agent 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 installation packages.

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 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 Agent 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 Agent 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 Agent 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:

MIB Definition File

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

END

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

Optional 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 that 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 md5 and sha1. If this directive is not specified, the default is md5.

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 des and aes. The default, if encryption is in use and this directive is not specified, is des.

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: ipaddr): The IP address of the sender as provided in the trap message. Note that there is a $MessageSourceAddress field set by the 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. 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, 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

Example 1. Using MIB definitions to parse SNMP traps

The InputType snmp directive in the im_udp module block is required to parse the SNMP payload in the UDP message.

nxlog.conf

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

Example 2. Parsing authenticated and encrypted SNMP traps

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.

nxlog.conf

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