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.

Note

The zentrap service supports SNMP trap filtering. For more information about enabling this feature, please contact Zenoss Support.

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:
1. From the Navigation area, select Events > Event Classes.
2. Ensure Mapping Instances appears.
3. Select the event map you created.
4. 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, ifyou 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:
- 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)