SNMP Traps

There are a few tasks you must complete before your server can receive SNMP traps:

You can configure SNMP traps to customize the types of information you receive and the conditions under which Horizon converts traps into an event. For example, you may want to see an event only when a device is down, or when a combination of criteria are met (for example, OID X with "major" severity level and status "indeterminate"). These traps are transformed into events only when the conditions you define are met.

There are several ways to configure Horizon to customize the events you receive and see:

Some events, especially SNMP traps, have additional information sent with them called "variable bindings" (varbinds). In the ciscoC3800SysAggregateStatusChange event listed above, there are four of them. You can use the parm replacement token to access them. Each parameter consists of a name and a value.

For example, the ciscoC3800SysAggregateStatusChange event description lists out each of the parameters. Thus the second parameter, the sysName, is printed using %parm[#2]%.

See Parameter tokens for more information.

Variable bindings (varbinds) are key-value pairs that provide alert data in SNMP traps. You can use varbinds as filters for further granularity on the conditions for creating an event through the mask block.

Using our previous ciscoC3800SysAggregateStatusChange example, what should its severity be? The event is generated whenever the status changes, but we don’t know if the change is "bad" (from operational to non-operational) or "good" (the non-operational status is cleared).

The parameters passed with the event contain that information, particularly parameter #3, the trap severity.

We rewrite our event as follows:

In the example, adding a mask with a varbind tag will match on the same ID, generic, and specific values, but also requires that the third parameter is equal to "3" (indicating a Cisco-determined trap severity of "major").

With a "status change" event, you may want to create separate events for each status value. To do this, copy the event definition once for each status value, add the varbind mask, and then change the UEI, description, severity, and logmsg to match the event.

You can also match more than one varbind and more than one value per varbind:

The above code snippet will match if the third parameter has a value of "2" or "3" and the fourth parameter has a value of "2" or "3".

You can also use a regular expression match on the varbind value. Just specify the expression prefixed with a with a "~":

This will match a varbind 1 that contains the word "Down" or "down" anywhere within its value. You can also do quick prefix matches with the '%' in a varbind value:

This will match varbind 1 with any String beginning with "Error:".

REMINDER: The order in which events are listed is very important. Put the most specific events first.

A lot of MIBs define specific variables to code the value of some OIDs. As an example, the SNMP agent returns a numerical value for the ifAdminStatus and ifOperStatus: 1 means Up and 2 means Down.

Because Horizon does not have a MIB parser, we usually put this map (between the numerical encoded value and its meaning) into the event description. Use the varbindsdecode element to convert the event varbind value into a decoded String.

With varbindsdecode, Horizon decodes the numerical value sent into trap varbinds to the corresponding String values, which then can be substituted into the logmsg.

For example, a Cisco HSRP status change trap (OID `.1.3.6.1.4.1.9.9.106.2, generic 6, and specific 1), which corresponds to the uei.opennms.org/vendor/Cisco/traps/cHsrpStateChange event.

The trap contains the following varbind: cHsrpGrpStandbyState, with possible values from 1 to 6:

The following is the original event definition:

The following example shows how to change the event definition so that the HSRP status is decoded and the literal definition is displayed inside the logmsg:

The first varbind into the trap (parm[#1]) is translated using the decode map. If the value of the first OID in this trap is 6, the the log message will be the following:

When octet Strings are translated into event parameters, Horizon first attempts to treat them as character encodings. If all bytes in the String are valid UTF-8 or ISO-8859-1 characters, the String is stored as these characters. If this is not possible, the value is encoded as a Base64 String.

When SNMP traps are forwarded through a proxy using SNMPv2c or SNMPv3, preserving the original source IP address is a challenge due to the lack of an agent-addr field in the TRAP-V2 PDU used in those protocol versions. RFC 3584 defines an optional varbind snmpTrapAddress (.1.3.6.1.6.3.18.1.3.0) that you can add to forwarded traps to convey the original source IP address.

To configure Horizon to honor snmpTrapAddress when present, set use-address-from-varbind="true" in the top-level element of ${OPENNMS_HOME}/etc/trapd-configuration.xml and restart Horizon.