SNMP traps

An SNMP trap is a message that is initiated by a network element and sent to the network management system. Often, traps indicate a failure of some sort, such as a router message indicating a power supply failure, or a printer message indicating an "out-of-ink" condition.

If an SNMP trap enters the system, and Collection Zone cannot identify the event (the event is classified as "/Unknown"), then you can classify the event so that the system handles it consistently.

Classifying SNMP traps

By default, most SNMP traps will appear in the /Unknown event class. To map them to a more meaningful event class, you can re-classify them with an event mapping.

To classify an SNMP trap event:

From the Event Console, select the unknown event or events.
Click the Reclassify an event icon. The Classify Events dialog appears.
Select /App, and then click Submit.

To edit this classification:

From the Navigation area, select Events > Event Classes.
Ensure Mapping Instances appears.
Select the event map you created.
In the left panel, select Edit from the Action icon.

The edit page appears. This page contains rules used to map the event to the /App category. This rule, since it matches the trap by a specific OID, is all that is needed.

In the Transform area, you can enter code to modify the summary. For example, if you want to set the summary string to Spam Filter Detects Virus, then you can enter:
```
evt.summary = "Spam Filter Detects Virus"
```
A trap has a header with some standard information, followed by a sequence of attribute/values.

You have indicated you want the value for the OID ".1.3.6.1.4.1.9789.1500.2.5" as the summary. If you had the MIB loaded, you could do this:
```
evt.summary = evt.spamFilterDetectsVirus
```
However, the OID and the data is still in there. Instead, use the slightly more cryptic:
```
evt.summary = getattr(evt, ".1.3.6.1.4.9789.1500.2.5", "Unexpected missing OID")
```
The "device" object for the event has been made available, as well:
```
evt.summary = getattr(evt, ".1.3.6.1.4.9789.1500.2.5", "Unexpected missing OID") + " from device " + device.getId()
```
Collection Zone uses MIBs to translate SNMP traps that contain raw OID values. Loading a MIB into the system allows it to translate numeric OIDs such as .1.3.6.1.2.1.1.6 into descriptive phrases like "sysLocation". It also makes it easier to manipulate the events in an event mapping.

Following is a small demonstration MIB.
```
NOTIFICATION-TEST-MIB DEFINITIONS ::= BEGIN 
IMPORTS 
ucdavis FROM UCD-SNMP-MIB 
NOTIFICATION-TYPE FROM SNMPv2-SMI 
; 
demonotifs OBJECT IDENTIFIER 
::= { ucdavis 991 } 
demo-notif NOTIFICATION-TYPE 
OBJECTS { sysLocation } 
STATUS current 
DESCRIPTION "Just a test notification" 
::= { demonotifs 17 } 
END
```

Receiving SNMP v3 traps

Zenoss Cloud can receive SNMP v3 traps from your devices, but there are some prerequisites:

The device sending the traps must be added as a monitored device
The zSnmpEngineId configuration property must be set to match the value from the device

To receive SNMP v3 traps for a device, follow these steps:

If you are not already monitoring the device, add it to an appropriate device class.
Set the zSnmpEngineId property for the device by either:
- Adding the zenoss.snmp.SnmpV3EngineIdMap modeler plugin to the device and remodeling.
- Setting the value manually. To get the engine ID from the device, consult the manufacturer's documentation.
Note

The zenoss.snmp.SnmpV3EngineIdMap modeler plugin only works for devices configured for SNMP v3 monitoring and that have no Engine ID already set.

Note

Each device with a configured zSnmpEngineId must have a unique value for this property. For virtual machine devices that are cloned from a template machine image, this may require changing the engineIDType value in the snmpd.conf configuration file. Please see the Net-SNMP documentation for more details.

Testing SNMP v3 traps

To confirm that your collector is capable of receiving SNMP v3 traps, you may wish to send a test trap and confirm its receipt and conversion into an event on your Event Console. You will need:

A Linux host, configured for monitoring via SNMP v3
Access to the command line of that host
To install the net-snmp and net-snmp-utils packages, if not already installed

The syntax for the snmptrap command takes the form of:

snmptrap -v3 -e {dev/zSnmpEngineId} -u {dev/zSnmpSecurityName} -l authPriv -a SHA -A {dev/zSnmpAuthPassword} -x AES -X {dev/zSnmpPrivPassword} $COLLECTOR_IP '' SNMPv2-MIB::sysORUpTime.1

After substituting the {dev/*} variables and the $COLLECTOR_IP, a test command might look like the following:

snmptrap -v3 -e 80001f88806f6c4959a3cc0c5f00000000 -u zenmonitor -l authPriv -a SHA -A authPass -x AES -X privPass 192.0.2.100 '' SNMPv2-MIB::sysORUpTime.1

Mapping SNMP variables to events

Some SNMP traps can include variables (varbind objects), which are ordered implicitly. The ordering requirement takes the form of Name.Number (for example, someVar.0) and in many cases there will be a series of varbind objects with different numbers on the same name. The following tables provide an example variable and varbind objects.

OID	Value
1.2.1.1.3.0	Message0
1.2.1.1.3.1	Message1

Assuming a MIB (imported into Collection Zone) specifies the name someVar (1.2.1.1.3) then the event details would be as follows:

Name	Value
someVar.0	Message0
someVar.1	Message1
someVar.sequence	0,1

The following tables illustrate how the implicit ordering is encoded in event details.

Example trap with an SNMP varbind object

OID	Value
1.3.6.1.2.1.2.2.1.1.143	143
1.3.6.1.2.1.2.2.1.7.143	1
1.3.6.1.2.1.2.2.1.8.143	1
1.3.6.1.2.1.2.2.1.2.143	"F23"
1.3.6.1.2.1.31.1.1.1.18.143	""

Event details for example trap

Name	Value
ifIndex.143	143
ifIndex.sequence	143
ifAdminStatus.143	1
ifAdminStatus.sequence	143
ifOperStatus.143	1
ifOperStatus.sequence	143
ifDescr.143	F23
ifDescr.sequence	143
ifAlias.143
ifAlias.sequence	143

The event details are repetitive, but an event transform can parse and process sequenced varbind objects.

For example, the following event transform concatenates the someVar parts into the event's summary attribute:

seq = getattr(evt, "someVar.sequence", None) 
if seq is not None:
    values = [] 
    for idx in str(seq).split(','):
        value = getattr(evt, "someVar." + idx, '')
        values.append(value)
    evt.summary = ' '.join(values)

SNMP trap filtering

The zentrap service supports SNMP trap filtering.

To edit your filters, navigate to the ADVANCED > Settings > Events page. The rules can be configured in the SNMP Trap Filtering Rules text entry field.

Filter syntax

The filter entry field contains an abbreviated version of the original zentrap.filter.conf file. You can view the full configuration file below.

zentrap.filter.conf

#
# SNMP Trap Filter Definitions
#
# This file defines optional filters which zentrap applies to incoming traps.
# The filters defined in this file are only applied if the 'trapFilterFile'
# parameter in zentrap.conf specifies this file, for example,
#       trapFilterFile zentrap.filter.conf
#
# Each line defines a single filter definition to either include or exclude
# a particular trap. Lines beginning with "#" and blank lines are ignored.
# The order of the definitions doesn't matter, but duplicates aren't allowed.
# The filtering logic matches each incoming trap to the most specific filter
# definition. It then either includes or excludes that trap based on the filter
# definition.
#
# If no valid filters are found, for instance, everything is commented
# out, then no traps are filtered.
#
# zentrap exits on the first syntax error, so check the zentrap log for
# details about the specific error.
#
# At a high level, the generic syntax for each filter definition is:
#      ACTION SNMP_VERSION MATCHING_RULE
# where:
#      ACTION        is the filter action; must be one of "include" or "exclude"
#      SNMP_VERSION  identifies the SNMP version; must be one of "v1" and "v2"
#      MATCHING_RULE is the matching rule for trap (varies by SNMP version)
#
# Valid definitions for SNMP V1 traps have one of the following formats:
#      include|exclude v1 TRAP_TYPE
#      include|exclude v1 GLOBBED_OID
#      include|exclude v1 OID *|SPECIFIC_TRAP
# where:
#     TRAP_TYPE       is a generic trap type in the range [0-5]
#     GLOBBED_OID     is an OID ending with ".*"
#     OID             is a valid OID
#     SPECIFIC_TRAP   is any specific trap type (any non-negative integer)
# Note that the last two cases are used for enterprise-specific traps, such as 
# where the generic trap type is 6.
#
# Valid filter definitions for SNMP V2 traps have one of the following formats:
#    include|exclude v2 OID
#    include|exclude v2 GLOBBED_OID
# where
#    OID             is an valid OID
#    GLOBBED_OID     is an OID ending with ".*"
#

# Include all generic SNMP V1 Traps 0-5
include v1 0
include v1 1
include v1 2
include v1 3
include v1 4
include v1 5

# Include all enterprise-specific SNMP V1 traps
include v1 *

# Include all SNMP V2 traps
include v2 *