SNMP Trapmon Plug-in - Technical Reference

Introduction

The Geneos Trapmon plug-in 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 plug-in, 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 plug-in supports SNMP versions 1 to 3. However, SNMP version 3 is not supported on Windows.

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.

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.

Mandatory: No
Default: TRAPS

translateGenericType

This setting indicates if the genericType in the trap dataview should be translated to human-readable text (instead of numbers) according to descriptions specified in RFC 1157.

Mandatory: No

mibFiles

Additional MIB definitions that the plug-in should load before running.

Mandatory: No

customViews

Dataviews to display incoming traps meeting certain user configured criteria.

Mandatory: No

customViews > regexView > regexGroup

Criteria which incoming traps must match to be displayed in the custom view. Specified as a set of matchers, all of which must match for the trap to be displayed.

Mandatory: Yes

customViews > regexView > clearTrapRules

Rules that will automatically remove existing traps from the custom view when given new traps arrive.

Mandatory: No

customViews > regexView > clearTrapRules > incomingMatches

Criteria which incoming traps must match to trigger the clearing rule. Specified as a set of matchers. An incoming trap must match all of the criteria defined to trigger the rule.

Mandatory: Yes

customViews > regexView > clearTrapRules > clearMatchGroups

Specifies which existing traps to remove if this clearing rule is fired.

Mandatory: Yes

customViews > regexView > clearTrapRules > clearMatchGroups > clearMatchGroup

Criteria that will be used to select which existing traps to remove if this clearing rule is fired. If a trap matches any of the clearMatches specified in the configuration it will be removed.

Mandatory: Yes

customViews > regexView > clearTrapRules > clearMatchGroups > clearMatchGroup > clearMatch

Criteria that will be used to select which existing traps to remove if this clearing rule is fired. Checks each trap against a matcher or by comparing values in a given column with the incoming trap.

If a trap matches all of the matchers and specific vaalues in this part of the configuration it will be removed.

Mandatory: Yes

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

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

Mandatory: No

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

Specific trap variable. If the trap being tested for removal has the same value for this variable as the incoming trap, then it will be removed when the rule fires.

Mandatory: No

customViews > regexView > displayColumns

Specifies which trap variables to display as columns in the dataview.

Mandatory: No
Default: Display columns for all incoming variables (up to 20 new variables)

customViews > regexView > displayColumns > showColumns

A list of trap variable names whose values will be displayed in the dataview.

Note: No other trap variables will be displayed in the dataview with this setting.

Mandatory: No

customViews > regexView > displayColumns > hideColumns

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