Integrating PATROL with SNMP

Integrating PATROL with SNMP February 2000

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............................. 5 MIB 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 Integrating PATROL with SNMP ii

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........................ 22 The PATROL MIB...................................... 23 PATROL MIB Tree Objects Table...................... 24 PATROL MIB Tree Variables Table..................... 25 PATROL MIB Tree Applications Table.................. 26 PATROL MIB Tree Instances Table..................... 28 PATROL MIB Tree Trap Table........................ 30 Using PSL to Control PATROL and SNMP Listening for SNMP Traps............................... 34 Sending SNMP Traps................................... 34 Starting and Stopping the SNMP Sub-Agent................. 34 Getting and Setting MIB Variables......................... 35 Using PSL to Change the Registered SNMP Manager List...... 36 Debugging PSL Functions for SNMP....................... 36 Interpreting Error Messages from PSL Functions.............. 37 Using SNMP to Send Traps Methods of Sending SNMP Traps.......................... 38 PATROL Event Manager and SNMP Traps.................. 39 Standard Event Classes.................................. 40 Configuring the Event Catalog for SNMP Traps........... 42 Altering Event Classes for Trap Notification................. 43 Configuring the List of Recipients for SNMP Traps............ 43 Configuring the Agent for SNMP Trap Sending............... 44 PATROL Agent SNMP Configuration Variables Items That Cannot Be Changed............................ 47 Changing the PATROL Master Agent Directory and Start Line......................................... 48 Changing the Events That Trigger SNMP Traps............... 50 Changing Whether PSL Supports SNMP.................... 51 Changing SNMPV1 Managers That Get SNMP Traps from the Agent......................................... 52 Changing the MIB File That the Agent Uses for SNMP......... 52 Changing Port Information for PSL SNMP Functions.......... 52 Changing Community Names for SNMP Operations........... 53 Changing Retry and Timeout for PSL and SNMP Operations.... 54 Changing Whether SNMP Is Started with Agent.............. 54 Appendix A: ASN.1 Branch Object Identifiers................................ 55 Leaf Objects........................................... 56 Object Syntax Definitions............................. 57 Integrating PATROL with SNMP iii

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 implementing SNMP in your PATROL environment. This paper explains what components of the PATROL Agent are required to implement SNMP, why these components are required, and how to access the PATROL MIB and other MIBs using the PATROL Agent. The following topics are covered: SNMP an Introduction.................................... 2 PATROL SNMP Implementation........................... 12 Configuring PATROL for SNMP........................... 16 Using PSL to Control PATROL and SNMP................... 33 Using SNMP to Send Traps............................... 38 PATROL Agent SNMP Configuration Variables............... 46 Appendix A: ASN.1..................................... 55 Integrating PATROL with SNMP 1

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. Three solutions 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-term solution. SNMP has been very successful because it is light and flexible. Since SNMP is a light-weight communications 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 are monitored 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 security methods led to V2 dropping its security solution. However, V2 did manage to fix some bugs and introduce new data types and message formats. Recently, V3 has been proposed and provides a security solution. This paper address SNMP V1 with little reference to V2 tolerance. Integrating PATROL with SNMP 2

The SNMP Standard SNMP can be viewed in many different ways, but the perspective presented here will be that SNMP 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 messages are 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 generally hidden by the network management software. This part of the standard is highly involved and of 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 managed object, set values on the managed object, and allow the managed object to communicate with the network manager: get request get next request set request trap message PDU SNMP works very simply. It exchanges network information through messages (technically known 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 reading terminal data, one deals with setting terminal data, and one is used for monitoring network events 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 to send out a read PDU to that terminal. If the terminal was attached to the network, you would receive back the PDU, its value being yes, the terminal is attached. If the terminal was shut off, you would receive a packet sent out by the terminal being shut off informing you of the shutdown. In this instance a trap PDU would have been dispatched by the terminal. Integrating PATROL with SNMP 3

Get Request Specific vales can be obtained from a device using the get request. Typically, many different values can be obtained from a device using SNMP without the overhead associated with logging 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 a device to discover all the names and values that the device supports. This is accomplished by starting with the value of the first SNMP object and then using the get net request until there are 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. This allows the device to notify the manager of specific problems. Typically, the use of traps requires each device on the network to be configured to issue SNMP traps to one or more network 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 identifier expressed in dot notation. The list of SNMP objects and their values is often referred to as the SNMP Management information Base (MIB). The MIB is simply an abstraction like database that represents all the 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 the governing specifications for SNMP). The standard MIB includes various objects to measure and 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 was booted is represented as one of the following values: sysuptime 1.3.6.1.2.1.1.3.0 Integrating PATROL with SNMP 4

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 MIB objects. MIB Structure and Objects To use SNMP effectively, users need to become acquainted with the SNMP MIB which defines 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 determines what 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 as passwords required for to SNMP objects to be manipulated. Community names exist to allow portions of the MIB and object subsets to be referenced. As the term community implies, the true purpose of these values is to identify commonality between SNMP object sets. Is is common to make the community strings obscure to limit access to SNMP capability by outside users. MIB Tree Structure The SNMP MIB is arranged in a tree-structure, similar to the directory structure of files on a disk. The top-level SNMP branch begins with the ISO internet directory that contains four branches: mgmt this branch contains the standard SNMP objects that are supported by most network devices. private this branch contains the extended SNMP objects that are defined by network equipment 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 MIB tree are constant, and all other MIBs are added to those branches. Figure 3 on page 6 shows the top of the MIB object tree: Integrating PATROL with SNMP 5

Figure 3 MIB Object Tree The tree structure is an integral part of the SNMP standard. and the most important parts of the 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 tree structure. 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 table objects have a.instance (dot-instance) extension where the instance is a number greater than 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 a current value/state of a device. that make them particularly useful for scanning information from a network for the purposes of comparing device performance. These are the end points in the MIB tree. Integrating PATROL with SNMP 6

Table Objects SNMP tables are special types of SNMP objects that allow parallel arrays of information to be supported. Tables are distinguished from discrete objects because they can grow without bounds. For example, SNMP defines the ifdescr object (a standard SNMP object) that indicates 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 an array 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. Several constraints are placed on SNMP objects: Each object in the Entry directory of a table must contain the same number of elements as other objects in the same Entry directory where the instance numbers of all entries are the same. Table objects are always regarded as parallel arrays of data. When creating a new Entry object, SNMP requires that a value is associated with each table 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 a control element that is documented to perform the table deletion. (This applies only if the row 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 shows how the PSL snmp_walk() function would access the MIB table using the OID as an index into the table: Figure 4 MIB Table Indexing Integrating PATROL with SNMP 7

MIB Object Types All MIB objects have specific value types. Table 5 list the primitive object types defined by SNMP: Table 5 Type Text Counter Gauge Integer EnumVal Time Object IPAddr PhysAd String Table Branch MIB Object Types Description A DisplayString type that can contain textual information (usually limited to 256 characters). The text must contain only printable characters. A numeric value that can only increase. 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. A basic integer value that can contain either positive or negatives values. Usually, this value is supplanted by Counter or Gauge values. A enumerated value that associates a textual label with a numeric value. This type is common in the standard MIB. 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. 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. 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. 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. 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 hexadecimal values 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. 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. A value that defines an SNMP branch that contains additional SNMP objects. Integrating PATROL with SNMP 8

Compiling MIB Objects One of the principle components of an SNMP manager is a MIB compiler that allows new MIB 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 the new objects that are supported by agents on the network. The concept is similar to adding a new schema to a database. The agent is not affected by the MIB compilation since it is already 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 standard object 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 could add 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 specially formatted text files using Abstract Syntax Notation One (ASN.1) standard syntax. ASN.1 is a type 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. Note The MIB of a device is usually constructed by the network equipment vendor and is static and cannot be modified. The addition of MIB objects refers to SNMP management software. SNMP management software becomes aware of the MIB values supported by a device by compiling a description of the device into the network management program. Integrating PATROL with SNMP 9

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 with SNMP and ANMP objects. Typically, an SNMP manager will provide the following functionality: 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 by network 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 an agent. 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 devices to report their own problems. Alarm Polling Most substantial SNMP managers provide some ability to set thresholds on SNMP MIB objects, and respond with some type of notification when these thresholds are violated. This provides a means of constantly testing a networks integrity against a baseline. The alarm polling functionality will also determine what devices are responding and which devices are not responding. Integrating PATROL with SNMP 10

Trend Monitoring Most SNMP managers provide some ability to continuously watch an SNMP value over time and view trends in the network. Trend monitoring can be used to determine load of a network over time by watching bandwidth. Typically a management system will plot network utilization versus time. SNMP Master Agents The SNMP master agent is a process that runs on a platform that supports the SNMP protocol. It listens for SNMP requests on the default SNMP port 161 and serves as a gateway to 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. The process supports the sub protocol of the master agent and responds to requests for information from 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 or process data through SNMP protocol. BMC offers the PATROL SNMP toolkit as shareware to instrument applications for management via SNMP. Integrating PATROL with SNMP 11

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 PATROL Sub-agent, other sub-agents supporting SMUX, and other SNMP devices through encapsulation. PATROL SNMP Sub-agent The PATROL subagent is a process combined with the PATROL process to translate SMUX messages to the PATROL Agent. The sub-agent can be started with PSL or with a configuration variable of the PATROL Agent. The PATROL SNMP Master Agent must be running for the sub-agent to run. Integrating PATROL with SNMP 12

PATROL SNMP Implementation Windows NT SNMP on WINDOWS NT is delivered as a service dll to which other SNMP agents communicate with through the WINSNMP API. The service is installed optionally, and it is set as the default master agent listening on port 161. Figure 7 shows how PATROL SNMP support is implemented on Windows NT: Figure 7 PATROL SNMP Implementation on Windows NT Integrating PATROL with SNMP 13

PATROL SNMP Implementation Unix Unix vendors support default master agents listening on port 161. AIX uses SMUX, HP uses Emanate. HP loads the sub-agents into the master agent s process space. Figure 7 shows how PATROL 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 using the 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 and manipulate the SNMP MIB through the KM. The PATROL SNMP Master Agent is not required to use the PATROL Console as an SNMP manager. MIB to KM Wizard The MIB to KM Wizard is a tool that reads a MIB definition and creates a KM that includes parameters, 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 the SNMP devices along with other applications. You can obtain the PATROL MIB to KM Wizard from the BMC Software Developer Connection (DevCon) Web Site at http:\\devcon.bmc.com. Integrating PATROL with SNMP 14

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 the PATROL MIB after you compile the PATROL MIB into your SNMP management application. MIB supports V1 syntax. Some MIB compilers will generate errors so MIBs may need 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 MIB is fairly static, and the OIDs remain constant. However, in PATROL the many of the OIDs correspond 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 look very 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 the traps, 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 to recognize 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 configuration file. The PATROL SNMP Toolkit The PATROL SNMP Toolkit is a set of tools that help you integrate third-party applications with PATROL. The toolkit helps you set up applications to communicate with SNMP and set their values so that they can be accessed through SNMP. You can obtain the PATROL SNMP Toolkit from the BMC Software Developer Connection (DevCon) Web Site at http:\\devcon.bmc.com. Integrating PATROL with SNMP 15

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 not true for the SNMP Agents, but SNMP support must be active for this communication to take place. 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 standard known as 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). For more information on configuring the PATROL SNMP Master Agent see Configuring the 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, the PATROL Agent starts the SNMP Sub-Agent when the PATROL Agent is started. On Unix the /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. Note The 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 and tables. 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. Integrating PATROL with SNMP 16

Figure 10 shows the process for configuring the PATROL Agent to run with SNMP: Figure 10 Configuring PATROL for SNMP Set the port number and community name for the PATROL SNMP Master Agent. Verify that the SNMP support variable is on. (default setting) Add the SNMP manager to the list of interested SNMPV1 managers. Set the user access, host access, and mode access for the SNMP manager. Set the severity level of events that trigger traps. 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 known as 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 contained in the PATROL SNMP Master Agent configuration file. Below is the name and path of this file: 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 SNMP listening port. This configuration file is in ASCII text format, which means you can use any text 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 internal SNMP structures and provides SNMP information to SNMP Managers in the form of SNMP traps and responses to SNMP queries. Integrating PATROL with SNMP 17

The configuration of the PATROL SNMP Master Agent is controlled by the values contained in 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 Integrating PATROL with SNMP 18

The PATROL Agent SNMP Support Variables There are two PATROL Agent configuration variables that need to be on for the SNMP support 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: Table 12 Variables for Starting SNMP with the PATROL Agent Variable /snmp/agent_auto_start Description 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 if 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 or does not exist, the SNMP Master Agent starts when it is started by the SNMPStart parameter. For more information on the PATROL Agent configuration variables see PATROL Agent SNMP Configuration Variables on page 46. Integrating PATROL with SNMP 19

PATROL Agent SNMP Interested Managers For SNMP support (trap listening) to be active in PATROL, you must enter the SNMP Manager 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 of interested managers for PATROL SNMP traps: Table 13 The List of Interested Managers for SNMP Traps with the PATROL Agent Variable /snmp/piv1m_list Description The list of SNMPV1 managers that are interested in getting automatic SNMP traps from the Agent 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. For more information on the PATROL Agent configuration variables see PATROL Agent SNMP Configuration Variables on page 46. Integrating PATROL with SNMP 20

Variables for Configuring the Agent with SNMP You configure the Agent to run with SNMP by changing the appropriate variable. Table 14 shows each part of the process for configuring the Agent to run with SNMP and lists the section that contains information about the variable that must be changed. Table 14 Configuring the Agent to Run with SNMP You Want to Set the port number and community name for the PATROL SNMP Master Agent Find the Variable in This Section 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 When Configuration Changes Take Effect Table 15 shows when changes made to the PATROL SNMP Master Agent configuration file take effect. Table 15 When Changes to the Agent Configuration Take Effect Operating System Unix All non-unix When Changes Take Effect when the SNMP Master Agent is restarted after you restart the PATROL SNMP Master Agent 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 Agent is shut down and restarted. Integrating PATROL with SNMP 21

Testing Agent SNMP Trap Sending Testing is the next step after the PATROL SNMP Agent is configured correctly to send SNMP traps. 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 PSL snmp_trap_listen() and snmp_trap_receive(). Essentially, this procedure sets up 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. Integrating PATROL with SNMP 22

The PATROL MIB The MIB in PATROL is a set of tables that are dynamically built as the agent loads KMs and discovers the instances. Since the PATROL discovery is a dynamic process that sometimes happens on a user request, the id s of the applications in the MIB will probably be different each 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 Integrating PATROL with SNMP 23

PATROL MIB Tree Objects Table The PATROL MIB object table contains all the nodes from the PATROL Agent namespace starting 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 Integrating PATROL with SNMP 24

PATROL MIB Tree Variables Table The PATROL MIB varaible table contains all the leaves from the PATROL Agent namespace starting 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 Integrating PATROL with SNMP 25

PATROL MIB Tree Applications Table The PATROL MIB applications table contains all the applications loaded on the PATROL Agent. Figure 18 shows the basic structure of the PATROL MIB applications table: Figure 18 The PATROL MIB Tree Applications Table Integrating PATROL with SNMP 26

The PATROL MIB application tables can be accessed to find out what applications are loaded on 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 Integrating PATROL with SNMP 27

PATROL MIB Tree Instances Table The PATROL MIB instances table contains all the application instances that have been discovered by the PATROL Agent. Figure 20 shows the basic structure of the PATROL MIB instances table: Figure 20 The PATROL MIB Tree Instances Table Integrating PATROL with SNMP 28

The PATROL MIB instance table can be accessed to find out what instances of an application have 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 instance table (all the instances for the PRINTER application): Figure 21 The PATROL MIB Tree Instances Example Integrating PATROL with SNMP 29

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 Integrating PATROL with SNMP 30

Figure 23 shows the format of the SNMP traps sent by PATROL: Figure 23 The PATROL MIB Tree Trap Example Integrating PATROL with SNMP 31

PATROL MIB Tree Enterprise Traps Figure 24 shows the PATROL MIB enterprise traps: Figure 24 The PATROL MIB Enterprise Traps Integrating PATROL with SNMP 32

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 use PSL with PATROL and SNMP. It is available on the BMC Software Developer Connection (DevCon) Web Site at http://devcon.bmc.com. Integrating PATROL with SNMP 33

Listening for SNMP Traps During trap listening, the PATROL Agent works as an SNMP manager. Table 26 lists the function to use for the task you want to perform. Table 26 Functions for Trap Listening Task to be Performed close a trap socket and ignore all unprocessed and/or arriving traps capture the arriving traps start accumulating incoming traps PSL Function to Use snmp_trap_ignore() snmp_trap_receive() snmp_trap_listen() Sending SNMP Traps During trap sending, the PATROL Agent works in an SNMP agent role. Table 27 lists the function to use for the task you want to perform. Table 27 Functions for Sending Traps Task You Want to Perform send any traps to any given SNMP manager send the trap patroltrapv1raised, with patroltraptext.0 in a packet, to all entities registered in the prv1mtable PSL Function to Use snmp_trap_send() snmp_trap_raise_std_trap( text ) 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 28 Functions for Starting and Stopping the SNMP Agent Task You Want to Perform request the current state of the SNMP Sub-Agent restart the SNMP Sub-Agent stop the SNMP Sub-Agent PSL Function to Use snmp_agent_config() snmp_agent_start() snmp_agent_stop() Integrating PATROL with SNMP 34

Getting and Setting MIB Variables The PATROL Agent can act as an SNMP Manager by getting and setting variables inside SNMP agents through PSL functions. Table 29 lists the function to use for the task you want to perform. Table 29 Functions for Getting and Setting MIB Variables Task You Want to Perform close the session with SNMP agent list SNMP sessions that are currently open, return default parameters for a specific snmp session, or alter the default settings for an SNMP session fetch MIB variables from an SNMP agent open a session to an SNMP agent by locating the host and creating an internal structure with default information set MIB variables PSL Function to Use snmp_close() snmp_config() 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. snmp_open() 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. Note snmp_h_* functions use port 161 and cannot be configured to use a different port. Integrating PATROL with SNMP 35

Using PSL to Change the Registered SNMP Manager List The list of registered SNMP Managers is contained in the PiV1mTable. Table 30 lists the function to use for the task you want to perform. Table 30 Functions for Changing the Registered SNMP Manager List Task You Want to Perform add an SNMP Manager to the list delete an SNMP manager from the list print the list of SNMP Managers PSL Function to Use snmp_agent_register_im() snmp_agent_register_im() snmp_agent_register_im() 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. It returns the old settings or NULL indicating an error. Table 31 lists the function to use for the task you want to perform. Table 31 Functions for Debugging PSL Functions Task You Want to Perform dump all in/out packets on stdout when the agent is in no-daemon mode get error information that may not be reported to the console window, such as timeouts snmp_debug (flags) Function to Use snmp_dump_packet (1) snmp_report_error (2) Integrating PATROL with SNMP 36

Interpreting Error Messages from PSL Functions Table 32 describes global error messages for PSL functions for SNMP. They are considered global because any SNMP PSL function can generate one of these messages. Table 32 Global Error Messages for SNMP PSL Functions Error Message E_PSL_BAD_FUNCTION_PARAMETER E_PSL_SNMP_ERROR E_PSL_SNMP_NOT_SUPPORTED Description A function fails to parse a parameter, which could be caused, for example, by a bad address or trap definition. A function tries to send or receive an invalid packet to or from another SNMP entity. SNMP support is turned off. NULL If an error occurs, a function returns a null string or. 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. A user can determine which error occurred most recently by displaying or printing the value of the PATROL PSL error variable. This variable holds an integer that corresponds to one of the error messages above. The PATROL Script Language Reference Manual provides more information on working with error messages. Integrating PATROL with SNMP 37

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 and handle traps within the PATROL Agent, and to gather PATROL data from the PATROL MIB static tables. Methods of Sending SNMP Traps Sending SNMP traps to an SNMP management console is a common method for the notification of critical events detected in the PATROL environment. SNMP traps can also be sent 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 trap message can be configured/changed number of different trap formats possible methods of controlling format of these traps situations causing trap sending no no two event catalog settings and Agent configuration generation of an event in the associated event class yes yes unlimited PSL coding, almost unlimited options any method of PSL execution Integrating PATROL with SNMP 38

PATROL Event Manager and SNMP Traps The PATROL Event Manager (PEM) associates the individual SNMP trap configuration settings with each event class. This applies to both the Standard Event Catalog and any application-specific event catalog created for a KM. For each event class, the settings of NO_TRAP or SEND_TRAP has been added to specify whether 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 little control over the format of the SNMP traps. For example, you can not control the event-specific sub ID, or the enterprise ID used. Integrating PATROL with SNMP 39

Standard Event Classes Table 35 lists all the standard event classes. These event classes can be useful for sending SNMP traps in other situations, such as a console disconnecting. Table 35 Standard Event Classes for Sending SNMP Traps (Part 1 of 2) Event Class RegApp UpdAppState WorstApp UpdParState UpdInstState UnregAllApp UpdMachineState Diag RemPsl Result PslSet RemProcess EventArchive Disconnect Unload R3FilterData Meaning 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). new or updated application state. This application now has the worst state of all applications in the agent. new or updated parameter state. new or updated instance state. Unregister all applications. new or updated state for the entire agent (due to some change in the state of an application). Diagnosis event. Used by remote PSL execution. Used by remote PSL execution. Used for remote PSL set execution. Used in remote PSL file transfer and the API. Events have been archived. Console disconnected from agent. KM class was unloaded by agent. 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, and the 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. Integrating PATROL with SNMP 40

Table 35 Standard Event Classes for Sending SNMP Traps (Part 2 of 2) Event Class Meaning 13 Suspended all parameters of this KM class. 14 or 15 Restarting 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. Integrating PATROL with SNMP 41