SNMP Trapmon Plug-in - Technical Reference

Introduction

The Geneos Trapmon plugin allows the monitoring of Simple Network Management Protocol (SNMP) Trap traffic via Geneos. The plug-in provides two modes of operation. The first pushes the messages to a Geneos stream that can be monitored using the File Keyword Monitor (FKM) plug-in in the same way as a regular file. The second displays incoming traps that match user-specified criteria.

In Trapmon plugin, net-snmp writes trap information or debug to standard error (stderr).

Note: The remote devices being monitored must have traps enabled and be configured to send the traps to the host where the Netprobe with the Trapmon plug-in is running.

The Trapmon plugin supports SNMP versions 1 and 2c in both Windows and Linux.

On Windows Netprobe, this plugin does not support the new MIB files, Custom View, and Clear Trap command features.

For more information, see 5.x Compatibility Matrix.

Functionality Overview

In all modes, the plug-in listens for SNMP traps sent to the host on which the netprobe is running. Further processing is then performed in one of the following modes:

Geneos Streams Mode

snmp-trapmon0

In this mode, incoming traps are pushed onto a named Geneos stream and sent to the FKM plug-in. The stream of incoming traps can then be used as any other FKM file by configuring the plug-in with a file with the same name as the trapmon stream and the deliveryType set to STREAM.

Custom Views Mode

snmp-trapmon1

In this mode, incoming traps are tested against a series of matchers and displayed in dataviews published by the plug-in if they match successfully. Each dataview and the corresponding matchers are configured by the user to match information within the incoming traps. A row is displayed in the dataview for each incoming trap.

Clearing Traps

Once a trap is displayed in the plug-in, it can be dismissed from the dataview by right clicking and using the Clear Traps command.

It is also possible to specify Custom Clearing Commands. A variable name is specified in the configuration and when the command is run on an existing trap, all traps that have been received with the same value in the column specified by the variable will be cleared.

Finally, each view can have Automatic Clearing Rules defined. These rules clear traps matching certain criteria when certain traps arrive. For example, a trap that is sent out to indicate a failure could be automatically cleared by a trap sent out indicating that service has resumed.

Views

Diagnostic View

snmp-trapmon3

Headline Legend

Name	Description
streamName	The name of the Geneos stream down which the plug-in pushes incoming traps. This name can then be used with the FKM plug-in.

Table Legend

Name	Description
tmLastRecv	The time at which the last trap was received.
totalTrapsRecv	Total number of traps received since starting the plug-in.

Custom Views

In addition to the standard diagnostic view, additional views can be configured that show incoming traps matching user specified criteria. Each row corresponds to a trap received and displays a column for all the variable bindings contained within the trap as well as columns for metadata about the trap itself. A number of these columns are displayed by default. Unwanted default columns can be hidden using the Active Console hide column feature. In addition, columns created by variable bindings in traps can be hidden or always shown in the plug-in configuration.

Repeated occurrences of the same trap increment the count column of the view.

The plug-in filters incoming traps and only displays those matching those matching the specified Matchers: a pair of Column Name and a regular expression for the value of the variable. The Column Name may be one of the following:

a trap variable
arrivalTime
genericType
specificType
source
version
community
oid

In the screenshot below, the view has been configured to display traps where the SMI::enterprises_1824_1_0_0_1 variable begins with the string TRAP using the regular expression TRAP.*.

snmp-trapmon4

Default Columns

Name	Description
UID	Unique identifier for each incoming trap
arrivalTime	Arrival time of the last occurrence of the trap This column shows the latest arrival time if a trap is repeatedly received.
count	Number of times this trap has been received.
genericType	SNMP generic type for this trap.
specificType	SNMP specific type for this trap. This field displays `N/A` for SNMPv2 traps whose specific type cannot be determined from the Trap OID, e.g. generic (predefined) traps.
source	Source from where the trap originated. For Windows platforms, this is the source IP address.
version	SNMP version for this trap.
community	SNMP community for this trap.
oid	For SNMPv1 traps, this column shows the Enterprise OID. For SNMPv2 traps, this column shows the Trap OID.
uptime	Uptime of the source from where the trap originated

In addition, there will be columns displaying the variable bindings for each incoming trap.

In the case of the screenshot above, the plug-in is following the default behaviour and displaying a column for each variable of the incoming traps. In this case, the traps had the SNMPv2-SMI::enterprises_1824_1_0_0_1 and SNMPv2-SMI::enterprises_1824_1_0_0_2 variables set.

If the incoming traps provide a number of unwanted variables in addition to those in which the user is interested, the plug-in configuration can be set to display a static set of columns or hide specific columns from the dataview.

To prevent too many columns being created and swamping the dataview, the maximum number of additional columns is set to 20 and can be adjusted in the configuration.

Similarly, the maximum number of traps that will be displayed in a single dataview is set to 1000 and can be adjusted in the configuration.

Custom traps can also be grouped according to specified columns. This is intended for multiple traps with trap variables using some sort of index. This groups several trap variables into one column using the specified pattern, instead of creating additional trap variable columns.

For example, if two traps with the following variables are sent:

Trap 1: IF-MIB::ifAdminStatus.12 = INTEGER: down(2)
Trap 2: IF-MIB::ifAdminStatus.14 = INTEGER: up(1)

Instead of creating a new column for IF-MIB::ifAdminStatus_14, the second trap can reuse the same trap variable column as the first trap by specifying a column group "IF-MIB::ifAdminStatus". The two trap variables are differentiated in the column value row by the value after the "IF-MIB::ifAdminStatus":

snmp-trapmon5

This functionality is intended for multiple traps with a common OID pattern and if addition of similarly patterned trap variable columns isn't needed.

Multiple column groupings can be specified (duplicate column groupings are ignored). If a trap variable falls under two or more groups, then the trap variable only appears under the more generic column group.

Note: The values displayed on the dataview for trap variables is similar to the output value of snmpget command with "-O q" parameter. The format of the timeticks data type is DD:HH:MM:SS.SS, where DD is the number of days, HH is the number of hours, MM is the number of minutes, SS.SS is the number of seconds.

Menu Options

The Clear Trap command allows for a specific trap to be removed from a custom view by right clicking on the row for that trap.

Additionally, custom Clear Trap Commands can be defined in the user configuration. These then add additional clearing commands to the right click menu that clear other traps with the same values for the variable specified in the configuration.

For example: define a Clear Trap Command called test_clear with the column name SNMPv2-SMI::enterprises_1824_1_0_0_2. After receiving 3 traps, the dataview would look as below:

Right-clicking on the first row and choosing Trap Monitor > test_clear from the context menu removes the first and third rows, as they both have TRAPA2 in the appropriate column.

Outside Netprobe Configuration

If you have MIB definitions stored in a non-standard location, the MIBDIRS environment variable must be set to point to the custom location.

This allows the Trapmon plug-in to find the MIB files which contain the type and description of the MIB variables. Setting this environment variable to the correct value ensures that this translates the trap variable into its textual form.

You may have to run the Netprobe as the root user when using the standard port on Linux.

To use all possible MIB files, set it to ALL in the environment variable:

export MIBS=ALL

Matchers

Key to the configuration is the concept of a matcher. This is a combination of a variable name and a regular expression and is applied to incoming and existing traps in a number of locations within the plug-in to control behaviour.

For example, a matcher defined as:

Variable A: Value.*

would successfully match an incoming trap with the following variable binding:

Variable A: Value A

Matchers are configured as follows:

Column Name

The name of the variable to test. Corresponds to a column in the plug-in dataview.

Mandatory: Yes

Pattern

Perl Compatible Regular Expression which is applied to the value of the given variable when matching.

Plug-in Configuration

Caution: When you update the configuration of a Trapmon sampler, the Netprobe running it has to restart in order to properly clean up the SNMP daemon thread. Be aware of other potentially unrelated plug-ins that can be affected when you configure this particular plug-in.

The following parameters can be configured for this plug-in:

port

This setting specifies the UDP port that SNMP traps are received on. (This setting is ignored on the Windows netprobe).

Mandatory: No

Default: 162

streamName

The name of the Geneos stream produced by this plug-in. This stream is referenced by the FKM plug-in in the file list configuration.

customViews > regexView > clearTrapRules > clearMatchGroups > clearMatchGroup > clearMatch > match > regex

Matchers that must match for a trap to be removed when the rule fires.

Mandatory: No

A list of trap variables whose values will not be displayed in the dataview.

Mandatory: No

customViews > regexView > displayColumns > hideColumns > maxAdditionalColumns

The maximum number of new incoming trap variables for which to add columns.

Mandatory: No

Default: 20

customViews > regexView > columnGroups

A list of trap variable names to use for column groupings.

Mandatory: No

customViews > regexView > columnGroups > columnGroup

The trap variable name to use for a column grouping.

Mandatory: No

customViews > regexView > maxRows

The maximum number of traps to display in the dataview.

Mandatory: No

Default: 1000

clearTrapCommands

Custom commands to clear other traps based on the value of a variable in a given trap.

Mandatory: No

clearTrapCommands > clearTrapCommand > customPattern > columnName

The name of the trap variables to test. The value for this variable of the target of the command will be compared against the values in the other traps in the system and if they match they will be removed.

Mandatory: Yes