Event Management Commands › catrap-Issue SNMP Traps in a Network

catrap-Issue SNMP Traps in a Network

Valid on UNIX/Linux, Windows, z/OS

Note: Windows TCP/IP support must be installed for this command to be operational.

In this discussion, %CAIGLBL0000% for Windows and $CAIGLBL0000 for UNIX/Linux refers to the Enterprise Management installation directory.

A key feature of the SNMP facilities of Enterprise Management is the catrap command (%CAIGLBL0000%\bin\catrap.exe (Windows), or $CAIGLBL0000/snmp/bin/catrap (UNIX/Linux, z/OS)). catrap can issue SNMP traps to any destination in your network.

Unlike other commands capable of issuing SNMP traps, catrap does not require optional Network Management products to be licensed on the node on which it is executed. Additionally, no special authority is needed to run the catrap command.

The catrap command supports all the operands accepted as Open System standards for an SNMP trap command. It can be used interactively, through shell scripts, or as part of automated event handling policies defined to the Event Management function. The operands provided as destination and information data to the catrap command are automatically converted into the appropriate Open Systems standard datagram and sent to the designated trap destination.

The catrap command can coexist with existing SNMP daemons through the use of port sharing. The catrap command opens the port only for the duration of time required to send the SNMP message. The catrap command makes use of the system call getservbyname() to determine the actual port number to use (by convention, port 161 is reserved for this use). If this service has been modified, catrap may not be able to locate the correct port. Most operating systems with TCP/IP support utilize an /etc/services file, which can be consulted to determine the port number reserved for SNMP on that machine. On a Windows system, look for this file in %SystemRoot%\SYSTEM32\DRIVERS\ETC\SERVICES .

SNMP traps are typically issued by an agent implemented in the firmware of a particular device. The catrap command, however, makes it simple for user applications, shell scripts that are part of production jobs, or Event Management policies to issue SNMP traps of their own, by executing this command with the appropriate arguments.

Unlike other SNMP trap commands, the catrap command provided with Enterprise Management is not restricted to any particular set of ISO or Enterprise MIBs, and is totally open for use with any MIB or pseudo MIB. While just as real and meaningful as an ISO or Enterprise MIB, a pseudo MIB takes many defaults from the platform on which it is executing.

This command has the following format:

catrap [-d] [-t timeout] [-r retries] [-p port] [-c community]
          target-node
          enterprise-id
          agent address
          generic trap
          specific trap
          time stamp
          [variable binding info1][variable binding info2] [variable binding
           infon]

This command uses the following parameters:

-d

Display the trap request datagrams in dump format.

-t timeout

Identifies the timeout value as a positive integer in 1/10 second increments.

-r retries

Identifies the number of retries to be made when a busy or other recoverable error condition is detected while attempting to send the SNMP trap.

-p port

Identifies the remote port number to which the SNMP trap request is to be sent. Use this option if your Network Manager or the catrapd service provider is listening on a port other than the internet standard snmp-trap port, 162.

-c community

Send this trap to the specified SNMP community. This option may be used to override the default of public.

target-node

Identifies the node to which this SNMP trap is to be sent. It may be specified either as a host name or as an IP address.

Note: For IPv6, a hostname must be used.

enterprise-id

Identifies the enterprise MIB that should be associated with this SNMP trap. If specified as the setting for Windows or UNIX/Linux, system environment variable %CAICATD0000% (NT) or $CAICATD0000 (UNIX/Linux) is used. If %CAICATD0000% or $CAICATD0000 is not set, the CA Enterprise code 1.3.6.1.4.1.791 is used.

agent-address

This operand is provided for proxies that need to send trap requests for a host that cannot send SNMP trap requests. This agent address is used to identify the SNMP trap on the Event Management console log. This may be specified as a hostname or as an IP address. If specified as "" the IP address of the current hostname is used.

Note: For IPv6, a hostname must be used.

generic-trap

Specifies a single digit, in the range 0 to 6, which defines the class of generic trap being sent. Under most circumstances, use code 6 to indicate that an Enterprise-specific SNMP trap code is being used.

Codes 0 through 5 have specific industry standard predefined meanings as defined by the Internet Activities Board (IAB) RFC1215. These are:

0 Coldstart

1 Warmstart

2 Link down

3 Link up

4 Authentication failure

5 EGP neighbor loss

specific-trap

Identifies an Enterprise specific trap number up to a 32-bit integer. This number may identify a trap request for your organization. It can also be used to define an Enterprise specific MIB for your organization that identifies the trap codes to use. This allows your network manager to take advantage of the other facilities of SNMP Management.

time-stamp

Indicates the time, in hundredths of a second, that the application sending the SNMP trap has been active. Specify any whole number greater than or equal to zero. If specified as "", the time stamp value defaults to the value of the system uptime() call.

variable-binding-info, variable-binding-info2,…variable-binding infon (trapvar)

There are three parts to the binding information:

object-ID

data-type

data-value

You may specify multiple sets of binding information in a single trap request. However, in order to specify a subsequent set of binding information, the previous binding information must be completely specified (all three parts must be present).

The SNMP standard limits trap requests to 484 bytes. This limitation should not cause a problem during normal use. However, when you use multiple or long variable bindings, this limitation could cause a problem. To estimate the size of a trap, count the number of characters used in the catrap command, add 19 for datagram overhead, and 6 for each set of variable bindings. For a more accurate count, run catrapd with the d option. If you find that you are exceeding the length restriction, try splitting the variable bindings into multiple catrap commands, or reduce the length of text strings in the bindings.

Examples

1.3.6.1.2.1.1.1.0 octetstringascii 'hello world'

1.3.6.1.2.1.1.1.0 integer 12345

1.3.6.1.2.1.1.1.0 null

object-ID

The Object ID associated with this variable. If not specified, the setting for the Windows System Environment Variable%CAICATD0001% is used. If %CAICATD0001% is not set, the Internet MIBII-MGMT SYSTEM sysDescr code of 1.3.6.1.2.1.1.1.0 is used.

data-type

The type of variable data. The support types are defined in the IAB RFC1155 and derived data types, as follows:

integer

A number that can be represented as a signed 32-bit integer.

octetstring

An octet string of data.

octetstringascii

A string of ASCII characters. If this value is more than one token, enclose the value in single or double quotes.

gauge

A non-negative integer that may increase or decrease. The maximum value is 2 to the power of 32 -1 (4294967295 decimal)

counter

A non-negative integer that monotonically increases to a maximum value of 2 to the power of 32 -1 (4294967295 decimal)

timeticks

A non-negative integer that counts the time in hundredths of a second since some epoch.

opaque

See the Internet Activities Board (IAB) RFC1155 description.

objectidentifier

An Object ID.

null

No value.

ipaddress

An IP address, represented as an octetstring of length 4 (for example, 999.999.999.999).

data-value

The value to be associated with the variable binding in an ASCII representation.

Example 1

The following fictional scenario demonstrates how the catrap command might be used.

A company has defined its own pseudo MIB, which describes an event tree. Each node on the tree represents information that could be sent when specified as a variable on the catrap command.

Sending a trap with the variable of 999.1.1.2 is equivalent to sending the message that the enterprise database server that handles the general ledger database has been started.

The variable of 999.1.1.3 indicates that the General Ledger database has encountered a journal full condition. And the variable 999.2.1.1 indicates that General Ledger financial application has resumed processing after a temporary outage (warm start).

To take the example further, assume that Enterprise Management is executing on several nodes in this network, but you have decided that all SNMP trap traffic should be directed to a single monitoring machine running on a node called EVNTMGR. The EVNTMGR node receives trap traffic that is recorded and acted upon by the Event Management function of Enterprise Management.

Another machine in the network is used for the production of financial applications. This node is called FINPROD. For some unknown reason, an error occurs and the General Ledger production application running on node FINPROD terminates with an error. Testing the return code issued by this executable, the shell script realizes that the exit code indicates there was a problem, and issues an SNMP trap to alert the EVNTMGR node that something has gone wrong, by simply executing the following command:

catrap EVNTMGR "" "" 6 0 22 999.2.1.3 integer 128

Note: A full syntactical description of the catrap command is included after this example.

The first operand directs the catrap command to send the identified trap information to the node EVNTMGR. The next two operands, "" and "", instruct catrap to take the default Enterprise code and the default agent address for this node. The number 6 indicates that this command is sending a specific trap, the 0 identifies the specific trap number for this example and 22 is an arbitrary number we have selected as a timestamp indicator. The next three operands identify the variable binding information for the trap, as follows: 999.2.1.3 is the Object ID of the object about which information is being sent. (If you refer back to the event tree described earlier, you can see that the string 999.2.1.3 refers to an error in the enterprise financial application, General Ledger). The last two operands provide additional information about the event; in this case, "send an integer value of 128 to node EVNTMGR." For this example, we are assuming that 128 is an error code that has some meaning to the General Ledger application, or it is the exit code that the shell script detected as indicating an error. When received at the trap target node, in this example, EVNTMGR, the Event Management function can then decode the event and perform automatic actions in response.

If you see the event tree, you can see what other types of events can be sent, such as 999.1.1.1, indicating that the Enterprise data server Database for the General Ledger system has been shut down.

The catrap command provides additional functionality when coupled with the capabilities of Enterprise Management. For example, you can use the catrap Event Management facilities to intercept the error messages from any application and automatically execute user customized catrap commands in response. The Workload Management function could detect key events and send traps in response to files available for processing, or applications completing their processing. When traps are received, Event Management message handling policies can be used to automatically open problem tickets, send warning messages to other consoles or terminals, start recovery jobs, post dependencies as having been met (so that other production jobs can proceed), issue additional SNMP traps to other nodes, or any number of other actions. The possibilities for using SNMP trap information are numerous.

Example 2

When the Enterprise Management catrap service provider is operational, SNMP traps directed to the node on which it is executing are automatically forwarded to Event Management. Once received, these trap messages are automatically recorded in the event log, and become eligible for sophisticated automatic processing by the Event Management function of Enterprise Management. This example shows you how to issue an SNMP trap (using the catrap command) and the format of the resulting message as it is presented to the Event Management function by the catrap service provider (catrapd) that receives the trap.

The following catrap command causes an SNMP trap to be sent to node xyzlhu33:

catrap xyzlhu33 "" "" 6 1 1 1.3.6.1.4.1.791.1.4 octetstring "hello world"

The catrap daemon (catrapd) running on node xyzlhu33 receives the trap and presents it to the Event Management function in the following format:

.CATD_I_060 SNMPTRAP:  -c  public  Computer.Associates 999.999.9.999 xyzlhu33 6 1 00:00:00 1 OID: 1.3.6.1.4.1.791.1.4 .iso.org.dod.internet.private.enterprises.791.1.4 VALUE: hello world

Within the Event Management function of Enterprise Management, this message is divided into character "tokens" which can be tested individually or in combination with one another as part of user-defined Event Management policies. The message in the preceding example has 17 tokens. The tokens are:

The preceding explanation of how SNMP traps are sent and how they are presented to the Event Management function of Enterprise Management provides the information needed to begin using SNMP facilities in an installation.

Note: If your organization does not have its own enterprise ID (assigned by the Internet Assigned Numbers Authority), you can continue to use the system descriptor 1.3.6.1.4.791.1 that was used in the preceding example. This descriptor represents subtree 1 of the CA enterprise ID. (The formal system descriptor for the CA enterprise ID is 1.3.6.1.4.1.791.1, where "1.3.6.1.4.1.791" is the ID that the Internet Assigned Numbers Authority has reserved for CA, and the subsequent ".1" represents the subtree that CA has reserved for client use.)

Enterprise IDs are assigned by an independent industry organization, the Internet Assigned Numbers Authority. If you wish to obtain an enterprise ID for your organization, you must request one from the Internet Assigned Numbers Authority, whose email address is iana@isi.edu mailto:iana@isi.edu.