Trap Receiver User Manual

Preface
This document contains the basic functional specifications and configuration information for Trap
Receiver. It describes the softwares 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 and the Trap Receiver logo are trademarks of TrapReceiver.com.

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 (you will have to stop the Microsoft snmptrap service first). 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.
Play a sound file.
Discard the trap.

Trap Receiver is composed of two parts:

The service that handles trap receiving, watch matching, action executing, and logging
The GUI that allows a graphical viewing of the incoming traps, configuring everything,
and performing certain actions

Important Note: As of Windows 7/Server 2008, Windows services cannot interact directly
with the desktop. For that reason, the GUI is used to execute some actions. The built in
action "Play a sound" is executed only by the GUI. The built in action "Execute a program"
has an option to specify whether desktop interaction is required. You would check this
option if the program being executed displays a window.
Actions that are executed by the GUI, that is, "play a sound" and "execute an action" with
the "Requires Desktop" option checked, will execute only if the GUI is running.
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:
support@trapreceiver.com.

The Trap Receiver Service (TrapRcvr)

The bulk of the work is performed by the TrapRcvr service. This is a windows service added to
the service control manager. The executable run by the service control manager is trThread.exe.
thThread.exe accepts three parameters: -v (verify that the service is installed correctly), -i (to
install the service into the service control manager), and -u (to uninstall the service from the
service control manager).
Use the NET command to start and stop the service. Starting is accomplished by entering "net
start traprcvr" at a DOS prompt. Similarly, entering "net stop traprcvr" will stop it. You can also
use the Services control panel applet to do so. Click Start->Run and enter "services.msc" in the
dialog box presented.

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).
New in version 6.40: From the main window Use the system menu to export the current
configuration to a file, or import a previously exported configuration file.

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.

Hey! What is this Name thing!? And an AND Group!?

This is a new feature in version 7.47. Previously, each watch was evaluated individually. If the
watch's condition was true, the action(s) would be performed. Now, however, you can logically
AND watches using the Name field. Each watch that has the same name is considered part of an
AND group, and in order to evaluate to true, ALL watch conditions must evalute to true. You
must first configure the "Master" watch which also contains the actions. Do not check the "No
Actions - Part of AND Group" checkbox on this Master watch. To logically AND another watch,
add a new watch, use the same name as the "Master", and check the "No Actions - Part of AND
Group" box.

Note: When configuring groups, it is a good idea to click the "Apply" button after configuring the
"Master" watch. Be warned.

Watch Values
Community
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-=_+,./;'[]\<>?:"{}|`~

Generic Type
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.

SenderIP
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)

SpecificType
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).

SenderOID
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.

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

VarbindValue
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. New in version
7.12 and later, if you are watching a varbind value that is of the string type, you can match using
wildcard specifiers. For example, you can specify "1.3.6.1.2.1.2154.1.0:*Temperature:=", and that
would match as you would expect with wildcards: "CPU Temperature is too high", "System
Temperature normal", "Temperature out of range", etc. The "?" character is also supported. The
varbind must be a string type and the condition must be "=".
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
Play a sound

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 (or be forwarded) to multiple destinations as configured
through the Configure Exploders tab (note: exploders must be configured before checking this box,
see the Exploders section below). When exploder destinations are configured, you can select, by
pressing the now enabled "Configure" button, which destinations are to be used for this trap using
the Select Exploder Destinations dialog box:

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.
The "Requires Desktop" checkbox is used to notify Trap Receiver that this executable displays a
window and therefore needs to be performed by the GUI's action processing loop since Windows
services are not allowed to interact with the desktop.
To generate electronic mail messages, check the Email option (note: email destinations must be
configured before checking this box, see the email section below). When email addresses are
configured, you can select, by pressing the now enabled "Configure" button, which addresses are
to be used for this trap using the Select Email Recipients dialog box:

New in version 6.40: hover over the Recipient column for more details on that particular entry.

Sound
Trap Receiver can play a sound as an action. To configure a sound, specify the WAV file to be
played and whether it should be played once or repeatedly (loop) until cancelled by the user.

Email
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%
%TIMESTAMP%
%SPECIFICTYPE%
%GENERICTYPE%
%COMMUNITY%
%SENDEROID%
%VBOIDn%
%VBDATAn%
%VBOIDn% and %VBDATAn% may be used to include the OID or the DATA from the
n-th varbind. For example, %VBDATA1% will include the data from the first varbind.

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". As of version 6.0, you can embed carriage returns and line feeds into the message. To
do so, enter "\\r" to embed a carriage return and "\\n" to embed a line feed. To keep the spacing
consistent, these special strings will be replaced by a space and the appropriate character (LF or
CR). "\\N" and "\\R" are also accepted.
Trap Receiver supports SMTP STARTTLS command for those SMTP servers (like gmail) that
requires a secure connection before transferring data. If this applies to your server, check this SSL
Required checkbox.

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 O - print varbind Oid
o T - print varbind Type
o 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.
Separator Character tells Trap Receiver which single character to use to separate the fields. The
default is a space, which shows up as an empty box.

Debug Button
Trap Receiver now supports built-in logging of application behavior to help support resolve
problems in certain circumstances. Presently, only "Email Problems", "Action Problems", and
"Logging Problems" are supported. Use the following dialog box to enable tracing of email related
application events. This causes trap receiver to log to TrapRcvr.smtp.log, TrapRcvr.action.log,
and TrapRcvr.logging.log respectively. The location of these files is usually the same directory to
which Trap Receiver was installed.

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.
Note on "Real Ip": Real Ip comes from the socket layer, not from the Agent Address field
(SNMPv1) or SnmpTrapAddress varbind (SNMPv2).

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.
WE DO NOT RECOMMEND UNLOADING MIBS EXCEPT FOR THOSE LOADED BY
THE USER.

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 will minimize the GUI to the System Tray instead of the task bar to
help conserve space there. This option was added to accomodate those users who need to keep the
GUI running in order to play sounds or execute programs that display a window.
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).
Enable Deduplication causes Trap Receiver to evaluate whether the current trap is a duplicate of a
trap previously received within the Deduplication Interval. If it is, it does not cause actions to be
performed. A trap is considered a duplicate if both the IP address and Sender's OID match.
Deduplication Interval specifies the number of minutes between successive traps to be considered
duplicates.

Add SnmpTrapAddress Varbind instructs Trap Receiver to add, if not present, the
SnmpTrapAddress.0 varbind to SNMPv2 traps or SNMPv2 INFORMS generated as part of the
explode action.

Glossary
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
Community packet is received, the remote access server looks for the name in its community
String
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.