integrating patrol® with snmp

8/20/2019 Integrating PATROL® with SNMP

1/63

Integrating PATROL ® with SNMP

February 2000


2/63

Integrating PATROL with SNMP ii

Contents

SNMP an Introduction

The SNMP Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Standard Message Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

PDU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Standard Set of Managed Objects . . . . . . . . . . . . . . . . . . . . . . . . 4

MIB Structure and Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

MIB Object Access Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5MIB Tree Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Discrete MIB Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Table Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

MIB Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Compiling MIB Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Standard Addition of Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

SNMP Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

SNMP Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

SNMP Master Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

SNMP Sub-agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Instrumenting Applications for Management . . . . . . . . . . . . . . 11

PATROL SNMP Implementation

PATROL SNMP Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

PATROL SNMP Master Agent . . . . . . . . . . . . . . . . . . . . . . . . . 12

PATROL SNMP Sub-agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

PATROL SNMP Implementation–Windows NT . . . . . . . . . . . 13

PATROL SNMP Implementation–Unix . . . . . . . . . . . . . . . . . . 14

PATROL as an SNMP Manager . . . . . . . . . . . . . . . . . . . . . . . . 14

MIB to KM Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Third-party SNMP Managers . . . . . . . . . . . . . . . . . . . . . . . . . . 15

The PATROL SNMP Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . 15


3/63

Integrating PATROL with SNMP iii

Configuring PATROL for SNMP

Configuring the PATROL SNMP Master Agent . . . . . . . . . . . . . . . 17

The PATROL Agent SNMP Support Variables . . . . . . . . . . . . . . . . 19

PATROL Agent SNMP Interested Managers . . . . . . . . . . . . . . . . . 20

Variables for Configuring the Agent with SNMP . . . . . . . . . . . 21

When Configuration Changes Take Effect . . . . . . . . . . . . . . . . 21

Testing Agent SNMP Trap Sending . . . . . . . . . . . . . . . . . . . . . . . . 22The PATROL MIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

PATROL MIB Tree–Objects Table . . . . . . . . . . . . . . . . . . . . . . 24PATROL MIB Tree–Variables Table . . . . . . . . . . . . . . . . . . . . . 25PATROL MIB Tree–Applications Table . . . . . . . . . . . . . . . . . . 26

PATROL MIB Tree–Instances Table . . . . . . . . . . . . . . . . . . . . . 28PATROL MIB Tree–Trap Table . . . . . . . . . . . . . . . . . . . . . . . . 30

Using PSL to Control PATROL and SNMP

Listening for SNMP Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Sending SNMP Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Starting and Stopping the SNMP Sub-Agent . . . . . . . . . . . . . . . . . 34

Getting and Setting MIB Variables . . . . . . . . . . . . . . . . . . . . . . . . . 35Using PSL to Change the Registered SNMP Manager List . . . . . . 36Debugging PSL Functions for SNMP . . . . . . . . . . . . . . . . . . . . . . . 36Interpreting Error Messages from PSL Functions . . . . . . . . . . . . . . 37

Using SNMP to Send Traps

Methods of Sending SNMP Traps . . . . . . . . . . . . . . . . . . . . . . . . . . 38PATROL Event Manager and SNMP Traps . . . . . . . . . . . . . . . . . . 39

Standard Event Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Configuring the Event Catalog for SNMP Traps . . . . . . . . . . . 42

Altering Event Classes for Trap Notification . . . . . . . . . . . . . . . . . 43Configuring the List of Recipients for SNMP Traps . . . . . . . . . . . . 43Configuring the Agent for SNMP Trap Sending . . . . . . . . . . . . . . . 44

PATROL Agent SNMP Configuration Variables

Items That Cannot Be Changed . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Changing the PATROL Master Agent Directoryand Start Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Changing the Events That Trigger SNMP Traps . . . . . . . . . . . . . . . 50Changing Whether PSL Supports SNMP . . . . . . . . . . . . . . . . . . . . 51Changing SNMPV1 Managers That Get SNMP Trapsfrom the Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Changing the MIB File That the Agent Uses for SNMP . . . . . . . . . 52

Changing Port Information for PSL SNMP Functions . . . . . . . . . . 52Changing Community Names for SNMP Operations . . . . . . . . . . . 53

Changing Retry and Timeout for PSL and SNMP Operations . . . . 54Changing Whether SNMP Is Started with Agent . . . . . . . . . . . . . . 54

Appendix A: ASN.1

Branch Object Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Leaf Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Object Syntax Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57


4/63

Integrating PATROL with SNMP 1


This paper introduces SNMP, provides an overview of SNMP architecture, provides an

overview of the PATROL SNMP architecture, and provides information on implementingSNMP in your PATROL environment.

This paper explains what components of the PATROL Agent are required to implementSNMP, why these components are required, and how to access the PATROL MIB and otherMIBs using the PATROL Agent.

The following topics are covered:

SNMP an Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2PATROL SNMP Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Configuring PATROL for SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Using PSL to Control PATROL and SNMP. . . . . . . . . . . . . . . . . . . 33Using SNMP to Send Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38PATROL Agent SNMP Configuration Variables . . . . . . . . . . . . . . . 46

Appendix A: ASN.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55


5/63


SNMP an Introduction 2

SNMP was born out of the U.S> Department of Defense’s Advanced Research Projects

Agency’s efforts to manage their expanding network of systems from different vendors. Threesolutions were proposed:

• High-level Entity Management System (HEMS)• Simple Network Management Protocol (SNMP)• CMIP

CMIP was chosen as the preferred solution, but SNMP evolved out of CMIP as a short-termsolution.

SNMP has been very successful because it is light and flexible. Since SNMP is a light-weightcommunications protocol, it adds very little traffic to a network that it is managing.

Additionally, SNMP’s simple design allows users to expand the applications that aremonitored by SNMP very easily.

The original specification for SNMP (V1) caught on quickly but exposed a few deficiencies:

• bugs• security

To address these deficiencies SNMP V2 was introduced, but disagreements about securitymethods led to V2 dropping its security solution. However, V2 did manage to fix some bugsand introduce new data types and message formats. Recently, V3 has been proposed andprovides a security solution.

This paper address SNMP V1 with little reference to V2 tolerance.


6/63


The SNMP Standard

SNMP can be viewed in many different ways, but the perspective presented here will be thatSNMP is actually three distinct standards:

• a standard message format

• a standard set of managed objects• a standard way of adding objects

Standard Message Format

SNMP has a standard communication protocol that defines a message format. The messagesare encoded into a protocol called Protocol Data Units (PDU). PDU messages are exchanged

by SNMP devices. While the format of the PDU messages is very complex, it is generallyhidden by the network management software. This part of the standard is highly involved andof little interest to users, but on the other hand PDU is of great interest to SNMP

programmers.

Message Types

Four types of SNMP messages are defined that allow you to get values from the managedobject, set values on the managed object, and allow the managed object to communicate withthe network manager:

• get request• get next request• set request

• trap message

PDU

SNMP works very simply. It exchanges network information through messages (technicallyknown as protocol data units (or PDUs)). From a high-level perspective, the message (PDU)can be looked at as an object that contains variables that have both titles and values.

There are four basic PDUs that SNMP employs to monitor a network: two deal with readingterminal data, one deals with setting terminal data, and one is used for monitoring networkevents such as terminal start-ups or shut-downs.

Therefore, if you want to see if a terminal is attached to the network, you would use SNMP tosend out a read PDU to that terminal. If the terminal was attached to the network, you wouldreceive back the PDU, its value being “yes, the terminal is attached.” If the terminal was shutoff, you would receive a packet sent out by the terminal being shut off informing you of theshutdown. In this instance a trap PDU would have been dispatched by the terminal.


7/63


Get Request

Specific vales can be obtained from a device using the get request. Typically, many differentvalues can be obtained from a device using SNMP without the overhead associated withlogging into the device, or establishing a TCP connection with the device.

Get Next Request

With the get next request, SNMP managers can “walk ” through all the SNMP values of adevice to discover all the names and values that the device supports. This is accomplished bystarting with the value of the first SNMP object and then using the get net request until thereare no more SNMP objects to get. The process of using the get next request to obtain the

values of all the SNMP objects is referred to as “walking” the objects.

Set Request

The set request provides a mechanism by which devices can managed using SNMP. With the

set request, SNMP can be used to accomplish activities such as disabling interfaces,disconnecting users, clearing registers, and more on the managed device.

Trap Message

The trap message allows the SNMP managed device to communicate with the manager. Thisallows the device to notify the manager of specific problems. Typically, the use of trapsrequires each device on the network to be configured to issue SNMP traps to one or morenetwork devices that are awaiting or listening for the traps.

Standard Set of Managed Objects

SNMP is a standard set of values (SNMP objects) that can be queried from a device.Specifically, the standard includes values for monitoring TCP, IP, UDP, and device interfaces.Each manageable object is identified with an official name, and also with a numeric identifierexpressed in dot notation.

The list of SNMP objects and their values is often referred to as the SNMP Managementinformation Base (MIB). The MIB is simply an abstraction like database that represents allthe SNMP objects or any portion of the data associated with the network.

The various SNMP values in the standard MIB are defined in RFC-1213 (one of thegoverning specifications for SNMP). The standard MIB includes various objects to measureand monitor IP activity, TCP activity, UDP activity, IP routes, TCP connections, interfaces,and general system information. Each of these values is associated with an official name and

a numeric value in dot notation. For example, the elapsed time since a managed object wasbooted is represented as one of the following values:

• sysUpTime• 1.3.6.1.2.1.1.3.0


8/63


Usually, the tendency is to use the name of the MIB object instead of the numerical identifier.much like the way host names are used instead of IP addresses on the Web.

See “MIB Structure and Objects” on page 5 for more information on the description of MIBobjects.

MIB Structure and Objects

To use SNMP effectively, users need to become acquainted with the SNMP MIB whichdefines all the values that SNMP is capable of reading or setting. Each SNMP object is

defined to have a particular access, either read-only, read-write, or write-only that determineswhat can be done to the object.

MIB Object Access Values

Before any object can be manipulated the SNMP community name must be known.Community names are configured into the system by the administrator, and can be viewed aspasswords required for to SNMP objects to be manipulated. Community names exist to allowportions of the MIB and object subsets to be referenced. As the term community implies, thetrue purpose of these values is to identify commonality between SNMP object sets. Is iscommon to make the community strings obscure to limit access to SNMP capability byoutside users.

MIB Tree Structure

The SNMP MIB is arranged in a tree-structure, similar to the directory structure of files on adisk. The top-level SNMP branch begins with the ISO internet directory that contains fourbranches:

• mgmt–this branch contains the standard SNMP objects that are supported by mostnetwork devices.

• private–this branch contains the extended SNMP objects that are defined by networkequipment vendors.

• experimental–this branch usually contains no meaningful data or objects.• directory–this branch usually contains no meaningful data or objects.

The MIB is a tree structure much like a file directory structure. The top five levels of the MIBtree are constant, and all other MIBs are added to those branches. Figure 3 on page 6 showsthe top of the MIB object tree:


9/63


Figure 3 MIB Object Tree

The tree structure is an integral part of the SNMP standard. and the most important parts ofthe tree are the leaf objects that provide actual management data regarding the devices.Generally, the leaf objects are divided into two groups that reflect the organization of the treestructure.

• discrete MIB objects contain one piece of information• table MIB objects contain multiple pieces of information

Discrete and table objects are identified by their extensions. Discrete objects have a “.0” (dot-zero) extension added to their name indicating that they are discrete objects, and tableobjects have a “.instance” (dot-instance) extension where the instance is a number greaterthan zero that represents the index into the SNMP table for this value.

Discrete MIB Objects

Discrete objects are scalar values that usually represent summary values for a device or acurrent value/state of a device. that make them particularly useful for scanning informationfrom a network for the purposes of comparing device performance. These are the end pointsin the MIB tree.


10/63


Table Objects

SNMP tables are special types of SNMP objects that allow parallel arrays of information tobe supported. Tables are distinguished from discrete objects because they can grow without

bounds. For example, SNMP defines the ifDescr object (a standard SNMP object) thatindicates the text description of each interface supported by a particular device. Since network

devices can be configured with more than one interface, this object must be represented as anarray to accommodate multiple and expanding values.

SNMP objects are always grouped in a Entry directory within an object with a Table suffix.

The ifDescr object residues in the iEntry directory contained in the ifTable directory. Severalconstraints are placed on SNMP objects:

• Each object in the Entry directory of a table must contain the same number of elements asother objects in the same Entry directory where the instance numbers of all entries are thesame. Table objects are always regarded as parallel arrays of data.

• When creating a new Entry object, SNMP requires that a value is associated with eachtable entry in a single SNMP message (PDU). This means that to create a row in a table,

using the SNMP set command, a value must be specified for each element in the row.

• If a table row can be deleted, SNMP requires that at least one object in the entry has acontrol element that is documented to perform the table deletion. (This applies only if therow can be deleted, which is not necessarily required of an SNMP table.)

MIB tables are access by using the OID that represents an index into the table. Figure 4 showshow the PSL snmp_walk() function would access the MIB table using the OID as an indexinto the table:

Figure 4 MIB Table Indexing


11/63


MIB Object Types

All MIB objects have specific value types. Table 5 list the primitive object types defined bySNMP:

Table 5 MIB Object Types

Type Description

Text A DisplayString type that can contain textual information (usually limited to 256 characters). The text must

contain only printable characters.

Counter A numeric value that can only increase.

Gauge A numeric value that can increase or decrease. While this value is not very common in the standard MIB is

widely used in private MIBs.

Integer A basic integer value that can contain either positive or negatives values. Usually, this value is supplanted

by Counter or Gauge values.

EnumVal A enumerated value that associates a textual label with a numeric value. This type is common in the

standard MIB.

Time A TimeTicks type that represents an elapsed time. This time always has a resolution of one hundredth of a

second, even if it is not used. Network managers frequently format this time as HH:MM:SS:ss for display.

The time value is always an elapsed time value. For example, sysUpTime indicates the elapsed time since

the device was booted.

Object A value that an contain the identifier for another SNMP object. If the named object is compiled into the

MIB, the name is usually displayed as the name of the SNMP object.

IPAddr A value that contains an IP address of a network device. This type of object is often displayed in the type

as an IP address in conventional dot notation.

PhysAd A value that contains the physical address of a network device. Managers often display this value as a

series of hexadecimal values, prefixed by the hex keyword and separated by colons.

String A value that contains arbitrary byte strings. If the byte string contains only ASCII characters, managers

display the value as a text string. Otherwise the managers display this type as a sequence of hexadecimalvalues prefixed by the hex keyword and separated by colons. Tis value is not common in the standard MIB

objects but it is occasionally found in private MIBs.

Table A value that is a branch object containing table entries. This object is always an intermediate name that

contains an Entry directory that contains various table objects.

Branch A value that defines an SNMP branch that contains additional SNMP objects.


12/63


Compiling MIB Objects

One of the principle components of an SNMP manager is a MIB compiler that allows newMIB objects to be added to the management system. This concept can be confusing to new

users because of the strange nomenclature associated with this term.

When a MIB is compiled into an SNMP manager, the manager is simply made aware of thenew objects that are supported by agents on the network. The concept is similar to adding anew schema to a database. The agent is not affected by the MIB compilation since it isalready aware of its own objects. The act of compiling the MIB allows the manager to learn

about special objects supported by the agent and access these objects as part of the standardobject set.

Standard Addition of Objects

Certainly, one reason that SNMP has become popular and an industry standard is that it has a

method for expanding the standard set of managed objects, so network device vendors couldadd new objects that are specific to a particular network.

SNMP adds new objects to the MIB through a process referred to as compiling a new MIB.The new definitions are usually supplied by network equipment vendors in speciallyformatted text files using Abstract Syntax Notation One (ASN.1) standard syntax. ASN.1 is atype declaration language, adopted by SNMP and used in few other places. See “Appendix A:ASN.1” on page 55 for more information on ASN.1 syntax.

NoteThe MIB of a device is usually constructed by the network equipment

vendor and is static and cannot be modified. The addition of MIB objectsrefers to SNMP management software.

SNMP management software becomes aware of the MIB values supported by a device bycompiling a description of the device into the network management program.


13/63


SNMP Architecture

SNMP architecture consists of the following components:

• SNMP manager• SNMP master agent

• SNMP sub-agents• SNMP instrumenting applications

SNMP Managers

The SNMP manager is an application that provides some basic components for working withSNMP and ANMP objects. Typically, an SNMP manager will provide the followingfunctionality:

• alarm polling functions

• trend monitoring functions• trap reception• management tools• a MIB compiler

MIB Compiler

SNMP managers must also have the ability to add new MIB objects that are provided bynetwork equipment. MIB objects are added using a MIB compiler.

Management Tools

SNMP managers provide tools for inspecting raw MIB objects and setting SNMP values of anagent. This is usually in the form of a MIB browser.

Trap Reception

All SNMP managers provide some ability to receive and filter SNMP traps issued by network

devices. SNMP traps are an important part of the SNMP standard because they allow devicesto report their own problems.

Alarm Polling

Most substantial SNMP managers provide some ability to set thresholds on SNMP MIBobjects, and respond with some type of notification when these thresholds are violated. Thisprovides a means of constantly testing a networks integrity against a baseline. The alarmpolling functionality will also determine what devices are responding and which devices arenot responding.


14/63


Trend Monitoring

Most SNMP managers provide some ability to continuously watch an SNMP value over timeand view trends in the network. Trend monitoring can be used to determine load of a networkover time by watching bandwidth. Typically a management system will plot networkutilization versus time.

SNMP Master Agents

The SNMP master agent is a process that runs on a platform that supports the SNMPprotocol. It listens for SNMP requests on the default SNMP port 161 and serves as a gatewayto other processes on the same platform that support either a sub protocol (emanate, SMUX)or some private protocol (i.e. proxy service)

SNMP Sub-agents

A subagent may be a stand alone process or part of the application to be managed. Theprocess supports the sub protocol of the master agent and responds to requests for informationfrom the master agent.

Instrumenting Applications for Management

Instrumented applications are simply applications that are set up to communicate with SNMP

and set their values so that they can be accessed through SNMP.

Instrumenting applications is the process of providing access methods to an application orprocess data through SNMP protocol. BMC offers the PATROL SNMP toolkit as sharewareto instrument applications for management via SNMP.


15/63


PATROL SNMP Implementation 6

This section provides an overview of the SNMP implementation in PATROL. PATROL

SNMP Architecture and the PATROL MIB are discussed.

PATROL SNMP Architecture

PATROL SNMP architecture consists of the following components:

• SNMP manager• SNMP master agent• SNMP sub-agents• SNMP instrumenting applications

PATROL SNMP Master Agent

The PATROL SNMP master agent listens for SNMP requests on port 161 and serves as a

gateway to other processes. It supports the SMUX sub protocol. It supports the PATROLSub-agent, other sub-agents supporting SMUX, and other SNMP devices throughencapsulation.

PATROL SNMP Sub-agentThe PATROL subagent is a process combined with the PATROL process to translate SMUXmessages to the PATROL Agent. The sub-agent can be started with PSL or with aconfiguration variable of the PATROL Agent. The PATROL SNMP Master Agent must berunning for the sub-agent to run.


16/63


PATROL SNMP Implementation–Windows NT

SNMP on WINDOWS NT is delivered as a service dll to which other SNMP agentscommunicate with through the WINSNMP API. The service is installed optionally, and it isset as the default master agent listening on port 161. Figure 7 shows how PATROL SNMPsupport is implemented on Windows NT:

Figure 7 PATROL SNMP Implementation on Windows NT


17/63


PATROL SNMP Implementation –Unix

Unix vendors support default master agents listening on port 161. AIX uses SMUX, HP usesEmanate. HP loads the sub-agents into the master agent’s process space. Figure 7 shows howPATROL SNMP support is implemented on Unix:

Figure 8 PATROL SNMP Implementation on Unix

PATROL as an SNMP Manager

The PATROL console can be used as an SNMP manager if you create a PATROL KM usingthe PSL SNMP commands that communicates with and manages applications.

When you are using PATROL as an SNMP manager, the PATRPL KM is the interface to the

SNMP MIB. The KM is mapped to the SNMP objects, and the KM allows you to monitor andmanipulate the SNMP MIB through the KM.

The PATROL SNMP Master Agent is not required to use the PATROL Console as an SNMPmanager.

MIB to KM Wizard

The MIB to KM Wizard is a tool that reads a MIB definition and creates a KM that includesparameters, infoboxes, and applications based on the object definitions in a MIB. You can edit

the KM to add functionality, or the KM can then be loaded and PATROL can manage theSNMP devices along with other applications. You can obtain the PATROL MIB to KM

Wizard from the BMC Software Developer Connection (DevCon) Web Site athttp:\\devcon.bmc.com.


18/63


Third-party SNMP Managers

Third-party SNMP managers can be used to manage and monitor PATROL using SNMP.Here are some considerations for using third-party SNMP managers with PATROL.

Compiling the PATROL MIB

When you are using a third-party SNMP Manager. You can manage PATROL objects in thePATROL MIB after you compile the PATROL MIB into your SNMP managementapplication. MIB supports V1 syntax. Some MIB compilers will generate errors so MIBs mayneed to be edited to ensure the correct V1 syntax is used.

Dynamic OIDs

The PATROL MIB is a little unique because it has dynamic OIDs. Normally, an SNMP MIBis fairly static, and the OIDs remain constant. However, in PATROL the many of the OIDscorrespond to application instances and the corresponding elements of the application. So

when you are dealing with the PATROL MIB, you must be aware that it will probably lookvery different every time you access it.

It is very important to note that since PATROL OIDs are dynamic, an instance may be present

one moment and then gone the next moment if the instance disappears.

Configuring SNMP Management Consoles to Recognize PATROL Traps

SNMP trap notification requires configuration on two ends: the PATROL Agent sending thetraps, and the non-PATROL SNMP management console receiving the traps. The Agent needs

to know where to send the traps. The SNMP management console needs to know how torecognize PATROL traps, and what to do about them. Also, the SNMP manager must be

added to the PATROL Agents list of interested managers in the config.default configurationfile.

The PATROL SNMP Toolkit

The PATROL SNMP Toolkit is a set of tools that help you integrate third-party applicationswith PATROL. The toolkit helps you set up applications to communicate with SNMP and settheir values so that they can be accessed through SNMP. You can obtain the PATROL SNMPToolkit from the BMC Software Developer Connection (DevCon) Web Site athttp:\\devcon.bmc.com.


19/63


Configuring PATROL for SNMP 9

The PATROL Agent communicates with both SNMP Managers and SNMP Agents. It

communicates with the SNMP Managers through the SNMP Master Agent. The same is nottrue for the SNMP Agents, but SNMP support must be active for this communication to takeplace. Configuring PATROL for SNMP consists of the following steps:

• set the port number and community name for the PATROL SNMP Master Agent

The PATROL SNMP Master Agent/Sub-Agent model is based on an industry standardknown as SMUX that allows one or more SNMP Sub-Agents to connect to a singleSNMP Master Agent using a TCP SMUX port (TCP port 199 by default).

For more information on configuring the PATROL SNMP Master Agent see “Configuringthe PATROL SNMP Master Agent” on page 17.

• turn on the SNMP support variables

The PATROL Agent configuration variable /snmp/agent_auto_start is set to yes, thePATROL Agent starts the SNMP Sub-Agent when the PATROL Agent is started. On Unixthe /snmp/masteragent_auto_start variable must not be set to no.

For more information on configuring the PATROL Agent SNMP support variables see“The PATROL Agent SNMP Support Variables” on page 19.

• add the SNMP manager to the list of interested SNMPV1 managers.

For more information on adding SNMP managers to the list of interested managers see“PATROL Agent SNMP Interested Managers” on page 20.

NoteThe SNMP management console needs to know how to recognize PATROL traps, and

what to do about them. On some consoles it involves configuration of internal rules andtables. In others it may involve configuring the "trapd.conf" configuration file.

• configure events to send SNMP traps

For more information on adding SNMP managers to the list of interested managers see“PATROL Agent SNMP Interested Managers” on page 20.


20/63


Figure 10 shows the process for configuring the PATROL Agent to run with SNMP:

Figure 10 Configuring PATROL for SNMP

Configuring the PATROL SNMP Master Agent

The PATROL SNMP architecture is comprised of an SNMP Master Agent that is a separate

external process and an SNMP Sub-Agent that is part of the PATROL Agent.

The PATROL SNMP Master Agent/Sub-Agent model is based on an industry standard knownas SMUX that allows one or more SNMP Sub-Agents to connect to a single SNMP Master

Agent using a TCP SMUX port (TCP port 199 by default).

The configuration of the PATROL SNMP Master Agent is controlled by the values containedin the PATROL SNMP Master Agent configuration file. Below is the name and path of thisfile:

• On Unix, it is $PATROL_HOME/lib/snmpmagt.cfg.

• On Windows NT, it is %PATROL_HOME%\lib\snmpmagt.cfg.

The PATROL SNMP Master Agent configuration file lists the community name and SNMPlistening port. This configuration file is in ASCII text format, which means you can use anytext editor to effect changes.

An SNMP manager is an application that controls an SNMP Agent by making SNMP

requests of it and setting variables in it. An SNMP Agent is an application that builds internalSNMP structures and provides SNMP information to SNMP Managers in the form of SNMPtraps and responses to SNMP queries.

Set the portnumber andcommunityname for thePATROLSNMP Master

Verify that theSNMP supportvariable is on.

Add the SNMPmanager to thelist of interestedSNMPV1managers.

Set the useraccess, hostaccess, andmode accessfor the SNMPmanager.

Set the severitylevel of eventsthat triggertraps.

Agent.

(default setting)


21/63


The configuration of the PATROL SNMP Master Agent is controlled by the values containedin the PATROL SNMP Master Agent configuration file. The SNMP Master Agent

configuration file is found in the following locations:

• Unix–$PATROL_HOME/lib/snmpmagt.cfg• Windows NT–%PATROL_HOME%\lib\snmpmagt.cfg

Figure 11 on page 18 shows the snmpmagt.cfg file text:

Figure 11 PATROL SNMP Master Agent Configuration File


22/63


The PATROL Agent SNMP Support Variables

There are two PATROL Agent configuration variables that need to be on for the SNMPsupport to start with the PATROL Agent. The /snmp/agent_auto_start variable must be set to

yes for Windows NT and Unix, and the /snmp/masteragent_auto_start variable must not be set

to no on Unix.

Table 12 describes the PATROL Agent configuration variables for starting SNMP support:

For more information on the PATROL Agent configuration variables see “PATROL AgentSNMP Configuration Variables” on page 46.

Table 12 Variables for Starting SNMP with the PATROL Agent

Variable Description

/snmp/agent_auto_start Controls whether SNMP sub-agent is started when the Agent starts.

The default is yes.

/snmp/masteragent_auto_start Whether the SNMPStart parameter should automatically start the SNMP Master Agent.

The SNMPStart parameter is defined within each platform .km the parameter checks to see the SNMP Master Agent is running, and if it is not, it attempts to start it.

The NT.KM executes the following PSL script for the SNMPStart parameter:

requires SNMP_lib;

#

# Attempt to start the SNMP subagent.

# If it fails, attempt to start the

# SNMP master agent.

#

if (snmp_agent_start() == "ERR") {

master_agent_start();

}

The master_agent_start() function is a function in the SNMP_lib PSL library that starts the

SNMP Master Agent.

A value of no prevents the SNMP Master Agent from starting. If the variable has any other value

does not exist, the SNMP Master Agent starts when it is started by the SNMPStart parameter.


23/63


PATROL Agent SNMP Interested Managers

For SNMP support (trap listening) to be active in PATROL, you must enter the SNMPManager as one of the interested managers in the piV1mTable. The list of interested managers

is stored in the PATROL Agent configuration variable /snmp/piV!m_list.

Table 13 describes the PATROL Agent configuration variable for specifying the list ofinterested managers for PATROL SNMP traps:

For more information on the PATROL Agent configuration variables see “PATROL AgentSNMP Configuration Variables” on page 46.

Table 13 The List of Interested Managers for SNMP Traps with the PATROL Agent

Variable Description

/snmp/piV1m_list The list of SNMPV1 managers that are interested in getting automatic SNMP traps from the Age

Each SNMP manager listed here is entered in the piV1mTable in the · Management Information

Base (MIB). The piV1mTable is the dynamic register of interested SNMP managers. Changes ma

to this variable take effect without having to restart the Agent.

The default is that no managers get SNMP traps. Managers are entered in the form

hostname/port/

community. If port or community is omitted, the defaults are 162 and public, respectively

Entries must be separated by commas.


24/63


Variables for Configuring the Agent with SNMP

You configure the Agent to run with SNMP by changing the appropriate variable. Table 14shows each part of the process for configuring the Agent to run with SNMP and lists thesection that contains information about the variable that must be changed.

When Configuration Changes Take Effect

Table 15 shows when changes made to the PATROL SNMP Master Agent configuration filetake effect.

Changes made to the PATROL SNMP Master Agent configuration file are permanent; that is,the changes remain in effect regardless of how many times the PATROL SNMP Master Agentis shut down and restarted.

Table 14 Configuring the Agent to Run with SNMP

You Want to… Find the Variable in This Section…

Set the port number and community name

for the PATROL SNMP Master Agent

“Listening for SNMP Traps” on page 34

Turn on the SNMP support variable. “Changing Whether SNMP Is Started with Agent” on page 54

/snmp/agent_auto_start

Add the SNMP manager to the list of

interested SNMPV1 managers.

“Changing SNMPV1 Managers That Get SNMP Traps from the Agent” on

page 52

/snmp/PiV1m_list

Configure events to send SNMP traps. “Changing the Events That Trigger SNMP Traps” on page 50

standard or custom event catalog

Table 15 When Changes to the Agent Configuration Take Effect

Operating

System When Changes Take Effect

Unix when the SNMP Master Agent is restarted

All non-Unix after you restart the PATROL SNMP Master Agent


25/63


Testing Agent SNMP Trap Sending

Testing is the next step after the PATROL SNMP Agent is configured correctly to send SNMPtraps. The options for testing involve watching for outcoming SNMP traps.

• SNMP manager console—check to see if it is receiving the traps as configured.

• Agent self-testing—run a PSL script in the Agent to receive its own traps and print them.

The logic involving SNMP trap receiving can be used in this way, such as PSLsnmp_trap_listen() and snmp_trap_receive(). Essentially, this procedure setsup the PATROL Agent as an SNMP Agent.

For more information on the PSL snmp_trap_listen() and snmp_trap_receive() functions, refer to the PATROL Script Language Reference Manual.


26/63


The PATROL MIB

The MIB in PATROL is a set of tables that are dynamically built as the agent loads KMs anddiscovers the instances. Since the PATROL discovery is a dynamic process that sometimeshappens on a user request, the id’s of the applications in the MIB will probably be differenteach time the PATROL Agent starts.

The following components of the PATROL MIB tree are discussed in this section:

• objects table

• variables table

• applications table

• instances table trap table

• trap table


27/63


PATROL MIB Tree –Objects Table

The PATROL MIB object table contains all the nodes from the PATROL Agent namespacestarting from the path defined as the objects current working directory (objectsCwd).

Figure 16 shows the basic structure of the PATROL MIB objects table:

Figure 16 The PATROL MIB Tree Objects Table


28/63


PATROL MIB Tree –Variables Table

The PATROL MIB varaible table contains all the leaves from the PATROL Agent namespacestarting from the path defined as the objects current working directory (objectsCwd).

Figure 17 shows the basic structure of the PATROL MIB variables table:

Figure 17 The PATROL MIB Tree Variables Table


29/63


PATROL MIB Tree –Applications Table

The PATROL MIB applications table contains all the applications loaded on the PATROLAgent.

Figure 18 shows the basic structure of the PATROL MIB applications table:

Figure 18 The PATROL MIB Tree Applications Table


30/63


The PATROL MIB application tables can be accessed to find out what applications are loadedon the PATROL Agent. Figure 19 shows how the PSL snmp_walk() function can be used to

print the entries in the PATROL MIB applications table:

Figure 19 The PATROL MIB Tree Applications Example


31/63


PATROL MIB Tree –Instances Table

The PATROL MIB instances table contains all the application instances that have beendiscovered by the PATROL Agent.

Figure 20 shows the basic structure of the PATROL MIB instances table:

Figure 20 The PATROL MIB Tree Instances Table


32/63


The PATROL MIB instance table can be accessed to find out what instances of an applicationhave been discovered by the PATROL Agent. Figure 21 shows how the PSL snmp_walk()

function can be used to print the instances of an application in the PATROL MIB instancetable (all the instances for the PRINTER application):

Figure 21 The PATROL MIB Tree Instances Example


33/63


PATROL MIB Tree –Trap Table

Figure 22 shows the basic structure of the PATROL MIB trap table:

Figure 22 The PATROL MIB Tree Trap Table


34/63


Figure 23 shows the format of the SNMP traps sent by PATROL:

Figure 23 The PATROL MIB Tree Trap Example


35/63


PATROL MIB Tree –Enterprise Traps

Figure 24 shows the PATROL MIB enterprise traps:

Figure 24 The PATROL MIB Enterprise Traps


36/63


Using PSL to Control PATROL and SNMP 25

This section tells you how you can use PSL to control how the PATROL SNMP Master Agent

and the Agent interact with SNMP.

The following are the primary groups of PSL functions for SNMP:

• listening for traps• sending traps• starting and stopping the SNMP sub-agent• getting and setting Management Information Base (MIB) variables• changing the registered SNMP manager list• debugging

PSL functions allow you to manage a number of processes, including starting and stopping

the PATROL SNMP Sub-Agent and changing the list of registered SNMP managers.

Some of these PSL functions are briefly described in this section. Refer to the PATROL Script Language Reference Manual for detailed information about all PSL functions for SNMP.

There is a sample PATROL Knowledge Module SNMP_test.km that demonstrates how to usePSL with PATROL and SNMP. It is available on the BMC Software Developer Connection(DevCon) Web Site at http://devcon.bmc.com.


37/63


Listening for SNMP Traps

During trap listening, the PATROL Agent works as an SNMP manager. Table 26 lists thefunction to use for the task you want to perform.

Sending SNMP Traps

During trap sending, the PATROL Agent works in an SNMP agent role. Table 27 lists thefunction to use for the task you want to perform.

Starting and Stopping the SNMP Sub-Agent

You can stop, restart, and request the current state of the Agent using PSL functions. Table 28 lists the function to use for the task you want to perform.

Table 26 Functions for Trap Listening

Task to be Performed PSL Function to Use

close a trap socket and ignore all unprocessed and/or

arriving trapssnmp_trap_ignore()

capture the arriving traps snmp_trap_receive()

start accumulating incoming traps snmp_trap_listen()

Table 27 Functions for Sending Traps

Task You Want to Perform PSL Function to Use

send any traps to any given SNMP manager snmp_trap_send()

send the trap patrolTrapV1Raised, with

patrolTrapText.0 in a packet, to all entities registered in

the prV1mTable

snmp_trap_raise_std_trap(“text”)

Table 28 Functions for Starting and Stopping the SNMP Agent


request the current state of the SNMP Sub-Agent snmp_agent_config()

restart the SNMP Sub-Agent snmp_agent_start()

stop the SNMP Sub-Agent snmp_agent_stop()


38/63


Getting and Setting MIB Variables

The PATROL Agent can act as an SNMP Manager by getting and setting variables insideSNMP agents through PSL functions. Table 29 lists the function to use for the task you wantto perform.

Notesnmp_h_* functions use port 161 and cannot be configured to use adifferent port.

Table 29 Functions for Getting and Setting MIB Variables


close the session with SNMP agent snmp_close()

list SNMP sessions that are currently open, return default

parameters for a specific snmp session, or alter the default

settings for an SNMP session

snmp_config()

fetch MIB variables from an SNMP agent snmp_get(), snmp_get_next(), or snmp_walk()

You can also use snmp_h_* functions. The snmp_h_*

functions accept host name instead of session and

automatically open and close the session.

open a session to an SNMP agent by locating the host and

creating an internal structure with default informationsnmp_open()

set MIB variables snmp_set()

You can also use snmp_h_* functions. The snmp_h_*

functions accept host name instead of session and

automatically open and close the session.


39/63


Using PSL to Change the Registered SNMP Manager List

The list of registered SNMP Managers is contained in the PiV1mTable. Table 30 lists thefunction to use for the task you want to perform.

Debugging PSL Functions for SNMP

Use the snmp_debug ( flags) function to debug the PSL you write. The snmp_debug ( flags)function accepts a binary flag (0, 1, 2, or 3) that activates PSL SNMP debugging features. Itreturns the old settings or NULL indicating an error. Table 31 lists the function to use for thetask you want to perform.

Table 30 Functions for Changing the Registered SNMP Manager List


add an SNMP Manager to the list snmp_agent_register_im()

delete an SNMP manager from the list snmp_agent_register_im()

print the list of SNMP Managers snmp_agent_register_im()

Table 31 Functions for Debugging PSL Functions

Task You Want to Perform snmp_debug ( flags) Function to Use

dump all in/out packets on stdout when the agent is in

no-daemon modesnmp_dump_packet (1)

get error information that may not be reported to the console

window, such as timeoutssnmp_report_error (2)


40/63


Interpreting Error Messages from PSL Functions

Table 32 describes global error messages for PSL functions for SNMP. They are consideredglobal because any SNMP PSL function can generate one of these messages.

When an error occurs, the user does not see any of the error messages in Table 32. A user sees

nothing since all SNMP PSL functions return the NULL string after encountering an error. Auser can determine which error occurred most recently by displaying or printing the value ofthe PATROL PSL error variable. This variable holds an integer that corresponds to one of theerror messages above.

The PATROL Script Language Reference Manual provides more information on working witherror messages.

Table 32 Global Error Messages for SNMP PSL Functions

Error Message Description

E_PSL_BAD_FUNCTION_PARAMETER A function fails to parse a parameter, which could be

caused, for example, by a bad address or trap definition.

E_PSL_SNMP_ERROR A function tries to send or receive an invalid packet to or

from another SNMP entity.

E_PSL_SNMP_NOT_SUPPORTED SNMP support is turned off.

NULL If an error occurs, a function returns a null string or “ ”.


41/63


Using SNMP to Send Traps 33

This section discusses several methods of using the SNMP support in a PATROL environment

to send traps and problem notification to other SNMP management consoles, to receive andhandle traps within the PATROL Agent, and to gather PATROL data from the PATROL MIBstatic tables.

Methods of Sending SNMP Traps

Sending SNMP traps to an SNMP management console is a common method for thenotification of critical events detected in the PATROL environment. SNMP traps can also besent to a number of third-party products.

These are methods of sending SNMP traps in the PATROL Agent:

• using the agent to send a SNMP trap based on TRAP_SEND and NO_TRAP settings in

event definitions

• using the PATROL Script Language (PSL) to send an SNMP trap

Table 34 compares the differences between the SNMP trap sending methods.

Table 34 Comparing Methods for Sending Traps

SNMP Trap Features PEM Traps PSL Traps

requires configuration of out-of-box

install

yes yes

any trap format possible no yes

enterprise OID can be changed no yes

different OID possible for each KM

class

no yes

trap message can be

configured/changed

no yes

number of different trap formats

possible

two unlimited

methods of controlling format of these

traps

event catalog settings and Agent

configuration

PSL coding, almost unlimited options

situations causing trap sending generation of an event in the

associated event class

any method of PSL execution


42/63


PATROL Event Manager and SNMP Traps

The PATROL Event Manager (PEM) associates the individual SNMP trap configurationsettings with each event class. This applies to both the Standard Event Catalog and anyapplication-specific event catalog created for a KM.

For each event class, the settings of NO_TRAP or SEND_TRAP has been added to specifywhether the agent will send an SNMP trap when the event is created. This allows more

control over the number of SNMP traps and causes of SNMP traps. However, you have littlecontrol over the format of the SNMP traps. For example, you can not control theevent-specific sub ID, or the enterprise ID used.


43/63


Standard Event Classes

Table 35 lists all the standard event classes. These event classes can be useful for sendingSNMP traps in other situations, such as a console disconnecting.

Table 35 Standard Event Classes for Sending SNMP Traps (Part 1 of 2)

Event Class Meaning

RegApp New KM class is now registered and running in the agent (e.g. When a new console connects

requesting the KMs that it is interested in viewing).

UpdAppState new or updated application state.

WorstApp This application now has the worst state of all applications in the agent.

UpdParState new or updated parameter state.

UpdInstState new or updated instance state.

UnregAllApp Unregister all applications.

UpdMachineState new or updated state for the entire agent (due to some change in the state of an application).

Diag Diagnosis event.

RemPsl Used by remote PSL execution.

Result Used by remote PSL execution.

PslSet Used for remote PSL set execution.

RemProcess Used in remote PSL file transfer and the API.

EventArchive Events have been archived.

Disconnect Console disconnected from agent.

Unload KM class was unloaded by agent.

R3FilterData Used by the SAP R/3 KM only.

1 Agent’s overall state has changed for this agent machine.

2 Worst application class name is provided in this event, when the agent’s state has changed.

3 Worst application instance name is provided in this event, when the agent’s state has changed.

4 Discovery has been started for a KM class.

5 Discovery has been disabled for a KM class.

6 agent and console have different version of a KM.

7 Successful connection to the agent by a user. (i.e. A normal console connection or one involving the

API or PSL remote functions).

9 Alarm is cancelled because the condition regarding the parameters violating its thresholds has

disappeared. In other words, the parameter’s value is no longer a bad value that causes an alarm, andthe parameter is going back to the OK state.

10 Recovery action has been executed for the parameter.

11 Parameter value has exceeded the alarm range thresholds. This will raise a warning or alarm state for

this parameter.

12 All recovery actions have executed and failed to resolve the problem. The parameter will stay in its

current state. Agent will not execute any more recovery actions for this parameter.


44/63


13 Suspended all parameters of this KM class.

14 or 15 Restar ting all local and global parameters of the KM class.

16 Parameter description has been modified (i.e. KM editing) and the parameter state is reset to OK.17 or 18 Global parameter has started.

19 Local parameter has started.

20 Parameter had bad output. For example, PSL set on “value” did not provide an integer to a graph or

gauge parameter.

21 Local parameter is suspended and will no longer run.

22 or 23 Global parameter is suspended and will no longer run.

24 Agent process cache cycle changed.

25 Agent process cache cycle changed.

26 or 27 Application discovery is disabled for this KM class.

28 Username/password were invalid to connect to the Agent (e.g. through the API or PSL remote

functions).

29 Internal agent or PEM failure of some type.

38 Parameters of a KM were restarted.

39 Parameter threshold was exceeded by parameter value. State change event.

40 PSL response-related event. Created when a PSL response function is launched by the agent.

41, 42, or 43 Information event. Placeholder for user-defined events. Not generated internally by the agent.

Table 35 Standard Event Classes for Sending SNMP Traps (Part 2 of 2)

Event Class Meaning


45/63


Configuring the Event Catalog for SNMP Traps

The times when an agent can send automatic SNMP trap is tightly controlled by the settingsin the Standard Event Catalog.

The Standard Event Catalog specifies which events send SNMP traps on the creation of the

event.

Table 36 lists the commonly used main event classes.

By knowing under which circumstances various events are generated, you can choose whenSNMP traps are sent. Table 37 maps common situations to the events that the agent creates.

NoteSome exceptions exist. For example, if a PSL set() directly changes thestatus variable of a parameter to ALARM, this causes an UpdParState forthe state change, but not an alarm range threshold exceeded event of type11.

Table 36 Event Classes Used in Sending SNMP Traps

Event Class Description

UpdParState Update status of a parameter.

UpdInstState Update status of an instance.

UpdAppState Update status of an application class.

9 Parameter alarm cancelled, the exception no longer exists.

11 Parameter value exceeds the alarm range threshold value.

Table 37 Events Created by an Agent State Change

Agent State Change Situation Event Class Created

parameter changes state from OK to WARN/ALARM UpdParState and 11

parameter changes from WARN/ALARM to OK UpdParState (but not 9)

instance changes state from OK to WARN/ALARM UpdInstState

instance changes state from WARN/ALARM to OK UpdInstState

application class state changes (any) UpdAppState


46/63


Altering Event Classes for Trap Notification

Table 38 lists the most commonly used event classes for trap notification about state changes.

Configuring the List of Recipients for SNMP Traps

The recipient list of SNMP traps is set in the agent configuration. The /snmp/piV1m_list variable contains a comma separated list of hostnames and/or IP addresses, which representSNMP trap destinations. For more information on changing the /snmp/piV1m_list

variable, see “Changing SNMPV1 Managers That Get SNMP Traps from the Agent” on page52.

NoteThis list of trap destinations does not affect the recipients of SNMP traps

sent by PSL snmp_trap_send().

Table 38 Most Common Event Classes for Trap Notification

Event Class Purpose Standard Event Catalog Trap Settings

UpdParState new or updated parameter state NO_TRAP

UpdInstState new or updated instance state NO_TRAP

UpdAppState new or updated application state NO_TRAP

UpdMachineState new or updated state for entire agent NO_TRAP

9 alarm is cancelled, parameter back to OK SEND_TRAP

11 parameter exceeds threshold; triggered alert SEND_TRAP


47/63


Configuring the Agent for SNMP Trap Sending

In order to use the agent to send SNMP traps you must enable them in the agentconfiguration. Table 39 lists the configuration variables used for sending SNMP traps.

Table 39 Configuration Variables Used for Sending SNMP Traps (Part 1 of 2)

Agent Configuration Variable Purpose

/snmp/masterAgentStartLine starts the PATROL SNMP Master Agent

/snmp/masterAgentWorkingDir directory for the PATROL SNMP Master Agent

/snmp/agent_auto_start starts the SNMP sub-agent support when the PATROL Agent starts

It requires that the PATROL SNMP Master Agent be running in order to

successfully complete.

/snmp/masteragent_auto_start whether to automatically start SNMP Master Agent

Available only to the agent on Unix. A no value prevents the SNMP Master Agent

from starting. If the variable does not exist, the SNMP Master Agent should start.

/snmp/agent_r_community reads community string for PATROL SNMP Master Agent operations

/snmp/agent_w_community writes community string for PATROL SNMP Master Agent operations

/snmp/sysName value of MIB-II system.sysName

/snmp/sysContact value of MIB-II system.sysContact

/snmp/sysLocation value of MIB-II system.sysLocation

/snmp/trapConfTable whether to issue SNMP traps to managers of the pre-configured list in the

PATROL SNMP Master Agent configuration file

/snmp/trapMibTable whether to issue SNMP traps to managers of the pre-configured list in the

PATROL SNMP Master Agent configuration file

/snmp/masterAgentName name of the PATROL SNMP Master Agent executable file

/snmp/masterAgentDir directory containing the PATROL SNMP Master Agent executable file

/snmp/masterAgentConfigName name of PATROL SNMP Master Agent configuration file

/snmp/masterAgentConfigDir directory containing the PATROl SNMP Master Agent configuration file

/snmp/masterAgentParamName name of PATROL SNMP Master Agent nonvolatile information file

/snmp/masterAgentParamDir directory containing the PATROL SNMP Master Agent nonvolatile information file

/AgentSetup/localPortForRemoteOpen contains the local UDP port-number for the agent

The PSL remote_open() function uses this information to work through a firewall.

If this variable is not set (the default), the system chooses an arbitrary port to

use. This port must not be the same as the agent’s main port. For more about

remote_open(), see the PATROL Script Language Reference Manual .

/AgentSetup/pemPFSnmpNode node where the event occurred

/AgentSetup/pemPFSnmpNSeverity severity level that triggers SNMP traps

/AgentSetup/pemPFSnmpOrigin application where the event occurred

/AgentSetup/pemPFSnmpEidRange range of event IDs to filter

/AgentSetup/pemPFSnmpEvClass event class to filter

/AgentSetup/pemPFSnmpStartTime start time

/AgentSetup/pemPFSnmpEndTime end time


48/63


NotePay special attention to the SNMP listening port that controls access tothe PATROL SNMP Sub-Agent from an external SNMP Manager(s).

This port is not set by the snmp/master_agent_port variable or, for thatmatter, any agent configuration variable. Instead it is defined in theSNMP Master Agent configuration file,$PATROL_HOME/lib/snmpmagt.cfg.

For more information on the variables contained in the agent configuration, see “PATROLAgent SNMP Configuration Variables” on page 46 for more information on changing theagent configuration see the PATROL Agent Reference Manual.

/AgentSetup/pemPFSnmpPattern pattern to filter in the description of the event

/AgentSetup/pemPFSnmpTypeMask type tags

/AgentSetup/pemSnmpSupport whether PEM triggers SNMP events /AgentSetup/pemPFSnmpStatusMask status tags

/AgentSetup/pemIssueV31traps whether PATROL uses version 3.1 formats to send SNMP traps

/AgentSetup/pemIssueV30traps whether PATROL uses version 3.0 formats to send SNMP traps

/AgentSetup/snmpConfigAccess whether SNMP support can write to the configuration database

/snmp/accessControlList list of hosts for SNMP

/snmp/support whether SNMP support is available

/snmp/piV1m_list list of SNMPV1 managers to receive automatic state-change SNMP traps from

the PATROL Agent

/snmp/mibFileName MIB file that the PATROL Agent loads for PSL SNMP management functions

/snmp/trap_port UDP port number for SNMP trap listening

/snmp/default_r_community default community name for SNMP get and getnext operations in PSL

/snmp/default_w_community default community name for SNMP set operations in PSL

/snmp/default_retries number or retries for PSL and SNMP operations

/snmp/default_timeout timeout value in milliseconds for PSL and SNMP operations

Table 39 Configuration Variables Used for Sending SNMP Traps (Part 2 of 2)

Agent Configuration Variable Purpose


49/63


PATROL Agent SNMP ConfigurationVariables 40

The PATROL Agent configuration variables are set in the PATROL configuration file(config.default). The PATROL Agent configuration file is located in the following directories:

• Unix–$PATROL_HOME/lib/config.default

• Windows NT–%PATROL_HOME%\lib\ config.default

The config.default file is a text file that lists and defines the PATROL Agent configurationvalues. The Figure 41 shows the format for setting values in the PATROL configuration file:

Figure 41 PATROL Agent Configuration File Example

"/snmp/support" = { REPLACE="yes" },

"/snmp/agent_auto_start" = { REPLACE="yes" },

"/snmp/default_port" = { REPLACE="161" },

"/snmp/master_agent_port" = { REPLACE="1161" },

"/snmp/trap_port" = { REPLACE="162" },

"/snmp/sysName" = { REPLACE = "unknown" },

"/snmp/sysContact" = { REPLACE = "http://www.bmc.com" },

"/snmp/sysLocation" = { REPLACE = "BMC Software Inc." },

"/snmp/piV1m_list" = { REPLACE="" },

"/snmp/support" = { REPLACE="yes" },

"/snmp/agent_auto_start" = { REPLACE="yes" },

"/snmp/default_port" = { REPLACE="161" },

"/snmp/master_agent_port" = { REPLACE="1161" },

"/snmp/trap_port" = { REPLACE="162" },

"/snmp/sysName" = { REPLACE = "unknown" },

"/snmp/sysContact" = { REPLACE = "http://www.bmc.com" },

"/snmp/sysLocation" = { REPLACE = "BMC Software Inc." },

"/snmp/piV1m_list" = { REPLACE="" },


50/63


Table 42 lists some of the more important PATROL Agent configuration variables for SNMPsupport:

Items That Cannot Be Changed

Table 43 lists the values for those items that cannot be changed:

Table 42 Important SNMP PATROL Agent Configuration Variables

Variable Description Page

/snmp/support indicates if SNMP is turned on 1-51

/snmp/agent_auto_start indicates if the SNMP sub-agent is started when the Agent starts 1-55

/snmp/default_port the default port number that the PATROL Agent uses to open sessions with SNMP

agents

1-54

/snmp/master_agent_port the default listening port for the master agent (1161) 1-48

/snmp/trap_port the UDP port number for SNMP trap listening (162) 1-52

/snmp/sysName the value of MIB-II system.sysName 1-48

/snmp/sysContact The value of MIB-II system.sysContact 1-48

/snmp/sysLocation The value of MIB-II system.sysLocation 1-48

/snmp/piV1m_list the list of SNMPV1 managers that are interested in getting automatic SNMP trapsfrom the Agent

1-52

Table 43 Variables That Cannot be Changed

Item Variables

PATROL Agent Setup /AgentSetup/_name_

PATROL Agent setup type /AgentSetup/_type_

PATROL Agent tuning name AgentSetup/AgentTuning/_name_

PATROL Agent tuning type AgentSetup/AgentTuning/_type_

SNMP name /snmp/_name_

SNMP type /snmp/_type_


51/63


Changing the PATROL Master Agent Directory and StartLine

BMC Software recommends changing the configuration information for the PATROL MasterAgent using PSL. For more information, refer to the PATROL Script Language Reference

Manual for the functions to use to change the PATROL Master Agent configuration.

You can control the working directory for the PATROL Master Agent and the start line(command string) that starts the PATROL Master Agent. Use Table 44 to find the variable forthe item you want to change.

Table 44 Changing the PATROL SNMP Master Agent and Start Line (Part 1 of 2)

Item You Want to Change Variable to Change Additional Information

The command that is used on a Unix system to

start the PATROL Master Agent

/snmp/masterAgentStartLine This variable is for Unix platforms

only.

The working directory for the PATROL Master Agent

(contains the PATROL Master Agent executable file)

on Unix

/snmp/masterAgentWorkingDir This variable is for Unix platforms

only. This directory must contain

the start line for the PATROL

Master Agent on Unix.

Whether the SNMP Agent support (SNMP

sub-agent) is started when the PATROL Agent

starts.

/snmp/agent_auto_start No means don’t start SNMP

sub-agent automatically on Agent

startup

Default: yes

The read community string for PATROL SNMP

Agent (PATROL Master Agent) operations

/snmp/agent_r_community Default: public

The write community strings for PATROL SNMP

Agent (PATROL Master Agent) operations

/snmp/agent_w_community Default: private

Default listening port /snmp/master_agent_port Default: 1161

The value of MIB-II system.sysName /snmp/sysName Default: unknown

The value of MIB-II system.sysContact /snmp/sysContact Default: http://www.bmc.com

The value of MIB-II system.sysLocation /snmp/sysLocation Default: BMC Software Inc.

Whether or not to issue SNMP traps to the

managers of the pre-configured list

(snmp_trap_register_in) in the PATROL Master

Agent configuration file.

/snmp/trapConfTable Default: no

Whether or not to issue SNMP traps to the

managers of the pre-configured list in the PATROL

Master Agent configuration file.

/snmp/trapMibTable Default: yes

Name of the PATROL Master Agent executable file. /snmp/masterAgentName This is used to build the start line.

Default: snmpagt

Name of the directory that contains the PATROL

Master Agent executable file.

/snmp/masterAgentDir This is used to build the start line.

Default: bin


52/63


Name of the PATROL Master Agent configuration

file.

/snmp/masterAgentConfigName This is used to build the start line.

Default: snmpagt.cfg

Name of the directory that contains the PATROLMaster Agent configuration file.

/snmp/masterAgentConfigDir This is used to build the start line.

Default: lib

Name of the PATROL Master Agent nonvolatile

information file.

/snmp/masterAgentParamName This is used to build the start line.

Default: NOV

Name of directory that contains the PATROL Master

Agent nonvolatile information file.

/snmp/masterAgentParamDir This is used to build the start line.

Default: log

Table 44 Changing the PATROL SNMP Master Agent and Start Line (Part 2 of 2)



53/63


Changing the Events That Trigger SNMP Traps

Use Table 45 to find the variable for the item you want to change.

Table 45 Variables for Events That Trigger SNMP Traps (Part 1 of 2)

Item You Want toChange Variable to Change Additional Information

Node where the event

occurred

/AgentSetup/pemPFSnmpNode This variable is reserved for future use.

Severity level that

triggers SNMP traps

/AgentSetup/pemPFSnmpNseverity Only events that are at or above the specified level trigger

SNMP traps.

The default is 1.

Application where the

event occurred

/AgentSetup/pemPFSnmpOrigin Use “” for any origin (default).

Range of event IDs

you want to filter

/AgentSetup/pemPFSnmpEidRange Valid range values are as follows:

• x reduced to the value of x• x/y any value between and including x and y

• -/y any positive value equal to or less than y

• x/- any positive value equal to or greater than x

where x is a positive cardinal value smaller than

xFFFFFFFF and y is any positive cardinal value smaller

than xFFFFFFFF (default value).

Event class you want

to filter

/AgentSetup/pemPFSnmpEvClass You can use either the exact match of an event class or

“” for any class (default).

Star t time /AgentSetup/pemPFSnmpStar tTime The string is of the form MMddhhmm[yy|yyyy] or “” for

any time.

End time /AgentSetup/pemPFSnmpEndTime The string is of the form MMddhhmm[yy|yyyy] or “” for

any time (default).

Pattern you want to

filter for in the

description of the

event

/AgentSetup/pemPFSnmpPattern For example, if you specify recovery, only events with a

description containing recovery will trigger SNMP traps.

Type tags /AgentSetup/pemPFSnmpTypeMask Valid type tags:

• S (change status)• E (error)• W (warning)• A (alarm)• R (response)• I (information)

The default is all tags.

In the following example, only events of type ALARM or

WARNING trigger SNMP traps:“/AgentSetup/pemPF

SnmpTypeMask” =

{REPLACE=”A,W”}

Whether PEM triggers

SNMP events

/AgentSetup/pemSnmpSupport If NO is selected, no SNMP trap are generated.


54/63


Changing Whether PSL Supports SNMP


Status tags /AgentSetup/pemPFSnmpStatusMask This variable specif ies a comma-separated event status

mask string containing one or more status tags.

Valid status tags:• O (opened)• A (acknowledged)• C (closed)• E (escalated)• D (deleted)

The default is all status tags.

Whether PATROL

uses PATROL Version

3.1 formats to issue

SNMP traps

/AgentSetup/pemIssueV31traps If this variable is set to yes, the agent uses PATROL

Version 3.1 formats to issue SNMP traps. The 3.1 format

contains additional information that can be used by the

SNMP Management Station.

If both the /AgentSetup/pemIssue

V30traps variable and the /AgentSetup/pemIssue

V31traps variable are enabled, the agent sends twoSNMP flags.

Whether PATROL

uses PATROL Version

3.0 formats to issue

SNMP traps

/AgentSetup/pemIssueV30traps If this variable is set to yes, the agent uses PATROL

Version 3.0 formats to issue SNMP traps.

This variable is provided for backward compatibility.

Table 46 Variables for Whether PSL Supports SNMP


Whether SNMP is turned

on

/snmp/support The default is yes.

Table 45 Variables for Events That Trigger SNMP Traps (Part 2 of 2)



55/63


Changing SNMPV1 Managers That Get SNMP Traps fromthe Agent


Changing the MIB File That the Agent Uses for SNMP


Changing Port Information for PSL SNMP Functions


Table 47 Variables for SNMPV1 Managers Receiving SNMP Traps


List of SNMPV1 managers that are

interested in getting automatic SNMP

traps from the Agent

/snmp/piV1m_list Each SNMP manager listed here is

entered in the piV1mTable in the ·

Management Information Base (MIB).

The piV1mTable is the dynamic register

of interested SNMP managers.

Changes made to this variable take

effect without having to restart the

Agent.

The default is that no managers get

SNMP traps. Managers are entered in

the form hostname/port/community. If port or community

is omitted, the defaults are 162 and

public, respectively. Entries must be

separated by commas.

Table 48 Variables for the MIB File Used for SNMP


The MIB file that the Agent loads for

PSL SNMP management functions

/snmp/mibFileName The default is patrol.mib.

If no MIB file is specified, the agent

uses mib.txt.

Table 49 Variables for Port Information for PSL SNMP Functions


UDP port number for SNMP trap

listening

/snmp/trap_port The default is 162.


56/63


Changing Community Names for SNMP Operations


Table 50 Variables for Community Names for SNMP Operations


Community name for SNMP get and

getnext operations in the SNMP agent

support

/snmp/agent_r_community This community name should be the

same as the community name specified

for SNMP get and getnext operations in

the configuration file for the PATROL

Master Agent.

BMC Software recommends that you

do not change this default.

The default is public.

Community name for SNMP set

operations in the SNMP agent support

/snmp/agent_w_community This community name should be the

same as the community name specifiedfor SNMP set operations in the

configuration file for the PATROL

Master Agent.



The default is private.

Default community name for SNMP get

and getnext operations in PSL

/snmp/default_r_community This community name should be the


for PSL SNMP get and getnext

operations in the configuration file for

the PATROL Master Agent.



The default is public.

Default community name for SNMP set

operations in PSL

/snmp/default_w_community This community name should be the


for PSL SNMP set operations in the

configuration file for the PATROL

Master Agent.



The default is private.


57/63


Changing Retry and Timeout for PSL and SNMPOperations


Changing Whether SNMP Is Started with Agent


Table 51 Variables for Retry and Timeout for PSL and SNMP


Number of retries for PSL and SNMP

operations.

/snmp/default_retries The default is 3 retries before the

operation fails.

Timeout value in milliseconds for PSL

and SNMP operations.

/snmp/default_timeout The default is 500 milliseconds.

Default port number which the PATROL

Agent uses to open sessions with

SNMP agents. See “Getting and

Setting MIB Variables” on page 1-35.

/snmp/default_port The default port is 161.

Table 52 Variables for Starting SNMP with the PATROL Agent


Whether SNMP sub-agent is started

when the Agent starts.

/snmp/agent_auto_start The default is yes.

Whether the SNMPStart parameter

should automatically start the SNMP

Master Agent.

/snmp/masteragent_auto_start Available only to the agent on Unix. A

no value prevents

the SNMP Master Agent from starting.

If the variable has any other value or

does

not exist, the SNMP Master Agent

should start.


58/63


Appendix A: ASN.1 53

Abstract Syntax Notation One (ASN.1) standard syntax is a type declaration language,

adopted by SNMP to define MIB objects. To explore the SNMP MIB, a user can examine theASN.1 definitions to see the object type, access, and descriptions of MIB objects.

SNMP administrators study the ASN.1 files to determine the capabilities provided by privateMIB objects. While ASN.1 is a complex language, SNMP only uses a simple subset of theASN.1 syntax. SNMP uses ASN.1 to define the following objects:

• branches• leaf objects

Branch Object Identifiers

Some SNMP objects have no value, and just serve as directories that contain other objects.Branches are defined using the OBJECT IDENTIFIER statement:

myBranch OBJECT IDENTIFIER ::= { parentBranch 100}

The following table describes the elements of the branch definition:

Since each branch reference its parent branch, you can trace back through the ASN.1 file todetermine the parent of each branch until you reach the root “internet” branch.

Element Description

myBranch the name of the branch, or directory, that is created

OBJECT IDENTIFIER the ASN.1 keyword that identifies this as a branch

parentBranch the parent branch of the branch being created

100 the unique object identifier (OID) for the branch under the parent branch


59/63


Leaf Objects

With a branch the user can define more branches or leaf objects that have specific values. Inthe object definitions the white space is ignored, but the definitions usually conform to aparticular style to make them more readable. The following syntax defines an SNMP objectwith a specific value:

(objectname) OBJECT-TYPE

SYNTAX (syntax)

ACCESS (access)

DESCRIPTION (description)

::= { (parent) (number) }

The following table describes the elements of the object definition:

Element Description

(objectname) the official object name of the SNMP object

ASN.1 requires that all object names begin with a lower-case letter.

Usually, the name is a mixture of upper and lower case letters.

OBJECT-TYPE a required keyword that is always present in any leaf object definition

SYNTAX a required keyword that indicates the following token is the type of object

being defined

The SYNTAX defines the type of object which should not be confused with

the OBJECT-TYPE keyword that defines the type of ASN.1 declaration.

(syntax) the type of object

A variety of object can be defined. ASN.1 requires that all object types

start with an upper-case letter. See “Object Syntax Definitions” on page57 for more information on objects.

ACCESS a required keyword that indicates the following token defines the access to

the object

(access) the access to the object

The access is usually one of the following values:

• read-only• read-write• write-only• no-accessNew access types have been added in recent versions of SNMP, but the

basic types apply to management software, and the new types are usually

not a concern to the administrator.

DESCRIPTION a required keyword that indicates the description follows

(description) the text description of the object that is used as commentary in the file

The description is a quoted string that can span multiple lines of the

ASN.1 file. The description is supplied by the designer of the SNMP

agent, and the description documents the MIB value supported by the

agent.


60/63


In addition to these required object definitions, an object can also have other keywords suchas STATUS, UNITS, or INDEX. These optional fields may or may not be used by a networkmanager, depending on the network management software.

These ASN.1 definitions reflect the characteristics of values supported by the SNMP agent.

The SNMP agent characteristics are not changed by changes to the objects definition. For

example, you could change the name of the object without affecting the agent operation, andit is common for a network administrator to make changes to an objects ASN.1 definition andcompile these changes into the management software.

NoteWhen making changes to a MIB object, the location of the object in theMIB, that is defined with the “::=” operator, cannot be changed. If youmake such a change to the ASN.1 file the network management softwarewill no longer be able t

integrating patrol® with snmp

Documents