Documente Academic
Documente Profesional
Documente Cultură
Manufacturing Part Number : T2579-90002 October 2006 Copyright 1990-2006 Hewlett-Packard Development Company, L.P.
Legal Notices
Warranty The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice. Restricted Rights Legend Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. Copyright Notices Copyright 1990-2006 Hewlett-Packard Development Company, L.P. Contains software from AirMedia, Inc. Copyright 1996 AirMedia, Inc. Trademark Notices Java and all Java based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Microsoft is a U.S. registered trademark of Microsoft Corporation. Windows NT is a U.S. registered trademark of Microsoft Corporation. Windows 2000 is a U.S. registered trademark of Microsoft Corporation. Windows and MS Windows are U.S. registered trademarks of Microsoft Corporation. Netscape and Netscape Navigator are U.S. trademarks of Netscape Communications Corporation. Oracle is a registered U.S. trademark of Oracle Corporation, Redwood City, California.
Oracle7 is a trademark of Oracle Corporation, Redwood City, California. OSF/Motif and Open Software Foundation are trademarks of Open Software Foundation in the U.S. and other countries. Pentium is a U.S. registered trademark of Intel Corporation. UNIX is a registered trademark of The Open Group.
Documentation Updates
This manuals title page contains the following identifying information: Software version number, which indicates the software version Document release date, which changes each time the document is updated Software release date, which indicates the release date of this version of the software
To check for recent updates, or to verify that you are using the most recent edition of a document, go to: http://ovweb.external.hp.com/lpe/doc_serv/ You will also receive updated or new editions if you subscribe to the appropriate product support service. Contact your HP sales representative for details.
Support
You can visit the HP OpenView Support web site at: www.hp.com/managementsoftware/support HP OpenView online support provides an efficient way to access interactive technical support tools. As a valued support customer, you can benefit by using the support site to: Search for knowledge documents of interest Submit and track support cases and enhancement requests Download software patches Manage support contracts Look up HP support contacts Review information about available services Enter into discussions with other software customers Research and register for software training
Most of the support areas require that you register as an HP Passport user and sign in. Many also require a support contract. To find more information about access levels, go to: www.hp.com/managementsoftware/access_level To register for an HP Passport ID, go to: www.managementsoftware.hp.com/passport-registration.html
Contents
1. Introduction to the NNM Software Developers Kit
The HP OpenView NNM Software Developers Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . The OVSNMP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The WinSNMP and Microsoft MGMT API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The SNMP API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 21 22 22 24
2. An Overview of SNMP
The SNMP Model of Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manager and Agent Interaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMPv1 and SNMPv2C Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Management Information Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Extended MIBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 27 27 28 28 31 33 35 37 37 39 40
Contents
The NNM Event Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The NNM Event Database API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 87 90 90
Contents
Integration via ovwMapClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Integrating via Services (Background Processes) . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Contents
10
Tables
Table 2-1. SNMP Request Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31 Table 2-2. SNMPv2C Request Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 Table 2-3. Summary of the SNMPv1 and SNMPv2 SMI Definitions . . . . . . . . . . . . .34 Table 2-4. ASN.1 Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37 Table 2-5. Outside Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40 Table 3-1. Protocol Operations Supported by the OVSNMP API . . . . . . . . . . . . . . . .48 Table 3-2. Protocol Error Status Supported by the OVSNMP API . . . . . . . . . . . . . . .49 Table 3-3. SNMP Communications API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .58 Table 3-4. OVsnmpAPI Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64 Table 3-5. Compilers Supported on Operating Systems . . . . . . . . . . . . . . . . . . . . . . .66 Table 3-6. OVSNMP Header Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68 Table 3-7. SNMP API Key Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70 Table 3-8. OVsnmpSession Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 Table 3-9. CallBack Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73 Table 3-10. CallBack Command Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74 Table 3-11. Elements of the OVsnmpPdu Data Structure . . . . . . . . . . . . . . . . . . . . . .77 Table 3-12. Elements of the OVsnmpVarBind Data Structure . . . . . . . . . . . . . . . . . .80 Table 3-13. OVsnmpVarBind Union Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81 Table 4-1. NNM Event Database API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87 Table 5-1. SNMP Configuration API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94 Table 5-2. SNMP Configuration API Data Structures . . . . . . . . . . . . . . . . . . . . . . . . .98 Table 5-3. OVsnmpConfEntry Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99 Table 5-4. OVsnmpConfWcList Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 Table 5-5. OVsnmpConfDest Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Table 5-6. OVsnmpConfCntl Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104 Table 6-1. Functions in the OVuTL API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111 Table 7-1. Functions in the OVsPMD API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119 Table 7-2. Purpose of Each Line in a Local Registration File . . . . . . . . . . . . . . . . . .121 Table 7-3. First Line of the LRF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122 Table 7-4. Second Line of the LRF& . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
11
Tables
12
Figures
Figure 1-1. SNMP API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 Figure 2-1. Sequence of Actions in a Hypothetical SNMP Session . . . . . . . . . . . . . . .29 Figure 2-2. Conceptual View of Communication Sequence with Traps . . . . . . . . . . .30 Figure 2-3. The Top of the MIB Naming Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 Figure 2-4. The Role of a Proxy in SNMP Communication . . . . . . . . . . . . . . . . . . . . .39 Figure 3-1. OVSNMP Bilingual Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46 Figure 3-2. OVsnmpPDU Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76 Figure 5-1. OVsnmpConfWcList Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 Figure 5-2. OVsnmpConfDest Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 Figure 6-1. Windows Event Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110 Figure 7-1. Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116 Figure 7-2. Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129 Figure 7-3. Decision Tree for Script Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . .132 Figure 7-4. Decision Tree for ovwMapClose Event Integration . . . . . . . . . . . . . . . .133 Figure 7-5. Decision Tree for Background Process Integration. . . . . . . . . . . . . . . . .134 Figure 7-6. Backup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135 Figure 7-7. API integration with Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138 Figure 7-8. Backup via Background Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
13
Figures
14
Conventions
The following typographical conventions are used in this manual. Font What the Font Represents For book or manual titles, and for manpage names. To provide emphasis. To specify a variable that you must supply when entering a command. Bold Computer For glossary terms. Text and items on the computer screen. Command names File and directory names. Process names. Window/dialog box names Computer Bold
Keycap
Example Refer to the OVW Developers Guide. You must follow these steps. At the prompt type: rlogin your_name where you supply your login name. The distinguishing attribute of this class... The Root map window ... The system replies: Press Enter Use the grep command ... /usr/bin/X11 Check to see if pmd is running. In the IP Internet map window... At the prompt, type: ovstatus. Press Return. Click [NET]. Click on the [Apply] button. Select Edit:Find->Objects by Comment
Italic
Text that you must enter. Keyboard keys. Buttons on the user interface. A menu name followed by a colon (:) means that you select the menu, then the item. When the item is followed by an arrow (->), a cascading menu follows.
15
16
Contact Information
Technical Support Technical support information can be found on the HP OpenView World Wide Web site at: http://openview.hp.com/ ________________________________ Documentation Feedback Your comments on and suggestions for the documentation help us understand your needs and better meet them. You can provide feedback about documentation via the HP documentation site at: http://www.docs.hp.com Or you can fill out the form provided in electronic form with NNM: Windows: install_dir\ReleaseNotes\nnm_doc_reply.txt UNIX: /opt/OV/ReleaseNotes/nnm_doc_reply.txt
Fill out one form per manual and email it to: ovdoc@fc.hp.com If you encounter serious errors in the documentation that impair your ability to use NNM, please contact the HP Response Center or your support representative so that your feedback can be entered into CHARTS (the HP Change Request Tracking System). ________________________________ Training Information For information on current HP OpenView training available, see the HP OpenView World Wide Web site at: http://openview.hp.com/ Select the support panel to obtain information about scheduled classes, training at customer sites, and class registration.
17
18
Chapter 1
19
This chapter introduces the SNMP component of the HP OpenView Network Node Manager (NNM) Software Developers Kit (SDK). It describes the SNMP APIs available for application development (OVSNMP and WinSNMP), and includes an illustration of the OVSNMP API architecture. Also included is an introduction to APIs used in application integration.
20
Chapter 1
Introduction to the NNM Software Developer s Kit The HP OpenView NNM Software Developer s Kit
This guide discusses the APIs for SNMP management (chapters 2, 3, and 4), tracing and logging (chapter 5), and process control (chapter 6). APIs related to OpenView Windows are discussed in the HP OpenView Windows Developers Guide.
NOTE
For information about installing the SDK, see README_SNMPDEV.txt on the SDK CD-ROM.
Chapter 1
21
Introduction to the NNM Software Developer s Kit The HP OpenView NNM Software Developer s Kit The OVSNMP API provides a native asynchronous event-loop programming model for Win32 on Windows operating systems and X11 on UNIX system platforms. For an overview of SNMP management, see Chapter 2, An Overview of SNMP. For more detailed information about the OVSNMP APIs, see Chapter 3, The OVSNMP Communications API, and Chapter 5, The OVSNMP Configuration API, on page 91
22
Chapter 1
Introduction to the NNM Software Developer s Kit The HP OpenView NNM Software Developer s Kit Figure 1-1 illustrates the primary components and data flows of the OVSNMP API, and their relationships to each other and to system services. Figure 1-1 SNMP API Architecture
OVsnmpEventOpen ( ", "myApp", recv, &rd, "{NO_FORWARDED,CORR{default}} .*")
netmon
ITO
ovactiond
Alarm Browser
Annotation server
OVEVENT
ovtrapd Port 162 pmd ANNO ECS I/O ecsmgr Perl script http server Drill Down
ovevents
ECS Correlation Services ASCII Events ECS Corr. Configuration Management GUI
Chapter 1
23
Introduction to the NNM Software Developer s Kit The HP OpenView NNM Software Developer s Kit
Integration APIs
Chapters 5 and 6 cover the activities and utilities you use to integrate your application into the HP OpenView SNMP platform on Network Node Manager. Integration requires you to make some straightforward modifications to your code, as well as create a few special files and scripts. There are two key areas for attention in integration: logging and tracing HP OpenView process management
It is not necessary for you to integrate in both areas. For example, you may elect to not integrate with the logging and tracing component. However, each point of integration makes it easier for your customer to take full advantage of your product.
NOTE
You must create a Local Registration File (LRF) for any agents you create. This is covered under process management in Chapter 6.
For further reading, see HP OpenView Integration Series: Integration Concepts and Managing Your Network with Network Node Manager.
24
Chapter 1
An Overview of SNMP
Chapter 2
25
An Overview of SNMP
This chapter provides an overview of the Simple Network Management Protocol (SNMP) as it is implemented in the HP OpenView OVSNMP API. The following information is provided: The SNMP Model of Communication, including: managers and agents SNMP messages SNMPv1 and SNMPv2c protocols The Management Information Base, including: object identifiers extended MIBs data representation A list of documents that provide more detailed information about SNMP and MIBs, including several RFCs (Request for Comment documents).
26
Chapter 2
Managers
A manager is a process (or node) that is an active participant in network management. It solicits and interprets data about network devices and network traffic, and typically interacts with a user to achieve the user's intentions. Therefore, a manager can also trigger changes in an agent (see the next section) by changing the value of a variable on the agent node. Managers are frequently implemented as network management applications.
Agents
From the perspective of network management, an agent is usually a passive entity. It responds to the requests of managers, supplying and changing the values of local variables as needed. An agent can become an active entity by emitting unsolicited messages (called notifications or traps) to alert managers of noteworthy local events (such as a system reboot).
NOTE
The HP OVSNMP API is intended for the development of SNMP-based network management applications. It does not fully support the development of SNMP agents beyond supporting the generation of traps.
Chapter 2
27
SNMP Messages
Requests and responses are transferred in Protocol Data Units, or PDUs. A PDU is the formal name for a message that is sent or received in the course of SNMP communication. Connectionless Operation SNMP uses a connectionless transport service for communication between the SNMP manager and agent. The HP OpenView SNMP API introduces a session-oriented model from the application perspective. However, this implementation serves only to bind the application to the OVSNMP API for a given destination. A connectionless transport is still used internally. 28 Chapter 2
An Overview of SNMP The SNMP Model of Communication The OVSNMP API supports SNMP over User Datagram Protocol/Internet Protocol (UDP/IP) on both UNIX and Windows platforms. The OVSNMP API on Windows also supports SNMP over Internet Packet Exchange (IPX). Requests and Responses Figure 2-1 illustrates a sequence of communications between a manager and an agent. Events in the diagram occur in top-to-bottom order. Figure 2-1 Sequence of Actions in a Hypothetical SNMP Session
Manager
Set up to send SNMP requests Create request PDU Add variable binding to request PDU Send request PDU Listen for response (retry Send if necessary)
Agent
Listen for requests
Receive request PDU Generate response PDU Send response PDU Receive response PDU
The diagram oversimplifies the sequence somewhat. The manager can send the request in either blocking or non-blocking mode. The type of mode affects the need to manage retransmissions. Also, since the implementation of the agent is unknown, the agent's actions are generic; the manager does not care how the agent generates the response PDU. Details about how to use the OVSNMP API to send messages and receive responses are in Chapter 3, The OVSNMP Communications API, and in the online reference pages.
Chapter 2
29
An Overview of SNMP The SNMP Model of Communication Notifications In the model presented previously, the manager requests information from the agent and the agent then responds. However, it is also possible for an agent to issue spontaneous (unsolicited) messages. Such a message is known as a notification. In SNMPv1, notifications are referred to as traps. In SNMPv2, a notification may be either a trap or an inform message. The diagram shown in Figure 2-2 illustrates the communication sequence involved with traps. Figure 2-2 Conceptual View of Communication Sequence with Traps
Manager
Set up to receive SMP traps
Agent
Initialize and begin operation Detect an internally significant state Create trap PDU Send trap PDU
Traps exist to handle special conditions. When an agent or a manager detects a special condition, each can emit a trap message. SNMP specifies several predefined traps, and a developer may also define application-specific traps. In practice, HP OpenView NNM uses a daemon process to manage trap traffic on an SNMP management node. This is because only one management application can bind to the SNMP/UDP trap port. On HP-UX, Solaris, and Linux, the NNM ovtrapd process binds to the trap port and then forwards traps to local applications. On Windows operating systems, the NNM ovtrapd process uses by default the WinSNMP trap receptor to listen on the trap port. This provides coexistence with native WinSNMP applications. However, ovtrapd can also be started with an override option to listen directly to the trap port. In this case, the WinSNMP application would not be able to receive notifications.
30
Chapter 2
SNMP Operations The SNMPv1 specification defines the following basic operations: Table 2-1 Request Type Set Request Get Request Get Next Request Get Response Trap Request SNMP Request Types Description Writes new data to one or more of the objects managed by an agent. Requests the value of one or more of the objects managed by an agent. Requests the Object Identifier(s) and value(s) of the next object(s) managed by an agent. Contains the data returned by an agent. Sends an unsolicited notification from an agent to a manager, indicating that an event or error has occurred on the agent system.
Chapter 2
31
An Overview of SNMP The SNMP Model of Communication The SNMPv2C protocol provides some new protocol operations over the original SNMP protocol. These include the following: Table 2-2 Request Type Get Bulk Request SNMPv2C Request Types Description Retrieves large amounts of object information in a single request/response transaction. GetBulk behaves as if many iterations of GetNext request/responses were issued, except that they are all performed in a single request/response. Sends an SNMPv2-style notification to an SNMP manager. The SNMPv2 Trap Request has a similar purpose as the SNMPv1 Trap Request, but is in a slightly different format. Sends an unsolicited but confirmed notification of a local event to a remote management station. In addition to these improved operations, SNMPv2C supports improved exception and error reporting, and new mechanisms for defining MIBs for SNMPv2. (MIB changes are described later in this overview.)
Inform Request
32
Chapter 2
Summary of the SNMPv1 and SNMPv2 SMI Definitions Differences Forms the basis for all existing SNMPv1-based MIBs. Defined in RFC 1155: Structure and Identification of Management Information for TCP/IP-based Internets Amended in RFC 1212: Concise MIB Definitions Defined as a superset of the SNMPv1 SMI. Some SNMPv1 data types have been renamed: Counter -> Counter32 Gauge -> Gauge32 INTEGER -> Integer32
SNMPv2 SMI
Extends the original SNMPv1 SMI to support these new data types: Counter64 (64-bit counter) Unsigned32 (32-bit unsigned integer). Indistinguishable from Gauge32. BITS (defines an enumeration of bits. Indistinguishable from OCTET STRING.
Allows custom data types to be built by constraining the range, size, or possible values of existing data types. For example, a new enumeration could be constructed by defining a small set of possible integer values. The SNMPv2 SMI refers to this form of definition as a textual convention. Defined in: RFC 1902: Structure of Management Information for Version 2 of the Simple Network Management Protocol RFC 1903: Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)RFC 1904: Conformance Statements for Version 2 of the Simple Network Management Protocol (SNMPv2)
34
Chapter 2
Object Identifiers
For the purposes of an SNMP developer, an object identifier (OID) is a data type that precisely identifies a MIB-II object definition. An OID (often referred to as the registration ID) consists of a sequence of non-negative integers that describe the only path through the object-naming hierarchy to the object. The naming hierarchy is commonly called the naming tree. The Naming Tree The naming tree has the structure of a conventional tree with arbitrary breadth and depth. The nodes are labeled with non-negative integers (each node among siblings must have a unique label). Various organizations have administrative authority for assigning labels within subtrees of the naming tree. They can assign subordinate (child) nodes, and/or delegate this responsibility to still other organizations. The root node of the naming tree has three children: ccitt(0) The administration authority for this branch is the International Telegraph and Telephone Consultative Committee (CCITT). The administration authority for this branch is the International Organization for Standards, and the International Electrotechnical Committee (ISO/IEC). This is the path under which networking management is defined. The administration authority for this branch is shared between CCITT and ISO/IEC.
iso(1)
joint-iso-ccitt(2)
Chapter 2
35
Figure 2-3
ccitt(0)
iso(1)
joint-iso-ccitt(2)
Every path through the naming tree ultimately terminates at a leaf node. The sequence of labels along the path (starting at the root) is the OID for the object named at the leaf. OIDs in Practice The convention for writing object identifiers is called dot notation. An OID in dot notation consists of the integers of the OID in sequence, with a period (dot) between them. Thus the prefix for the OIDs in the MIB-II is 1.3.6.1.2.1. Below is an example OID from the MIB-II. The full written name of the path is shown beneath the corresponding numerical identifiers in the OID: 1.3.6.1.2.1.6.7
iso.org.dod.internet.mgmt.mib.tcp.tcpAttemptFails
NOTE
The derivation of these examples is taken from the RFCs noted earlier in this chapter and in For More Information at the end of this chapter.
36
Chapter 2
Extended MIBs
Many agents support extended MIBs, which define objects that are not included in standard MIBs, such as MIB-II and enterprise-specific MIBs. Your application can query an object from an extended MIB exactly as it would query a MIB-II object. Users should use the proper registration authorities when defining MIB extensions.
Data Representation
Data is exchanged between SNMP processes using the Basic Encoding Rules (BER) defined for the Abstract Syntax Notation (ASN.1). ASN.1 is a rich data description language, and gaining a full understanding of it is a formidable task. Fortunately, as an SNMP developer, you do not deal directly with ASN.1 or the Basic Encoding Rules. The HP OpenView SNMP API takes care of the details of ASN.1 encoding and decoding. SNMP uses a few simple ASN.1 data types. Table 2-4, ASN.1 Data Types, lists the base data types that you work with in SNMP communication. The details of how you access them appear in the online reference pages. Table 2-4 Type INTEGER Integer32 OCTET STRING ASN.1 Data Types Description A simple type consisting of positive and negative whole numbers, including zero, and is of arbitrary size up to 32 bits. However, some objects restrict INTEGER to a range. A simple type taking zero or more octets, each octet being an ordered sequence of eight bits. The value of any octet in the string is unrestricted. An array of non-negative, 32-bit integers. Each integer represents one element of the object identifier. The maximum length of an OBJECT IDENTIFIER is limited to 128 sub-identifiers. A type representing a non-negative integer which calculates change and increases until it reaches a maximum value, when it then wraps around and starts increasing again from zero.
Chapter 2
37
An Overview of SNMP The Management Information Base Table 2-4 Type Gauge Gauge32 Timeticks NetworkAddress ASN.1 Data Types (Continued) Description A type representing a non-negative integer, which may increase or decrease, but which latches at a maximum value. A type representing a non-negative integer which counts the time in hundredths of a second since some event. A type representing an address from one of possibly several protocol families. Currently only one protocol family, the Internet family, is present. This data type is deprecated in SNMPv2. A type representing a 32-bit Internet address. It is represented as an OCTET STRING of length 4, in network byte-order. When this ASN.1 type is encoded using the ASN.1 basic encoding rules, only the primitive encoding form shall be used. A type representing a non-negative, 64-bit integer which calculates change and increases until it reaches a maximum value. It then wraps around and starts increasing again from zero. Values can range from 0 to 264^1. A non-negative 32-bit integer. Values can range from 0 to 232 ^1. This data type is indistinguishable from Gauge32 when encoded using ASN.1 BER. An arbitrary set of named bit enumerations encoded as an ASN.1 OCTET STRING.
IPAddress
Counter64
Unsigned32
BITS
38
Chapter 2
SNMP Proxies
The HP SNMP implementation provides special support for applications that communicate with a destination agent using an SNMP proxy. Such an application can address a message directly to the destination (foreign) agent; the SNMP API will determine which host is the proxy and send the message accordingly. Figure 2-4 illustrates this concept. Figure 2-4 The Role of a Proxy in SNMP Communication
The Manager addresses a message to the TargetAgent. The HP SNMP API recognizes that the agent has an SNMP proxy named ProxySys. The API routes the message to ProxySys, which in turn communicates with TargetAgent in some non-SNMP protocol, then relays the response to manager, using SNMP.
Manager
SNMP
ProxySys
Foreign Protocol
TargetAgent
The information used to recognize proxy agents resides in the SNMP Configuration Database. This proxy information must be configured by the administrator of the manager. For details, see xnmsnmpconf(1) in the online reference pages.
Chapter 2
39
RFC 1213: Management Information Base Network Management of TCP/IP based internets: MIB-II RFC 1215: Convention for Defining Traps for Use with the SNMP RFC 1901: Introduction to Community-based SNMPv2
RFC 1902: Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)
40
Chapter 2
An Overview of SNMP For More Information Table 2-5 Document RFC 1903: Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2) RFC 1904: Conformance Statements for Version 2 of the Simple Network Management Protocol (SNMPv2) Outside Reading (Continued) Description SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). MIB Definition language for refined data types. (Draft Standard. Obsoletes RFC 1443) SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). MIB Definition language for Conformance and Capability definitions. (Draft Standard. Obsoletes RFC 1444) SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Defines SNMPv2 protocol. (Draft Standard. Obsoletes RFC 1448) SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Defines SNMPv2 transport mappings for IP, IPX, DDP. (Draft Standard. Obsoletes RFC 1449) SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Defines MIB objects that are mandatory for SNMP agents that support SNMPv2. (Draft Standard. Obsoletes RFC 1450) SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Coexistence guidelines for SNMPv1 and SNMPv2. (Draft Standard. Obsoletes RFC 1452)
RFC 1905: Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2) RFC 1906: Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)
RFC 1907: Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)
RFC 1908: Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework
Chapter 2
41
42
Chapter 2
Chapter 3
43
This chapter describes the OVSNMP Communications API. The OVSNMP API provides all the functions and support you need to write a manager-based network management application. It is provided in the Software Developers Kit (SDK) for cross-platform portability of existing OVSNMP/UNIX system-based applications. This chapter discusses the following: OVSNMP API concepts, including: SNMPv1 and SNMPv2C protocol support, including changes in the API interface behavior OVSNMP over UDP/IP and IPX blocking and nonblocking programming models retransmission support memory management The OVSNMP Communications API routines The OVSNMP Communications API data structures
44
Chapter 3
If you have an existing application that uses the OVSNMP communications API, and do not need to communicate with remote systems using the SNMPv2C protocol, you can simply recompile your application and relink with the SNMP libraries provided in your developer kit. The OVSNMP API routines are fully backward-compatible with the previous OVSNMP communications API. However, if you wish to access SNMPv2C remote systems, you must write your application to specifically use the SNMPv2C API extensions. The extensions are easily accommodated by any existing application already using the OVSNMP communications API. The remainder of this section describes how you can take advantage of the dual support of the SNMPv1 and SNMPv2C protocols in the SNMP developers kit.
SNMPv1 and SNMPv2C Protocol Runtime Support The OVSNMP Communications API contains an embedded communications protocol stack that supports both the SNMPv1 and SNMPv2C protocols. This protocol stack contains the intelligence to support explicit requests for SNMPv1 or SNMPv2C protocol support, as well as a bilingual mode that supports both protocol stacks.
Chapter 3
45
The OVSNMP Communications API SNMPv1 and SNMPv2C Protocol Support The bilingual mode relies on information in the SNMP configuration database to determine which protocol version to use to communicate with a particular agent. The protocol stack automatically translates requests made in bilingual mode to the particular protocol supported for a particular agent. Figure 3-1 shows the relationship between the OVSNMP API and the bilingual/native protocol stack support. Figure 3-1 OVSNMP Bilingual Stack Management Application
OR
OR
controlled by OVSNMP_V2 API session flag controlled by protocol version (when the OVSNMP_V2 API flag is set)
SNMPv1 agent
SNMPv2 agent
Changes in the OVSNMP API Interface Behavior To support both the original SNMPv1 interface and the newer SNMPv2C bilingual communication mode, the OVSNMP API has been enhanced to support a new interface behavior. The enhancements accommodate the differences in error return codes introduced in the SNMPv2C protocol, while still retaining source code compatibility with existing OVSNMP API applications.
46
Chapter 3
The OVSNMP Communications API SNMPv1 and SNMPv2C Protocol Support You can use the OVSNMP API in its original interface style or in the new interface style, which is called OVSNMP_V2API. If you select the new interface style, your application can take advantage of both explicit SNMPv2C protocol support and bilingual SNMPv1/SNMPv2C protocol support. Your application, however, must also handle the different types of errors that can be returned through the SNMPv2-style interface. You may explicitly request that your application use either the SNMPv1 or SNMPv2C protocol. By default, if you use the SNMPv2-style interface, the SNMP stack will use the bilingual communication mode. The bilingual communication mode allows access to SNMP operations that might not initially appear to be valid for a given remote system. For example, you could use GetBulk Requests for a remote node that supports only the SNMPv1 protocol. When using bilingual communication mode, the SNMP run-time stack dynamically translates requests into SNMP operations that are valid for the particular type of remote system involved in the communication. For example, if a remote system supports only the SNMPv1 protocol, a GetBulkRequest is translated into a GetNext request. The OVSNMP API performs the following protocol translations when communicating with SNMPv1 agents through the SNMPv2-style interface: SNMPv2 GetBulk operations are translated into SNMPv1 GetNext operations. When transmitting SNMPv2 traps to SNMPv1 systems, the trap is first translated into the SNMPv1 trap format. If an SNMPv1 Trap Request is received and the API is operating in the SNMPv2-style interface mode, the SNMPv1 Trap Request is translated into the SNMPv2 Trap format. SNMPv2 Inform operations cannot be translated into an SNMPv1 equivalent operation, and therefore cannot be sent to an SNMPv1 system.
Chapter 3
47
The OVSNMP Communications API SNMPv1 and SNMPv2C Protocol Support Table 3-1, Protocol Operations Supported by the OVSNMP API, indicates which SNMPv1 or SNMPv2C protocol operations are supported by the OVSNMP API through the two interface styles. Table 3-1 Protocol Operations Supported by the OVSNMP API v1-style API x x v2-style API Bilingual x x x x x x x x x x x x x SNMPv1 x x xa x x x x x x SNMPv2C x x x x x
SNMP Operation
GET_REQ_MSG GETNEXT_REQ_MSG GETBULK_REQ_MSG SET_REQ_MSG RESPONSE_MSG V1TRAP_REQ_MSG V2TRAP_REQ_MSG INFORM_REQ_MSG Receive SNMPv1 trap in SNMPV2 trap format Receive SNMPv2 trap or inform in SNMPv1 trap format
a. When using the SNMPv2-style API with the SNMPv1 protocol version, each GetBulk request is mapped to a single GetNext request, regardless of the maximum number of repetitions specified. If necessary, you can determine which protocols are configured in the local OVSNMP Configuration Database for a remote system by using the OVsnmpGetVersions function or the xnmsnmpconf -getVersions command. For more information about querying the protocols supported by a remote system, see the reference page for xnmsnmpconf. Enhanced Error Codes If you select the SNMPv2-style interface to the OVSNMP API, you must be prepared to handle a much larger set of possible error codes than was possible with the SNMPv1-only interface.
48
Chapter 3
The OVSNMP Communications API SNMPv1 and SNMPv2C Protocol Support Table 3-2, Protocol Error Status Supported by the OVSNMP API, shows the errors that can be returned when using each of the OVSNMP API interface modes. The original SNMPv1-style interface supports only the error codes listed under v1-style Interface. SNMPv1 error codes are not translated to SNMPv2C code. The SNMPv2C codes are more specific than SNMPv1 codes, so there is no one-to-one translation between the two. Applications using the bilingual protocol mode must be able to deal with error codes that do not appear as SNMPv1 error codes, even if the messages originate from an SNMPv1 remote system. The bilingual mode is designed to hide the details of the lower level protocol, and to allow developers to write applications that work equally well when communicating with SNMPv1 and SNMPv2C-compatible remote systems. When using the SNMPv2-style API interface, the set of possible errors returned is the same, regardless of the actual SNMP protocol used to communicate with the remote system. See Table 3-2, Protocol Error Status Supported by the OVSNMP API. Table 3-2 Protocol Error Status Supported by the OVSNMP API v2-style Interface SNMP Response Errors v1 style Interface x x x x x Bilingual x x x x x x x x x x v1 native x x x x x v2 native x x x x x x x x x x 49
SNMP_ERR_NOERROR SNMP_ERR_TOOBIG SNMP_ERR_NOSUCHNAME SNMP_ERR_BADVALUE SNMP_ERR_GENERR SNMP_ERR_NOACCESS SNMP_ERR_WRONGTYPE SNMP_ERR_WRONGLENGTH SNMP_ERR_WRONGENCODING SNMP_ERR_WRONGVALUE Chapter 3
The OVSNMP Communications API SNMPv1 and SNMPv2C Protocol Support Table 3-2 Protocol Error Status Supported by the OVSNMP API v2-style Interface SNMP Response Errors v1 style Interface Bilingual x x x x x x x x x v1 native v2 native x x x x x x x x x
SNMP_ERR_NOCREATION SNMP_ERR_INCONSISTENTVALUE SNMP_ERR_RESOURCEUNAVAILABLE SNMP_ERR_COMMITFAILED SNMP_ERR_UNDOFAILED SNMP_ERR_AUTHORIZATIONERROR SNMP_ERR_NOTWRITABLE SNMP_ERR_INCONSISTENTNAME Varbind Exceptions
50
Chapter 3
The OVSNMP Communications API SNMPv1 and SNMPv2C Protocol Support Optionally, if you want to specify a particular communications protocol rather than use bilingual protocol support, you can set the protocol_version field in the OVsnmpSession structure. All communication from that point on will use the specified communication protocol. Valid choices for the protocol version are: SNMP_VERSION_1 SNMP_VERSION_2C SNMP_USE_DEFAULT_VERSION (bilingual)
Chapter 3
51
NOTE
Actual SNMP transmission over IPX is supported on the Windows operating systems only. However, the multi-transport interface to enable both UDP/IP and IPX can be used on all platforms to facilitate cross-platform portability.
The multi-transport interface for the OVSNMP API is nearly identical to the UDP/IP-only interface of previous releases. Existing applications continue to support SNMP over UDP/IP without any need to be modified. In addition, most of those applications, when ported to the WindowsNT/2000 operating system, will realize both UDP/IP and IPX support without any modification as well. Only applications that override the SNMP destination on a per-request (PDU) basis must be enhanced to realize full IPX support. The multi-transport capabilities are exported to an application in two areas: the OVsnmpOpen() function and the OVsnmpPdu structure.
52
Chapter 3
Chapter 3
53
into the application source code before including OVsnmp.h. This redefines the OVsnmpPdu address member to be a sockaddr (generic socket) structure. The address.sa family value then determines the type of address specified in the PDU. If this value is AF_UNSPEC, the session peername is used as the destination. Otherwise, AF_INET indicates a UDP/IP address (sockaddr_in format); and AF_IPX indicates an IPX address (sockaddr_in format). Existing applications that rely on the session peername when sending SNMP requests do not need to be modified. However, applications that override the destination on a per-request (PDU) basis must be modified to do the following: Use the new multi-transport interface directive. Reference the OVsnmpPdu address structure accordingly. Further, the OVsnmpPdu address type must be the same type as that of the session peername. Otherwise, the SNMP request will fail with SNMP_ERR_INVALID_HOST.
Developers of new applications are encouraged to use the multi-transport interface directive in all cases.
54
Chapter 3
Retransmission Support
OVSNMP uses either the User Datagram Protocol (UDP) or Internet Packet Exchange (IPX)1 at the transport layer. These connectionless protocols provide a simple but unreliable transport. A message can get lost in transmission and never arrive at its destination. Therefore, services such as SNMP may require some messages to be retransmitted. If your application uses blocking requests, the SNMP library handles retransmission based on the timeout and retry values established when the session is first opened. If your application uses nonblocking requests, the SNMP API provides three ways to manage retransmission:
The OVSNMP Communications API Blocking and Nonblocking Programming Models manual retransmission based on the select function automatic retransmission using the Win32 message loop (Windows only) automatic retransmission using the X11 event loop (UNIX only)
Each of the three modes uses a variant of the OVsnmpOpen function to create the OVsnmpSession, plus a slightly different mechanism for managing retransmission and determining when a response arrives. However, all other functions such as OVsnmpSend, OVsnmpCancel, and OVsnmpClose can be used with any type of OVsnmpSession. If you use OVsnmpOpen to create the session, you must call select() to wait for SNMP events to occur, such as the arrival of a response or the need for a retransmission. If you use the X11 or Win32 forms of nonblocking calls, you can rely on the X11 or Win32 event-processing loop to determine when responses arrive. With these types of nonblocking functions, retransmissions are automatically managed for you. The communications functions for the OVSNMP API are described in more detail later in this chapter and in the online reference pages. Select-based Retransmission Event-driven, select-based applications make nonblocking requests. As shown in the sample code fragment below, these applications create an OVsnmpSession by using OVsnmpOpen, then manage retransmissions by calling select() and the OVsnmpGetRetryInfo and OVsnmpDoRetry functions (which are described later in this chapter).
session=OVsnmpOpen(targetName,...applCb,applCbData); pdu=OVsnmpCreatePdu(...);OVsnmpAddNullVarbind(...); reqId=OVsnmpSend(session,pdu); ...other application specific code... while (1){ nfds=OVsnmpGetRetryInfo(&readfds, &tval); rc=select(nfds,readfds,NULL,NULL,&tval); if (rc>0)OVsnmpRead(&readfds); OVsnmpDoRetry(); } /* *Note:OVsnmpRead and OVsnmpDoRetry invoke the OVSNMP applCb *for SNMP responses, notifications and timeout conditions */
56
Chapter 3
The OVSNMP Communications API Blocking and Nonblocking Programming Models Automatic Retransmission Using the Win32 Message Loop The OVSNMP API on Windows operating systems includes native Win32 support for event-driven (nonblocking) applications. As illustrated in the sample code fragment below, you use this feature by calling the OVsnmpWOpen and OVsnmpSend functions, along with the Win32 message loop consisting of GetMessage to DispatchMessage. The OVsnmpGetRetryInfo and OVsnmpDoRetry functions are not used in this mode of operation.
session=OVsnmpWOpen(targetName,...applCb,applCb,applCbData); pdu=OVsnmpCreatePdu(...);OVsnmpAddNullVarbind(...); reqId=OVsnmpSend(session,pdu); ...other application specific code... while (GetMessage(&msg)){ TranslateMessage(&msg);/*For Keyboard accels*/ DispatchMessage(&msg); /* *Note:DispatchMessage() ultimately invokes the OVSNMP applCb *for SNMP responses, notifications and timeout conditions */
Automatic Retransmission Using X11 Event Loop (UNIX Only) The OVsnmpAPI library includes extended support for event-driven X11-based applications. These applications use OVsnmpXOpen and OvsnmpSend. When you use this feature, the SNMP library manages all message retransmissions for you using XtAppMainLoop(3). The sample code fragment illustrates how retransmissions are handled.
session=OVsnmpXOpen(XtCtx, target,...applCb,applCbData); pdu=OVsnmpCreatePDU(...);OVsnmpAddNullVarbind(...); reqId=OVsnmpSend(session,pdu); ..other application specific code... XtAppMainLoop(XtCtx); /* *Note:XtAppMainLoop() invokes the OVSNMP applCb *for SNMP responses, notifications and timeout conditions */
Chapter 3
57
SESSION MANAGEMENT FUNCTIONS OVsnmpOpen() Establishes a logical session with the OVsnmpAPI for the purpose of communicating with a specific remote system. Equivalent to OVsnmpOpen(), but prepares a logical session for use in an X-Windows programming environment. Equivalent to OVsnmpOpen(), but prepares a logical session for use in a Windows operating system programming environment. Terminates an SNMP session created by any of the OVSNMP session open functions. Provided for backward compatibility of existing X11 applications.
OVsnmpXOpen()
OVsnmpWOpen()
OVsnmpClose() OVsnmpXClose()
EVENT FRAMEWORK SESSION FUNCTIONS OVsnmpEventOpen() Successor to OVsnmpTrapOpen(). Establishes a logical session with the OVsnmpAPI for the purpose of receiving SNMP events via the OpenView Event Framework. It allows filters to be applied to events to reduce the number of events that are received. Equivalent to OVsnmpEventOpen(), but prepares a logical session for use in an X-Windows programming environment.
OVsnmpXEventOpen()
58
Chapter 3
The OVSNMP Communications API The SNMP Communications API Functions Table 3-3 Function Name OVsnmpWEventOpen() SNMP Communications API Functions (Continued) Description Equivalent to OVsnmpEventOpen(), but prepares a logical session for use in a WindowsNT/2000 operating system programming environment. Predecessor to the OVsnmpEventOpen() function. This function is provided for backward compatibility only. Use the OVsnmpEventOpen() routine in the future. Provided for backward compatibility of existing X11 applications.
OVsnmpTrapOpen()
OVsnmpXTrapOpen()
MESSAGE SETUP and MANIPULATION FUNCTIONS OVsnmpCreatePdu() OVsnmpAddNullVarBind() Allocates and initializes an OVsnmpPdu data structure suitable for the specified SNMP request operation. Used in conjunction with SNMP Get, GetNext, and SNMPv2 GetBulk Requests. Allocates, initializes, and appends an OVsnmpVarBind structure for the specified SNMP MIB object to the SNMP Request PDU. Used in conjunction with SNMP Set, Trap, and SNMPv2Inform Requests. Allocates, initializes, and appends an OVsnmpVarBind structure for the specified SNMP MIB object to the SNMP Request PDU. Allocates and initializes a new SNMP request PDU based on the specified response PDU. Any invalid variable bindings are omitted from the resulting PDU. Creates a copy of the specified OVsnmpPdu data structure and its contained elements. Deallocates the specified OVsnmpPdu data structure and its contained elements. Extract the OVsnmp UUID from an OVsnmpPdu Convert a string representation of an OVsnmp UUID to its packed form.
OVsnmpAddTypedVarBind()
OVsnmpFixPdu()
Chapter 3
59
The OVSNMP Communications API The SNMP Communications API Functions Table 3-3 Function Name OVsnmpUuidToStr() OVsnmpOidAppend() OVsnmpOidAppendN() OVsnmpOidConcat() OVsnmpOidConcatN() OVsnmpOidCopy() OVsnmpOidCompare() OVsnmpOidFromStr() OVsnmpOidFromName() SNMP Communications API Functions (Continued) Description Convert an OVsnmp UUID from the packed form to an ASCII string. Appends one object identifier fragments of type ObjectID to another object identifier. Appends one or more object identifier fragments of type ObjectID to another object identifier. Concatenates two object identifier fragments of type ObjectID together to produce a new object identifier. Concatenates two or more object identifier fragments of type ObjectID together to produce a new object identifier. Create a copy of an object identifier of type ObjectID. Compare two object identifiers of type ObjectID for lexicographic ordering (less than, equal to, greater than). Create a new object identifier of type ObjectID from a string in dotted-numeric notation. Create a new object identifier of type ObjectID from a string in either dotted-numeric notation, or mnemonic descriptor (name) form as defined in the HP OpenView loaded MIB database. Format an object identifier of type ObjectID as a string in dotted-numeric notation. Format an object identifier of type ObjectID as a string using the mnemonic descriptor (name) defined in the HP OpenView loaded MIB database. Allocate a block of unitialized dynamic memory. Allocate a block of dynamic memory initialized to zero. Change the size of a block of dynamically allocated memory.
OVsnmpOidToStr() OVsnmpOidToName()
60
Chapter 3
The OVSNMP Communications API The SNMP Communications API Functions Table 3-3 Function Name OVsnmpFree() SNMP Communications API Functions (Continued) Description Deallocate a block of previously allocated dynamic memory.
COMMUNICATIONS FUNCTIONS BLOCKING MODE OVsnmpBlockingSend() OVsnmpRecv() Sends a request PDU to an SNMP agent and waits for a response to be received. Receives an SNMP response or trap and returns the result. If no data is available, the call is suspended until data arrives.
COMMUNICATIONS FUNCTIONS NONBLOCKING MODE OVsnmpSend () OVsnmpEventSend() Sends a request PDU to an SNMP agent, but does not wait for a response. Send a notification PDU to the OpenView Event subsystem. Caller can override the source address and retrieve the OVsnmp UUID of the out going event. Receives incoming data on pending sessions. Information is returned via the callback function. Gets retransmission information on pending SNMP requests for use in the select() routine. Retransmits a pending SNMP request. Cancels an SNMP request for which a response has not yet been received. The application-defined function that handles responses to non-blocking requests. Acknowledge an event in the HP OpenView Event Subsystem. Delete an event in the HP OpenView Event Subsystem. Correlate two events in the HP OpenView Event Subsystem.
Chapter 3
61
The OVSNMP Communications API The SNMP Communications API Functions Table 3-3 Function Name OVsnmpEventUnack() OVsnmpEventChangeSev() OVsnmpEventChangeCat() SNMP Communications API Functions (Continued) Description Unacknowledge an alarm in the HP OpenView Event Subsystem. Change the severity of an alarm HP OpenView Event Subsystem. Change the category of an alarm in the HP OpenView Event Subsystem.
COMMUNICATIONS FUNCTIONS X11 NONBLOCKING MODE OVsnmpXSend() OVsnmpXCancel() Superseded by OVsnmpSend(). It is provided for backward compatibility of existing X11 applications. Superseded by OVsnmpCancel(). It is provided for backward compatibility of existing X11 applications.
ERROR REPORTING FUNCTIONS OVsnmpErrString() SNMP_STD2OV_ERR() Obtains a pointer to an error message string that corresponds to the specified OVsnmpErrno error code. Translates a pduerror_status value into an OVSNMP error code that is suitable for calling OVsnmpErrString(). Note: This is required only if you are using the V2-style API. The V1-style API allows pduerror_status to be passed directly. OVUint64 ARITHMETIC FUNCTIONS OVuint64FromStr() OVuint64ToStr() OVuint64Assign() OVuint64Cmp() Converts ASCII string notation of an unsigned 64-bit integer into OVuint64 data type. Convert OVuint64 data type into ASCII string notation. Assigns the low and high order portions of an OVuint64 value from two 32-bit values. Compares two OVuint64 values for less than, equality, and greater than.
62
Chapter 3
The OVSNMP Communications API The SNMP Communications API Functions Table 3-3 Function Name OVuint64Shift() OVuint64Add() OVuint64Subtract() OVuint64Multiply() OVuint64Divide() OVuint64CmpUInt32() OVuint64AddUInt32() OVuint64SubtractUInt32() OVuint64MultiplyUInt32() OVuint64DivideUInt32() SNMP Communications API Functions (Continued) Description Performs left or right bit-shift of an OVunit64 value. Adds two OVuint64 values and returns the sum. Subtracts two OVuint64 values and returns the difference. Multiplies two OVuint64 values and returns the product. Divides two OVuint64 values and returns the quotient. Compares an unsigned 32-bit value to an OVunit64 value for less than, equality, and greater than. Adds an unsigned 32-bit value to an OVuint64 value and returns the sum. Subtracts an unsigned 32-bit value from an OVuint64 value and returns the difference. Multiplies an OVuint64 value by an unsigned 32-bit and returns the product. Divides an OVuint64 value by an unsigned 32-bit and returns the quotient.
Memory Management
The HP OVSNMP Communications API uses two rules of thumb for memory management: When you pass a data structure into a library function, it is consumed. The memory it occupies is deallocated by the library. For example, the call to open a session creates an OVsnmpSession data structure, which is later consumed by the OVsnmpClose() call. When you obtain a data structure from a library function, you must deallocate the associated memory using an OVsnmp library function.
Chapter 3
63
The OVSNMP Communications API The SNMP Communications API Functions Sometimes you may supply data to fill in a structure that the SNMP library has allocated. For example, you might assign a Notification OID or Enterprise OID to an SNMP Trap PDU. Such data must always be dynamically allocated. Otherwise, a failure occurs when the library attempts to deallocate statically allocated memory. Make sure that whenever memory is allocated whether by the SNMP library or by your application it is later deallocated. Neglecting this can result in a memory leak which gradually consumes resources until a failure occurs. Four functions are provided for you to allocate and deallocate ancillary data assigned to OVSNMP data structures. The are: OVsnmpMalloc(), OVsnmpCalloc(), OVsnmpRealloc() and OVsnmpFree(). These functions behave the same as, and are implemented using, the underlying operating system malloc(), calloc(), realloc() and free() functions, respectively. The purpose of the OVSNMP API versions of these functions is to provide common memory allocation and deallocation, particularly on the WindowsNT/2000 operating system where the DEBUG (msvcrtd.dll) and non-DEBUG (msvcrt.dll) versions of the C-runtime library are not compatible with each other. The functions are also provide on UNIX systems for cross-platform portability. Table 3-4, OVsnmpAPI Memory Management, summarizes the types of data structures allocated or deallocated by the OVSNMP API functions. Refer to the specific function description for details. Table 3-4 OVsnmpAPI Memory Management OVsnmpAPI Function OVsnmpOpen() OVsnmpXOpen() OVsnmpWOpen() OVsnmpTrapOpen() OVsnmpXTrapOpen() OVsnmpEventOpen() OVsnmpXEventOpen() OVsnmpWEventOpen() Memory Management Performed Allocates returned OVsnmpSession.
64
Chapter 3
The OVSNMP Communications API The SNMP Communications API Functions Table 3-4 OVsnmpAPI Memory Management (Continued) OVsnmpAPI Function OVsnmpClose() OVsnmpXClose() OVsnmpCreatePdu() OVsnmpAddNullVarbind() OVsnmpAddTypedVarbind() OVsnmpCopyPdu() OVsnmpFixPdu() OVsnmpSend() OVsnmpXSend() OVsnmpBlockingSend() OVsnmpEventSend() OVsnmpRecv() OVsnmpCallback()(application supplied) Allocates returned OVsnmpPdu. Attaches allocated OVsnmpVarBind to a PDU. Allocates returned OVsnmpPdu (makes a duplicate of specified pdu). Deallocates specified OVsnmpPdu. Allocates returned OVsnmpPdu. Conditionally deallocates specified OVsnmpPdu based on associated session FREE_Pdu flag. If enabled, deallocates input PDU (only if no error occurs) otherwise caller must free input PDU. Allocates returned OVsnmpPdu; application must deallocate via OVsnmpFreePdu(). API allocated OVsnmpPdu passed as input; application must deallocate via OVsnmpFreePdu. Deallocates specified OVsnmpPdu. Allocates an object ID sequence that must be assigned to an OVsnmpPdu or deallocated using OVsnmpFree(). Deallocates specified OVsnmpPdu. Memory Management Performed Deallocates specified OVsnmpSession.
Chapter 3
65
The OVSNMP Communications API The SNMP Communication API Data Structures
Table 3-5
Compilers Supported on Operating Systems Compiler HP-UX C or ANSI C HP ANSI C++ Sun Studio compiler suite Microsoft Visual C++ Red Hat gcc or g++ Application Source Code Type, Operating System, or Computer Series HP 9000 series computers operating on HP-UX Applications written in C++ language on supported HP-UX platforms Applications written in C or C++ language on Solaris operating systems Microsoft Windows platforms Linux operating systems
NOTE
For a complete list of supported operating systems and compatible compiler versions, refer to Table A in HP OpenView Network Node Manager 7.51 Software Development Kit Release Notes.
66
Chapter 3
The OVSNMP Communications API The SNMP Communication API Data Structures
Header Files
The header file defines many data structures that are part of the OVSNMP API. All header files are stored under a common directory represented by the $OV_HEADER environment variable. See the reference page ov.envvars for details on the $OV_HEADER environment variable. The OVsnmp header files are shown in Table 3-6, OVSNMP Header Files.
Chapter 3
67
The OVSNMP Communications API The SNMP Communication API Data Structures
Table 3-6
OVSNMP Header Files Header File Purpose The main header file for OVSNMP applications. This file includes all other header files (except OVsnmpWfns.h and OVsnmpXfns.h) as a convenience. Main function declarations, structure definitions, and control definitions. More function declarations. ASN.1 type definitions for the API. These are the ASN.1 types that are supported by the OVSNMP library. Configuration parameter and function definitions. Error value definitions. Declarations for the Microsoft Win32-specific functions. Declarations for the X11-specific functions in the OVSNMP library. Declarations for 64-bit integer arithmetic functions.
$OV_HEADER/OV/OVsnmp.h
68
Chapter 3
The OVSNMP Communications API The SNMP Communication API Data Structures Guidelines for Applications Using the SNMPv2 API If your application uses the SNMPv2-style API, it must observe the following guidelines in addition to those mentioned above: All PDUs passed to the API by the application must be created by the API; that is, the PDUs must either be returned by one of the following: OVsnmpCreatePDU() OVsnmpCopyPDU() OVsnmpFixPDU() OVsnmpBlockingSend() OVsnmpRecv() or passed to the nonblocking mode OVsnmpCallback() function. Error values derived from a PDUs error_status field must be mapped to the OVSNMP API error code space before being passed to OVsnmpErrString(). This mapping is performed by the newly provided SNMP_STD2OV_ERR macro. Examples of how this macro is used can be found in $OV_MAIN_PATH/prg_samples/ovsnmp_app.
Chapter 3
69
The OVSNMP Communications API The SNMP Communication API Data Structures
Data Structures
The key data structures you will use with the OVSNMP API are described in Table 3-7. Table 3-7 Data Structure Name OVsnmpSession SNMP API Key Data Structures Description Obtained by a call to OVsnmpOpen(), it identifies a particular SNMP communication session. Used as an input parameter to several other functions. Created by OVsnmpOpen(); freed by OVsnmpClose(). Container for an SNMP message. It includes information about the type of message (Get, Get Next, GetBulk, Set, Trap, or Inform), as well as the message data itself. Created by OVsnmpCreatePdu(); freed by OVsnmpFreePdu(). Elements on a linked list of variables. Each element of the list includes an object identifier for the variable and the variable's value. Part of the OVsnmpPdu structure. Created by OVsnmpAddVarBind(); freed by OVsnmpFreePdu(). A union that can contain the value portion of an SNMP variable binding. Part of the OVsnmpVarBind structure. Created by OVsnmpAddVarBind(); freed by OVsnmpFreePdu(). The two data structures you will use most often are the OVsnmpSession structure and the OVsnmpPdu structure (including its substructures).
OVsnmpPdu
OVsnmpVarBind
OVsnmpVal
70
Chapter 3
The OVSNMP Communications API The SNMP Communication API Data Structures The OVsnmpSession Structure OVsnmpSession identifies a logical session between the manager and a specific destination SNMP agent. The OVsnmpSession structure is allocated by a call to OVsnmpOpen, and is an input parameter to several other functions. The fields are shown in Table 3-8. Table 3-8 Field Name community OVsnmpSession Fields Type u_char Description The community name of the agent. Defaults to public, or the value contained in the OVSNMP configuration database. When the session is closed, this memory is deallocated. The number of bytes in the community name. The community name of the agent for use in SNMP set requests. The number of bytes in the set community name. The socket file descriptor for the session. Used to establish the read mask for calls to select(). Points to the callback function to be invoked when a response returns from a call to OVsnmpSend() or OVsnmpXSend(), or when a notification is received using OVsnmpRead(). These two send functions are nonblocking, and the callback function is to be invoked when the corresponding response arrives. Points to application data the callback function is to receive (note the syntax of the callback invocation below). The memory is not accessed by the library.
callback_data
void *
Chapter 3
71
The OVSNMP Communications API The SNMP Communication API Data Structures Table 3-8 Field Name protocol_version OVsnmpSession Fields (Continued) Type long Description Defines a specific SNMP protocol version to use for this session. It is only valid when the OVSNMP_V2API bit in the session_flags field is enabled. Valid values are: SNMP_VERSION_1 SNMP_VERSION_2C SNMP_USE_DEFAULT_VERSION session_flags u_short A bitmask for information and control. The following values are defined: OVSNMP_FREE_PDU (and FREE_PDU): If set, the send functions deallocate memory associated with the input OVsnmpPdu structure. The default for this flag is set. OVSNMP_RECV_EVENTS (and RECV_TRAPS): Set this flag if you want notifications (traps and informs) to be passed to the calling application. The default when using OVsnmpOpen() or OVsnmpXOpen() is unset. The default when using OVsnmpEventOpen(), OVsnmpXEventOpen(), OVsnmpTrapOpen(), or OVsnmpXTrapOpen() is set. OVSNMP_V2API: Controls the interface semantics of the OVsnmpAPI with regard to SNMPv1 versus SNMPv2-style operation. The default for this flag is unset. OVSNMP_CLOSE_CALLBACK: If set, the nonblocking application callback function is invoked for each outstanding request that exists at the time the session is closed (via OVsnmpClose() or OVsnmpXClose(). The default for this flag is unset.
72
Chapter 3
The OVSNMP Communications API The SNMP Communication API Data Structures The Callback Function Your application determines the structure and purpose of the callback function. If you use the nonblocking calls in the OVSNMP API, the callback function defines the interaction of your application and the remote peer. The callback function is automatically invoked when your application uses OVsnmpRead() to obtain the response to a nonblocking send request. In X applications, the callback is invoked automatically when the response arrives. The call syntax is as follows:
callback (command, session, pdu, callback_data)
If the response or notification is obtained with OVsnmpRecv instead, the callback does not occur. Your callback function must define the parameters in Table 3-9. These input parameters are passed to the callback function. They are described further in the OVsnmpPdu data structure section. Table 3-9 CallBack Parameters Parameter command session Description An integer. Indicates why the callback function was called. See Table 3-10 for details. An OVsnmpSession structure. Identifies the session with which the incoming PDU is associated. An OVsnmpPdu structure. This is the PDU that was received, or a copy of the original request PDU on some error conditions. Application-specific data, which is specified as the value passed into the OVsnmpOpen call.
pdu
callback_data
The entries in Table 3-10 define the valid values for the callback command parameter.
Chapter 3
73
The OVSNMP Communications API The SNMP Communication API Data Structures
Table 3-10
CallBack Command Values Note 1 Description The pdu parameter contains the RESPONSE to the respective type of outstanding SNMP request. The pdu parameter contains the RESPONSE to an outstanding SNMP request. The pdu parameter contains unsolicited trap notifications. The pdu parameter contains unsolicited trap notifications. The pdu parameter contains an unsolicited inform notification. A timeout occurred without receiving a response. OVsnmpNoRspID (global variable) contains the outstanding request ID. structure. The pdu is NULL. The pdu is a copy of the outstanding request. Indicates the connection to OpenView Event subsystem is disconnected. For example, the pmd process has terminated via ovstop. The pdu is NULL. Indicates the specified session is being closed by OVsnmpClose (or OVsnmpXClose) when an SNMP request is still outstanding. The pdu is a copy of the outstanding request.
Command Value GET_REQ_MSG GETNEXT_REQ_MSG SET_REQ_MSG RESPONSE_MSG V1TRAP_REQ_MSG V2TRAP_REQ_MSG INFORM_REQ_MSG SNMP_ERR_NO_RESPONSE
2 1 2 2 1, 2
SNMP_SYSERR_LOST_CONN
SNMP_ERR_CLOSING_SESSION
Notes (1) Occurs only if the SNMP_V2API bit in the session_flags field is not set for the specified session parameter. (2) Occurs only if the SNMP_V2API bit in the session_flags field is set for the specified session parameter.
74
Chapter 3
The OVSNMP Communications API The SNMP Communication API Data Structures Table 3-10 CallBack Command Values (Continued) Note Description
Command Value
(3) Occurs only if the specified session was created using OVsnmpEventOpen(), OVsnmpEventXOpen(), OVsnmpTrapOpen(), or OVsnmpXTrapOpen(). (4) Occurs only if the OVSNMP_CLOSE_CALLBACK bit in the session_flags field is set for the specified session parameter. The OVsnmpPdu Structure The OVsnmpPdu data structure represents the SNMP Request, Response, or Trap PDU that is sent or received by the calling application. The information in this structure is encoded into and decoded from the ASN.1 contents of the SNMP packet. The OVsnmpPdu is created in one of two ways: Through a call to OVsnmpCreatePdu(). This is done while preparing to send a request. When a response or notification is received.
The SNMP send functions normally deallocate the memory associated with input PDU structures.1 To deallocate the PDU associated with a response or notification, use OVsnmpFreePdu().
NOTE
For SNMPv2 traps and informs, the OVsnmpPdu structure conveys the logical format of the notification. The notification identifier, timestamp and optional enterprise identifier are represented in fields of the OVsnmpPdu structure. The variables list contains only the data varbinds for the notification. When the V2 trap or inform pdu structure is encoded into or decoded from the SNMP message, these three attributes are inserted into or extracted from the SNMP message variable-binding list.
The OVSNMP Communications API The SNMP Communication API Data Structures The fields of the OVsnmpPdu structure are shown in order in Figure 3-2. Note that this PDU has two variables. Table 3-11 describes each of the elements in the OVsnmpPdu data structure. Figure 3-2 OVsnmpPDU Structure OVsnmpPdu
address command request_id error_status error_index *community community_len *variables Specific toV2 Traps & Informs Specific toV1 Traps Specific toV1 & V2 Traps & Informs *notify_oid notify_oid_length generic_type specific_type union *enterprise enterprise_length agent_addr time
OVsnmpVarBind
*next_variable *oid oid_length type val *integer *string *object_id *uint32 *uint64 val_len
OVsnmpVarBind
*nex_variable *oid oid_length type val *integer *string union *object id *uint32 *uint64 val_len
NULL
76
Chapter 3
The OVSNMP Communications API The SNMP Communication API Data Structures
Elements of the OVsnmpPdu Data Structure Type struct sockaddr Description The address of the agent. Supported address types are AF_UNSPEC (the default), AF_INET, and AF_IPX (Windows only). See OVSNMP Over UDP/IP and IPX on page 52 for details. Defines the specific SNMP protocol version that applies for this pdu. It is only valid if the OVSNMP_V2API mode of operation is enabled. Valid values are: SNMP_VERSION_1 SNMP_VERSION_2 SNMP_USE_DEFAULT_VERSION
protocol_version
long
command
int
The SNMP specific type of command. Must be one of the following: GET_REQ_MSG GETNEXT_REQ_MSG SET_REQ_MSG TRAP_REQ_MSG GET_RSP_MSG GETBULK_REQ_MSG INFORM_REQ_MSG V2TRAP_REQ_MSG
request_id
int
An identifier assigned by the SNMP API. This value must never be modified by your application.
Chapter 3
77
The OVSNMP Communications API The SNMP Communication API Data Structures Table 3-11 Field Name error_status Elements of the OVsnmpPdu Data Structure (Continued) Type int Description When a response PDU is received, this variable contains a positive value if an error occurred on the request. If no error occurred, the value is zero. This value is ignored in a call to a send function. An index into the variable list. If error_status shows that an error occurred, then error_index indicates which element of the list caused the error. When specified in a request PDU, this variable overrides the community name in the session parameter for this request only when a response PDU or trap PDU is received. This variable contains the community name returned by the agent. The number of bytes in the community name. This is a pointer to a linked list of variables, each element of which is an OVsnmpVarBind data structure. Memory referenced by this pointer is deallocated by a call to OVsnmpFreePdu(), OVsnmpFixPdu(), or any send function.
error_index
int
community
u_char *
community_len variables
u_int OVsnmpVarBind *
The following fields are specific to SNMPv1 trap and SNMPv2 trap/inform PDUs, and are invalid for all other PDUs. enterprise ObjectID A vendor-specific identifier that uniquely identifies the type of device sending the trap. Optional for SNMPv2 traps and informs. The number of elements in the object ID. The default has 11 elements.
enterprise_length
u_int
78
Chapter 3
The OVSNMP Communications API The SNMP Communication API Data Structures Table 3-11 Field Name agent_addr Elements of the OVsnmpPdu Data Structure (Continued) Type u_long Description The IP address of the agent that sent the trap. Represented in Network Byte Order. For OVSNMP over IPX, this value is zero. The time (in tenths-of-seconds) since the agent was last activated. The default is the length of time that the application has been running.
time
u_long
The following fields are specific to SNMPv1 trap requests, and are invalid for all other PDUs. generic_type specific_type int int One of the SNMP-defined types of trap. See RFC 1157 for details. When generic_type indicates that an enterprise-specific trap has occurred, the value of specific_type contains the specific trap. Otherwise, the value is meaningless.
The following fields are specific to SNMPv2 Trap and Inform Requests, and are invalid for all other PDUs. notify_oid ObjectID * Contains the snmpTrapOID variable bindings in the raw SNMPv2 Trap or Inform Request message. The number of elements in the object ID.
notify_oid_len
u_int
The OVsnmpVarBind Data Structure The OVsnmpVarBind data structure represents a single SNMP variable binding included in an SNMP PDU. The variable binding specifies the information the application wants to get from or set in the SNMP agent. Table 3-12 describes each of the elements.
Chapter 3
79
The OVSNMP Communications API The SNMP Communication API Data Structures
Elements of the OVsnmpVarBind Data Structure Type OVsnmpVarBind * ObjectID * u_int u_char OVsnmpVal Description Points to the next element in the variable list. NULL in last element. The object identifier (object ID) for this variable. The number of elements in the object ID for this variable. The ASN.1 type of the variable. Must be one of the types listed in Table 2-2. A union containing the possible data types. The active field is indicated by type (above). The number of elements in the value of the variable. Note that this may not equal the number of bytes in the val; object IDs, for example, consist of an array of long integers.
val_len
u_int
80
Chapter 3
The OVSNMP Communications API The SNMP Communication API Data Structures
The OVsnmpVal data structure is a union of the possible data types for the variable. The OVsnmpVal data can be any of the Union Members listed in Table 3-13. Table 3-13 OVsnmpVarBind Union Members Union Member integer Octet string (array of 8-bit values) object ID unsigned 32-bit integers unsigned 64-bit integers For SNMP Type: INTEGER OctetString, IpAddr Object ID Counter32, Gauge32, Unsigned32, TimeTicks Counter64
To see how the OVsnmpVal data structure relates to the OVsnmpVarBind data structure, see Figure 3-2.
Chapter 3
81
The OVSNMP Communications API The SNMP Communication API Data Structures
82
Chapter 3
Chapter 4
83
This chapter describes the functions and data structures in the HP NNM Event Database API. It includes descriptions of the following: The NNM Event Database NNM Event Database API functions
84
Chapter 4
Chapter 4
85
The NNM Event Database API The NNM Event Database There are two ways to get correlated events for a given event. Use OVEventDbFindCorrelatedEvents() and OVEventDbEventListGetNext() to retrieve a list of events, which are directly correlated to the parent event. Use OVEventDbGetCorrelationTree() and related API functions to recursively find all child events correlated to the parent event. Since each child event may have children, this operation involves a recursive descent. These events are stored in a list and returned in depth first order. The operation can be lengthy, because the entire correlation log must be searched to find the correlations.
86
Chapter 4
The NNM Event Database API The NNM Event Database API Functions
Chapter 4
87
The NNM Event Database API The NNM Event Database API Functions Table 4-1 NNM Event Database API Functions (Continued) Function OVEventDbFreeEventList() OVEventDbFreeCorrEntryList() OTHER DATA MANIPULATION OVEventDbEventListGetNext() Iterate through an event list and return the next event handle in the list. Iterate through a correlation entry list and return the next correlation entry in the list. Return the number of elements in the list associated with the OVcorrEntryListHandle. Return the status of a correlated event associated with the OVcorrEntryHandle. Return the eventId of the parent event associated with a OVcorrEntryHandle. Return the eventId of the child event associated with an OVcorrEntryHandle. Return the number of descendent events that are correlated below corrEntry. Return an OVeventHandle that refers to the child event associated with an OVcorrEntryHandle. Return the number of ancestor events that are correlated above corrEntry. Create an OVsnmpPdu from an event packet. Description Free the resources associated with an OVeventListHandle. Free the resources associated with an OVcorrEntryListHandle.
OVEventDbCorrEntryListGetNext()
OVEventDbCorrEntryListGetNumElements()
OVEventDbGetChildEvent()
OVEventDbGetTreeLevel() OVEventDbGetOVsnmpPdu()
88
Chapter 4
The NNM Event Database API The NNM Event Database API Functions Table 4-1 NNM Event Database API Functions (Continued) Function OVEventDbEventIdtoUuid() OVEventDbUuidToEventId() Description Convert OVeventId into OVsnmpUuid format. Convert OVsnmpUuid into OVevent format.
Chapter 4
89
Memory Management
If an OVEventDb API returns a handle, the calling application must free the memory associated with the handle. If the API has an output pointer, the calling application must free the memory associated with the output pointer.
Data Structure
Data structure handles in OVEventDb API are opaque to the application. You must use related API to manipulate them:
typedef void *OVeventDbHandle; typedef void *OVeventHandle; typedef void *OVeventListHandle; typedef void *OVcorrEntryHandle; typedef void *OVcorrEntryListHandle;
90
Chapter 4
Chapter 5
91
This chapter describes the functions and data structures in the HP OVSNMP Configuration API. It includes descriptions of the following: the OVSNMP Configuration database OVSNMP Configuration API functions key data structures in the OVSNMP Configuration API, including each element and its use
92
Chapter 5
The OVSNMP Configuration API provides programmer access to the SNMP configuration database. Three classes of configuration parameters are stored in the database: parameters for specific managed nodes parameters for wildcarded IP addresses parameters for a global default
Whenever the configuration parameters for a managed node are requested, they are obtained from these three classes of stored information. The resulting parameters and the associated IP address of the destination can be cached, allowing subsequent lookups to be performed more quickly.
Chapter 5
93
RESOLUTION OVsnmpConfResolveDest() OVsnmpConfFreeDest() Obtain the effective configuration parameters for a specified destination agent. Deallocate all memory associated with the OVsnmpConfDest structure returned by OVsnmpConfResolveDest(3).
EDITING OVsnmpConfReadNextEntry() OVsnmpConfReadEntry() OVsnmpConfCreateEntry() Sequentially read specific node records from the SNMP configuration database. Read a specific node record from the SNMP configuration database. Create a new specific node record in the SNMP configuration database. This operation will fail if a record already exists for the specified node.
94
Chapter 5
The OVSNMP Configuration API The OVSNMP Configuration API Functions Table 5-1 Function Name OVsnmpConfStoreEntry() OVsnmpConfDeleteEntry() OVsnmpConfAllocEntry() OVsnmpConfCopyEntry() SNMP Configuration API Functions (Continued) Description Create or replace, as necessary, a specific node record in the SNMP configuration database. Delete a specific node record from the SNMP configuration database. Allocate an OVsnmpConfEntry structure. Allocate and initialize an OVsnmpConfEntry structure with the values from the specified OVsnmpConfEntry structure. Allocate and initialize an OVsnmpConfEntry structure with the values extracted from a configuration string in the format of an ovsnmp.conf(4) configuration file entry. Deallocate all memory associated with the specified OVsnmpConfEntry structure. Read the list of IP address wildcard records from the SNMP configuration database. Since the semantics of wildcard records are partly dependent upon the order of the records in the database, these records can only be updated as a single list. Create or replace, as necessary, the list of IP address wildcard records in the SNMP configuration database. Allocate memory for an OVsnmpConfWcList structure. This structure may then be inserted into the wildcard list obtained using OVsnmpConfReadWcList(3). Deallocate all memory associated with the specified list of OVsnmpConfWcList structures. Read the global default record from the SNMP configuration database. Create or replace, as necessary, the global default record in the SNMP configuration database.
OVsnmpConfParseEntry()
OVsnmpConfFreeEntry() OVsnmpConfReadWcList()
OVsnmpConfStoreWcList() OVsnmpConfAllocWcLis()
Chapter 5
95
The OVSNMP Configuration API The OVSNMP Configuration API Functions Table 5-1 Function Name OVsnmpConfGetVersions() SNMP Configuration API Functions (Continued) Description Determine which SNMP protocol versions are supported by an agent by reading the SNMP configuration database. Store or modify the field in the SNMP configuration database that indicates the SNMP protocol versions, which are supported by a particular agent. Replace the contents of the SNMP configuration database with records extracted from configuration strings in the specified ovsnmp.conf configuration file. Dump the contents of the SNMP configuration database to the specified ovsnmp.conf configuration file.
OVsnmpConfSetVersions()
OVsnmpConfImportFile()
Read the current SNMP configuration database administration record. This record contains options which control run-time caching and use of the backward compatibility configuration file. Update the current SNMP configuration database administration record. This enables you to modify the options which control runtime caching and use of the backward compatibility file.
OVsnmpConfStoreCntl()
MISCELLANEOUS OVsnmpConfDeleteCache() Remove all entries from the SNMP configuration run-time cache. New entries accumulate in the cache as applications call OVsnmpOpen() and OVsnmpConfResolveDest(). Sequentially read entries from the SNMP configuration run-time cache. This function is provided for troubleshooting only (such as dumping the contents of the cache for inspection.)
OVsnmpConfReadNextDest()
96
Chapter 5
The OVSNMP Configuration API The OVSNMP Configuration API Functions Table 5-1 Function Name OVsnmpConfPrintDest() SNMP Configuration API Functions (Continued) Description Print the contents of an OVsnmpConfDest structure to stdout on UNIX systems or to the console window on Windows operating systems. Print the contents of an OVsnmpConfEntry structure to stdout on UNIX systems or to the console window on Windows operating systems. Print the contents of an OVsnmpConfCntl structure to stdout on UNIX systems or to the console window on Windows operating systems.
OVsnmpConfPrintEntry()
OVsnmpConfPrintCntl()
Chapter 5
97
The OVSNMP Configuration API Data Structures for the OVSNMP Configuration API
Header Files
The header file defines many data structures that are part of the OVSNMP configuration API. The only header file required to use the OVSNMP configuration API functions is $OV_HEADER/OV/OVsnmpConf.h1. See Table 3-5 for a list of all header files included in the OVSNMP API.
Data Structures
Table 5-2 describes the key data structures that are used with the OVSNMP Configuration API. Table 5-2 SNMP Configuration API Data Structures Data Structure OVsnmpConfEntry Description This structure contains the parameters that make up an SNMP configuration record for a particular destination in the managed environment. It is also used as a substructure in the OVsnmpConfWcList and OVsnmpConfDest structures. This structure forms an element of a linked list used to represent the IP address wildcard list.
OVsnmpConfWcList
1. See the reference page for ov.envvars for details on the environment variable $OV_HEADER. 98 Chapter 5
The OVSNMP Configuration API Data Structures for the OVSNMP Configuration API Table 5-2 SNMP Configuration API Data Structures (Continued) Data Structure OVsnmpConfDest Description This structure contains the fully-resolved configuration parameters for a particular destination in the managed environment. Additionally, it contains addressing information which is determined at run time instead of being stored in the configuration database. This structure contains administrative options which control how run-time caching and the backward compatibility configuration file are used by the OVSNMP API.
OVsnmpConfCntl
char *
community
Chapter 5
99
The OVSNMP Configuration API Data Structures for the OVSNMP Configuration API Table 5-3 Type char * OVsnmpConfEntry Structure (Continued) Name setCommunity Description The SNMP community name, which is used by the management application when issuing SNMP Set requests to the destination. The identity of a proxy for the destination. This may be an IP hostname or an IP address. If the destination is accessed directly, this field contains the value of SNMP_CONF_DONT_PROXY_STRING. The amount of time, in tenths of a second, the OVSNMP API will initially wait for an SNMP response before attempting to retransmit the SNMP request to the destination. The maximum number of retransmissions the OVSNMP API will attempt before generating a no response condition for an SNMP request. The frequency, in seconds, at which netmon determines the status of the destination node. This field is not used by the OVSNMP API. The UDP port number on the destination or proxy node (as appropriate) where the SNMP agent on that node expects to receive SNMP requests for the destination. The standard SNMP port is 161. This field is generally used only for specialized proxy agents which do not listen to the standard SNMP port.
char *
proxy
int
timeout
int
retry
int
pollInterval
u_short
remotePort
100
Chapter 5
The OVSNMP Configuration API Data Structures for the OVSNMP Configuration API In Figure 5-1, the fields of the OVsnmpConfWcList structure are shown in order. Note that the configuration parameters are contained in an OVsnmpConfEntry structure pointed to by the confEntry field. Figure 5-1 OVsnmpConfWcList Structure OVsnmpConfWcList * next * confEntry NULL
Table 5-4 describes the fields in the OVsnmpConfWcList data structure: Table 5-4 Type struct SNMPconfwclist * OVsnmpConfEntry * OVsnmpConfWcList Structure Field Name next Description A pointer to the next OVsnmpConfWcList entry in the IP address wildcard list. The value for this field should be NULL for the last entry in the list. A pointer to the OVsnmpConfEntry structure that contains the configuration parameters for the IP Address wildcard entry.
confEntry
Chapter 5
101
The OVSNMP Configuration API Data Structures for the OVSNMP Configuration API The OVsnmpConfWcList structure is returned by a call to OVsnmpConfReadWcList() and should be deallocated by a call to OVsnmpConfFreeWcList().
102
Chapter 5
The OVSNMP Configuration API Data Structures for the OVSNMP Configuration API Table 5-5 describes the fields in the OVsnmpConfDest data structure. Table 5-5 Type OVsnmpConfEntry * OVsnmpConfDest Data Structure Field Name confEntry Description A pointer to the OVsnmpConfEntry structure which contains the fully-resolved configuration parameters for the specified destination. A boolean flag indicating whether or not the IP address for this destination is that of the actual destination (FALSE) or that of a proxy node (TRUE). Pointer to the address of the SNMP agent for this destination. Supported address families are AF-INET and AF-IPX. By default, only AF_INET (udp/ip) destinations are returned. The SNMP_CONF_RESOLVE.ANYADDR flag must be specified as input to OVsnmpConfResolveDest() in order for both IP and IPX destinations to be returned. This is done for compatibility of existing IP-only applications. The IP address of the peer entity to which SNMP requests should be sent for the specified destination. This field has been replaced by agentAddr. It is retained for backwards compatibility of existing applications. For IP agents, this value is the same as (sockaddr_in*)agentAddr sin_addr.s_addr. For IPX agents, this value is zero. The date and time when the ipAddr field was last queried from the IP address name server. This value is obtained from time(). The fully distinguished name of the nex_hop agent associated with the destination target.
short
isProxied
struct sockaddr*
agentAddr
u_long
ipAddr
time_t
ipAddrAge
char *
agentName
Chapter 5
103
The OVSNMP Configuration API Data Structures for the OVSNMP Configuration API
cacheFlags_t
cacheFlags
compat3_2_t
compatFlags
Cache Flags The cache flag in the OVsnmpConfCntl structure may be set to one of the following: SNMP_CONF_CACHE_NONE Run-time caching of SNMP configuration parameters and IP addresses is disabled. The information is recomputed each time a destination is referenced.
104
Chapter 5
The OVSNMP Configuration API Data Structures for the OVSNMP Configuration API SNMP_CONF_CACHE_NOADDR SNMP configuration parameters for previously referenced destinations are maintained in the SNMP configuration run-time cache. However, the IP address of those destinations is not maintained in the cache. The IP address is determined each time the destination is referenced by consulting the IP address name server. SNMP_CONF_CACHE_ALL Both SNMP configuration parameters and the IP address of previously referenced destinations are maintained in the SNMP configuration run-time cache. Compatibility Flags The compatibility flag in the OVsnmpConfCntl structure may be set to one of the following: SNMP_CONF_SHADOW_NONE The configuration file for release 3.2 backward compatibility is not maintained. This mode of operation should only be used if all OVSNMP API-based applications installed and running on the system have been linked with a later release of the OVSNMP API. SNMP_CONF_SHADOW_32ONLY Only the subset of entries in the SNMP configuration database, which are configured to use the default SNMP port for communications, are maintained in the backward compatibility file. This will optimize performance of Release 3.2-based applications. However, if the xnmsnmpconf -import command is subsequently used with the resulting shadow file, some information in the SNMP configuration database will be lost. SNMP_CONF_SHADOW_ALL All entries in the SNMP configuration database are maintained in the Release 3.2-compatible configuration file. This mode of operation ensures absolute consistency between the SNMP configuration database and the compatibility configuration file. However, this mode may cause unnecessary performance degradation of Release 3.2-based applications if there are many proxy entries which use a non-default SNMP port configured in the SNMP configuration database.
Chapter 5
105
The OVSNMP Configuration API Data Structures for the OVSNMP Configuration API
106
Chapter 5
Chapter 6
107
Network management applications (managers and agents) are generally complex. Whenever unexpected behavior is seen, it is useful to have detailed information about the state of the application, and even a history of what preceded the behavior. Logging and tracing are two tools for obtaining this kind of information. They both involve tracking state changes in your software. The occurrence of certain incidents can trigger a new entry in the log file. For example, an agent might enter a log message when a particular value is set. A key attribute of each incident is its severity, which is one of four levels ranging from INFORMATIVE to DISASTER. Tracing, on the other hand, is used to trace step-by-step the execution of your program. For example, trace messages are typically written at the entry and exit points of each function.
108
Chapter 6
Tracing
The OVuTL API is provided to let you integrate your application with the common logging and tracing facility called nettl. This facility uses daemon processes to receive log and trace data from network applications (including the platform itself), and to direct that data to its appropriate destination. For more information about the nettl subsystem, see the nettl (1M) manpage, as well as other manpages to which it refers.
Chapter 6
109
110
Chapter 6
Integrating with Logging and Tracing The OVuTL Application Programming Interface
OVuLog()
OVuTrace()
Chapter 6
111
Integrating with Logging and Tracing The OVuTL Application Programming Interface
112
Chapter 6
Chapter 7
113
The HP OpenView platform provides a robust process management mechanism, which coordinates the startup, shutdown, pause, and resume of the various NNM processes. This permits you to specify which processes your application or process expects to find when it wakes up, and to control other related aspects of your interaction with NNM. This chapter covers a brief overview of process management in the HP OpenView platforms the OVsPMD application programming interface (OVsPMD API) guidelines for constructing the first and second lines of a Local Registration File guidelines for integrating your application with NNMs automated backup
NOTE
The Local Registration File (LRF) is an important file for your process. This chapter discusses only the first and second line of that file, since these lines pertain to process management. Any additional lines in this file are not relevant to Network Node Manager.
114
Chapter 7
ovspmd obtains information about which processes to start, and when to start them, from the startup file, or SUF. The SUF is constructed by the ovaddobj command, which adds startup information each time it is run, based on the Local Registration File that it reads.
Chapter 7
115
NOTE
On Windows operating systems, ovspmd is a service. Refer to your Windows operating system documentation for details on services.
Figure 7-1
Process Management Administrative Commands: ovstart, ovstop, ovpause, ovresume,ovstatus Requests Responses ovsnmpd Tracing & Logging Subsystem ovsuf LRF ovaddobj command
Well-behaved Process
Well-behaved Process
Non-well-behaved Process
Daemon Process
Figure 7-1 illustrates how the ovspmd process operates. Note that the diagram shows three kinds of processes: Well-behaved Processes A well-behaved process uses the OVsPMD API the topic of the next section to communicate with ovspmd. It sends ovspmd status information regarding successful and unsuccessful initialization, normal and abnormal termination, and pause and resume information if configured to do so. ovspmd considers a well-behaved process to have initialized successfully only when it explicitly reports that it has. A well-behaved process also exits when it receives the command OVS_CMD_EXIT from ovspmd. If the process fails to respond, the exit command is escalated to
116
Chapter 7
Integrating with Process Management Process Management for HP OpenView Applications SIGTERM, and eventually to SIGKILL. It will respond to OVS_CMD_PAUSE and OVS_CMD_RESUME commands if it is configured to receive them. The status information passed by the managed process to ovspmd is used by ovstart, ovstop, ovstatus, ovpause or ovresume, if currently running. The last message received from each managed process is saved, and forwarded, on request, to ovstatus. The messages received from well-behaved processes are also logged using the nettl logging and tracing facility. Non-well-behaved Process ovspmd can also manage object managers that do not use the OVsPMD API (non-well-behaved processes) only if they do not go into the background of their own accord (see OVs_DAEMON which follows). Since a non-well-behaved process returns no status messages, ovspmd considers such processes to have initialized successfully if the process has not exited within the lrf specified timeout interval. During shutdown, the ovspmd process sends SIGTERM to non-well- behaved processes to notify them of the need to terminate. Non-well-behaved processes that fail to terminate within the configured timeout are sent SIGKILL. Daemon Process Managed processes that go into the background cannot be managed either with a communication channel or with signals. ovspmd can start such a process, but cannot stop or report meaningful status about it, since it has neither a communication channel nor a process ID for it. However, you can run a script or program to stop the daemon. Refer to Field 7: Daemon Stop Command on page 126. You need to decide which type of process to create. 1. If you are writing a new program, you will probably want to use the OVsPMD API and create a well-behaved process. This is by far the best choice. Chapter 7 117
Integrating with Process Management Process Management for HP OpenView Applications 2. If you have an existing process that does not go into the background, you can decide to not modify it, and declare it a non-well-behaved process. This may be expedient, but it is less than ideal. It would be better to take a little time to incorporate simple calls to the OVsPMD API and create a well-behaved process. 3. If you have an existing process that does go into the background, you can decide to not modify it, and declare it a daemon process. This too may be expedient, but results in a poorly integrated process. 4. If you want your process to receive pause and resume notification, your process must be well-behaved. To decide what to do, you may want to understand something about the OVsPMD API, the topic of the next section.
118
Chapter 7
OVsInitComplete() OVsReceive()
OVsDone()
OVsResponse()
See the reference page for OVsPMD_API (3) for additional details. In general, use these rules to create a well-behaved process: 1. Call OVsInit() when your process begins initialization. This gives you a socket for later communication with the ovspmd process. 2. After initialization is completeand regardless of whether it was successful or notyou must call OVsInitComplete(). A parameter to OVsInitComplete() indicates the initialization status; if initialization failed, your process should call OVsInitComplete() and exit (do not call OVsDone()).
Chapter 7
119
Integrating with Process Management The OVsPMD Application Programming Interface 3. Your processs control thread should be organized around a select() loop, waiting for input from managers or from the managed object. Select for reading on the file descriptor returned by OVsInit(). 4. When select() indicates the ovspmd file descriptor is readable, use OVsReceive() to get the command from ovspmd. OVS_CMD_EXIT means your process should clean up, call OVsDone(), and exit. OVS_CMD_PAUSE means your process should suspend data processing. OVS_CMD_RESUME means your process can resume data processing. 5. If your process exits on its own initiative (that is, without instructions from ovspmd), call OVsDone(), indicating in the message parameter the reason for termination. This message will be logged by ovspmd along with other exit information. 6. Never go into the background (fork and exit in the parent); the child process cannot be managed by ovspmd.
120
Chapter 7
As a developer, it is your responsibility to provide an LRF with your process. The LRF makes it possible for the HP OpenView platform to manage your process. The LRF must contain the first two lines of information, which describe the process.
Chapter 7
121
General Syntax
Each line in an LRF contains two or more fields. Each field is terminated by a colon, including the last field. Some fields are optional; it is recommended that you still include the colon terminator for the missing fields. The number symbol (#) indicates the beginning of a comment, which continues to the end of the line. White space (spaces, tab characters, and newlines) is not permitted within any field, nor are any multibyte characters. In the first two lines of the LRF, only printable ASCII characters are allowed (values between decimal 32 and 126). The colon (:), comma (,), backslash (\), and number sign (#) can only appear as terminator characters, as noted above and in later syntax descriptions.
NOTE
You must put a backslash in front of the colon that specifies the drive specification on the Windows operating systems. This prevents the colon in the path from being interpreted as a field terminator.
Field 1: Name Specifies the name of the process being registered. You are responsible for ensuring the uniqueness of the process name. For example, you could append your companys name:
IPMgr_A.017.0_MegaCorp_International
122
Chapter 7
Integrating with Process Management The Local Registration File The name must be the same name used in the session parameter to the mp_bind() function call, and is the name used when invoking ovstart, ovstop, ovstatus, and ovisrunning. Field 2: Path Specifies the location of the process executable code. Specify the full (absolute) pathname. If you have set up universal path names, you can specify the partial pathname relative to the path install_dir\BIN or $OV_BIN. Note that if a directory is not specified for the executable, install_dir\BIN or $OV_BIN is assumed.
NOTE
You must put a backslash in front of the colon that specifies the drive specification on Windows operating systems. This prevents the colon in the path from being interpreted as a field terminator. For example,
IPMgr_A.017.0_MegaCorp_International:C\:install_dir\bin\netmon:
LRF Line One Example Following are examples of the first line of a hypothetical LRF on HP-UX, Solaris, or Linux. The process executable is located in $OV_BIN/MEGA/ip_mgr.
IPMgr_A.017.0_MegaCorp_International:MEGA/ip_mgr:
The following is an example of the first line of a hypothetical LRF on Windows. The process executable is located in C:install_dir\bin\MEGA\ip_mgr.
IPMgr_A.017.0_MegaCorp_International:C\:install_dir\bin\MEGA\ip_mgr:
Chapter 7
123
Integrating with Process Management The Local Registration File There are seven fields in the second line of the LRF. Each field is terminated by a colon (:). The following Table 7-4 describes each field in turn. Following the table is a complete description of each field. Table 7-4 Second Line of the LRF& Field 1: Initial Start Flag 2: Dependencies Syntax A character string; optional. A series of character strings, separated by commas; optional. A series of character strings, separated by commas; optional. A character string; optional. An integer; optional. A character string; optional. A character string; optional Default OVs_NO_START None (that is, can be started at any time).
3: Arguments
Field 1: Initial Start Flag This flag indicates whether or not the process is to be launched when the ovstart command is issued without arguments. Possible values for this field: OVs_YES_START and OVs_NO_START. The OVs_YES_START flag means the process will be started by the ovstart command. The OVs_NO_START flag means the process will not be started by the ovstart command. Processes that use OVs_NO_START must be explicitly started by name (for example, ovstart process_name).
124
Chapter 7
Integrating with Process Management The Local Registration File Field 2: Dependencies This is a list of process names, separated by commas, that must already be running before your process can be started. ovspmd uses this information to determine the order in which to start processes. Use the names as they appear in the Name field of the pertinent LRFs. Field 3: Arguments The arguments specified in this field are passed to the process as it starts up, just as if a user had passed them from the command line. Commas or blanks can be used to separate multiple arguments in this field. For example, suppose the arguments field had this entry -i,-b,amazon:. This would be equivalent to -i -b amazon on the command line. Field 4: Behavior This field specifies how the process will interact with ovspmd. Processes can be well-behaved, non-well-behaved, or daemons, as described earlier. Possible values for this field: OVs_WELL_BEHAVED, OVs_NON_WELL_BEHAVED, and OVs_DAEMON. Field 5: Timeout For well-behaved processes, this field is used to manage evident startup failures. There are two cases: Your process invokes OVsInitComplete() and returns OVS_RSP_FAILURE in the status code parameter, but fails to terminate before the timeout expires. Your process invokes OVsDone(), but fails to terminate before the timeout expires.
In either case, ovspmd terminates the process, sending it SIGTERM and if necessary, SIGKILL. If your process is either non-well-behaved, or a daemon, ovspmd waits until the timeout expires before starting any process that lists your process in its Dependencies field. Also, after ovspmd sends your process SIGTERM, it waits until the timeout expires before sending it a SIGKILL signal.
Chapter 7
125
Integrating with Process Management The Local Registration File This field is also used as the PAUSE timeout. It specifies the amount of time a process has to respond to an OVS_CMD_PAUSE. If the process does not respond in time, the pause operation fails. For well-behaved processes with Field 6 set to PAUSE, the timeout field is also used to manage a failure to respond to an OVs_CMD_PAUSE. A failure to respond within the timeout is processed as a PAUSE NACK. Field 6: Pause For well-behaved processes, this field is used to register for pause and resume messages. Possible values for this field include: PAUSE and NOPAUSE. The default is NOPAUSE: specifying NOPAUSE or leaving the field blank prevents ovspmd from sending pause and resume messages to your process. A process that is dependent on one or more NNM processes must accurately specify these dependencies in its LRF to ensure that it is paused before and resumed after all processes on which it is dependent. For more information about backup refer to Integration with NNM Automated Backup on page 127. Field 7: Daemon Stop Command This field can be used only for OVS daemon processes. It follows the same rules as the PATH field in the first line. It identifies a command (script or executable) that is to be run to stop the OVS daemon process. It may contain optional parameters. If a specific path is not specified, \install_dir\BIN (Windows) or $OV_BIN (UNIX) is assumed. The command should return 0 for success; anything else for failure. LRF Line Two Example The following is an example of the second line of a hypothetical LRF:
OVs_YES_START:pmd,ovead:-v,-n:OVs_WELL_BEHAVED:15:NOPAUSE::
126
Chapter 7
NOTE
Integration with backup is not required. However, while NNM is paused, ovw and other OV processes block on any received OVw and OVwDb API calls. Applications and services (background processes) that do not integrate with automated backup, but that do interact with HP OpenView APIs and processes cannot communicate with NNM while the HP OpenView processes are paused. For this reason, you need to understand and possibly respond to the backup model even though you do not intend to participate in backups.
Chapter 7
127
128
Chapter 7
Figure 7-2
Operational Phase
pause processes
copy operational data to staging area Data Restore Stage Analytical Phase resume processes copy data from permanent archive
To guarantee the synchronization of the operational data, ovbackup.ovpl uses ovpause to issue a pause that is sent to every ovspmd process that has registered to receive pause notifications. (Refer to the ovspmd reference page for details.) After all processes have paused, ovbackup.ovpl creates a data snapshot by running any script found in the $OV_CONF/ovbackup/checkpoint/operational directory. Because all processes are paused when the snapshot is created, all data contained in the snapshot is guaranteed to be synchronized. As soon as the snapshot is created, ovresume is called, and all processes are released from the paused state.
Chapter 7
129
Integrating with Process Management Integration with NNM Automated Backup After the operational phase has completed, the analytical phase is run. The purpose of this phase is to create a snapshot of any HP OpenView data that needs to be backed up, but does not need to be synchronized with the operational data. During the analytical phase NNM provides scripts to create a snapshot of the following data: snmpCollect data ($OV_DB/snmpCollect) NNM Data Warehouse data
After the analytical phase has ended, ovbackup will terminate. A snapshot of the HP OpenView data is in the staging area, ready to be copied to long term backup media. Options to ovbackup.ovpl enable an administrator to back up only the operational data (- operational) or only the analytical data (- analytical). Archiving Data The automated backup utilities do not provide tools for archiving the data after it is placed into the staging directory. Each site needs to provide tools to archive the data from the staging area to backup media. Restoring Data The restore utility, ovrestore.ovpl, requires that NNM is halted (ovstop) the archived data has been copied to the staging area
Like ovbackup.ovpl, there are options to ovrestore.ovpl to enable the administrator to restore only operational data or only analytical data. See the reference page for ovrestore.ovpl.
Integrating with Process Management Integration with NNM Automated Backup The three ways of integrating are script integration, ovwMapClose integration, and background process integration: Script integration is done by adding scripts to the backup script directories. It is a way for an application to get its data backed up along with the NNM data. ovwMapClose integration is done by making an applications behavior sensitive to the OVwEventSource parameter in the ovwMapClose callback. It is a way for an application to optimize its behavior by eliminating those actions that are necessary for responding to a real map close but not for responding to a paused system. This is what applications must do to receive PAUSE notification. Background process integration (integrating via services) is done by modifying a background process to receive and handle pause and resume notification. It is a way for a background process to change its behavior during backup or to act as a proxy to inform other processes of the paused state of the system so that those processes can change their behavior. This is how background processes or proxies receive PAUSE notification.
Evaluating An Application
To make it easy to integrate with automated backup this section provides the information to help you determine which means of integrating are relevant to your application. Then, you can focus on those sections of the documentation which provide the integration information needed by your application, while skipping the other sections. For each decision tree, answer the question in the diamonds based on what you know about the internals of your application. When you reach the end of each decision tree you will know if that form of integration is relevant to your application. The sections referenced at the end points of the decision trees are the parts of the documentation which provide additional information about how to integrate. Note that the three means of integrating are not mutually exclusive. For a particular application one, two, or all three may be appropriate.
Chapter 7
131
Integrating with Process Management Integration with NNM Automated Backup Script Integration Script integration is done by adding scripts to the backup script directories. It is a way for an application to get its data backed up along with the NNM data. Script integration consists of providing a backup script and a recovery script for the applications data. The script may be integrated into the operational or analytical directory, depending on the relationship of the applications data to the NNM operational data. If this applies to your application, refer to Writing Backup Scripts on page 135. Figure 7-3 Decision Tree for Script Integration
NO
YES
Investigate script integration for the application. See Writing Backup Scripts.
Integration Via ovwMapClose Event This type of integration applies to applications that use the OVw API and register with OVW via an application registration file. ovwMapClose integration is done by making an applications behavior sensitive to the OVwEventSource parameter in the ovwMapClose callback. It is a way for an application to optimize its behavior by eliminating those activities which, while necessary for responding to a real map close, are not necessary for responding to a pause. ovwMapClose integration consists of looking at the OVwEventSource in the ovwMapClose callback and optimizing the applications behavior when the value of the OVwEventSource indicates that the event
132
Chapter 7
Integrating with Process Management Integration with NNM Automated Backup triggering the callback is a pause rather than an actual map close. If this applies to your application, refer to Integration via ovwMapClose on page 137. Figure 7-4 Decision Tree for ovwMapClose Event Integration
NO
Background Process Integration Background integration is a way for a background process to change its behavior during backup or to act as a proxy to inform other processes of the paused state of the system so that they can change their behavior.
Chapter 7
133
Integrating with Process Management Integration with NNM Automated Backup Background process integration consists of 1) registering to receive pause and resume notification from ovspmd when backup takes place and 2) implementing the pause behavior that is appropriate for the background process. If this applies to your application, refer to Integrating via Services (Background Processes) on page 138. Figure 7-5 Decision Tree for Background Process Integration
Does the application have a background process that registers with ovspmd?
NO
YES
NO Does that background process have dependencies on other NNM background processes? Does the background process access the applications data store?
NO
YES
YES
134
Chapter 7
ovbackup.ovpl runs:
Operational Phase
operational scripts
initiate restore post-resume scripts Analytical Phase resume system restore operational data restore analytical data
analytical scripts
Chapter 7
135
Integrating with Process Management Integration with NNM Automated Backup pre-pause scripts: This step is used infrequently. Scripts in $OV_CONF/ovbackup/pre_pause are run before the global pause. You might want to add a script during this step if your application has an SQL database that you want to prepare before continuing with the backup. operational scripts: Scripts in $OV_CONF/ovbackup/checkpoint/operational manage data that must remain synchronized. ovbackup.ovpl calls each script in this directory in random order. post-resume scripts: Like the pre-pause scripts, this step is used infrequently. Scripts in this step are run after NNM processes are resumed. analytical scripts: Scripts in $OV_CONF/ovbackup/checkpoint/analytical manage data for processes such as snmpCollect that are able to resynchronize their data with the main NNM databases or that do not require their data to correlate directly with NNM databases. ovbackup.ovpl calls each script in this directory in random order.
When writing backup scripts for your application, the most important decision to make is whether to locate the scripts in the operational directory or the analytical directory. The key to making this decision is whether your data is dependent on the data in one or more of NNMs databases. NNM processes remain paused while all scripts in the $OV_CONF/ovbackup/checkpont/operational directory run. Adding scripts to this directory increases the time that NNM is unavailable to users during backup. If your data is dependent on the data in one or more of NNMs topology, object, and map databases, then your backup script belongs in the operational directory. Otherwise, locate your script in the analytical directory. The analytical step is provided for data that is not dependent on the operational data. By locating your script in the analytical directory, you help to limit the time that the system pauses. An example of dependent data that would have to be backed up and restored with the NNM-dependent data is data that uses an OVW object ID as a key. In this case, you would provide a script for the operational directory.
136
Chapter 7
Integrating with Process Management Integration with NNM Automated Backup Refer to the reference pages for ovbackup.ovpl, ovpause, ovresume, ovuispmd, ovsmpd, ovrestore.ovpl, and the backup scripts in $OV_CONF/ovbackup/checkpoint/operational and $OV_CONF/ovbackup/checkpoint/analytical for more information on backup scripts.
Chapter 7
137
Integrating with Process Management Integration with NNM Automated Backup Applications that choose to keep their map-related information rather than deleting it can simply resume operations as though the pause had not taken place. Other applications must reload their map information. Figure 7-7 API integration with Backup
Data Copy Stage Integrating Application initiate backup ovwMapClose pause system copy operational data to staging area Acknowledge and respond Data Archive Stage copy data to permanent archive
resume system
138
Chapter 7
Integrating with Process Management Integration with NNM Automated Backup it is dependent. For more information on well-behaved processes and how to use the LRF, refer to See The Local Registration File on page 121 and to the lrf (4) reference page. To integrate with backup you must specify PAUSE in Field 6 of the LRF so that pause and resume messages will be sent to your service. As Figure 7-8 shows, when ovbackup.ovpl executes ovpause, ovspmd sends notification (OVS_CMD_PAUSE) to all registered services. When your service receives this notification, it should stop all operations, flush data to disk if necessary, and acknowledge the pause request with OVsResponse(OVW_RSP_PAUSE_ACK, "Paused"). If your service cannot stop operations, the proper response is OVsResponse(OVW_RSP_PAUSE_NACK,"Text"). The text, which is sent to ovpause, should describe the reason for the negative acknowledgment. Figure 7-8 Backup via Background Services Data Copy Stage initiate backup
pause processes
OVS_CMD_PAUSE OVS_RSP_PAUSE_ACK
wellbehaved process
resume processes
OVS_CMD_RESUME OVS_RSP_RESUME_ACK
Chapter 7
139
After NNM completes the dependent phase of its backup process, ovspmd sends notification (OVS_CMD_RESUME) to registered services. Your service should acknowledge the resume message using OVsResponse(OVS_RSP_RESUME_ACK "text"). If your service cannot resume operations, use OVsResponse(OVS_RSP_RESUME_NACK "text") Care should be taken when choosing a timeout value for your process. If the timeout duration is too short, your process may cause the ovpause command to fail (and therefore cause ovbackup.ovpl to fail). If it is too long, the system could take too long to report a valid error with your process. Some of the ovw processes will have been paused already, and the user will be unable to interact with these subsystems. Remember that the timeout value is specified in seconds. Also keep in mind that some users may have slow machines.
140
Chapter 7
Index
A agent, 27 agents daemon, 117, 125 non-well-behaved, 125 well-behaved, 116 API architecture, 23 applications SNMPv2 style, 69 ASN.1, 37, 76, 79 data representation, 37 data types, 37 B background, sending your process into, 120 bilingual communication mode, 47 BITS, 37 blocking mode, 29, 55 C cache flags, in OVsnmpConfCntl, 104 callback function, 73 parameters, 73 ccitt(0), 35 communications APIs for communications, 58 for manual retransmission, 58 for message setup/management, 58 for session management, 58 in SNMP library, 58 communications model agent process, 27 manager process, 27 SNMP, 27 compatibility flags, in OVsnmpConfCntl, 105 compiling and linking, 66 configuration API, 93 data structures, 98 header files, 98 connectionless operation, 28 conventions typographical, 15 correlated events receiving, 53 Correlation Log File Group, 85 Counter, 37 Counter32, 37 Counter64, 37 D data structures, 66, 70, 98 memory management, 64 data types ASN.1, 37 dot notation, 36 E enterprise-specific MIB, 37 environment variables OV_HEADER, 67 error codes, 48 error values macro for mapping, 69 Event Log File Group, 85 extended MIB, 37 F file descriptor for a session, 71 flags, 104, 105 foreign device definition, 28 G Gauge, 37 Gauge32, 37 Get Bulk Request, 32 Get Next Request, 31 Get Request, 31 Get Response, 31 H header files, 67, 98 I include files, 67, 98 inform message, 30 Inform Request, 32 installing the SDK, 21 INTEGER, 37 Integer32, 37 integration with logging, 109 with process management, 115 with tracing, 109 interface behavior, 47 IPAddress, 37 IPX protocol, 52 iso(1), 35
141
Index
J joint-iso-ccitt(2), 35 L linking, with library, 66 location transparency and proxies, 39 logging and OVuTL API, 109 description of, 109 severity levels, 109 LRF, 115 agent name and location, 122 and ovstart, ovstop, ovstatus, and mp_bind(), 123 and Process Management, 121 contents of, 121 general syntax, 122 line 1 syntax, 122 line 2 syntax, 124 mandatory, 24 M Management Information Base, 33 manager, 27 manual retransmission communications APIs, 58 memory management, 63 message setup/management communications APIs, 58 MIB enterprise-specific, 37 extended, 37 MIB-II, 33 MIB-II object definition OID, 35 N naming tree, 35 ccitt(0), 35 iso(1), 35 joint-iso-ccitt(2), 35 NDBM Offset File Group, 85 nettl, 109 NetworkAddress, 37 non-blocking mode, 29, 55 notifications, 27, 30 NT. See Windows O OBJECT IDENTIFIER, 37 object identifier, 35, 36 OCTET STRING, 37 OID, 35, 36 OID, dot notation, 36 OV_HEADER, 67 ovaddobj, and SUF, 115 OVEventDb API, 85 OVEventDbClose, 87 OVEventDbCorrEntryListGetNext, 88 OVEventDbCorrEntryListGetNumElements OVEventDbEventIdtoUuid, 89 OVEventDbEventListGetNext, 86, 88 OVEventDbFindCorrelatedEvents, 86, 87 OVEventDbFreeCorrEntry, 87 OVEventDbFreeCorrEntryList, 88 OVEventDbFreeEvent, 87 OVEventDbFreeEventList, 88 OVEventDbGetChildEvent, 88 OVEventDbGetChildId, 88 OVEventDbGetCorrelationTree, 86, 87 OVEventDbGetCorrEventStatus, 88 OVEventDbGetNumChildren, 88 OVEventDbGetOVsnmpPdu, 88 OVEventDbGetParentId, 88 OVEventDbGetTreeLevel, 88 OVEventDbIsEventCorrelated, 87 OVEventDbOpenCorrLogforReading, 87 OVEventDbOpenLogforReading, 87 OVEventDbOpenStreamforReading, 87 OVEventDbReadNextCorrEntry, 87 OVEventDbReadNextEvent, 87 OVEventDbUuidToEventId, 89 OVsDone(), 119 OVsInit(), 119 OVsInitComplete(), 119 OVSNMP API, 21 enhanced error codes, 49 IPX support, 52 memory management, 63 multitransport interface, 52 on Windows, 57 protocol support, 45, 50 protocol translations, 47 OVSNMP API, architecture, 23 OVSNMP configuration API, 93 functions, 94 OVsnmpAddNullVarBind, 58 OVsnmpAddTypedVarBind, 58 OVsnmpBlockingSend, 58
, 88
142
Index
OVsnmpCallback, 58 OVsnmpCancel, 58 OVsnmpClose, 58 OVsnmpConfCntl structure cache flags, 104 compatibility flags, 105 description of, 104 OVsnmpConfDest structure, 102 OVsnmpConfEntry structure, 99 OVsnmpConfWcList structure, 100 OVsnmpCopyPdu, 58 OVsnmpCreatePdu, 58 OVsnmpErrString, 58 OVsnmpEventOpen, 58 OVsnmpFixPdu, 58 OVsnmpFreePdu, 58 OVsnmpGetRetryInfo, 58 OVsnmpOpen, 52, 58 OVsnmpPdu, 75, 79, 100, 102 OVsnmpPdu structure, 54, 70, 75, 79 OVsnmpRead, 58 OVsnmpRecv, 58, 73 OVsnmpSend, 58 OVsnmpSession structure, 56, 71 OVsnmpTrapOpen, 58 OVsnmpVal, 70, 81 OVsnmpVarBind, 70 OVsnmpVarBind structure, 76, 79 OVsnmpWEventOpen, 58 OVsnmpWOpen, 58 OVsnmpXCancel, 58 OVsnmpXClose, 58 OVsnmpXEventOpen, 58 OVsnmpXOpen, 58 OVsnmpXSend, 58 OVsnmpXTrapOpen, 58 ovspmd diagram, 115 process management daemon, 115 OVsPMD API functions in, 119 rules for use, 119 OVsReceive(), 119 ovstart, 115 ovstatus, 115 ovstop, 115 ovtrapd on UNIX, 30 on Windows, 30 OVuint64Add, 58 OVuint64AddUInt32, 58 OVuint64Assign, 58 OVuint64Cmp, 58 OVuint64CmpUInt32, 58 OVuint64Divide, 58 OVuint64DivideUInt32, 58 OVuint64FromStr, 58 OVuint64Multiply, 58 OVuint64MultiplyUInt32, 58 OVuint64Shift, 58 OVuint64Subtract, 58 OVuint64SubtractUInt32, 58 OVuint64ToStr, 58 OVuLog(), 111 OVuTL API functions of, 111 tracing and logging, 109 OVuTrace(), 111 P PDU description of, 28 trap, 76, 79 process management, 115 ovspmd, 115 OVsPMD API, 119 ovstart, 115 ovstatus, 115 ovstop, 115 protocol support, 45 protocols SNMP, 31 proxy and location transparency, 39 description of, 28 R references to other documents, 40 retransmission communications APIs, 58 retransmissions, 55, 57 RFC list, 40 S select(), 120 select(2), 71 session management communications APIs, session, sequence of communication, 29 Set Request, 31 SMI, 33 SNMPv1, 33 SNMP operations, 31
58
143
Index
SNMP Configuration API data structures, 98 functions in, 94 header files, 98 SNMP library, communications API functions in, 58 SNMP session sequence of actions, 29 SNMP_STD2OV_ERR, 58 SNMPv1 operations, 31 SNMPv1 protocol, 31, 45 SNMPv2 operations, 32 SNMPv2 Trap Request, 32 SNMPv2C protocol, 31, 45 Software Development Kit, 21 startup file (SUF), 115 Stream Log File Group, 85 Structure of Management Information, 33 structures, 98, 104 OVsnmpConfDest, 102 OVsnmpConfEntry, 99 OVsnmpConfWcList, 100 OVsnmpPdu, 54, 75, 79 OVsnmpSession, 71 OVsnmpVarBind, 76, 79 T Timeticks, 37 tracing and OVuTL API, 109 description of, 109 trap PDU, 76, 79 Trap Request, 31 trapd, 30 traps, 27, 30, 76, 79 communication sequence, 30 U UDP, 28, 52 User Datagram Protocol/Internet Protocol,
29
W Win32 message loop, 57 Windows IPX support, 52 ported application support, 52 traps, 30 144