You are on page 1of 140

SNMP Developers Guide

HP OpenView Integration Series

Manufacturing Part Number : J1261-90072 May 2002

United States Copyright 2002 Hewlett-Packard Company.

Legal Notices
Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and tness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material. Warranty. A copy of the specic warranty terms applicable to your Hewlett- Packard product and replacement parts can be obtained from your local Sales and Service Ofce. Restricted Rights Legend. All rights are reserved. No part of this document may be photocopied, reproduced, or translated to another language without the prior written consent of Hewlett-Packard Company. The information contained in this document is subject to change without notice. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 for DOD agencies, and subparagraphs (c) (1) and (c) (2) of the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 for other agencies. HEWLETT-PACKARD COMPANY 3404 E. Harmony Road Fort Collins, CO 80528 U.S.A. Use of this manual and exible disk(s), tape cartridge(s), or CD-ROM(s) supplied for this pack is restricted to this product only. Additional copies of the programs may be made for security and back-up purposes only. Resale of the programs in their present form or with alterations, is expressly prohibited. Copyright Notices. Copyright 1983-2002 Hewlett-Packard Company, all rights reserved. Reproduction, adaptation, or translation of this document without prior written permission is prohibited, except as allowed under the copyright laws.

Contains software from AirMedia, Inc. Copyright 1996 AirMedia, Inc. Trademark Notices Java is a U.S. trademark of Sun Microsystems, Inc. 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.

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 19 20 20 22

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 Identiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Extended MIBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 25 25 26 26 29 31 33 35 35 37 38

3. The OVSNMP Communications API


SNMPv1 and SNMPv2C Protocol Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before Accessing the SNMPv2C Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting the Interface Style and Communication Protocol . . . . . . . . . . . . . . . . . . . . OVSNMP Over UDP/IP and IPX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The OVsnmpOpen() Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Communication with the HP OpenView Event Subsystem . . . . . . . . . . . . . . . . . . . . The OVsnmpPdu Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Blocking and Nonblocking Programming Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retransmission Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The SNMP Communications API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The SNMP Communication API Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 43 48 50 50 51 52 53 53 56 61 64 64 67

Contents
4. The NNM Event Database API
The NNM Event Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The NNM Event Database API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 83 86 86

5. The OVSNMP Conguration API


The OVSNMP Conguration Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 The OVSNMP Conguration API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Data Structures for the OVSNMP Conguration API . . . . . . . . . . . . . . . . . . . . . . . . . 94 Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 The OVsnmpConfEntry Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 The OVsnmpConfWcList Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 The OVsnmpConfDest Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 The OVsnmpConfCntl Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

6. Integrating with Logging and Tracing


Overview of Logging and Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HP-UX and Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Windows Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The OVuTL Application Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 105 106 107

7. Integrating with Process Management


Process Management for HP OpenView Applications . . . . . . . . . . . . . . . . . . . . . . . . . The OVsPMD Application Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . The Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of the Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . First Line of the LRF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Second Line of the Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration with NNM Automated Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Automated Backup and Pre-NNM 6.0 Applications . . . . . . . . . . . . . . . . . . . . . . . . . The Backup Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Three Ways of Integrating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Evaluating An Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 111 115 117 117 118 118 119 123 123 124 126 127

Contents
Writing Backup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Integration via ovwMapClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Integrating via Services (Background Processes) . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Contents

Tables
Table 2-1. SNMP Request Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Table 2-2. SNMPv2C Request Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Table 2-3. Summary of the SNMPv1 and SNMPv2 SMI Denitions . . . . . . . . . . . . 32 Table 2-4. ASN.1 Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Table 2-5. Outside Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Table 3-1. Protocol Operations Supported by the OVSNMP API . . . . . . . . . . . . . . . 46 Table 3-2. Protocol Error Status Supported by the OVSNMP API . . . . . . . . . . . . . . 47 Table 3-3. SNMP Communications API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Table 3-4. OVsnmpAPI Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Table 3-5. OVSNMP Header Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Table 3-6. SNMP API Key Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Table 3-7. OVsnmpSession Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Table 3-8. CallBack Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Table 3-9. CallBack Command Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Table 3-10. Elements of the OVsnmpPdu Data Structure . . . . . . . . . . . . . . . . . . . . . 74 Table 3-11. Elements of the OVsnmpVarBind Data Structure . . . . . . . . . . . . . . . . . 77 Table 3-12. OVsnmpVarBind Union Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Table 4-1. NNM Event Database API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Table 5-1. SNMP Conguration API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Table 5-2. SNMP Conguration API Data Structures . . . . . . . . . . . . . . . . . . . . . . . . 94 Table 5-3. OVsnmpConfEntry Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Table 5-4. OVsnmpConfWcList Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Table 5-5. OVsnmpConfDest Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Table 5-6. OVsnmpConfCntl Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Table 6-1. Functions in the OVuTL API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Table 7-1. Functions in the OVsPMD API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Table 7-2. Purpose of Each Line in a Local Registration File . . . . . . . . . . . . . . . . . 117 Table 7-3. First Line of the LRF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Table 7-4. Second Line of the LRF& . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Tables

10

Figures
Figure 1-1. SNMP API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Figure 2-1. Sequence of Actions in a Hypothetical SNMP Session . . . . . . . . . . . . . . 27 Figure 2-2. Conceptual View of Communication Sequence with Traps . . . . . . . . . . 28 Figure 2-3. The Top of the MIB Naming Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Figure 2-4. The Role of a Proxy in SNMP Communication . . . . . . . . . . . . . . . . . . . . 37 Figure 3-1. OVSNMP Bilingual Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Figure 3-2. OVsnmpPDU Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Figure 5-1. OVsnmpConfWcList Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Figure 5-2. OVsnmpConfDest Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Figure 6-1. Windows Event Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Figure 7-1. Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Figure 7-2. Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Figure 7-3. Decision Tree for Script Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Figure 7-4. Decision Tree for ovwMapClose Event Integration . . . . . . . . . . . . . . . 129 Figure 7-5. Decision Tree for Background Process Integration. . . . . . . . . . . . . . . . 130 Figure 7-6. Backup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Figure 7-7. API integration with Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Figure 7-8. Backup via Background Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

11

Figures

12

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.

[Button] Menu Items

13

14

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 ll 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.

15

16

Introduction to the NNM Software Developers Kit

Chapter 1

17

Introduction to the NNM Software Developers Kit

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.

18

Chapter 1

Introduction to the NNM Software Developers Kit The HP OpenView NNM Software Developers Kit

The HP OpenView NNM Software Developers Kit


The NNM Software Developers Kit is used to write applications that are integrated with the feature set of NNM. The kit, which is shipped on a CD-ROM, provides application programming interfaces (APIs) for the following: SNMP management OpenView Windows OpenView tracing and logging OpenView process control

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.

The OVSNMP API


The HP OpenView SNMP (OVSNMP) API provides SNMP communication and conguration support for HP OpenView integrated applications. The OVSNMP API originated in the UNIX system version of the Network Node Manager product. It has now been made available on the Windows operating systems to provide portability for cross-platform applications. The OVSNMP API supports both SNMP version 1 (SNMPv1) and Community-based SNMP Version 2 (SNMPv2C) through a common bilingual interface. The primary transport mechanism is SNMP over UDP/IP. However, the Windows version also supports SNMP over IPX communication.

Chapter 1

19

Introduction to the NNM Software Developers Kit The HP OpenView NNM Software Developers 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 Conguration API.

The WinSNMP and Microsoft MGMT API


The WinSNMP API and the Microsoft MGMT API are not included in the HP OpenView Software Developers Kit. However, applications developed with the WinSNMP API or Microsoft MGMT API are fully compatible with Network Node Manager and other applications developed using Windows versions of the HP OpenView Software Developers Kit (SDK). The OVSNMP library uses WinSNMP for SNMP notication (trap) reception, which in turn is compatible with the Microsoft SNMPTRAP service. Therefore, all three types of applications can coexist without conict over the shared SNMP trap port. The ACE*COMM NetPlus WinSNMP run-time library is bundled with Network Node Manager for use only on the installed NNM system. For more information about the WinSNMP API, refer to the technical specication available in postscript form on the CD-ROM for the NNM SDK.

The SNMP API Architecture


The OpenView Event Handler or subsystem passes all HP OpenView events between HP OpenView applications. The Event Correlation Services (ECS) engine is an integral part of the event subsystem. Event correlation logic can be loaded into the ECS engine. This logic changes the combination of events available for subscription from the event subsystem. The OVSNMP and WinSNMP APIs are compatible with each other, which includes the ability to share (receive) notications on the standard SNMP trap port. This compatibility enables a mixture of applications to run on the same system. However, HP OpenView events will be delivered to OVSNMP applications only (and not to WinSNMP applications).

20

Chapter 1

Introduction to the NNM Software Developers Kit The HP OpenView NNM Software Developers Kit Figure 1-1 illustrates the primary components and data ows 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

SNMP V1/V2 Traps

ECS Correlation Services ASCII Events ECS Corr. Configuration Management GUI

Chapter 1

21

Introduction to the NNM Software Developers Kit The HP OpenView NNM Software Developers 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 modications to your code, as well as create a few special les 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.

22

Chapter 1

An Overview of SNMP

Chapter 2

23

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 identiers extended MIBs data representation A list of documents that provide more detailed information about SNMP and MIBs, including several RFCs (Request for Comment documents).

24

Chapter 2

An Overview of SNMP The SNMP Model of Communication

The SNMP Model of Communication


Managing computer networks requires an approach that simplies the potentially complex problems of communication and coordination. The prevailing approach, which has been adopted by the SNMP (Simple Network Management Protocol), is to treat the network as a collection of cooperative, communicating entities. There are two basic types of entities: management processes (managers) and managed processes (agents).

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 trafc, 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 notications 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

25

An Overview of SNMP The SNMP Model of Communication

Manager and Agent Interaction


A manager can be one of many processes on a computer. For example, a manager might try to provide data about certain gateways. It would make use of the gateway agent by requesting data about throughput, retransmission rates, and other parameters. Such a manager might also need to periodically reset gateway counters by communicating with the gateway agent. An agent takes care of SNMP activity for the managed node. It can be simple or complex, depending on the device it represents. Like a manager, an agent may actually be one of many processes on a specic computer. On the other hand, it might be implemented in the ROM of a device like a bridge or hub. A device that does not directly support SNMP is said to be foreign. A proxy is an agent that translates between SNMP and the private protocol of a foreign device. Managers do not need to know any internal details about the object managed by an agent. Likewise, an SNMP agent can service requests from many SNMP managers. The agent does not need to know the context of the request, or the structure of the manager making the request. The agent simply validates the request, services it, and enters its passive state awaiting the next request. This division of responsibilities simplies network management solutions. The concept of managers and agents provides a general solution to an otherwise complex problem. All devices share a common model for communication, which is the model promoted in SNMP.

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. 26 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 oversimplies 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

27

An Overview of SNMP The SNMP Model of Communication Notications 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 notication. In SNMPv1, notications are referred to as traps. In SNMPv2, a notication 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

Receive 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 species several predened traps, and a developer may also dene application-specic traps. In practice, HP OpenView NNM uses a daemon process to manage trap trafc on an SNMP management node. This is because only one management application can bind to the SNMP/UDP trap port. On HP-UX and Solaris, 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 notications.

28

Chapter 2

An Overview of SNMP The SNMP Model of Communication

SNMPv1 and SNMPv2C Protocols


There are two versions of SNMP currently in use: the original SNMP protocol (also known as SNMPv1), and a newer version called Community-based SNMPv2 (also known as SNMPv2C). SNMPv2C provides a growth path to more secure network management while remaining backwards compatible with SNMPv1 wherever possible. This section describes some of the key differences between SNMPv1 and SNMPv2C. For more complete information about the protocols, refer to: RFC 1157: The Simple Network Management Protocol RFC 1905: Protocol Operations for version 2 of the Simple Network Management Protocol (SNMPv2)

SNMP Operations The SNMPv1 specication denes 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 Identier(s) and value(s) of the next object(s) managed by an agent. Contains the data returned by an agent. Sends an unsolicited notication from an agent to a manager, indicating that an event or error has occurred on the agent system.

Chapter 2

29

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 notication 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 conrmed notication 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 dening MIBs for SNMPv2. (MIB changes are described later in this overview.)

SNMPv2 Trap Request

Inform Request

30

Chapter 2

An Overview of SNMP The Management Information Base

The Management Information Base


This section presents highlights of data representation and the concept of a Management Information Base, or MIB. The MIB is a general concept for expressing managed objects. A MIB contains the denitions for a collection of standardized and nonstandardized (vendor, experimental) objects. A MIB denition species objects with a standardized notation, call the Structure of Management Information (SMI). The Internet MIB-II is one of many standard MIBs. The purpose of the MIB-II is to dene common objects for managing TCP/IP networks. Other standard MIBs exist (or are being dened) to manage specic network elements as well.1 The Internet MIB-II denition (RFC 1213) denes standardized objects for TCP/IP agents. To access the value of a MIB-II object, an SNMP manager sends a request to the agent representing the desired instance of the object. The request message contains MIB information (an object identier) that lets the agent identify the specic objects. The corresponding response message from the agent carries the same identifying information. MIBs are dened using an Internet-standard language called the Structure of Management Information (SMI). MIBs can be dened using either of two SMI versions: the original SMI denition, and a newer SNMPv2 SMI denition. The key differences are described in Table 2-3, Summary of the SNMPv1 and SNMPv2 SMI Denitions.

1. Because it is a superset of MIB-I, MIB-II only is mentioned in this discussion. Chapter 2 31

An Overview of SNMP The Management Information Base

Table 2-3 SMI Denition SNMPv1 SMI

Summary of the SNMPv1 and SNMPv2 SMI Denitions Differences Forms the basis for all existing SNMPv1-based MIBs. Dened in RFC 1155: Structure and Identication of Management Information for TCP/IP-based Internets Amended in RFC 1212: Concise MIB Denitions Dened 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 (denes 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 dening a small set of possible integer values. The SNMPv2 SMI refers to this form of denition as a textual convention. Dened 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)

32

Chapter 2

An Overview of SNMP The Management Information Base

Object Identiers
For the purposes of an SNMP developer, an object identier (OID) is a data type that precisely identies a MIB-II object denition. 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 dened. The administration authority for this branch is shared between CCITT and ISO/IEC.

iso(1)

joint-iso-ccitt(2)

Chapter 2

33

An Overview of SNMP The Management Information Base

Figure 2-3

The Top of the MIB Naming Tree root

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 identiers 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 prex 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 identiers 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.

Similarly, the prex for the OIDs in HP enterprise-specic MIBs is 1.3.6.1.4.1.11.

34

Chapter 2

An Overview of SNMP The Management Information Base

Extended MIBs
Many agents support extended MIBs, which dene objects that are not included in standard MIBs, such as MIB-II and enterprise-specic 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 dening MIB extensions.

Data Representation
Data is exchanged between SNMP processes using the Basic Encoding Rules (BER) dened 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 identier. The maximum length of an OBJECT IDENTIFIER is limited to 128 sub-identiers. 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.

OBJECT IDENTIFIER Counter Counter32

Chapter 2

35

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

36

Chapter 2

An Overview of SNMP The Management Information Base

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 Conguration Database. This proxy information must be congured by the administrator of the manager. For details, see xnmsnmpconf(1) in the online reference pages.

Chapter 2

37

An Overview of SNMP For More Information

For More Information


The documents listed in Table 2-5, Outside Reading, contain more detailed information that is beyond the scope of this guide. These documents are neither published nor sold by Hewlett-Packard. Table 2-5 Document RFC 1155: Structure and Identication of Management Information for TCP/IP-based Internets RFC 1157: A Simple Network Management Protocol RFC 1187: Bulk Table Retrieval with the SNMP RFC 1212: Concise MIB Denitions Outside Reading Description K. McCloghrie and M. T. Rose, (May 1990). Contains MIB object denitions. (Obsoletes RFC 1065) J. D. Case, M. Fedor, M. L. Schoffstall, and C. Davin, (May 1990). Denes SNMP. (Obsoletes RFC 1098) K. McCloghrie, M. T. Rose, and C. Davin, (October 1990). K. McCloghrie and M. T. Rose, (March 1991). Describes the format for creating MIB object les. K. McCloghrie and M. T. Rose, eds., (March 1991). Denes MIB-II. (Obsoletes RFC 1158; most current edition as of the printing of this guide.) M. T. Rose, ed. (March 1991). SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Denes Community-based SNMPv2. (Experimental. Obsoletes RFC 1441) SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). MIB Denition language for Managed Objects (Draft Standard. Obsoletes RFC 1442)

RFC 1213: Management Information Base Network Management of TCP/IP based internets: MIB-II RFC 1215: Convention for Dening 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)

38

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 Denition language for rened data types. (Draft Standard. Obsoletes RFC 1443) SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). MIB Denition language for Conformance and Capability denitions. (Draft Standard. Obsoletes RFC 1444) SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Denes SNMPv2 protocol. (Draft Standard. Obsoletes RFC 1448) SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Denes 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). Denes 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

39

An Overview of SNMP For More Information

40

Chapter 2

The OVSNMP Communications API

Chapter 3

41

The OVSNMP Communications API

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

42

Chapter 3

The OVSNMP Communications API SNMPv1 and SNMPv2C Protocol Support

SNMPv1 and SNMPv2C Protocol Support


The OVSNMP API allows you to communicate with remote systems in the following ways: using the original SNMPv1 protocol using the newer, Community-based SNMPv2 protocol (also called SNMPv2C) letting the OVSNMP API determine which version to use

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 specically 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.

Before Accessing the SNMPv2C Protocol


Before you access the SNMPv2C protocol, you should be aware of two topics that will affect your implementation: SNMPv1 and SNMPv2C protocol runtime support changes in the OVSNMP API interface behavior

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

43

The OVSNMP Communications API SNMPv1 and SNMPv2C Protocol Support The bilingual mode relies on information in the SNMP conguration 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
SNMPv1 Style API v1 mode

OR
controlled by OVSNMP_V2 API session flag v2C mode controlled by protocol version (when the OVSNMP_V2 API flag is set)

SNMPv2 Style API v1 mode bilingual mode

SNMPv1 protocol SNMPv1 protocol SNMPv2C protocol

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.

44

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 rst 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

45

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 specied. If necessary, you can determine which protocols are congured in the local OVSNMP Conguration 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.

46

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 specic 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 47

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

Selecting the Interface Style and Communication Protocol


The OVSNMP API provides straightforward access to the original SNMPv1-style, or to the newer SNMPv2-style interface and communication protocol selection. By default, a session created while using any of the session API functions operates with the original SNMPv1-style interface. This provides full backward compatibility for existing applications. To place the OVSNMP API in the SNMPv2-style interface mode, rst create the session structure using any of the standard session API routines, such as OVsnmpOpen(). Next, set the OVSNMP_V2API bit in the session_flags eld of the OVsnmpSession structure. (The OVsnmpSession structure is described later in this chapter.) Thereafter, all calls to the OVSNMP API will return results or errors that conform to the SNMPv2-style interface.

48

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 eld in the OVsnmpSession structure. All communication from that point on will use the specied communication protocol. Valid choices for the protocol version are: SNMP_VERSION_1 SNMP_VERSION_2C SNMP_USE_DEFAULT_VERSION (bilingual)

Chapter 3

49

The OVSNMP Communications API OVSNMP Over UDP/IP and IPX

OVSNMP Over UDP/IP and IPX


The OVSNMP API supports communication with SNMP agent systems using either the User Datagram/Internet Protocol (UDP/IP) or Novells Internet Packet Exchange (IPX) protocol.

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 modied. In addition, most of those applications, when ported to the WindowsNT/2000 operating system, will realize both UDP/IP and IPX support without any modication 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.

The OVsnmpOpen() Function


The OVsnmpOpen(), OVsnmpXOpen(), and OVsnmpWOpen() functions take peername and remote_port parameters as input. The peername is a character string that identies the destination of SNMP requests issued on the session. The peername can be an IP hostname, IP address (with dot notation), or an IPX address (netnum:nodenum notation). The remote_port is a number identifying the UDP port or IPX socket of the SNMP agent. If SNMP_USE_DEFAULT_REMOTE_PORT is specied for remote_port, the appropriate default value is used (such as UDP/161 or IPX/36879).

50

Chapter 3

The OVSNMP Communications API OVSNMP Over UDP/IP and IPX

Communication with the HP OpenView Event Subsystem


The event subsystem passes all HP OpenView events between HP OpenView applications. The Event Correlation Services (ECS) engine is an integral part of the event subsystem. Event correlation logic can be loaded into the ECS engine. This logic changes the combination of events available for subscription from the event subsystem. The concepts of event ows and event streams distinguish the combination of events available for subscription. An application subscribing to events must specify one of three event ows: RAW, CORR, or ALL. The RAW event ow includes all events received by the event subsystem excluding events originating in the ECS engine. The correlated (CORR) event ow includes all events coming from a named event stream. The ALL event ow includes all events received by the event subsystem plus all events created inside the ECS engine. Using OVsnmpEventOpen() or its variants, applications can establish a direct communication session with the event subsystem to send and receive events. Through the lter parameter of OVsnmpEventOpen(), you can specify the type of event ow (RAW, CORR, or ALL) from which to receive HP OpenView events. In the case of CORR event ow, you can specify the name of the ECS stream for receiving correlated events. Each event in the event subsystem has a unique ID, (OVsnmp UUID) assigned to it. Applications can access OVsnmp UUID data through OVsnmpEventSend() or OVsnmpExtractUUID(). OVsnmp UUID data can be manipulated through OVsnmpUuidFromStr() or OVsnmpUuidToStr(). To identify an existing event in the event subsystem see the OVsnmpEventAck (3), OVsnmpEventDel (3), OVsnmpEventUnack (3), OVsnmpEventChange (3), OVsnmpEventChangeCat (3), and OVsnmpEventCorrelate (3) online reference pages.

Chapter 3

51

The OVSNMP Communications API OVSNMP Over UDP/IP and IPX

The OVsnmpPdu Structure


The second area in which multi-transport capabilities are exported to applications is the OVsnmpPdu structure. This structure contains an address member that is dened by default as sockaddr_in (internet socket). To fully enable the multi-transport interface, insert the compiler directive
#define OVSNMP_MULTI_TRANSPORT

into the application source code before including OVsnmp.h. This redenes the OVsnmpPdu address member to be a sockaddr (generic socket) structure. The address.sa family value then determines the type of address specied 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 modied. However, applications that override the destination on a per-request (PDU) basis must be modied 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.

52

Chapter 3

The OVSNMP Communications API Blocking and Nonblocking Programming Models

Blocking and Nonblocking Programming Models


The OVSNMP API lets you communicate with an SNMP agent system in either a blocking or nonblocking mode. The choice between blocking and nonblocking mode depends on whether the application is suspended while the request is being processed. If you issue a blocking request, your application is suspended until either a response is received or a timeout occurs. The OVSNMP API transparently manages a number of communications behaviors, such as retransmission, on behalf of the application. If you issue a nonblocking request, control returns to your application as soon as the request is submitted, but before a response is received. This can be advantageous if the response may not return promptly, or if your application needs to process other events while waiting for a response. In nonblocking communication, the OVSNMP stack needs a mechanism for informing your application when a response arrives. This is the role of the callback function. Thus, when you issue a nonblocking request, you also must supply the name of a callback function that will be invoked when the response is received.

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 rst opened. If your application uses nonblocking requests, the SNMP API provides three ways to manage retransmission:

1. OVSNMP over IPX is supported on Windows operating systems only. Chapter 3 53

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 */

54

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

55

The OVSNMP Communications API The SNMP Communications API Functions

The SNMP Communications API Functions


Table 3-3, SNMP Communications API Functions, shows how the OVSNMP API functions are grouped, and the name and description of each OVSNMP API function. Table 3-3 Function Name SNMP Communications API Functions Description

SESSION MANAGEMENT FUNCTIONS OVsnmpOpen() Establishes a logical session with the OVsnmpAPI for the purpose of communicating with a specic 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 lters 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()

56

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 specied SNMP request operation. Used in conjunction with SNMP Get, GetNext, and SNMPv2 GetBulk Requests. Allocates, initializes, and appends an OVsnmpVarBind structure for the specied 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 specied SNMP MIB object to the SNMP Request PDU. Allocates and initializes a new SNMP request PDU based on the specied response PDU. Any invalid variable bindings are omitted from the resulting PDU. Creates a copy of the specied OVsnmpPdu data structure and its contained elements. Deallocates the specied 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()

OVsnmpCopyPdu() OVsnmpFreePdu() OVsnmpExtractUuid() OVsnmpUuidFromStr()

Chapter 3

57

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 identier fragments of type ObjectID to another object identier. Appends one or more object identier fragments of type ObjectID to another object identier. Concatenates two object identier fragments of type ObjectID together to produce a new object identier. Concatenates two or more object identier fragments of type ObjectID together to produce a new object identier. Create a copy of an object identier of type ObjectID. Compare two object identiers of type ObjectID for lexicographic ordering (less than, equal to, greater than). Create a new object identier of type ObjectID from a string in dotted-numeric notation. Create a new object identier of type ObjectID from a string in either dotted-numeric notation, or mnemonic descriptor (name) form as dened in the HP OpenView loaded MIB database. Format an object identier of type ObjectID as a string in dotted-numeric notation. Format an object identier of type ObjectID as a string using the mnemonic descriptor (name) dened 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()

OVsnmpMalloc() OVsnmpCalloc() OVsnmpRealloc()

58

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 notication 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-dened 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.

OVsnmpRead() OVsnmpGetRetryInfo() OVsnmpDoRetry() OVsnmpCancel() OVsnmpCallback() OVsnmpEventAck() OVsnmpEventDel() OVsnmpEventCorrelate()

Chapter 3

59

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 specied 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.

60

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

61

The OVSNMP Communications API The SNMP Communications API Functions Sometimes you may supply data to ll in a structure that the SNMP library has allocated. For example, you might assign a Notication 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 specic 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.

62

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 specied pdu). Deallocates specied OVsnmpPdu. Allocates returned OVsnmpPdu. Conditionally deallocates specied OVsnmpPdu based on associated session FREE_Pdu ag. 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 specied OVsnmpPdu. Allocates an object ID sequence that must be assigned to an OVsnmpPdu or deallocated using OVsnmpFree(). Deallocates specied OVsnmpPdu. Memory Management Performed Deallocates specied OVsnmpSession.

OVsnmpFreePdu() OVsnmpMalloc() OVsnmpCalloc() OVsnmpRealloc() OVsnmpFree()

Chapter 3

63

The OVSNMP Communications API The SNMP Communication API Data Structures

The SNMP Communication API Data Structures


This section introduces the key data structures. See the online reference pages for specic details about other data structures. The reference pages also contain information on compiling and linking your application.

NOTE

HP recommends that HP-UX developers use an ANSI C compiler, such as the HP-UX C/ANSI C compiler, for the HP 9000 Series computers. For C++ source code, the HP Cfront C++ compiler must be used for development on HP-UX 10.X operating systems. For HP 11.0, the HP ANSI C++ compiler must be used for C++ source code. In addition, for development on HP-UX 11.0, the HP ANSI C++ compiler/linker must be used to link all executables. Microsoft Windows developers must use Microsoft Visual C++. Refer to the Release Notes for the required version. For Solaris 2.x HP recommends that developers use an ANSI C compiler for C source code, for C++ source code HP recommends the use of the SPARCworks compiler suite. Refer to the Release Notes for the required version.

Header Files
The header le denes many data structures that are part of the OVSNMP API. All header les 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 les are shown in Table 3-5, OVSNMP Header Files.

64

Chapter 3

The OVSNMP Communications API The SNMP Communication API Data Structures

Table 3-5

OVSNMP Header Files Header File Purpose The main header le for OVSNMP applications. This le includes all other header les (except OVsnmpWfns.h and OVsnmpXfns.h) as a convenience. Main function declarations, structure denitions, and control denitions. More function declarations. ASN.1 type denitions for the API. These are the ASN.1 types that are supported by the OVSNMP library. Conguration parameter and function denitions. Error value denitions. Declarations for the Microsoft Win32-specic functions. Declarations for the X11-specic functions in the OVSNMP library. Declarations for 64-bit integer arithmetic functions.

$OV_HEADER/OV/OVsnmp.h

$OV_HEADER/OV/OVsnmpApi.h $OV_HEADER/OV/OVsnmpClnt.h $OV_HEADER/OV/OVsnmpAsn1.h

$OV_HEADER/OV/OVsnmpConf.h $OV_HEADER/OV/OVsnmpErr.h $OV_HEADER/OV/OVsnmpWfns.h $OV_HEADER/OV/OVsnmpXfns.h $OV_HEADER/OV/OVuint64.h

Chapter 3

65

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 eld 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.

66

Chapter 3

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-6. Table 3-6 Data Structure Name OVsnmpSession SNMP API Key Data Structures Description Obtained by a call to OVsnmpOpen(), it identies 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 identier 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

Chapter 3

67

The OVSNMP Communications API The SNMP Communication API Data Structures The OVsnmpSession Structure OVsnmpSession identies a logical session between the manager and a specic destination SNMP agent. The OVsnmpSession structure is allocated by a call to OVsnmpOpen, and is an input parameter to several other functions. The elds are shown in Table 3-7. Table 3-7 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 conguration 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 le 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 notication 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.

community_len setCommunity setCommunity_len sock_fd (*callback)()

u_int u_char u_int int (void *)()

callback_data

void *

68

Chapter 3

The OVSNMP Communications API The SNMP Communication API Data Structures Table 3-7 Field Name protocol_version OVsnmpSession Fields (Continued) Type long Description Denes a specic SNMP protocol version to use for this session. It is only valid when the OVSNMP_V2API bit in the session_flags eld 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 dened: OVSNMP_FREE_PDU (and FREE_PDU): If set, the send functions deallocate memory associated with the input OVsnmpPdu structure. The default for this ag is set. OVSNMP_RECV_EVENTS (and RECV_TRAPS): Set this ag if you want notications (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 ag 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 ag is unset.

Chapter 3

69

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 denes 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 notication is obtained with OVsnmpRecv instead, the callback does not occur. Your callback function must dene the parameters in Table 3-8. These input parameters are passed to the callback function. They are described further in the OVsnmpPdu data structure section. Table 3-8 CallBack Parameters Parameter command session Description An integer. Indicates why the callback function was called. See Table 3-9 for details. An OVsnmpSession structure. Identies 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-specic data, which is specied as the value passed into the OVsnmpOpen call.

pdu

callback_data

The entries in Table 3-9 dene the valid values for the callback command parameter.

70

Chapter 3

The OVSNMP Communications API The SNMP Communication API Data Structures

Table 3-9

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 notications. The pdu parameter contains unsolicited trap notications. The pdu parameter contains an unsolicited inform notication. 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 specied 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 eld is not set for the specied session parameter. (2) Occurs only if the SNMP_V2API bit in the session_flags eld is set for the specied session parameter.

Chapter 3

71

The OVSNMP Communications API The SNMP Communication API Data Structures Table 3-9 CallBack Command Values (Continued) Note Description

Command Value

(3) Occurs only if the specied session was created using OVsnmpEventOpen(), OVsnmpEventXOpen(), OVsnmpTrapOpen(), or OVsnmpXTrapOpen(). (4) Occurs only if the OVSNMP_CLOSE_CALLBACK bit in the session_flags eld is set for the specied 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 notication 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 notication, use OVsnmpFreePdu().

NOTE

For SNMPv2 traps and informs, the OVsnmpPdu structure conveys the logical format of the notication. The notification identifier, timestamp and optional enterprise identifier are represented in elds of the OVsnmpPdu structure. The variables list contains only the data varbinds for the notication. 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.

1. Memory is not deallocated if an error occurs on the call. 72 Chapter 3

The OVSNMP Communications API The SNMP Communication API Data Structures The elds of the OVsnmpPdu structure are shown in order in Figure 3-2. Note that this PDU has two variables. Table 3-10 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

Chapter 3

73

The OVSNMP Communications API The SNMP Communication API Data Structures

Table 3-10 Field Name address

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 50 for details. Denes the specic 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 specic 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 identier assigned by the SNMP API. This value must never be modied by your application.

74

Chapter 3

The OVSNMP Communications API The SNMP Communication API Data Structures Table 3-10 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 specied 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 elds are specic to SNMPv1 trap and SNMPv2 trap/inform PDUs, and are invalid for all other PDUs. enterprise ObjectID A vendor-specic identier that uniquely identies 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

Chapter 3

75

The OVSNMP Communications API The SNMP Communication API Data Structures Table 3-10 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 elds are specic to SNMPv1 trap requests, and are invalid for all other PDUs. generic_type specific_type int int One of the SNMP-dened types of trap. See RFC 1157 for details. When generic_type indicates that an enterprise-specic trap has occurred, the value of specific_type contains the specic trap. Otherwise, the value is meaningless.

The following elds are specic 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 species the information the application wants to get from or set in the SNMP agent. Table 3-11 describes each of the elements.

76

Chapter 3

The OVSNMP Communications API The SNMP Communication API Data Structures

Table 3-11 Field Name next_variable oid oid_length type val

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 identier (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 eld 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

Chapter 3

77

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-12. Table 3-12 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.

78

Chapter 3

The NNM Event Database API

Chapter 4

79

The NNM Event Database API

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

80

Chapter 4

The NNM Event Database API The NNM Event Database

The NNM Event Database


The OVEventDb API is a set of library functions which provide read access to the OpenView Event Database. (see eventdb (4) for a description of the OpenView Event Database.) It enables the calling application to retrieve log events and/or stream events stored in the OpenView Event Database. Applications can also get correlation information between events from the OpenView Event Database. There are four log le groups in the OpenView database. Event Log File Group contains all the raw events received by pmd and all the events generated by the Event Correlation engine with the following exception. Events congured as IGNORE in trapd.conf are not logged in the event database. OVEventDbOpenLogForReading(), OVEventDbReadNextEvent(), and OVEventDbGetOVsnmpPdu() can access data from this le group. NDBM Offset File Group is a series of four New Database Manager databases (NDBM) which are maintained in lock-step with the Event Log File Group. That is, whenever an event record is written to an Event Log File, a corresponding NDBM event offset record is written to the corresponding NDBM Offset File. There is no API to directly access this le group. Stream Log File Group is a series of four binary les that record the association of an event with an ECS event stream. OVEventDbOpenStreamForReading(), OVEventDbReadNextEvent(), and OVEventDbGetOVsnmpPdu() can access data from this le group. Correlation Log File Group is a series of four binary les that record the association of two events within an ECS event stream. The correlation log contains records of this relationship. Often, an event is the parent of several child events. In this case, the log contains a corresponding number or records, each with the same parent event in the association but with different child events. OVEventDbOpenCorrLogForReading(), OVEventDbFindCorrelatedEvents(), OVEventDbGetCorrelationTree(), and other related API functions can access data from this le group (see the OVEventdb API list below).

Chapter 4

81

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 nd 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 rst order. The operation can be lengthy, because the entire correlation log must be searched to nd the correlations.

82

Chapter 4

The NNM Event Database API The NNM Event Database API Functions

The NNM Event Database API Functions


The functions in the NNM Event Database AP fall into the following categories: database access, freeing resources, and other data manipulation such as correlating events, and determining tree events. Table 4-1 NNM Event Database API Functions Function DATABASE ACCESS and QUERYING OVEventDbOpenCorrLogforReading() OVEventDbOpenLogforReading() OVEventDbOpenStreamforReading() OVEventDbReadNextCorrEntry() OVEventDbReadNextEvent() OVEventDbClose() OVEventDbIsEventCorrelated() OVEventDbFindCorrelatedEvents() OVEventDbGetCorrelationTree() FREEING RESOURCES OVEventDbFreeEvent() OVEventDbFreeCorrEntry() Free the resources associated with an OVeventHandle. Free the resources associated with an OVcorrEntryHandle. Open the OpenViewEvent Database Correlation log le group for reading. Open the OpenView Event Database log le group for reading. Open the OpenView Event Database stream log le group for reading. Retrieve the next correlation entry from the open database. Reactivate the next event from the open database. Close the eventdb handle. Determine if an event is correlated or not. Find a list of events that are correlated with a particular event. Recursively nd all child events which are correlated under a particular event. Description

Chapter 4

83

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()

OVEventDbGetCorrEventStatus() OVEventDbGetParentId() OVEventDbGetChildId() OVEventDbGetNumChildren()

OVEventDbGetChildEvent()

OVEventDbGetTreeLevel() OVEventDbGetOVsnmpPdu()

84

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

85

The NNM Event Database API Memory Management

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;

86

Chapter 4

The OVSNMP Conguration API

Chapter 5

87

The OVSNMP Conguration API

This chapter describes the functions and data structures in the HP OVSNMP Conguration API. It includes descriptions of the following: the OVSNMP Conguration database OVSNMP Conguration API functions key data structures in the OVSNMP Conguration API, including each element and its use

88

Chapter 5

The OVSNMP Conguration API The OVSNMP Conguration Database

The OVSNMP Conguration Database


The OVSNMP conguration database is a repository on the management station for the conguration information that controls the behavior of an SNMP session. The conguration parameters control behaviors such as: the number and frequency of retries if a response is not received the community name to use in SNMP requests the port on the agent node where requests should be sent whether the agent is a proxy agent the protocol version to be used

The OVSNMP Conguration API provides programmer access to the SNMP conguration database. Three classes of conguration parameters are stored in the database: parameters for specic managed nodes parameters for wildcarded IP addresses parameters for a global default

Whenever the conguration 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

89

The OVSNMP Conguration API The OVSNMP Conguration API Functions

The OVSNMP Conguration API Functions


The thirty-two functions in the OVSNMP Conguration API fall into ve categories: database access, resolution, editing, administration, and miscellaneous. Table 5-1 Function Name DATABASE ACCESS OVsnmpConfOpen() OVsnmpConfClose() OVsnmpConfDbName() OVsnmpConfFileName() Open the SNMP conguration database for subsequent access. Close the SNMP conguration database. Obtain the pathname of the SNMP conguration database. Obtain the pathname of the backwards compatibility (shadow) le that is associated with the SNMP conguration database. SNMP Conguration API Functions Description

RESOLUTION OVsnmpConfResolveDest() OVsnmpConfFreeDest() Obtain the effective conguration parameters for a specied destination agent. Deallocate all memory associated with the OVsnmpConfDest structure returned by OVsnmpConfResolveDest(3).

EDITING OVsnmpConfReadNextEntry() OVsnmpConfReadEntry() OVsnmpConfCreateEntry() Sequentially read specic node records from the SNMP conguration database. Read a specic node record from the SNMP conguration database. Create a new specic node record in the SNMP conguration database. This operation will fail if a record already exists for the specied node.

90

Chapter 5

The OVSNMP Conguration API The OVSNMP Conguration API Functions Table 5-1 Function Name OVsnmpConfStoreEntry() OVsnmpConfDeleteEntry() OVsnmpConfAllocEntry() OVsnmpConfCopyEntry() SNMP Conguration API Functions (Continued) Description Create or replace, as necessary, a specic node record in the SNMP conguration database. Delete a specic node record from the SNMP conguration database. Allocate an OVsnmpConfEntry structure. Allocate and initialize an OVsnmpConfEntry structure with the values from the specied OVsnmpConfEntry structure. Allocate and initialize an OVsnmpConfEntry structure with the values extracted from a conguration string in the format of an ovsnmp.conf(4) conguration le entry. Deallocate all memory associated with the specied OVsnmpConfEntry structure. Read the list of IP address wildcard records from the SNMP conguration 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 conguration 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 specied list of OVsnmpConfWcList structures. Read the global default record from the SNMP conguration database. Create or replace, as necessary, the global default record in the SNMP conguration database.

OVsnmpConfParseEntry()

OVsnmpConfFreeEntry() OVsnmpConfReadWcList()

OVsnmpConfStoreWcList() OVsnmpConfAllocWcLis()

OVsnmpConfFreeWcList() OVsnmpConfReadDefault() OVsnmpConfStoreDefault()

Chapter 5

91

The OVSNMP Conguration API The OVSNMP Conguration API Functions Table 5-1 Function Name OVsnmpConfGetVersions() SNMP Conguration API Functions (Continued) Description Determine which SNMP protocol versions are supported by an agent by reading the SNMP conguration database. Store or modify the eld in the SNMP conguration database that indicates the SNMP protocol versions, which are supported by a particular agent. Replace the contents of the SNMP conguration database with records extracted from conguration strings in the specied ovsnmp.conf conguration le. Dump the contents of the SNMP conguration database to the specied ovsnmp.conf conguration le.

OVsnmpConfSetVersions()

OVsnmpConfImportFile()

OvsnmpConfExportFile() ADMINISTRATION OVsnmpConfReadCntl()

Read the current SNMP conguration database administration record. This record contains options which control run-time caching and use of the backward compatibility conguration le. Update the current SNMP conguration database administration record. This enables you to modify the options which control runtime caching and use of the backward compatibility le.

OVsnmpConfStoreCntl()

MISCELLANEOUS OVsnmpConfDeleteCache() Remove all entries from the SNMP conguration run-time cache. New entries accumulate in the cache as applications call OVsnmpOpen() and OVsnmpConfResolveDest(). Sequentially read entries from the SNMP conguration run-time cache. This function is provided for troubleshooting only (such as dumping the contents of the cache for inspection.)

OVsnmpConfReadNextDest()

92

Chapter 5

The OVSNMP Conguration API The OVSNMP Conguration API Functions Table 5-1 Function Name OVsnmpConfPrintDest() SNMP Conguration 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

93

The OVSNMP Conguration API Data Structures for the OVSNMP Conguration API

Data Structures for the OVSNMP Conguration API


This section describes key data structures, including their purposes and relationships. Specic details about other parameters to SNMP functions are available in the online reference pages.

Header Files
The header le denes many data structures that are part of the OVSNMP conguration API. The only header le required to use the OVSNMP conguration API functions is $OV_HEADER/OV/OVsnmpConf.h1. See Table 3-5 for a list of all header les included in the OVSNMP API.

Data Structures
Table 5-2 describes the key data structures that are used with the OVSNMP Conguration API. Table 5-2 SNMP Conguration API Data Structures Data Structure OVsnmpConfEntry Description This structure contains the parameters that make up an SNMP conguration 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. 94 Chapter 5

The OVSNMP Conguration API Data Structures for the OVSNMP Conguration API Table 5-2 SNMP Conguration API Data Structures (Continued) Data Structure OVsnmpConfDest Description This structure contains the fully-resolved conguration 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 conguration database. This structure contains administrative options which control how run-time caching and the backward compatibility conguration le are used by the OVSNMP API.

OVsnmpConfCntl

The OVsnmpConfEntry Structure


The OVsnmpConfEntry structure is the principal data structure used for SNMP conguration. This structure contains the parameters that make up the SNMP conguration record for a particular destination in the managed environment. When used alone or in the OVsnmpConfWcList structure with the conguration editing function, some of the elds may not be lled in; that is, they are assigned a value that indicates use default. In this case the actual conguration value is determined at runtime by the OVsnmpConfResolveDest() function as part of the OVsnmpConfDest structure. The OVsnmpConfEntry structure has the elds shown in Table 5-3: Table 5-3 Type char * OVsnmpConfEntry Structure Name name Description The name of the destination for which the conguration parameters apply. This may be an IP hostname, an IP address, an IP address wildcard, or a non-SNMP entity that is proxied for. The SNMP community name, which is used by the OVSNMP API when issuing SNMP Get and GetNext requests to the destination. This community name is also used for SNMP Set requests if the setCommunity eld is not specied.

char *

community

Chapter 5

95

The OVSNMP Conguration API Data Structures for the OVSNMP Conguration 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 eld 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 eld 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 eld 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

The OVsnmpConfWcList Structure


The OVsnmpConfWcList structure is used to create a linked list of OVsnmpConfEntry structures that represent the IP address wildcard conguration. The linked list is required since the semantics of an IP address wildcard record depends upon the order of the records within the IP address wildcard list. When OVsnmpConfResolveDest() resolves defaulted conguration values, it searches the IP address wildcard list in order to ll in those defaulted values.

96

Chapter 5

The OVSNMP Conguration API Data Structures for the OVSNMP Conguration API In Figure 5-1, the elds of the OVsnmpConfWcList structure are shown in order. Note that the conguration parameters are contained in an OVsnmpConfEntry structure pointed to by the confEntry eld. Figure 5-1 OVsnmpConfWcList Structure OVsnmpConfWcList * next * confEntry NULL

OVsnmpConfWcList * next * confEntry

OVsnmpConfEntry *name *community *setCommunity *proxy timeout retry pollInterval remotePort

OVsnmpConfEntry *name *community *setCommunity *proxy timeout retry pollInterval remotePort

Table 5-4 describes the elds 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 eld should be NULL for the last entry in the list. A pointer to the OVsnmpConfEntry structure that contains the conguration parameters for the IP Address wildcard entry.

confEntry

Chapter 5

97

The OVSNMP Conguration API Data Structures for the OVSNMP Conguration API The OVsnmpConfWcList structure is returned by a call to OVsnmpConfReadWcList() and should be deallocated by a call to OVsnmpConfFreeWcList().

The OVsnmpConfDest Structure


The OVsnmpConfDest structure contains the fully resolved conguration parameters for a particular destination in the managed environment. It is based upon the OVsnmpConfEntry structure, and it contains addressing information which is determined at run time instead of being stored in the conguration database. The values assigned to the OVsnmpConfEntry portion of this structure are obtained from a combination of specic node, IP address wildcards and global default conguration records to determine an actual conguration value for each eld. The OVsnmpConfDest structure is returned by a call to OVsnmpConfResolveDest() and should be deallocated by a call to OVsnmpConfFreeDest(). In Figure 5-2 the elds of the OVsnmpConfDest structure are shown in order. The conguration parameters are contained in an OVsnmpConfEntry structure pointed to by the confEntry eld. Figure 5-2 OVsnmpConfDest Data Structure OVsnmpConfDest *confEntry isProxied ipAddr ipAddrAge agent name agentAddr OVsnmpConfEntry *name *community *setCommunity *proxy timeout retry pollInterval remotePort

98

Chapter 5

The OVSNMP Conguration API Data Structures for the OVSNMP Conguration API Table 5-5 describes the elds 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 conguration parameters for the specied destination. A boolean ag 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 ag must be specied 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 specied destination. This eld 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 eld 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

99

The OVSNMP Conguration API Data Structures for the OVSNMP Conguration API

The OVsnmpConfCntl Structure


The OVsnmpConfCntl structure contains administrative options which control how run-time caching and the backward compatibility conguration le is used by the OVSNMP API. Its elds are shown in Table 5-6. Table 5-6 Type int OVsnmpConfCntl Structure Name ipAddrAge Description The age limit, in seconds, for IP address stored in the SNMP conguration run-time cache. This value is used by OVsnmpConfResolveDest() to determine when a cached IP address must be updated by consulting the systems IP address name server. The level of run-time cache enabled for the SNMP conguration database. By default, resolved conguration parameters and the IP address of previously referenced destinations are cached. This improves the performance of applications when the same destination is subsequently referenced. The level of backward compatibility for SNMP Platform Release 3.2 that is enabled for the SNMP conguration database. This compatibility mode is disabled by default beginning with NNM Release 5.0.

cacheFlags_t

cacheFlags

compat3_2_t

compatFlags

Cache Flags The cache ag in the OVsnmpConfCntl structure may be set to one of the following: SNMP_CONF_CACHE_NONE Run-time caching of SNMP conguration parameters and IP addresses is disabled. The information is recomputed each time a destination is referenced.

100

Chapter 5

The OVSNMP Conguration API Data Structures for the OVSNMP Conguration API SNMP_CONF_CACHE_NOADDR SNMP conguration parameters for previously referenced destinations are maintained in the SNMP conguration 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 conguration parameters and the IP address of previously referenced destinations are maintained in the SNMP conguration run-time cache. Compatibility Flags The compatibility ag in the OVsnmpConfCntl structure may be set to one of the following: SNMP_CONF_SHADOW_NONE The conguration le 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 conguration database, which are congured to use the default SNMP port for communications, are maintained in the backward compatibility le. This will optimize performance of Release 3.2-based applications. However, if the xnmsnmpconf -import command is subsequently used with the resulting shadow le, some information in the SNMP conguration database will be lost. SNMP_CONF_SHADOW_ALL All entries in the SNMP conguration database are maintained in the Release 3.2-compatible conguration le. This mode of operation ensures absolute consistency between the SNMP conguration database and the compatibility conguration le. 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 congured in the SNMP conguration database.

Chapter 5

101

The OVSNMP Conguration API Data Structures for the OVSNMP Conguration API

102

Chapter 5

Integrating with Logging and Tracing

Chapter 6

103

Integrating with Logging and Tracing

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 le. 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.

104

Chapter 6

Integrating with Logging and Tracing Overview of Logging and Tracing

Overview of Logging and Tracing


HP-UX and Solaris
Logging and tracing have different objectives: Logging Logging is generally provided for the benet of system or network administrators and some sophisticated end users. The messages you log should be understandable to this class of user. The system administrator uses the nettl utility to congure, lter, and format log messages. Owing to its implementation, HP OpenView logging has practically no impact on the performance of your manager or agent. Therefore, logging is generally turned on at all times. Tracing is far more comprehensive in its intent. Tracing provides unambiguous evidence about the state of execution at key points in the code. Tracing is intended primarily for the developer, to assist during the testing phase of development. It is not intended for end-customer use; the information in the tracing les is typically understood only by the developer, or by trained eld support personnel. When you turn tracing on, you should expect to experience a moderate degradation of performance. Therefore, tracing is generally on only during testing and debugging.

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

105

Integrating with Logging and Tracing Overview of Logging and Tracing

Windows Operating Systems


On Windows operating systems, the Event Log APIs provide a way to handle application and system logging. The Event Viewer application lets you view and manipulate log data. The Event Viewer lets you lter events by category, source, type (severity), dates, computer, and event ID. You can set the log size and overwrite options. The Event Viewer also formats and displays the data. The OVuTL API lets you integrate your application with the common logging and tracing facility using the Event Viewer. The Event Viewer, shown below, is found in the Administrative Tools program group. Refer to your Windows operating system documentation for details on using the Event Viewer. Figure 6-1 Windows Event Viewer

106

Chapter 6

Integrating with Logging and Tracing The OVuTL Application Programming Interface

The OVuTL Application Programming Interface


There are three functions in the OVuTL API: Table 6-1 Function OVuTLInit() Functions in the OVuTL API Description Initializes the name of the calling software and the hostname for the logging and tracing output. You must call OVuTLInit() once only, before any calls to OVuLog() or OVuTrace(). Enters a log message in the log le. By default this is $NETFMT_LOG_FILE (HP-UX and Solaris) or Event Viewer (Windows). Enters a trace message in the trace le. By default this is $NETFMT_TRC_FILE (HP-UX and Solaris) or Event Viewer (Windows). For more information about the OVuTL API, see the OVuTL (3) reference page in this manual. It contains important details, examples of how to use this API, and examples of how to get output.

OVuLog() OVuTrace()

Chapter 6

107

Integrating with Logging and Tracing The OVuTL Application Programming Interface

108

Chapter 6

Integrating with Process Management

Chapter 7

109

Integrating with Process Management

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 nd 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 rst 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 le for your process. This chapter discusses only the rst and second line of that le, since these lines pertain to process management. Any additional lines in this le are not relevant to Network Node Manager.

110

Chapter 7

Integrating with Process Management Process Management for HP OpenView Applications

Process Management for HP OpenView Applications


From the perspective of a system administrator, process management on the HP OpenView platform is largely invisible. Two commands ovstart and ovstop execute the startup and shutdown functions. ovstatus obtains status information for processes controlled by ovpsmd. ovpause and ovresume put NNM processes in a state that allows for safe backup and returns them to normal processing. Behind these commands, however, is the process management daemon ovspmd, as illustrated in Figure 7-1. This daemon: handles requests from the administrative commands noted above starts and stops processes as required pauses and resumes processes which access NNMs databases, log les, and conguration les and returns these processes to normal processing monitors processes for termination logs startup and shutdown information to the tracing and logging subsystem.

ovspmd obtains information about which processes to start, and when to start them, from the startup le, 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

111

Integrating with Process Management Process Management for HP OpenView Applications

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 congured 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

112

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 congured 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 specied 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 congured 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 122. 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 113

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 notication, 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.

114

Chapter 7

Integrating with Process Management The OVsPMD Application Programming Interface

The OVsPMD Application Programming Interface


To create a well-behaved process, you need to use the OVsPMD API, which has these functions: Table 7-1 Function OVsInit() Functions in the OVsPMD API Description Indicates that the process is beginning its initialization phase. Returns a le descriptor (communication channel) for communicating with ovspmd. Indicates that the process has nished its initialization phase. Receives a command from ovspmd. The commands are OVS_CMD_EXIT, which indicates that your process should terminate, OVS_CMD_PAUSE which indicates that your process should pause, and OVS_CMD_RESUME which indicates that your process should resume. Informs ovspmd that the process is terminating normally. One parameter is a text message used to indicate the reason for termination. Responds to pause and resume commands issued by ovspmd.

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

115

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 le descriptor returned by OVsInit(). 4. When select() indicates the ovspmd le 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.

116

Chapter 7

Integrating with Process Management The Local Registration File

The Local Registration File


Each process must have an associated Local Registration File, or LRF. The LRF is a specially formatted ASCII le that serves two functions: The LRF declares information about the process, including: its name where its executable code is located how to start it. The LRF also declares information about the objects the process manages. (These declarations appear in any additional lines after the rst two in the LRF)

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 rst two lines of information, which describe the process.

Structure of the Local Registration File


Table 7-2 describes the purpose of each line in an LRF. Table 7-2 Purpose of Each Line in a Local Registration File Line First Second Description Species the process name, and the pathname of its executable le. Species process management information, which is described next.

Chapter 7

117

Integrating with Process Management The Local Registration File

General Syntax
Each line in an LRF contains two or more elds. Each eld is terminated by a colon, including the last eld. Some elds are optional; it is recommended that you still include the colon terminator for the missing elds. 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 eld, nor are any multibyte characters. In the rst 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 species the drive specication on the Windows operating systems. This prevents the colon in the path from being interpreted as a eld terminator.

First Line of the LRF


The rst line of the LRF species the name and location of the process: Table 7-3 First Line of the LRF Field 1: Name 2: Path Syntax A character string for the process name. A character string. Default None (must be specied). None (must be specied).

Field 1: Name Species 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

118

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 Species 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 specied for the executable, install_dir\BIN or $OV_BIN is assumed.

NOTE

You must put a backslash in front of the colon that species the drive specication on Windows operating systems. This prevents the colon in the path from being interpreted as a eld terminator. For example,
IPMgr_A.017.0_MegaCorp_International:C\:install_dir\bin\netmon:

LRF Line One Example Following are examples of the rst line of a hypothetical LRF on HP-UX or Solaris. The process executable is located in $OV_BIN/MEGA/ip_mgr.
IPMgr_A.017.0_MegaCorp_International:MEGA/ip_mgr:

If you used the absolute path on HP-UX or Solaris:


IPMgr_A.017.0_MegaCorp_International:/opt/OV/bin/MEGA/ip_mgr:

The following is an example of the rst 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:

Second Line of the Local Registration File


The second line of the LRF species process management options.

Chapter 7

119

Integrating with Process Management The Local Registration File There are seven elds in the second line of the LRF. Each eld is terminated by a colon (:). The following Table 7-4 describes each eld in turn. Following the table is a complete description of each eld. 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

None (no arguments required).

4: Behavior 5: Timeout 6: Pause 7: Daemon Stop

OVs_NON_WELL_BEHAVED 5 seconds. NOPAUSE Empty string

Field 1: Initial Start Flag This ag indicates whether or not the process is to be launched when the ovstart command is issued without arguments. Possible values for this eld: OVs_YES_START and OVs_NO_START. The OVs_YES_START ag means the process will be started by the ovstart command. The OVs_NO_START ag 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).

120

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 eld of the pertinent LRFs. Field 3: Arguments The arguments specied in this eld 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 eld. For example, suppose the arguments eld had this entry -i,-b,amazon:. This would be equivalent to -i -b amazon on the command line. Field 4: Behavior This eld species how the process will interact with ovspmd. Processes can be well-behaved, non-well-behaved, or daemons, as described earlier. Possible values for this eld: OVs_WELL_BEHAVED, OVs_NON_WELL_BEHAVED, and OVs_DAEMON. Field 5: Timeout For well-behaved processes, this eld 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 eld. Also, after ovspmd sends your process SIGTERM, it waits until the timeout expires before sending it a SIGKILL signal.

Chapter 7

121

Integrating with Process Management The Local Registration File This eld is also used as the PAUSE timeout. It species 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 eld 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 eld is used to register for pause and resume messages. Possible values for this eld include: PAUSE and NOPAUSE. The default is NOPAUSE: specifying NOPAUSE or leaving the eld 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 123. Field 7: Daemon Stop Command This eld can be used only for OVS daemon processes. It follows the same rules as the PATH eld in the rst line. It identies a command (script or executable) that is to be run to stop the OVS daemon process. It may contain optional parameters. If a specic path is not specied, \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::

122

Chapter 7

Integrating with Process Management Integration with NNM Automated Backup

Integration with NNM Automated Backup


This section provides information about automated backups integration model and discusses integrating with automated backup as it applies to developers of new applications and to developers enhancing existing applications. Before reading this chapter, review the description of automated backup in the Managing Your Network manual. Topics in this section include: the backup model three ways of integrating decision trees for evaluating an application to determine the relevance of each way of integrating implementation information

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.

Automated Backup and Pre-NNM 6.0 Applications


The automated backup feature in NNM is designed to be (backwards) compatible with applications that were developed for earlier versions of NNM. There is nothing in the automated backup implementation that breaks existing applications. However, there is the opportunity to modify these applications to take advantage of the automated backup feature and provide the end-user with some benets.

Chapter 7

123

Integrating with Process Management Integration with NNM Automated Backup

The Backup Model


This section provides an overview of the automated backup process. For details refer to the ovbackup.ovpl reference page. The backup utility, ovbackup.ovpl is intended to be integrated into a preexisting backup procedure or to have a backup procedure built around it. ovbackup.ovpl is a Perl script that creates a snapshot image of HP OpenView data, assuring that synchronization between dependent data stores is maintained. It then places the snapshot in the staging area, $OV_TMP/ovbackup, where it can be copied to long term backup media. As Figure 7-2 shows, ovbackup.ovpl operates in two phases. These phases are known as the operational phase and the analytical phase. The operational phase is run rst; its purpose is to create a snapshot of all data that must be synchronized together. This data is called the operational data and consists of the following databases and directories: $OV_DB/OpenView $OV_DB/eventdb $OV_LOG $OV_CONF $OV_LRF $OV_REGISTRATION $OV_FIELDS $OV_SYMBOLS

124

Chapter 7

Integrating with Process Management Integration with NNM Automated Backup

Figure 7-2

Backup Data Copy Stage initiate backup

Data Archive Stage copy data to permanent archive

Operational Phase

pause processes

copy operational data to staging area

Data Restore Stage copy data from permanent archive

Analytical Phase

resume processes

copy analytical data to staging area

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 notications. (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

125

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.

Three Ways of Integrating


The process of evaluating an application to determine how it should integrate with automated backup is the same for developers of both new applications and applications that are being updated to take advantage of the NNM 6.0 features. There are three ways of integrating with automated backup. It may be appropriate for an application to be integrated with automated backup by using all three or only one or two of them. For other applications there may be no benet to integrating at all. 126 Chapter 7

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 notication. Background process integration (integrating via services) is done by modifying a background process to receive and handle pause and resume notication. 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 notication.

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

127

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 131. Figure 7-3 Decision Tree for Script Integration

Does the application have its own data store?

NO

There is no need for the application to provide scripts.

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 le. 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

128

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 133. Figure 7-4 Decision Tree for ovwMapClose Event Integration

Does the application register for the ovwMapClose event?

NO

ovwMapClose integration is not relevant to the application.

YES Consider ovwMapClose integration. See Integration Via ovwMapClose.

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

129

Integrating with Process Management Integration with NNM Automated Backup Background process integration consists of 1) registering to receive pause and resume notication 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 134. Figure 7-5 Decision Tree for Background Process Integration

Does the application have a background process that registers with ovspmd?

NO

Background process integration does not apply.

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

Consider background process integration. See Integrating Via Services.

130

Chapter 7

Integrating with Process Management Integration with NNM Automated Backup

Writing Backup Scripts


If your application has its own data store, you need to supply backup scripts if you want the data backed up along with the NNM data. If your application only adds data to the NNM databases, you do not need to supply any backup scripts. As Figure 7-6 shows, you can add scripts to be run from any of four points in the ovbackup process. Figure 7-6 Backup Scripts Data Copy Stage Data Archive Stage initiate backup pre-pause scripts copy data to permanent archive

ovbackup.ovpl runs:

pause system copy operational data to staging area

Operational Phase

operational scripts

Data Restore Stage

initiate restore post-resume scripts Analytical Phase resume system restore operational data restore analytical data

administrator runs restore script

analytical scripts

copy analytical data to staging area

The four script points include:

Chapter 7

131

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.

132

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.

Integration via ovwMapClose


As Figure 7-7 shows, applications that integrate via OVw APIs receive notication of pause and resume operations via the ovwMapClose and ovwMapOpen events. When an OVW process receives the command to pause, it sends an ovwMapClose event to those applications registered to receive map close events. This particular ovwMapClose event contains an OVwEventSource parameter value of ovwEventSourcePause, to allow applications to distinguish it from other map close events. Applications that receive an ovwMapClose event must complete any current operations related to the map, and then acknowledge the map close event by calling OVwAckMapClose(). There are, however, some potential performance gains for applications that choose to recognize the special pause condition. Specically, applications may choose to keep their map-related information, rather than deleting it, and may choose to accept the proposed closing-time value rather that engage in any special calculations. When commanded to pause, ovw does not really close the map, but rather puts the map into a stable state (for example, for a backup operation), and then makes the map unavailable for the duration of the paused state. ovw will not respond to API calls while paused (a process that makes an OVw API call to clock). When later commanded to resume, OVW sends an ovwMapOpen event to those applications registered to receive map open events. This map open event contains an OVwEventSource parameter value of ovwEventSourcePause, and indicates that the formerly unavailable map is one again available.

Chapter 7

133

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

ovwAckMapClose Place application in appropriate state Data Restore Stage

initiate restore restore operational data

resume system

ovwMapOpen Resume communication with NNM

copy analytical data to staging area

restore analytical data

Integrating via Services (Background Processes)


Only well-behaved processes can integrate with pause and resume. Each service uses its local registration le (LRF) to indicate interest in notication for backups. 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

134

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 117 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 notication (OVS_CMD_PAUSE) to all registered services. When your service receives this notication, it should stop all operations, ush 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

copy operational data to staging area wellbehaved process

resume processes

OVS_CMD_RESUME OVS_RSP_RESUME_ACK

copy analytical data to staging area

Chapter 7

135

Integrating with Process Management Integration with NNM Automated Backup

After NNM completes the dependent phase of its backup process, ovspmd sends notication (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 specied in seconds. Also keep in mind that some users may have slow machines.

136

Chapter 7

Index
A agent, 25 agents daemon, 113, 121 non-well-behaved, 121 well-behaved, 112 API architecture, 21 applications SNMPv2 style, 66 ASN.1, 35, 73, 76 data representation, 35 data types, 35 B background, sending your process into, 116 bilingual communication mode, 45 BITS, 35 blocking mode, 27, 53 C cache ags, in OVsnmpConfCntl, 100 callback function, 70 parameters, 70 ccitt(0), 33 communications APIs for communications, 56 for manual retransmission, 56 for message setup/management, 56 for session management, 56 in SNMP library, 56 communications model agent process, 25 manager process, 25 SNMP, 25 compatibility ags, in OVsnmpConfCntl, 101 compiling and linking, 64 conguration API, 89 data structures, 94 header les, 94 connectionless operation, 26 conventions typographical, 13 correlated events receiving, 51 Correlation Log File Group, 81 Counter, 35 Counter32, 35 Counter64, 35 D data structures, 64, 67, 94 memory management, 62 data types ASN.1, 35 dot notation, 34 E enterprise-specic MIB, 35 environment variables OV_HEADER, 64 error codes, 46 error values macro for mapping, 66 Event Log File Group, 81 extended MIB, 35 F le descriptor for a session, 68 ags, 100, 101 foreign device denition, 26 G Gauge, 35 Gauge32, 35 Get Bulk Request, 30 Get Next Request, 29 Get Request, 29 Get Response, 29 H header les, 64, 94 I include les, 64, 94 inform message, 28 Inform Request, 30 installing the SDK, 19 INTEGER, 35 Integer32, 35 integration with logging, 105 with process management, 111 with tracing, 105 interface behavior, 45 IPAddress, 35 IPX protocol, 50 iso(1), 33

137

Index
J joint-iso-ccitt(2), 33 L linking, with library, 64 location transparency and proxies, 37 logging and OVuTL API, 105 description of, 105 severity levels, 105 LRF, 111 agent name and location, 118 and ovstart, ovstop, ovstatus, and mp_bind(), 119 and Process Management, 117 contents of, 117 general syntax, 118 line 1 syntax, 118 line 2 syntax, 120 mandatory, 22 M Management Information Base, 31 manager, 25 manual retransmission communications APIs, 56 memory management, 61 message setup/management communications APIs, 56 MIB enterprise-specic, 35 extended, 35 MIB-II, 31 MIB-II object denition OID, 33 N naming tree, 33 ccitt(0), 33 iso(1), 33 joint-iso-ccitt(2), 33 NDBM Offset File Group, 81 nettl, 105 NetworkAddress, 35 non-blocking mode, 27, 53 notications, 25, 28 NT. See Windows O OBJECT IDENTIFIER, 35 object identier, 33, 34 OCTET STRING, 35 OID, 33, 34 OID, dot notation, 34 OV_HEADER, 64 ovaddobj, and SUF, 111 OVEventDb API, 81 OVEventDbClose, 83 OVEventDbCorrEntryListGetNext, 84 OVEventDbCorrEntryListGetNumElements OVEventDbEventIdtoUuid, 85 OVEventDbEventListGetNext, 82, 84 OVEventDbFindCorrelatedEvents, 82, 83 OVEventDbFreeCorrEntry, 83 OVEventDbFreeCorrEntryList, 84 OVEventDbFreeEvent, 83 OVEventDbFreeEventList, 84 OVEventDbGetChildEvent, 84 OVEventDbGetChildId, 84 OVEventDbGetCorrelationTree, 82, 83 OVEventDbGetCorrEventStatus, 84 OVEventDbGetNumChildren, 84 OVEventDbGetOVsnmpPdu, 84 OVEventDbGetParentId, 84 OVEventDbGetTreeLevel, 84 OVEventDbIsEventCorrelated, 83 OVEventDbOpenCorrLogforReading, 83 OVEventDbOpenLogforReading, 83 OVEventDbOpenStreamforReading, 83 OVEventDbReadNextCorrEntry, 83 OVEventDbReadNextEvent, 83 OVEventDbUuidToEventId, 85 OVsDone(), 115 OVsInit(), 115 OVsInitComplete(), 115 OVSNMP API, 19 enhanced error codes, 47 IPX support, 50 memory management, 61 multitransport interface, 50 on Windows, 55 protocol support, 43, 48 protocol translations, 45 OVSNMP API, architecture, 21 OVSNMP conguration API, 89 functions, 90 OVsnmpAddNullVarBind, 56 OVsnmpAddTypedVarBind, 56 OVsnmpBlockingSend, 56

, 84

138

Index
OVsnmpCallback, 56 OVsnmpCancel, 56 OVsnmpClose, 56 OVsnmpConfCntl structure cache ags, 100 compatibility ags, 101 description of, 100 OVsnmpConfDest structure, 98 OVsnmpConfEntry structure, 95 OVsnmpConfWcList structure, 96 OVsnmpCopyPdu, 56 OVsnmpCreatePdu, 56 OVsnmpErrString, 56 OVsnmpEventOpen, 56 OVsnmpFixPdu, 56 OVsnmpFreePdu, 56 OVsnmpGetRetryInfo, 56 OVsnmpOpen, 50, 56 OVsnmpPdu, 72, 76, 96, 98 OVsnmpPdu structure, 52, 67, 72, 76 OVsnmpRead, 56 OVsnmpRecv, 56, 70 OVsnmpSend, 56 OVsnmpSession structure, 54, 68 OVsnmpTrapOpen, 56 OVsnmpVal, 67, 78 OVsnmpVarBind, 67 OVsnmpVarBind structure, 73, 76 OVsnmpWEventOpen, 56 OVsnmpWOpen, 56 OVsnmpXCancel, 56 OVsnmpXClose, 56 OVsnmpXEventOpen, 56 OVsnmpXOpen, 56 OVsnmpXSend, 56 OVsnmpXTrapOpen, 56 ovspmd diagram, 111 process management daemon, 111 OVsPMD API functions in, 115 rules for use, 115 OVsReceive(), 115 ovstart, 111 ovstatus, 111 ovstop, 111 ovtrapd on UNIX, 28 on Windows, 28 OVuint64Add, 56 OVuint64AddUInt32, 56 OVuint64Assign, 56 OVuint64Cmp, 56 OVuint64CmpUInt32, 56 OVuint64Divide, 56 OVuint64DivideUInt32, 56 OVuint64FromStr, 56 OVuint64Multiply, 56 OVuint64MultiplyUInt32, 56 OVuint64Shift, 56 OVuint64Subtract, 56 OVuint64SubtractUInt32, 56 OVuint64ToStr, 56 OVuLog(), 107 OVuTL API functions of, 107 tracing and logging, 105 OVuTrace(), 107 P PDU description of, 26 trap, 73, 76 process management, 111 ovspmd, 111 OVsPMD API, 115 ovstart, 111 ovstatus, 111 ovstop, 111 protocol support, 43 protocols SNMP, 29 proxy and location transparency, 37 description of, 26 R references to other documents, 38 retransmission communications APIs, 56 retransmissions, 53, 55 RFC list, 38 S select(), 116 select(2), 68 session management communications APIs, session, sequence of communication, 27 Set Request, 29 SMI, 31 SNMPv1, 31 SNMP operations, 29
56

139

Index
SNMP Conguration API data structures, 94 functions in, 90 header les, 94 SNMP library, communications API functions in, 56 SNMP session sequence of actions, 27 SNMP_STD2OV_ERR, 56 SNMPv1 operations, 29 SNMPv1 protocol, 29, 43 SNMPv2 operations, 30 SNMPv2 Trap Request, 30 SNMPv2C protocol, 29, 43 Software Development Kit, 19 startup le (SUF), 111 Stream Log File Group, 81 Structure of Management Information, 31 structures, 94, 100 OVsnmpConfDest, 98 OVsnmpConfEntry, 95 OVsnmpConfWcList, 96 OVsnmpPdu, 52, 72, 76 OVsnmpSession, 68 OVsnmpVarBind, 73, 76 T Timeticks, 35 tracing and OVuTL API, 105 description of, 105 trap PDU, 73, 76 Trap Request, 29 trapd, 28 traps, 25, 28, 73, 76 communication sequence, 28 U UDP, 26, 50 User Datagram Protocol/Internet Protocol,
27

WinSNMP API, 20 X X11 event loop, 55

W Win32 message loop, 55 Windows IPX support, 50 ported application support, 50 traps, 28 140