	Trap Receiver
	Html Help File

[ Overview ] [ User Interface ] [ Configuration ] [ Glossary ]

Preface

This document contains the basic functional specifications and configuration information for Trap Receiver, Version 5.00 from Network Computing Technologies. It describes the software’s capabilities, features, active fields, and actions. Also included is a Glossary of Terms.

The intended audience of this handbook is the operators of the Trap Receiver. It is assumed that the operator has some knowledge of Simple Network Management Protocol (SNMP) and is responsible for implementing and configuring the system.

Trap Receiver, the Trap Receiver logo, and the Network Computing Technologies logo are trademarks of Network Computing Technologies.

Overview

Trap Receiver captures, displays, and logs Simple Network Management Protocol (SNMP) Traps. Trap Receiver allows the instantaneous viewing of alert notifications from any network device that supports SNMP.

Trap Receiver performs raw decoding off the wire. There is no dependency on the snmptrap service. Trap Receiver supports full decoding and archiving of SNMP V1 and V2 traps, and SNMPv2 INFORMS (with auto response generation). Each trap is decoded and the data is presented in a typical GUI window. Complete trap logging details can be found in the "Trap Details and Logging" section.

Trap Receiver allows the operator to define a watch; an SNMP field, a trigger value, and the action or actions to be taken. Trap Receiver enables the following fields to be watched:

	Community String
	Generic Trap Type
	Sender IP Address
	Sender Object ID
	Specific Trap Type
	Varbind Object ID
	Varbind Value

When a trap is received that contains the specified field with matching value, an action is then performed. The following actions may be taken:

	Explode the trap to multiple destinations.
	Execute a program.
	Generate an e-mail message.
	Discard the trap.

Trap Receiver is composed of two parts: 1) the service that handles trap receiving, watch matching, action executing, and logging and 2) the GUI that allows a graphical viewing of the incoming traps and a GUI for configuring everything.

The following sections describe the configuration of Trap Receiver. All features are explained and value ranges are described. Any bugs discovered may be reported to the following e-mail address: trbugs@ncomtech.com.

User Interface

The main window shows three pieces of information: The source of the traps (a UDP port number or SNMPTRAP Service), the total traps received, and a list of those traps. The list of traps highlights the Sender, the general message of the trap (i.e., linkDown), and a timestamp of when the trap was received. The "Ack" field is provided as a convenience when investigating trap related troubles.

Traps listed in this main window can be deleted by first selecting (highlighting) the trap to be deleted, then right-clicking anywhere in the list. Right-clicking pops up a menu with two options; to delete the selected trap or delete all traps. The "delete this trap" option will be grayed out if not trap is selected. Both options will be grayed out if there are no traps in the list.

To generate a detailed display of only one particular trap, double click the trap in the main trap display screen (see figure below).

Configuration

On the Trap Receiver main screen, in the lower right corner, click the configuration button.

The following sections describe the tabs found in the configuration's main dialog window.

Actions

On the Actions tab, click the Add button (or if one has already been added, either double-click it or select it and then press the modify button. The Watch pull-down menu lists the fields that may be watched. After choosing the field to watch, fill in the Equals box with appropriate parameters (described below) then choose the Action(s) to be triggered by a match on the field. For more information on actions, see the section below.

A community name denotes a particular group of stations with the same access permission. A community string acts as a password for SNMP.

To set Trap Receiver to look for a particular string, fill in the Equals box with the required value. Any input is accepted including characters such as !@#$%^&*()1234567890-=_+,./;'[]\<>?:"{}|`~

The Generic Trap Type can be any of the following seven categories: Cold Start (0), Warm Start (1), Link Down (2), Link Up (3), Authentication Failure (4), EGP Neighbor Loss (5), or Enterprise Specific (6). Fill in the Equals box with the numeric value of the generic trap type.

The SenderIP can be the IP address of the sender. For V1 Traps, this information comes from data encoded in the trap. For V2 traps, this information comes from the networking layer of the operating system. Fill in the Equals box with an IP address in decimal dot notation. (For example: 192.1.12.123)

The Specific Type is used to further refine the trap information when the Generic Type is set to Enterprise Specific (6). This data can be acquired from the MIB where the trap is defined. Fill in the Equals box with any integer as defined by structure of management information (SMI), 0 plus or minus 2 billion (actually 2,147,483,648).

The Sender Object ID (OID) represents a Management Information Base (MIB) object. For Sender OIDs, the objects are TRAP-TYPE or NOTIFICATION-TYPE macros in ASN.1. These MIB objects are organized in a tree fashion. Each digit (known as a sub-identifier) in the OID represents a branch and the final digit represents a specific object in that branch known as an instance. OIDs are also represented in decimal dot notation. An example is: 1.3.6.1.4.1.2854.1

Hence, the object type, x, would be 1.3.6.1.2.1.1.1 to which is appended an instance sub-identifier of 0. That is, 1.3.6.1.2.1.1.1.0 identifies the one and only instance of sysDescr. To configure the Sender OID, fill in the Equals box in decimal dot notation.

The Varbind OIDs represent a MIB object as well. To configure the Varbind OID, fill in the Equals box in decimal dot notation.

The Varbind Value selections allows you to monitor incoming traps that contain a particular MIB variable and compare that value to some constant. For example, if your Server generates a trap when CPU utilization reaches 50 percent and again when it reaches 75%, then you can watch for a trap that contains that MIB variable (let's say it is 1.3.6.1.4.1.311.23.4.7.0) and generate an email when the value is 50. You can then set up another watch, watching for the same MIB variable, but with a value of 75 and execute a program in addition to generating an email (typical escalation procedure). After specifying the watch as Varbind Value, populate the equals box with the MIB variable, value, and condition formatted as <MIB Variable's OID>:<value>:[<condition>]. If no condition is specified, it defaults to ">" or greater than. So for our example (CPU at 50%), the we would type in the equals box: "1.3.6.1.4.1.311.23.4.7.0:50:=", without the quotes of course. Valid conditions are "=", ">", "<", "!=", ">=" or "<=" representing "equal to", "greater than", "less than", "not equal to", "greater than or equal to", and "less than or equal to" respectively.

After choosing the field to watch and setting the appropriate match parameter for the field, choose the Action that is triggered by a match on the field. The available actions are:

Explode the trap to one or more destinations
Execute an external program
Generate an email message
Discard

The discard action causes the trap to be dropped from all further processing including watches, logging, and being displayed in the GUI.

A trap may be configured to explode to multiple destinations as configured through the Configure Exploders tab (note: exploders must be configured before checking this box, see the Exploders section below).

A trap may be configured to execute a program, First check the Execute option. The Configure button then becomes enabled. Click the Configure button to choose the program to execute and set its command line parameters.

The "Include Trap Data" checkbox is used to pass trap data to the program. See the section Trap Data section below for details on how this is accomplished.

To generate electronic mail messages, check the Email option (note: email destinations must be configured before checking this box, see the email section below).

From the main configuration window, select the email tab:

On the Email tab, click the Add button (or if one has already been added, either double-click it or select it and then press the modify button. The Add Recipient window appears:

Fill in the SMTP Server Host and Port fields with the appropriate Simple Mail Transfer Protocol host name and port number. Then fill in the From, To, Subject, and Message fields with your preferred values. The message field may use the following predefined substitutions:

%SENDERIP%
%SPECIFICTYPE%
%GENERICTYPE%
%COMMUNITY%
%SENDEROID%

For example, entering the following text in the message field:

"A trap from %SENDERIP% of type %GENERICTYPE%/%SPECIFICTYPE% was received"

would yield an email messages containing the text: "A trap from 10.1.1.2 of type 5/0 was received"

Trap Receiver supports AUTH-LOGIN as per RFC2554 for those SMTP servers that require authentication. If your SMTP server requires authentication, check the "Authentication Required" checkbox which will enable the "Set" button. Clicking on the set button will allow you to specify the necessary user name and password for your SMTP server.

Exploders

From the main configuration window, select the Exploders tab:

On the Exploders tab, click the Add button (or if one has already been added, either double-click it or select it and then press the modify button. The Add Exploder window appears:

Enter the IP address or hostname and port number of the destination to which the trap should be delivered. Pressing Add will add the destination and redisplay this window. Press Close when you are done adding destinations.

Logging

Each incoming trap is logged to an ASCII log file (except for those that match a watch with an action of "discard"). For performance reasons, the logs are only written on a period basis.

Logging can be turned on or off by selecting the appropriate radio button.

The flush interval can be set to from 1 to 15 minutes in one-minute increments. Use the slider to select an interval for optimal performance on your computer. The flush interval tell Trap Receiver how often to write the queue of received traps to the log file.

The default filename for the log is TrapRcvr.log. You can specify any name you choose or use the browse button to select a different directory and/or name.

You can choose to append new trap data to the log file or overwrite the file by selecting the appropriate radio button.

The format of the ASCII log has a fixed part and a variable part. The format of the variable part is specified in the "Log File Format" text string.

The fixed part consists of the timestamp. If a trap is acknowledged from the GUI, that trap will contain an 'A'. If a trap is deleted from the GUI, that trap will have a 'D'.

The variable part which follows the fixed part is controlled by the format string. The following specifiers are allowed in the format string:

%v - print version 0 for V1, 1 for V2 or inform
%c - print community string
%g - print generic type (V1 only)
%s - print specific type (V1 only)
%t - print timestamp field (V1 only)
%i - print sender's IP address
%o - print sender's OID
%b - print varbind data; MUST be followed by one or more of the following:
- O - print varbind Oid
- T - print varbind Type
- D - print varbind Data

These can be specified in any order (except the %b must always be followed by 'O', 'T', and/or 'D'). Here's a couple of examples:

%i%bOTD - prints sender's IP and all varbind data

%v%i%bOD%c - prints version, sender's IP, varbind OID and Data, and community string.

Trap Data

In order to support legacy applications that process fault data from the network, Trap Receiver can hand to external programs the trap data in one of two ways; through environment variables and/or through command line parameters. This is controlled on the Trap Data tab.

In addition to supporting these two techniques, Trap Receiver allows complete customization of the environment variables and command line parameters.

Environment variables consist of name/value pairs. The value part comes from the trap itself. The name part is completely up to the application designer. For example, if your application expects the IP address of the device that generated the trap to be in an environment variable called "NetworkIP", Trap Receiver can support this. Clicking on the "Specify Variables" button presents you with the means to configure the environment variables.

Please note that since a trap may have more than one variable binding, the name for Varbind Data and the name for Varbind OID will be appended with the number as they appear in the variable binding list. For example, for a trap that contains three (3) varbinds, the environment variables names will be "VbData1", "VbData2", and "VbData3" as per the configuration depicted above.

Command line parameters behave somewhat similarly. We typically see command line parameters in the form "-f <filename>" where <filename> is a placeholder for an actual file name. The "-f" prompts the external program to expect a filename to follow. This type of command line parameter follows the name/value pair paradigm described above for environment variables. However, there is another flavor of command line parameter; the optionless type. An example would be "-debug" in which case the external application needs no additional information to understand the parameter. Another example is simply <filename> as in "notepad <filename>". Here the application notepad understands the parameter to be a file to be opened for editing. Trap Receiver can support both of these conventions.

The window for configuring command line parameters is identical to the one for configuring environment variables. To support the optional argument syntax (i.e., "-c <community>") as described above, check the box next to community and enter a "-c" in the text field. To support the optionless syntax (i.e., "<ip address>"), just check the box next to IP Address and leave the text field blank.

Mibs

Trap Receiver supports textual trap data loaded from MIBs. The loading of MIBs is supported on the Mibs tab of the Configure Trap Receiver dialog box.

Because MIBs are provided by third parties, they can occasionally contain errors and dependencies which are unresolved. As such, Trap Receiver's ability to import can be limited.

To import a MIB, simply click on the "Load MIB" button. The resulting dialog box provides the means to locate the MIB file. Trap Receiver reads MIBS to be able to translate TRAP definitions, object definitions, and enumeration definitions. The results of the MIB reading are then presented. To unload a MIB, select one of the currently loaded MIBs and click the "Unload MIB" button.

To assist in analyzing the MIB import funtionality, the GUI applicatin DbView is included with the Trap Receiver application. With DbView, you can see the results of a MIB import with respect to TRAP definitions, object definitions, and enumeration definitions. At this time, no modifications to the databases are allowed.

If MIB importing errors are as a result of missing dependencies, you can place the missing MIB files in the "mibs" directory which is located under the Trap Receiver installation directory.

Miscellaneous

The following section details the miscellaneous options that affect the operation of Trap Receiver.

Port Number specifies on which port the application is to listen for traps. Modifying this value requires the TrapRcvr service to be restarted (stopped then started again).

Max log file size in Mbytes specifies the maximum size that the ASCII log file will be allowed to grow. Once this maximum size has been reached, logs will continue to be logged to a rolled over file (original filename logfile.txt -> logfile1.txt, etc.).

Ping Timeout in mSec is not used at this time.

Tray Icon when Minimized is not used at this time.

Reverse Hostname Lookup will force any display showing IP addresses to resolve the IP address to hostnames when this option is selected. Note: this option impacts the performance since it results in a DNS query.

Automatically Generate Inform Responses tells the trap receiver mechanism to acknowledge SNMPv2 INFORM messages as they are received. Modifying this value requires the TrapRcvr service to be restarted (stopped then started again).

Glossary

Community String	In SNMP, a community is a group of stations with the same access permission. Each SNMP request packet includes a community name or string. When a request packet is received, the remote access server looks for the name in its community table. If the name is not found, the request is denied and an error is returned. If the name is found, the associated access level is checked and the request is accepted if the access level is high enough for the request.
DLL	Dynamic Link Library. Allows a user to share functions or resources among Windows programs.
Event	Network message indicating operational irregularities in physical elements of a network or a response to the occurrence of a significant task, typically the completion of a request for information.
IETF	Internet Engineering Task Force. A large, open international community of network designers, operators, vendors, and researchers concerned with the evolution of the Internet architecture and the smooth operation of the Internet. The IETF is responsible for collecting and advertising internetworking Requests for Comment (RFC), and for formalizing internetworking standards.
IP Address	Internet Protocol Address. A unique number that identifies a networked system so it can communicate via IP. It consists of four numbers separated by periods. Most often, each part of the IP address is a number between 0 and 225; however, the first number must be less than 224 and the last number can not be 0.
MIB	Management Information Base. A set of defined variables that are accessed through the Simple Network Management Protocol.
NMS	Network Management System. System responsible for managing at least part of a network. An NMS is generally a reasonably powerful and well-equipped computer such as an engineering workstation. NMSs communicate with agents to help keep track of network statistics and resources.
OID	Object Identifier. Identifies network objects such as routers or transmission equipment.
SMI	Structure of Management Information. Provides a framework to show how MIB objects are managed, including how they are named, grouped, operations that they are allowed to perform, permitted data types, and syntax information.
SMTP	Simple Mail Transfer Protocol. A protocol that regulates what goes on between the mail servers.
SNMP	Simple Network Management Protocol. Defined in IETF RFC-1157, based on the client-server model and implemented over User Datagram Protocol, SNMP enables network managers to remotely monitor and control the evolution of network objects.
Trap	Message sent by an SNMP agent to an NMS, console, or terminal to indicate the occurrence of a significant event, such as a specifically defined condition or a threshold that was reached.
Varbind	A varbind consists of an ASN.1 object identifier and a value. There is no specific relationship between the object identifier and value contained within a varbind.