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 topic, %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.

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 that are 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 that are defined to the Event Management function. The operands that are 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 by using port sharing. The catrap command opens the port only during the time that is required to send the SNMP message. The catrap command uses 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 use an /etc/services file, which can be consulted to determine the port number that is reserved for SNMP on that computer. On a Windows system, look for this file in %SystemRoot%\SYSTEM32\DRIVERS\ETC\SERVICES .

Agent that is implemented in the firmware of a particular device typically issues SNMP traps. The catrap command 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. The catrap command does this by executing this command with the appropriate arguments.

The catrap command that is provided with Enterprise Management is not restricted to any particular set of ISO or Enterprise MIBs, and is open for use with any MIB or pseudo MIB. A pseudo MIB is as real as an ISO or Enterprise MIB and takes many defaults from the platform on which it is executing.

Syntax

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]

Parameters

-d

Displays the trap request datagrams in dump format.

-t timeout

Timeout value as a positive integer in 1/10 second increments.

-r retries

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

Remote port number to which the SNMP trap request is 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

Sends this trap to the specified SNMP community. This option can override the default of public.

target-node

Node to which this SNMP trap is sent. Specify it as a host name or as an IP address.

Note: For IPv6, a hostname must be used.

enterprise-id

Enterprise MIB that is 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 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. Specify 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

A single digit, in the range 0 through 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.

0 Coldstart

1 Warmstart

2 Link down

3 Link up

4 Authentication failure

5 EGP neighbor loss

specific-trap

Enterprise specific trap number up to a 32-bit integer. This number can 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 lets your network manager to use the other facilities of SNMP Management.

time-stamp

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)

The three parts to the binding information are:

object-ID

data-type

data-value

You can specify multiple sets of binding information in a single trap request. To specify a subsequent set of binding information, the previous binding information must be 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. 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 that are 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 are exceeding the length restriction, split 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

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 according tthe 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 can 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 from 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- How to Use the catrap Command

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 is directed to a single monitoring computer running on a node named EVNTMGR. The EVNTMGR node receives trap traffic that the Event Management function of Enterprise Management records and acts upon.

Another computer in the network is used for the production of financial applications. This node is named 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 that this executable issued, the shell script realizes that the exit code indicates that there was a problem. The shell script 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 that 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 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 more 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.

In 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 more 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 could 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 more SNMP traps to other nodes, or more actions. The possibilities for using SNMP trap information are numerous.

Example 2 - catrap Command Syntax

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 how to issue an SNMP trap using the catrap command. The format of the resulting message is 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 as part of user-defined Event Management policies. The message in the preceding example has 17 tokens.

The preceding explanation of how the SNMP traps are sent and how they are presented to the Event Management function of Enterprise Management provides the information 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. "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.

An independent industry organization, the Internet Assigned Numbers Authority, assigns enterprise IDs. To obtain an enterprise ID for your organization, request one from the Internet Assigned Numbers Authority: iana@isi.edu mailto:iana@isi.edu.