Nnm751 Snmp Dev PDF

SNMP Developer’s Guide

HP OpenView Integration Series

Manufacturing Part Number : T2579-90002

October 2006

© Copyright 1990-2006 Hewlett-Packard Development Company, L.P.

Legal Notices

Warranty

The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

The information contained herein is subject to change without notice.

Restricted Rights Legend

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Copyright Notices

© Copyright 1990-2006 Hewlett-Packard Development Company, L.P.

Contains software from AirMedia, Inc.

© Copyright 1996 AirMedia, Inc.

Trademark Notices

Java™ and all Java based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

Microsoft® is a U.S. registered trademark of Microsoft Corporation.

Windows NT® is a U.S. registered trademark of Microsoft Corporation.

Windows® 2000 is a U.S. registered trademark of Microsoft Corporation.

Windows® and MS Windows® are U.S. registered trademarks of Microsoft Corporation.

Netscape™ and Netscape Navigator™ are U.S. trademarks of Netscape Communications Corporation.

Oracle® is a registered U.S. trademark of Oracle Corporation, Redwood City, California.

2

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.

3

Documentation Updates

This manual’s title page contains the following identifying information:

• Software version number, which indicates the software version

• Document release date, which changes each time the document is updated

• Software release date, which indicates the release date of this version of the software

To check for recent updates, or to verify that you are using the most recent edition of a document, go to:

http://ovweb.external.hp.com/lpe/doc_serv/

You will also receive updated or new editions if you subscribe to the appropriate product support service. Contact your HP sales representative for details.

4

Support

You can visit the HP OpenView Support web site at:

www.hp.com/managementsoftware/support

HP OpenView online support provides an efficient way to access interactive technical support tools. As a valued support customer, you can benefit by using the support site to:

• Search for knowledge documents of interest

• Submit and track support cases and enhancement requests

• Download software patches

• Manage support contracts

• Look up HP support contacts

• Review information about available services

• Enter into discussions with other software customers

• Research and register for software training

Most of the support areas require that you register as an HP Passport user and sign in. Many also require a support contract.

To find more information about access levels, go to: www.hp.com/managementsoftware/access_level

To register for an HP Passport ID, go to:

www.managementsoftware.hp.com/passport-registration.html

5

6

Contents

1. Introduction to the NNM Software Developer’s KitThe HP OpenView NNM Software Developer’s Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

The OVSNMP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21The WinSNMP and Microsoft MGMT API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22The SNMP API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Integration APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2. An Overview of SNMPThe SNMP Model of Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Managers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Manager and Agent Interaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28SNMP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28SNMPv1 and SNMPv2C Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

The Management Information Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Object Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Extended MIBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Data Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37SNMP Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3. The OVSNMP Communications APISNMPv1 and SNMPv2C Protocol Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Before Accessing the SNMPv2C Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Selecting the Interface Style and Communication Protocol . . . . . . . . . . . . . . . . . . . . 50

OVSNMP Over UDP/IP and IPX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52The OVsnmpOpen() Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Communication with the HP OpenView Event Subsystem . . . . . . . . . . . . . . . . . . . . 53The OVsnmpPdu Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Blocking and Nonblocking Programming Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Retransmission Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

The SNMP Communications API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Memory Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

The SNMP Communication API Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

4. The NNM Event Database API

7

Contents

The NNM Event Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85The NNM Event Database API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

5. The OVSNMP Configuration APIThe OVSNMP Configuration Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93The OVSNMP Configuration API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Data Structures for the OVSNMP Configuration API . . . . . . . . . . . . . . . . . . . . . . . . . 98

Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98The OVsnmpConfEntry Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99The OVsnmpConfWcList Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100The OVsnmpConfDest Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102The OVsnmpConfCntl Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

6. Integrating with Logging and TracingOverview of Logging and Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

HP-UX, Solaris, and Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Windows Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

The OVuTL Application Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

7. Integrating with Process ManagementProcess Management for HP OpenView Applications . . . . . . . . . . . . . . . . . . . . . . . . . 115The OVsPMD Application Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 119The Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Structure of the Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122First Line of the LRF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Second Line of the Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Integration with NNM Automated Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Automated Backup and Pre-NNM 6.0 Applications . . . . . . . . . . . . . . . . . . . . . . . . . 127The Backup Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Three Ways of Integrating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Evaluating An Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Writing Backup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

8

Contents

Integration via ovwMapClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Integrating via Services (Background Processes) . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

9

Contents

10

Tables

Table 2-1. SNMP Request Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31Table 2-2. SNMPv2C Request Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32Table 2-3. Summary of the SNMPv1 and SNMPv2 SMI Definitions . . . . . . . . . . . . .34Table 2-4. ASN.1 Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37Table 2-5. Outside Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Table 3-1. Protocol Operations Supported by the OVSNMP API . . . . . . . . . . . . . . . .48Table 3-2. Protocol Error Status Supported by the OVSNMP API . . . . . . . . . . . . . . .49Table 3-3. SNMP Communications API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .58Table 3-4. OVsnmpAPI Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64Table 3-5. Compilers Supported on Operating Systems . . . . . . . . . . . . . . . . . . . . . . .66Table 3-6. OVSNMP Header Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68Table 3-7. SNMP API Key Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70Table 3-8. OVsnmpSession Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71Table 3-9. CallBack Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73Table 3-10. CallBack Command Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74Table 3-11. Elements of the OVsnmpPdu Data Structure . . . . . . . . . . . . . . . . . . . . . .77Table 3-12. Elements of the OVsnmpVarBind Data Structure . . . . . . . . . . . . . . . . . .80Table 3-13. OVsnmpVarBind Union Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81Table 4-1. NNM Event Database API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87Table 5-1. SNMP Configuration API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94Table 5-2. SNMP Configuration API Data Structures . . . . . . . . . . . . . . . . . . . . . . . . .98Table 5-3. OVsnmpConfEntry Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99Table 5-4. OVsnmpConfWcList Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101Table 5-5. OVsnmpConfDest Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103Table 5-6. OVsnmpConfCntl Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104Table 6-1. Functions in the OVuTL API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111Table 7-1. Functions in the OVsPMD API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119Table 7-2. Purpose of Each Line in a Local Registration File . . . . . . . . . . . . . . . . . .121Table 7-3. First Line of the LRF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122Table 7-4. Second Line of the LRF& . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

11

Tables

12

Figures

Figure 1-1. SNMP API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23Figure 2-1. Sequence of Actions in a Hypothetical SNMP Session . . . . . . . . . . . . . . .29Figure 2-2. Conceptual View of Communication Sequence with Traps . . . . . . . . . . .30Figure 2-3. The Top of the MIB Naming Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36Figure 2-4. The Role of a Proxy in SNMP Communication . . . . . . . . . . . . . . . . . . . . .39Figure 3-1. OVSNMP Bilingual Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46Figure 3-2. OVsnmpPDU Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76Figure 5-1. OVsnmpConfWcList Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101Figure 5-2. OVsnmpConfDest Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102Figure 6-1. Windows Event Viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110Figure 7-1. Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116Figure 7-2. Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129Figure 7-3. Decision Tree for Script Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . .132Figure 7-4. Decision Tree for ovwMapClose Event Integration . . . . . . . . . . . . . . . .133Figure 7-5. Decision Tree for Background Process Integration. . . . . . . . . . . . . . . . .134Figure 7-6. Backup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135Figure 7-7. API integration with Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138Figure 7-8. Backup via Background Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

13

Figures

14

ConventionsThe following typographical conventions are used in this manual.

Font What the Font Represents Example

Italic For book or manual titles, and for manpage names.

Refer to the OVW Developer’s Guide.

To provide emphasis. You must follow these steps.

To specify a variable that you must supply when entering a command.

At the prompt type: rlogin your_name where you supply your login name.

Bold For glossary terms. The distinguishing attribute of this class...

Computer Text and items on the computer screen.

The Root map window ...

The system replies: Press Enter

Command names Use the grep command ...

File and directory names. /usr/bin/X11

Process names. Check to see if pmd is running.

Window/dialog box names In the IP Internet map window...

Computer Bold

Text that you must enter. At the prompt, type: ovstatus.

Keycap Keyboard keys. Press Return.

[Button] Buttons on the user interface. Click [NET]. Click on the [Apply] button.

Menu Items

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.

Select Edit:Find->Objects by Comment

15

16

Contact Information

Technical Support Technical support information can be found on the HP OpenView World Wide Web site at:

http://openview.hp.com/

________________________________

Documentation Feedback

Your comments on and suggestions for the documentation help us understand your needs and better meet them.

You can provide feedback about documentation via the HP documentation site at:

http://www.docs.hp.com

Or you can fill out the form provided in electronic form with NNM:

• Windows®: install_dir\ReleaseNotes\nnm_doc_reply.txt

• UNIX: /opt/OV/ReleaseNotes/nnm_doc_reply.txt

Fill out one form per manual and email it to: [email protected]

If you encounter serious errors in the documentation that impair your ability to use NNM, please contact the HP Response Center or your support representative so that your feedback can be entered into CHARTS (the HP Change Request Tracking System).

________________________________

Training Information

For information on current HP OpenView training available, see the HP OpenView World Wide Web site at:

http://openview.hp.com/

Select the support panel to obtain information about scheduled classes, training at customer sites, and class registration.

17

18

1 Introduction to the NNM Software Developer’s Kit

Chapter 1 19

Introduction to the NNM Software Developer’ s Kit

This chapter introduces the SNMP component of the HP OpenView Network Node Manager (NNM) Software Developer’s 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.

Chapter 120

Introduction to the NNM Software Developer’ s KitThe HP OpenView NNM Software Developer’ s Kit

The HP OpenView NNM Software Developer’s KitThe NNM Software Developer’s 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 Developer’s 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 configuration 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 21


The OVSNMP API provides a native asynchronous event-loop programming model for Win32 on Windows operating systems and X11 on UNIX system platforms.

For an overview of SNMP management, see Chapter 2, “An Overview of SNMP.” For more detailed information about the OVSNMP APIs, see Chapter 3, The OVSNMP Communications API, and Chapter 5, “The OVSNMP Configuration API,” on page 91

The WinSNMP and Microsoft MGMT API

The WinSNMP API and the Microsoft MGMT API are not included in the HP OpenView Software Developer’s 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 Developer’s Kit (SDK). The OVSNMP library uses WinSNMP for SNMP notification (trap) reception, which in turn is compatible with the Microsoft SNMPTRAP service. Therefore, all three types of applications can coexist without conflict 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 specification 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) notifications 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).

Chapter 122


Figure 1-1 illustrates the primary components and data flows of the OVSNMP API, and their relationships to each other and to system services.

Figure 1-1 SNMP API Architecture

Port162

ECSI/O

ANNO

OVsnmpEventOpen ( ", "myApp", recv, &rd,"{NO_FORWARDED,CORR{default}} .*")

Alarm Browser

Drill Down

http server

Perl script

ecsmgr

Annotationserver

ECS Correlation Services

ECS Corr. ConfigurationManagement GUIASCII

Events

OVEVENT

oveventsSNMP V1/V2 Traps

ITOnetmon

ovactiond

ovtrapd

pmd

Chapter 1 23


Integration APIs

Chapters 5 and 6 cover the activities and utilities you use to integrate your application into the HP OpenView SNMP platform on Network Node Manager. Integration requires you to make some straightforward modifications to your code, as well as create a few special files and scripts.

There are two key areas for attention in integration:

• logging and tracing

• HP OpenView process management

It is not necessary for you to integrate in both areas. For example, you may elect to not integrate with the logging and tracing component. However, each point of integration makes it easier for your customer to take full advantage of your product.

NOTE You must create a Local Registration File (LRF) for any agents you create. This is covered under process management in Chapter 6.

For further reading, see HP OpenView Integration Series: Integration Concepts and Managing Your Network with Network Node Manager.

Chapter 124

2 An Overview of SNMP

Chapter 2 25

An Overview of SNMP

This chapter provides an overview of the Simple Network Management Protocol (SNMP) as it is implemented in the HP OpenView OVSNMP API. The following information is provided:

• The SNMP Model of Communication, including:

— managers and agents

— SNMP messages

— SNMPv1 and SNMPv2c protocols

• The Management Information Base, including:

— object identifiers

— extended MIBs

— data representation

• A list of documents that provide more detailed information about SNMP and MIBs, including several RFCs (Request for Comment documents).

Chapter 226

An Overview of SNMPThe SNMP Model of Communication

The SNMP Model of CommunicationManaging computer networks requires an approach that simplifies 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 traffic, and typically interacts with a user to achieve the user's intentions. Therefore, a manager can also trigger changes in an agent (see the next section) by changing the value of a variable on the agent node. Managers are frequently implemented as network management applications.

Agents

From the perspective of network management, an agent is usually a passive entity. It responds to the requests of managers, supplying and changing the values of local variables as needed. An agent can become an active entity by emitting unsolicited messages (called notifications or traps) to alert managers of noteworthy local events (such as a system reboot).

NOTE The HP OVSNMP API is intended for the development of SNMP-based network management applications. It does not fully support the development of SNMP agents beyond supporting the generation of traps.

Chapter 2 27


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 specific 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 simplifies 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.

Chapter 228


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

The diagram oversimplifies the sequence somewhat. The manager can send the request in either blocking or non-blocking mode. The type of mode affects the need to manage retransmissions. Also, since the implementation of the agent is unknown, the agent's actions are generic; the manager does not care how the agent generates the response PDU.

Details about how to use the OVSNMP API to send messages and receive responses are in Chapter 3, The OVSNMP Communications API, and in the online reference pages.

Manager Agent

Listen for requests

Receive request PDU

Generate response PDU

Send response PDU

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)

Receive response PDU

Chapter 2 29


Notifications

In the model presented previously, the manager requests information from the agent and the agent then responds. However, it is also possible for an agent to issue spontaneous (unsolicited) messages. Such a message is known as a notification. In SNMPv1, notifications are referred to as traps. In SNMPv2, a notification may be either a trap or an inform message.

The diagram shown in Figure 2-2 illustrates the communication sequence involved with traps.

Figure 2-2 Conceptual View of Communication Sequence with Traps

Traps exist to handle special conditions. When an agent or a manager detects a special condition, each can emit a trap message. SNMP specifies several predefined traps, and a developer may also define application-specific traps.

In practice, HP OpenView NNM uses a daemon process to manage trap traffic on an SNMP management node. This is because only one management application can bind to the SNMP/UDP trap port. On HP-UX, Solaris, and Linux, the NNM ovtrapd process binds to the trap port and then forwards traps to local applications.

On Windows operating systems, the NNM ovtrapd process uses by default the WinSNMP trap receptor to listen on the trap port. This provides coexistence with native WinSNMP applications. However, ovtrapd can also be started with an override option to listen directly to the trap port. In this case, the WinSNMP application would not be able to receive notifications.

Manager Agent

Set up to receive SMP traps

Receive trap PDU

Initialize and begin operation

Detect an internally significant state

Create trap PDU

Send trap PDU

Chapter 230


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 specification defines the following basic operations:

Table 2-1 SNMP Request Types

Request Type Description

Set Request Writes new data to one or more of the objects managed by an agent.

Get Request Requests the value of one or more of the objects managed by an agent.

Get Next Request Requests the Object Identifier(s) and value(s) of the next object(s) managed by an agent.

Get Response Contains the data returned by an agent.

Trap Request Sends an unsolicited notification from an agent to a manager, indicating that an event or error has occurred on the agent system.

Chapter 2 31


The SNMPv2C protocol provides some new protocol operations over the original SNMP protocol. These include the following:

In addition to these improved operations, SNMPv2C supports improved exception and error reporting, and new mechanisms for defining MIBs for SNMPv2. (MIB changes are described later in this overview.)

Table 2-2 SNMPv2C Request Types

Request Type Description

Get Bulk Request 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.

SNMPv2 Trap Request Sends an SNMPv2-style notification to an SNMP manager. The SNMPv2 Trap Request has a similar purpose as the SNMPv1 Trap Request, but is in a slightly different format.

Inform Request Sends an unsolicited but confirmed notification of a local event to a remote management station.

Chapter 232

An Overview of SNMPThe Management Information Base

The Management Information BaseThis 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 definitions for a collection of standardized and non- standardized (vendor, experimental) objects. A MIB definition specifies 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 define common objects for managing TCP/IP networks. Other standard MIBs exist (or are being defined) to manage specific network elements as well.1

The Internet MIB-II definition (RFC 1213) defines 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 identifier) that lets the agent identify the specific objects. The corresponding response message from the agent carries the same identifying information.

MIBs are defined using an Internet-standard language called the Structure of Management Information (SMI). MIBs can be defined using either of two SMI versions: the original SMI definition, and a newer SNMPv2 SMI definition. The key differences are described in Table 2-3, “Summary of the SNMPv1 and SNMPv2 SMI Definitions.”

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

Chapter 2 33


Table 2-3 Summary of the SNMPv1 and SNMPv2 SMI Definitions

SMI Definition Differences

SNMPv1 SMI Forms the basis for all existing SNMPv1-based MIBs. Defined in RFC 1155: Structure and Identification of Management Information for TCP/IP-based Internets Amended in RFC 1212: Concise MIB Definitions

SNMPv2 SMI Defined as a superset of the SNMPv1 SMI. Some SNMPv1 data types have been renamed:

• Counter -> Counter32

• Gauge -> Gauge32

• INTEGER -> Integer32

Extends the original SNMPv1 SMI to support these new data types:

• Counter64 (64-bit counter)

• Unsigned32 (32-bit unsigned integer). Indistinguishable from Gauge32.

• BITS (defines an enumeration of bits. Indistinguishable from OCTET STRING.

Allows custom data types to be built by constraining the range, size, or possible values of existing data types. For example, a new enumeration could be constructed by defining a small set of possible integer values. The SNMPv2 SMI refers to this form of definition as a “textual convention.”

Defined in: RFC 1902: Structure of Management Information for Version 2 of the Simple Network Management Protocol RFC 1903: Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)RFC 1904: Conformance Statements for Version 2 of the Simple Network Management Protocol (SNMPv2)

Chapter 234


Object Identifiers

For the purposes of an SNMP developer, an object identifier (OID) is a data type that precisely identifies a MIB-II object definition. An OID (often referred to as the registration ID) consists of a sequence of non-negative integers that describe the only path through the object-naming hierarchy to the object. The naming hierarchy is commonly called the naming tree.

The Naming Tree

The naming tree has the structure of a conventional tree with arbitrary breadth and depth. The nodes are labeled with non-negative integers (each node among siblings must have a unique label).

Various organizations have administrative authority for assigning labels within subtrees of the naming tree. They can assign subordinate (child) nodes, and/or delegate this responsibility to still other organizations.

The root node of the naming tree has three children:

ccitt(0) The administration authority for this branch is the International Telegraph and Telephone Consultative Committee (CCITT).

iso(1) The administration authority for this branch is the International Organization for Standards, and the International Electrotechnical Committee (ISO/IEC). This is the path under which networking management is defined.

joint-iso-ccitt(2) The administration authority for this branch is shared between CCITT and ISO/IEC.

Chapter 2 35


Figure 2-3 The Top of the MIB Naming Tree

Every path through the naming tree ultimately terminates at a leaf node. The sequence of labels along the path (starting at the root) is the OID for the object named at the leaf.

OIDs in Practice

The convention for writing object identifiers is called dot notation. An OID in dot notation consists of the integers of the OID in sequence, with a period (dot) between them. Thus the prefix for the OIDs in the MIB-II is 1.3.6.1.2.1.

Below is an example OID from the MIB-II. The full written name of the path is shown beneath the corresponding numerical identifiers in the OID:

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 prefix for the OIDs in HP enterprise-specific MIBs is 1.3.6.1.4.1.11.

joint-iso-ccitt(2)iso(1)ccitt(0)

root

iso.org.dod.internet.mgmt.mib.tcp.tcpAttemptFails

1.3.6.1.2.1.6.7

Chapter 236


Extended MIBs

Many agents support extended MIBs, which define objects that are not included in standard MIBs, such as MIB-II and enterprise-specific MIBs. Your application can query an object from an extended MIB exactly as it would query a MIB-II object. Users should use the proper registration authorities when defining MIB extensions.

Data Representation

Data is exchanged between SNMP processes using the Basic Encoding Rules (BER) defined for the Abstract Syntax Notation (ASN.1).

ASN.1 is a rich data description language, and gaining a full understanding of it is a formidable task. Fortunately, as an SNMP developer, you do not deal directly with ASN.1 or the Basic Encoding Rules. The HP OpenView SNMP API takes care of the details of ASN.1 encoding and decoding.

SNMP uses a few simple ASN.1 data types. Table 2-4, ASN.1 Data Types, lists the base data types that you work with in SNMP communication. The details of how you access them appear in the online reference pages.

Table 2-4 ASN.1 Data Types

Type Description

INTEGER

Integer32

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.

OCTET STRING 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.

OBJECT IDENTIFIER

An array of non-negative, 32-bit integers. Each integer represents one element of the object identifier. The maximum length of an OBJECT IDENTIFIER is limited to 128 sub-identifiers.

Counter

Counter32

A type representing a non-negative integer which calculates change and increases until it reaches a maximum value, when it then wraps around and starts increasing again from zero.

Chapter 2 37


Gauge

Gauge32

A type representing a non-negative integer, which may increase or decrease, but which latches at a maximum value.

Timeticks A type representing a non-negative integer which counts the time in hundredths of a second since some event.

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

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

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

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

BITS An arbitrary set of named bit enumerations encoded as an ASN.1 OCTET STRING.

Table 2-4 ASN.1 Data Types (Continued)

Type Description

Chapter 238


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 information used to recognize proxy agents resides in the SNMP Configuration Database. This proxy information must be configured by the administrator of the manager. For details, see xnmsnmpconf(1) in the online reference pages.

The Manager addresses a message to theTargetAgent. The HP SNMP API recognizesthat the agent has an SNMP proxy namedProxySys. The API routes the message toProxySys, which in turn communicates withTargetAgent in some non-SNMP protocol,then relays the response to manager, usingSNMP.

TargetAgent

Manager

ProxySys

SNMP

Foreign Protocol

Chapter 2 39

An Overview of SNMPFor More Information

For More InformationThe 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 Outside Reading

Document Description

RFC 1155: Structure and Identification of Management Information for TCP/IP-based Internets

K. McCloghrie and M. T. Rose, (May 1990). Contains MIB object definitions. (Obsoletes RFC 1065)

RFC 1157: A Simple Network Management Protocol

J. D. Case, M. Fedor, M. L. Schoffstall, and C. Davin, (May 1990). Defines SNMP. (Obsoletes RFC 1098)

RFC 1187: Bulk Table Retrieval with the SNMP

K. McCloghrie, M. T. Rose, and C. Davin, (October 1990).

RFC 1212: Concise MIB Definitions K. McCloghrie and M. T. Rose, (March 1991). Describes the format for creating MIB object files.

RFC 1213: Management Information Base Network Management of TCP/IP based internets: MIB-II

K. McCloghrie and M. T. Rose, eds., (March 1991). Defines MIB-II. (Obsoletes RFC 1158; most current edition as of the printing of this guide.)

RFC 1215: Convention for Defining Traps for Use with the SNMP

M. T. Rose, ed. (March 1991).

RFC 1901: Introduction to Community-based SNMPv2

SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Defines “Community-based SNMPv2.” (Experimental. Obsoletes RFC 1441)

RFC 1902: Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). MIB Definition language for Managed Objects (Draft Standard. Obsoletes RFC 1442)

Chapter 240


RFC 1903: Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). MIB Definition language for refined data types. (Draft Standard. Obsoletes RFC 1443)

RFC 1904: Conformance Statements for Version 2 of the Simple Network Management Protocol (SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). MIB Definition language for Conformance and Capability definitions. (Draft Standard. Obsoletes RFC 1444)

RFC 1905: Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Defines SNMPv2 protocol. (Draft Standard. Obsoletes RFC 1448)

RFC 1906: Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Defines SNMPv2 transport mappings for IP, IPX, DDP. (Draft Standard. Obsoletes RFC 1449)

RFC 1907: Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Defines MIB objects that are mandatory for SNMP agents that support SNMPv2. (Draft Standard. Obsoletes RFC 1450)

RFC 1908: Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework

SNMPv2 WG, J.Case, K. McCloghrie, M.T. Rose, S. Waldbusser, (January 1996). Coexistence guidelines for SNMPv1 and SNMPv2. (Draft Standard. Obsoletes RFC 1452)

Table 2-5 Outside Reading (Continued)

Document Description

Chapter 2 41


Chapter 242

3 The OVSNMP Communications API

Chapter 3 43

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 Developer’s 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

Chapter 344

The OVSNMP Communications APISNMPv1 and SNMPv2C Protocol Support

SNMPv1 and SNMPv2C Protocol SupportThe 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 specifically use the SNMPv2C API extensions. The extensions are easily accommodated by any existing application already using the OVSNMP communications API.

The remainder of this section describes how you can take advantage of the dual support of the SNMPv1 and SNMPv2C protocols in the SNMP developer’s 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 45


The bilingual mode relies on information in the SNMP configuration database to determine which protocol version to use to communicate with a particular agent. The protocol stack automatically translates requests made in bilingual mode to the particular protocol supported for a particular agent.

Figure 3-1 shows the relationship between the OVSNMP API and the bilingual/native protocol stack support.

Figure 3-1 OVSNMP Bilingual Stack

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.

Management Application

SNMPv1 Style API

v1 mode

SNMPv2 Style API

SNMPv1protocol

v1 bilingualmodemode

v2Cmode

SNMPv1protocol

SNMPv2Cprotocol

controlled byOVSNMP_V2API session flag

controlled byprotocol version(when theOVSNMP_V2API flag is set)

OR OR

SNMPv2 agentSNMPv1 agent

Chapter 346


You can use the OVSNMP API in its original interface style or in the new interface style, which is called OVSNMP_V2API. If you select the new interface style, your application can take advantage of both explicit SNMPv2C protocol support and bilingual SNMPv1/SNMPv2C protocol support. Your application, however, must also handle the different types of errors that can be returned through the SNMPv2-style interface.

You may explicitly request that your application use either the SNMPv1 or SNMPv2C protocol. By default, if you use the SNMPv2-style interface, the SNMP stack will use the bilingual communication mode.

The bilingual communication mode allows access to SNMP operations that might not initially appear to be valid for a given remote system. For example, you could use GetBulk Requests for a remote node that supports only the SNMPv1 protocol. When using bilingual communication mode, the SNMP run-time stack dynamically translates requests into SNMP operations that are valid for the particular type of remote system involved in the communication. For example, if a remote system supports only the SNMPv1 protocol, a GetBulkRequest is translated into a GetNext request.

The OVSNMP API performs the following protocol translations when communicating with SNMPv1 agents through the SNMPv2-style interface:

• SNMPv2 GetBulk operations are translated into SNMPv1 GetNext operations.

• When transmitting SNMPv2 traps to SNMPv1 systems, the trap is first translated into the SNMPv1 trap format.

• If an SNMPv1 Trap Request is received and the API is operating in the SNMPv2-style interface mode, the SNMPv1 Trap Request is translated into the SNMPv2 Trap format.

• SNMPv2 Inform operations cannot be translated into an SNMPv1 equivalent operation, and therefore cannot be sent to an SNMPv1 system.

Chapter 3 47


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.

If necessary, you can determine which protocols are configured in the local OVSNMP Configuration Database for a remote system by using the OVsnmpGetVersions function or the xnmsnmpconf -getVersions command. For more information about querying the protocols supported by a remote system, see the reference page for xnmsnmpconf.

Enhanced Error Codes If you select the SNMPv2-style interface to the OVSNMP API, you must be prepared to handle a much larger set of possible error codes than was possible with the SNMPv1-only interface.

Table 3-1 Protocol Operations Supported by the OVSNMP API

SNMP Operation v1-style API

v2-style API

Bilingual SNMPv1 SNMPv2C

GET_REQ_MSG x x x x

GETNEXT_REQ_MSG x x x x

GETBULK_REQ_MSG x x a x

SET_REQ_MSG x x x x

RESPONSE_MSG x x x x

V1TRAP_REQ_MSG x x

V2TRAP_REQ_MSG x x

INFORM_REQ_MSG x x

Receive SNMPv1 trap in SNMPV2 trap format

x x x

Receive SNMPv2 trap or inform in SNMPv1 trap format

x

a. When using the SNMPv2-style API with the SNMPv1 protocol version, each GetBulk request is mapped to a single GetNext request, regardless of the maximum number of repetitions specified.

Chapter 348


Table 3-2, Protocol Error Status Supported by the OVSNMP API, shows the errors that can be returned when using each of the OVSNMP API interface modes. The original SNMPv1-style interface supports only the error codes listed under “v1-style Interface.” SNMPv1 error codes are not translated to SNMPv2C code. The SNMPv2C codes are more specific than SNMPv1 codes, so there is no one-to-one translation between the two.

Applications using the bilingual protocol mode must be able to deal with error codes that do not appear as SNMPv1 error codes, even if the messages originate from an SNMPv1 remote system. The bilingual mode is designed to hide the details of the lower level protocol, and to allow developers to write applications that work equally well when communicating with SNMPv1 and SNMPv2C-compatible remote systems.

When using the SNMPv2-style API interface, the set of possible errors returned is the same, regardless of the actual SNMP protocol used to communicate with the remote system. See Table 3-2, “Protocol Error Status Supported by the OVSNMP API.”

Table 3-2 Protocol Error Status Supported by the OVSNMP API

SNMP Response Errors v1 style Interface

v2-style Interface

Bilingual v1 native

v2 native

SNMP_ERR_NOERROR x x x x

SNMP_ERR_TOOBIG x x x x

SNMP_ERR_NOSUCHNAME x x x x

SNMP_ERR_BADVALUE x x x x

SNMP_ERR_GENERR x x x x

SNMP_ERR_NOACCESS x x

SNMP_ERR_WRONGTYPE x x

SNMP_ERR_WRONGLENGTH x x

SNMP_ERR_WRONGENCODING x x

SNMP_ERR_WRONGVALUE x x

Chapter 3 49


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, first 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 field 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.

SNMP_ERR_NOCREATION x x

SNMP_ERR_INCONSISTENTVALUE x x

SNMP_ERR_RESOURCEUNAVAILABLE x x

SNMP_ERR_COMMITFAILED x x

SNMP_ERR_UNDOFAILED x x

SNMP_ERR_AUTHORIZATIONERROR x x

SNMP_ERR_NOTWRITABLE x x

SNMP_ERR_INCONSISTENTNAME x x

Varbind Exceptions x x

Table 3-2 Protocol Error Status Supported by the OVSNMP API

SNMP Response Errors v1 style Interface

v2-style Interface

Bilingual v1 native

v2 native

Chapter 350


Optionally, if you want to specify a particular communications protocol rather than use bilingual protocol support, you can set the protocol_version field in the OVsnmpSession structure. All communication from that point on will use the specified communication protocol. Valid choices for the protocol version are:

• SNMP_VERSION_1

• SNMP_VERSION_2C

• SNMP_USE_DEFAULT_VERSION (bilingual)

Chapter 3 51

The OVSNMP Communications APIOVSNMP Over UDP/IP and IPX

OVSNMP Over UDP/IP and IPXThe OVSNMP API supports communication with SNMP agent systems using either the User Datagram/Internet Protocol (UDP/IP) or Novell’s 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 modified. In addition, most of those applications, when ported to the WindowsNT/2000 operating system, will realize both UDP/IP and IPX support without any modification as well. Only applications that override the SNMP destination on a per-request (PDU) basis must be enhanced to realize full IPX support.

The multi-transport capabilities are exported to an application in two areas: the OVsnmpOpen() function and the OVsnmpPdu structure.

The OVsnmpOpen() Function

The OVsnmpOpen(), OVsnmpXOpen(), and OVsnmpWOpen() functions take peername and remote_port parameters as input.

The peername is a character string that identifies 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 specified for remote_port, the appropriate default value is used (such as UDP/161 or IPX/36879).

Chapter 352


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 flows and event streams distinguish the combination of events available for subscription.

An application subscribing to events must specify one of three event flows: RAW, CORR, or ALL. The RAW event flow includes all events received by the event subsystem excluding events originating in the ECS engine. The correlated (CORR) event flow includes all events coming from a named event stream. The ALL event flow 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 filter parameter of OVsnmpEventOpen(), you can specify the type of event flow (RAW, CORR, or ALL) from which to receive HP OpenView events. In the case of CORR event flow, 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 53


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 defined 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 redefines the OVsnmpPdu address member to be a sockaddr (generic socket) structure. The address.sa family value then determines the type of address specified in the PDU. If this value is AF_UNSPEC, the session peername is used as the destination. Otherwise, AF_INET indicates a UDP/IP address (sockaddr_in format); and AF_IPX indicates an IPX address (sockaddr_in format).

Existing applications that rely on the session peername when sending SNMP requests do not need to be modified. However, applications that override the destination on a per-request (PDU) basis must be modified to do the following:

• Use the new multi-transport interface directive.

• Reference the OVsnmpPdu address structure accordingly. Further, the OVsnmpPdu address type must be the same type as that of the session peername. Otherwise, the SNMP request will fail with SNMP_ERR_INVALID_HOST.

Developers of new applications are encouraged to use the multi-transport interface directive in all cases.

Chapter 354

The OVSNMP Communications APIBlocking and Nonblocking Programming Models

Blocking and Nonblocking Programming ModelsThe 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 first 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 55


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

Chapter 356


Automatic Retransmission Using the Win32 Message Loop

The OVSNMP API on Windows operating systems includes native Win32 support for event-driven (nonblocking) applications. As illustrated in the sample code fragment below, you use this feature by calling the OVsnmpWOpen and OVsnmpSend functions, along with the Win32 message loop consisting of GetMessage to DispatchMessage. The OVsnmpGetRetryInfo and OVsnmpDoRetry functions are not used in this mode of operation.

session=OVsnmpWOpen(targetName,...applCb,applCb,applCbData);pdu=OVsnmpCreatePdu(...);OVsnmpAddNullVarbind(...);reqId=OVsnmpSend(session,pdu); ...other application specific code...while (GetMessage(&msg)){ TranslateMessage(&msg);/*For Keyboard accels*/ DispatchMessage(&msg);/* *Note:DispatchMessage() ultimately invokes the OVSNMP applCb *for SNMP responses, notifications and timeout conditions */

Automatic Retransmission Using X11 Event Loop (UNIX Only)

The OVsnmpAPI library includes extended support for event-driven X11-based applications. These applications use OVsnmpXOpen and OvsnmpSend. When you use this feature, the SNMP library manages all message retransmissions for you using XtAppMainLoop(3). The sample code fragment illustrates how retransmissions are handled.

session=OVsnmpXOpen(XtCtx, target,...applCb,applCbData);pdu=OVsnmpCreatePDU(...);OVsnmpAddNullVarbind(...);reqId=OVsnmpSend(session,pdu); ..other application specific code...XtAppMainLoop(XtCtx);/* *Note:XtAppMainLoop() invokes the OVSNMP applCb *for SNMP responses, notifications and timeout conditions */

Chapter 3 57

The OVSNMP Communications APIThe SNMP Communications API Functions

The SNMP Communications API FunctionsTable 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 SNMP Communications API Functions

Function Name Description

SESSION MANAGEMENT FUNCTIONS

OVsnmpOpen() Establishes a logical session with the OVsnmpAPI for the purpose of communicating with a specific remote system.

OVsnmpXOpen() Equivalent to OVsnmpOpen(), but prepares a logical session for use in an X-Windows programming environment.

OVsnmpWOpen() Equivalent to OVsnmpOpen(), but prepares a logical session for use in a Windows operating system programming environment.

OVsnmpClose() Terminates an SNMP session created by any of the OVSNMP session open functions.

OVsnmpXClose() Provided for backward compatibility of existing X11 applications.

EVENT FRAMEWORK SESSION FUNCTIONS

OVsnmpEventOpen() Successor to OVsnmpTrapOpen(). Establishes a logical session with the OVsnmpAPI for the purpose of receiving SNMP events via the OpenView Event Framework. It allows filters to be applied to events to reduce the number of events that are received.

OVsnmpXEventOpen() Equivalent to OVsnmpEventOpen(), but prepares a logical session for use in an X-Windows programming environment.

Chapter 358


OVsnmpWEventOpen() Equivalent to OVsnmpEventOpen(), but prepares a logical session for use in a WindowsNT/2000 operating system programming environment.

OVsnmpTrapOpen() Predecessor to the OVsnmpEventOpen() function. This function is provided for backward compatibility only. Use the OVsnmpEventOpen() routine in the future.

OVsnmpXTrapOpen() Provided for backward compatibility of existing X11 applications.

MESSAGE SETUP and MANIPULATION FUNCTIONS

OVsnmpCreatePdu() Allocates and initializes an OVsnmpPdu data structure suitable for the specified SNMP request operation.

OVsnmpAddNullVarBind() Used in conjunction with SNMP Get, GetNext, and SNMPv2 GetBulk Requests. Allocates, initializes, and appends an OVsnmpVarBind structure for the specified SNMP MIB object to the SNMP Request PDU.

OVsnmpAddTypedVarBind() Used in conjunction with SNMP Set, Trap, and SNMPv2Inform Requests. Allocates, initializes, and appends an OVsnmpVarBind structure for the specified SNMP MIB object to the SNMP Request PDU.

OVsnmpFixPdu() Allocates and initializes a new SNMP request PDU based on the specified response PDU. Any invalid variable bindings are omitted from the resulting PDU.

OVsnmpCopyPdu() Creates a copy of the specified OVsnmpPdu data structure and its contained elements.

OVsnmpFreePdu() Deallocates the specified OVsnmpPdu data structure and its contained elements.

OVsnmpExtractUuid() Extract the OVsnmp UUID from an OVsnmpPdu

OVsnmpUuidFromStr() Convert a string representation of an OVsnmp UUID to its packed form.

Table 3-3 SNMP Communications API Functions (Continued)


Chapter 3 59


OVsnmpUuidToStr() Convert an OVsnmp UUID from the packed form to an ASCII string.

OVsnmpOidAppend() Appends one object identifier fragments of type ObjectID to another object identifier.

OVsnmpOidAppendN() Appends one or more object identifier fragments of type ObjectID to another object identifier.

OVsnmpOidConcat() Concatenates two object identifier fragments of type ObjectID together to produce a new object identifier.

OVsnmpOidConcatN() Concatenates two or more object identifier fragments of type ObjectID together to produce a new object identifier.

OVsnmpOidCopy() Create a copy of an object identifier of type ObjectID.

OVsnmpOidCompare() Compare two object identifiers of type ObjectID for lexicographic ordering (less than, equal to, greater than).

OVsnmpOidFromStr() Create a new object identifier of type ObjectID from a string in dotted-numeric notation.

OVsnmpOidFromName() Create a new object identifier of type ObjectID from a string in either dotted-numeric notation, or mnemonic descriptor (name) form as defined in the HP OpenView loaded MIB database.

OVsnmpOidToStr() Format an object identifier of type ObjectID as a string in dotted-numeric notation.

OVsnmpOidToName() Format an object identifier of type ObjectID as a string using the mnemonic descriptor (name) defined in the HP OpenView loaded MIB database.

OVsnmpMalloc() Allocate a block of unitialized dynamic memory.

OVsnmpCalloc() Allocate a block of dynamic memory initialized to zero.

OVsnmpRealloc() Change the size of a block of dynamically allocated memory.



Chapter 360


OVsnmpFree() Deallocate a block of previously allocated dynamic memory.

COMMUNICATIONS FUNCTIONS — BLOCKING MODE

OVsnmpBlockingSend() Sends a request PDU to an SNMP agent and waits for a response to be received.

OVsnmpRecv() 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 () Sends a request PDU to an SNMP agent, but does not wait for a response.

OVsnmpEventSend() Send a notification PDU to the OpenView Event subsystem. Caller can override the source address and retrieve the OVsnmp UUID of the out going event.

OVsnmpRead() Receives incoming data on pending sessions. Information is returned via the callback function.

OVsnmpGetRetryInfo() Gets retransmission information on pending SNMP requests for use in the select() routine.

OVsnmpDoRetry() Retransmits a pending SNMP request.

OVsnmpCancel() Cancels an SNMP request for which a response has not yet been received.

OVsnmpCallback() The application-defined function that handles responses to non-blocking requests.

OVsnmpEventAck() Acknowledge an event in the HP OpenView Event Subsystem.

OVsnmpEventDel() Delete an event in the HP OpenView Event Subsystem.

OVsnmpEventCorrelate() Correlate two events in the HP OpenView Event Subsystem.



Chapter 3 61


OVsnmpEventUnack() Unacknowledge an alarm in the HP OpenView Event Subsystem.

OVsnmpEventChangeSev() Change the severity of an alarm HP OpenView Event Subsystem.

OVsnmpEventChangeCat() Change the category of an alarm in the HP OpenView Event Subsystem.

COMMUNICATIONS FUNCTIONS — X11 NONBLOCKING MODE

OVsnmpXSend() Superseded by OVsnmpSend(). It is provided for backward compatibility of existing X11 applications.

OVsnmpXCancel() Superseded by OVsnmpCancel(). It is provided for backward compatibility of existing X11 applications.

ERROR REPORTING FUNCTIONS

OVsnmpErrString() Obtains a pointer to an error message string that corresponds to the specified OVsnmpErrno error code.

SNMP_STD2OV_ERR() Translates a pdu→error_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 pdu→error_status to be passed directly.

OVUint64 ARITHMETIC FUNCTIONS

OVuint64FromStr() Converts ASCII string notation of an unsigned 64-bit integer into OVuint64 data type.

OVuint64ToStr() Convert OVuint64 data type into ASCII string notation.

OVuint64Assign() Assigns the low and high order portions of an OVuint64 value from two 32-bit values.

OVuint64Cmp() Compares two OVuint64 values for less than, equality, and greater than.



Chapter 362


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.

OVuint64Shift() Performs left or right bit-shift of an OVunit64 value.

OVuint64Add() Adds two OVuint64 values and returns the sum.

OVuint64Subtract() Subtracts two OVuint64 values and returns the difference.

OVuint64Multiply() Multiplies two OVuint64 values and returns the product.

OVuint64Divide() Divides two OVuint64 values and returns the quotient.

OVuint64CmpUInt32() Compares an unsigned 32-bit value to an OVunit64 value for less than, equality, and greater than.

OVuint64AddUInt32() Adds an unsigned 32-bit value to an OVuint64 value and returns the sum.

OVuint64SubtractUInt32() Subtracts an unsigned 32-bit value from an OVuint64 value and returns the difference.

OVuint64MultiplyUInt32() Multiplies an OVuint64 value by an unsigned 32-bit and returns the product.

OVuint64DivideUInt32() Divides an OVuint64 value by an unsigned 32-bit and returns the quotient.



Chapter 3 63


Sometimes you may supply data to fill in a structure that the SNMP library has allocated. For example, you might assign a Notification OID or Enterprise OID to an SNMP Trap PDU. Such data must always be dynamically allocated. Otherwise, a failure occurs when the library attempts to deallocate statically allocated memory.

Make sure that whenever memory is allocated — whether by the SNMP library or by your application — it is later deallocated. Neglecting this can result in a “memory leak” which gradually consumes resources until a failure occurs.

Four functions are provided for you to allocate and deallocate ancillary data assigned to OVSNMP data structures. The are: OVsnmpMalloc(), OVsnmpCalloc(), OVsnmpRealloc() and OVsnmpFree(). These functions behave the same as, and are implemented using, the underlying operating system malloc(), calloc(), realloc() and free() functions, respectively. The purpose of the OVSNMP API versions of these functions is to provide common memory allocation and deallocation, particularly on the WindowsNT/2000 operating system where the DEBUG (msvcrtd.dll) and non-DEBUG (msvcrt.dll) versions of the C-runtime library are not compatible with each other. The functions are also provide on UNIX systems for cross-platform portability.

Table 3-4, OVsnmpAPI Memory Management, summarizes the types of data structures allocated or deallocated by the OVSNMP API functions. Refer to the specific function description for details.

Table 3-4 OVsnmpAPI Memory Management

OVsnmpAPI Function Memory Management Performed

OVsnmpOpen()

OVsnmpXOpen()

OVsnmpWOpen()

OVsnmpTrapOpen()

OVsnmpXTrapOpen()

OVsnmpEventOpen()

OVsnmpXEventOpen()

OVsnmpWEventOpen()

Allocates returned OVsnmpSession.

Chapter 364


OVsnmpClose()

OVsnmpXClose()

Deallocates specified OVsnmpSession.

OVsnmpCreatePdu() Allocates returned OVsnmpPdu.

OVsnmpAddNullVarbind()

OVsnmpAddTypedVarbind()

Attaches allocated OVsnmpVarBind to a PDU.

OVsnmpCopyPdu() Allocates returned OVsnmpPdu (makes a duplicate of specified pdu).

OVsnmpFixPdu() Deallocates specified OVsnmpPdu. Allocates returned OVsnmpPdu.

OVsnmpSend()

OVsnmpXSend()

OVsnmpBlockingSend()

OVsnmpEventSend()

Conditionally deallocates specified OVsnmpPdu based on associated session FREE_Pdu flag.

If enabled, deallocates input PDU (only if no error occurs) otherwise caller must free input PDU.

OVsnmpRecv() Allocates returned OVsnmpPdu; application must deallocate via OVsnmpFreePdu().

OVsnmpCallback()(application supplied) API allocated OVsnmpPdu passed as input; application must deallocate via OVsnmpFreePdu.

OVsnmpFreePdu() Deallocates specified OVsnmpPdu.

OVsnmpMalloc()

OVsnmpCalloc()

OVsnmpRealloc()

Allocates an object ID sequence that must be assigned to an OVsnmpPdu or deallocated using OVsnmpFree().

OVsnmpFree() Deallocates specified OVsnmpPdu.

Table 3-4 OVsnmpAPI Memory Management (Continued)

OVsnmpAPI Function Memory Management Performed

Chapter 3 65

The OVSNMP Communications APIThe SNMP Communication API Data Structures

The SNMP Communication API Data StructuresThis section introduces the key data structures. See the online reference pages for specific details about other data structures. The reference pages also contain information on compiling and linking your application. You can use the following compilers to compile applications on various operating systems and computers.

NOTE For a complete list of supported operating systems and compatible compiler versions, refer to Table A in HP OpenView Network Node Manager 7.51 Software Development Kit Release Notes.

Table 3-5 Compilers Supported on Operating Systems

Compiler Application Source Code Type, Operating System, or Computer Series

HP-UX C or ANSI C

HP 9000 series computers operating on HP-UX

HP ANSI C++ Applications written in C++ language on supported HP-UX platforms

Sun Studio compiler suite

Applications written in C or C++ language on Solaris operating systems

Microsoft Visual C++

Microsoft Windows platforms

Red Hat gcc or g++

Linux operating systems

Chapter 366


Header Files

The header file defines many data structures that are part of the OVSNMP API. All header files are stored under a common directory represented by the $OV_HEADER environment variable. See the reference page ov.envvars for details on the $OV_HEADER environment variable. The OVsnmp header files are shown in Table 3-6, “OVSNMP Header Files.”

Chapter 3 67


Table 3-6 OVSNMP Header Files

Header File Purpose

$OV_HEADER/OV/OVsnmp.h The main header file for OVSNMP applications. This file includes all other header files (except OVsnmpWfns.h and OVsnmpXfns.h) as a convenience.

$OV_HEADER/OV/OVsnmpApi.h Main function declarations, structure definitions, and control definitions.

$OV_HEADER/OV/OVsnmpClnt.h More function declarations.

$OV_HEADER/OV/OVsnmpAsn1.h ASN.1 type definitions for the API. These are the ASN.1 types that are supported by the OVSNMP library.

$OV_HEADER/OV/OVsnmpConf.h Configuration parameter and function definitions.

$OV_HEADER/OV/OVsnmpErr.h Error value definitions.

$OV_HEADER/OV/OVsnmpWfns.h Declarations for the Microsoft Win32-specific functions.

$OV_HEADER/OV/OVsnmpXfns.h Declarations for the X11-specific functions in the OVSNMP library.

$OV_HEADER/OV/OVuint64.h Declarations for 64-bit integer arithmetic functions.

Chapter 368


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 PDU’s error_status field must be mapped to the OVSNMP API error code space before being passed to OVsnmpErrString(). This mapping is performed by the newly provided SNMP_STD2OV_ERR macro. Examples of how this macro is used can be found in $OV_MAIN_PATH/prg_samples/ovsnmp_app.

Chapter 3 69


Data Structures

The key data structures you will use with the OVSNMP API are described in Table 3-7.

The two data structures you will use most often are the OVsnmpSession structure and the OVsnmpPdu structure (including its substructures).

Table 3-7 SNMP API Key Data Structures

Data Structure Name

Description

OVsnmpSession Obtained by a call to OVsnmpOpen(), it identifies a particular SNMP communication session. Used as an input parameter to several other functions. Created by OVsnmpOpen(); freed by OVsnmpClose().

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

OVsnmpVarBind Elements on a linked list of variables. Each element of the list includes an object identifier for the variable and the variable's value. Part of the OVsnmpPdu structure. Created by OVsnmpAddVarBind(); freed by OVsnmpFreePdu().

OVsnmpVal A union that can contain the value portion of an SNMP variable binding. Part of the OVsnmpVarBind structure. Created by OVsnmpAddVarBind(); freed by OVsnmpFreePdu().

Chapter 370


The OVsnmpSession Structure

OVsnmpSession identifies a logical session between the manager and a specific destination SNMP agent. The OVsnmpSession structure is allocated by a call to OVsnmpOpen, and is an input parameter to several other functions. The fields are shown in Table 3-8.

Table 3-8 OVsnmpSession Fields

Field Name Type Description

community u_char The community name of the agent. Defaults to “public,” or the value contained in the OVSNMP configuration database. When the session is closed, this memory is deallocated.

community_len u_int The number of bytes in the community name.

setCommunity u_char The community name of the agent for use in SNMP set requests.

setCommunity_len u_int The number of bytes in the set community name.

sock_fd int The socket file descriptor for the session. Used to establish the read mask for calls to select().

(*callback)() (void *)() Points to the callback function to be invoked when a response returns from a call to OVsnmpSend() or OVsnmpXSend(), or when a notification is received using OVsnmpRead(). These two send functions are nonblocking, and the callback function is to be invoked when the corresponding response arrives.

callback_data void * 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.

Chapter 3 71


protocol_version long Defines a specific SNMP protocol version to use for this session. It is only valid when the OVSNMP_V2API bit in the session_flags field is enabled.

Valid values are:

SNMP_VERSION_1SNMP_VERSION_2CSNMP_USE_DEFAULT_VERSION

session_flags u_short A bitmask for information and control. The following values are defined:

• OVSNMP_FREE_PDU (and FREE_PDU): If set, the send functions deallocate memory associated with the input OVsnmpPdu structure. The default for this flag is set.

• OVSNMP_RECV_EVENTS (and RECV_TRAPS): Set this flag if you want notifications (traps and informs) to be passed to the calling application.

• The default when using OVsnmpOpen() or OVsnmpXOpen() is unset.

• The default when using OVsnmpEventOpen(), OVsnmpXEventOpen(), OVsnmpTrapOpen(), or OVsnmpXTrapOpen() is set.

• OVSNMP_V2API: Controls the interface semantics of the OVsnmpAPI with regard to SNMPv1 versus SNMPv2-style operation. The default for this flag is unset.

• OVSNMP_CLOSE_CALLBACK: If set, the nonblocking application callback function is invoked for each outstanding request that exists at the time the session is closed (via OVsnmpClose() or OVsnmpXClose(). The default for this flag is unset.

Table 3-8 OVsnmpSession Fields (Continued)


Chapter 372


The Callback Function

Your application determines the structure and purpose of the callback function. If you use the nonblocking calls in the OVSNMP API, the callback function defines the interaction of your application and the remote peer.

The callback function is automatically invoked when your application uses OVsnmpRead() to obtain the response to a nonblocking send request. In X applications, the callback is invoked automatically when the response arrives. The call syntax is as follows:

callback (command, session, pdu, callback_data)

If the response or notification is obtained with OVsnmpRecv instead, the callback does not occur.

Your callback function must define the parameters in Table 3-9. These input parameters are passed to the callback function. They are described further in the OVsnmpPdu data structure section.

The entries in Table 3-10 define the valid values for the callback command parameter.

Table 3-9 CallBack Parameters

Parameter Description

command An integer. Indicates why the callback function was called. See Table 3-10 for details.

session An OVsnmpSession structure. Identifies the session with which the incoming PDU is associated.

pdu An OVsnmpPdu structure. This is the PDU that was received, or a copy of the original request PDU on some error conditions.

callback_data Application-specific data, which is specified as the value passed into the OVsnmpOpen call.

Chapter 3 73


Table 3-10 CallBack Command Values

Command Value Note Description

GET_REQ_MSG

GETNEXT_REQ_MSG

SET_REQ_MSG

1 The pdu parameter contains the RESPONSE to the respective type of outstanding SNMP request.

RESPONSE_MSG 2 The pdu parameter contains the RESPONSE to an outstanding SNMP request.

V1TRAP_REQ_MSG 1 The pdu parameter contains unsolicited trap notifications.

V2TRAP_REQ_MSG 2 The pdu parameter contains unsolicited trap notifications.

INFORM_REQ_MSG 2 The pdu parameter contains an unsolicited inform notification.

SNMP_ERR_NO_RESPONSE 1, 2 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.

SNMP_SYSERR_LOST_CONN 3 Indicates the connection to OpenView Event subsystem is disconnected. For example, the pmd process has terminated via ovstop. The pdu is NULL.

SNMP_ERR_CLOSING_SESSION 4 Indicates the specified session is being closed by OVsnmpClose (or OVsnmpXClose) when an SNMP request is still outstanding. The pdu is a copy of the outstanding request.

Notes

(1) Occurs only if the SNMP_V2API bit in the session_flags field is not set for the specified session parameter.

(2) Occurs only if the SNMP_V2API bit in the session_flags field is set for the specified session parameter.

Chapter 374


The OVsnmpPdu Structure

The OVsnmpPdu data structure represents the SNMP Request, Response, or Trap PDU that is sent or received by the calling application. The information in this structure is encoded into and decoded from the ASN.1 contents of the SNMP packet.

The OVsnmpPdu is created in one of two ways:

• Through a call to OVsnmpCreatePdu(). This is done while preparing to send a request.

• When a response or notification is received.

The SNMP send functions normally deallocate the memory associated with input PDU structures.1 To deallocate the PDU associated with a response or notification, use OVsnmpFreePdu().

NOTE For SNMPv2 traps and informs, the OVsnmpPdu structure conveys the logical format of the notification. The notification identifier, timestamp and optional enterprise identifier are represented in fields of the OVsnmpPdu structure. The variables list contains only the “data varbinds” for the notification. When the V2 trap or inform pdu structure is encoded into or decoded from the SNMP message, these three attributes are inserted into or extracted from the SNMP message variable-binding list.

(3) Occurs only if the specified session was created using OVsnmpEventOpen(), OVsnmpEventXOpen(), OVsnmpTrapOpen(), or OVsnmpXTrapOpen().

(4) Occurs only if the OVSNMP_CLOSE_CALLBACK bit in the session_flags field is set for the specified session parameter.

Table 3-10 CallBack Command Values (Continued)

Command Value Note Description

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

Chapter 3 75


The fields of the OVsnmpPdu structure are shown in order in Figure 3-2. Note that this PDU has two variables. Table 3-11 describes each of the elements in the OVsnmpPdu data structure.

Figure 3-2 OVsnmpPDU Structure

*next_variable

*oid

oid_length

type

val

val_len

*integer

*string

*object_id

unio

n

*uint32

*uint64

address

command

request_id

error_status

error_index

*community

community_len

*variables

*enterprise

enterprise_length

agent_addr

generic_type

specific_type

time

Specific toV2 Traps & Informs

*nex_variable

*oid

oid_length

type

val

val_len

*integer

*string

*object idun

ion

*uint32

*uint64

*notify_oid

notify_oid_length

Specific toV1 Traps

Specific toV1 & V2 Traps & Informs

OVsnmpPdu

OVsnmpVarBind OVsnmpVarBind

NULL

Chapter 376


Table 3-11 Elements of the OVsnmpPdu Data Structure


address struct

sockaddr

The address of the agent. Supported address types are AF_UNSPEC (the default), AF_INET, and AF_IPX (Windows only). See “OVSNMP Over UDP/IP and IPX” on page 52 for details.

protocol_version long Defines the specific SNMP protocol version that applies for this pdu. It is only valid if the OVSNMP_V2API mode of operation is enabled.

Valid values are:

SNMP_VERSION_1

SNMP_VERSION_2

SNMP_USE_DEFAULT_VERSION

command int The SNMP specific type of command. Must be one of the following:

GET_REQ_MSG

GETNEXT_REQ_MSG

SET_REQ_MSG

TRAP_REQ_MSG

GET_RSP_MSG

GETBULK_REQ_MSG

INFORM_REQ_MSG

V2TRAP_REQ_MSG

request_id int An identifier assigned by the SNMP API. This value must never be modified by your application.

Chapter 3 77


error_status int 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.

error_index int 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.

community u_char * When specified in a request PDU, this variable overrides the community name in the session parameter for this request only when a response PDU or trap PDU is received. This variable contains the community name returned by the agent.

community_len u_int The number of bytes in the community name.

variables OVsnmpVarBind * 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.

The following fields are specific to SNMPv1 trap and SNMPv2 trap/inform PDUs, and are invalid for all other PDUs.

enterprise ObjectID A vendor-specific identifier that uniquely identifies the type of device sending the trap. Optional for SNMPv2 traps and informs.

enterprise_length u_int The number of elements in the object ID. The default has 11 elements.

Table 3-11 Elements of the OVsnmpPdu Data Structure (Continued)


Chapter 378


The OVsnmpVarBind Data Structure

The OVsnmpVarBind data structure represents a single SNMP variable binding included in an SNMP PDU. The variable binding specifies the information the application wants to get from or set in the SNMP agent. Table 3-12 describes each of the elements.

agent_addr u_long The IP address of the agent that sent the trap. Represented in Network Byte Order. For OVSNMP over IPX, this value is zero.

time u_long 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.

The following fields are specific to SNMPv1 trap requests, and are invalid for all other PDUs.

generic_type int One of the SNMP-defined types of trap. See RFC 1157 for details.

specific_type int When generic_type indicates that an enterprise-specific trap has occurred, the value of specific_type contains the specific trap. Otherwise, the value is meaningless.

The following fields are specific to SNMPv2 Trap and Inform Requests, and are invalid for all other PDUs.

notify_oid ObjectID * Contains the snmpTrapOID variable bindings in the raw SNMPv2 Trap or Inform Request message.

notify_oid_len u_int The number of elements in the object ID.

Table 3-11 Elements of the OVsnmpPdu Data Structure (Continued)


Chapter 3 79


Table 3-12 Elements of the OVsnmpVarBind Data Structure


next_variable OVsnmpVarBind * Points to the next element in the variable list. NULL in last element.

oid ObjectID * The object identifier (object ID) for this variable.

oid_length u_int The number of elements in the object ID for this variable.

type u_char The ASN.1 type of the variable. Must be one of the types listed in Table 2-2.

val OVsnmpVal A union containing the possible data types. The active field is indicated by type (above).

val_len u_int 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.

Chapter 380


The OVsnmpVal data structure is a union of the possible data types for the variable. The OVsnmpVal data can be any of the Union Members listed in Table 3-13.

To see how the OVsnmpVal data structure relates to the OVsnmpVarBind data structure, see Figure 3-2.

Table 3-13 OVsnmpVarBind Union Members

Union Member For SNMP Type:

integer INTEGER

Octet string (array of 8-bit values) OctetString, IpAddr

object ID Object ID

unsigned 32-bit integers Counter32, Gauge32, Unsigned32, TimeTicks

unsigned 64-bit integers Counter64

Chapter 3 81


Chapter 382

4 The NNM Event Database API

Chapter 4 83

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

Chapter 484

The NNM Event Database APIThe NNM Event Database

The NNM Event DatabaseThe 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 file 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 configured as IGNORE in trapd.conf are not logged in the event database. OVEventDbOpenLogForReading(), OVEventDbReadNextEvent(), and OVEventDbGetOVsnmpPdu() can access data from this file 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 file group.

• Stream Log File Group is a series of four binary files that record the association of an event with an ECS event stream. OVEventDbOpenStreamForReading(), OVEventDbReadNextEvent(), and OVEventDbGetOVsnmpPdu() can access data from this file group.

• Correlation Log File Group is a series of four binary files 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 file group (see the OVEventdb API list below).

Chapter 4 85

The NNM Event Database APIThe NNM Event Database

There are two ways to get correlated events for a given event.

• Use OVEventDbFindCorrelatedEvents() and OVEventDbEventListGetNext() to retrieve a list of events, which are directly correlated to the parent event.

• Use OVEventDbGetCorrelationTree() and related API functions to recursively find all child events correlated to the parent event. Since each child event may have children, this operation involves a recursive descent. These events are stored in a list and returned in depth first order. The operation can be lengthy, because the entire correlation log must be searched to find the correlations.

Chapter 486

The NNM Event Database APIThe NNM Event Database API Functions

The NNM Event Database API FunctionsThe 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 Description

DATABASE ACCESS and QUERYING

OVEventDbOpenCorrLogforReading()Open the OpenViewEvent Database Correlation log file group for reading.

OVEventDbOpenLogforReading()Open the OpenView Event Database log file group for reading.

OVEventDbOpenStreamforReading()Open the OpenView Event Database stream log file group for reading.

OVEventDbReadNextCorrEntry()Retrieve the next correlation entry from the open database.

OVEventDbReadNextEvent()Reactivate the next event from the open database.

OVEventDbClose() Close the eventdb handle.

OVEventDbIsEventCorrelated() Determine if an event is correlated or not.

OVEventDbFindCorrelatedEvents()Find a list of events that are correlated with a particular event.

OVEventDbGetCorrelationTree()Recursively find all child events which are correlated under a particular event.

FREEING RESOURCES

OVEventDbFreeEvent()Free the resources associated with an OVeventHandle.

OVEventDbFreeCorrEntry()Free the resources associated with an OVcorrEntryHandle.

Chapter 4 87


OVEventDbFreeEventList()Free the resources associated with an OVeventListHandle.

OVEventDbFreeCorrEntryList()Free the resources associated with an OVcorrEntryListHandle.

OTHER DATA MANIPULATION

OVEventDbEventListGetNext()Iterate through an event list and return the next event handle in the list.

OVEventDbCorrEntryListGetNext()Iterate through a correlation entry list and return the next correlation entry in the list.

OVEventDbCorrEntryListGetNumElements()Return the number of elements in the list associated with the OVcorrEntryListHandle.

OVEventDbGetCorrEventStatus()Return the status of a correlated event associated with the OVcorrEntryHandle.

OVEventDbGetParentId()Return the eventId of the parent event associated with a OVcorrEntryHandle.

OVEventDbGetChildId()Return the eventId of the child event associated with an OVcorrEntryHandle.

OVEventDbGetNumChildren()Return the number of descendent events that are correlated below corrEntry.

OVEventDbGetChildEvent()Return an OVeventHandle that refers to the child event associated with an OVcorrEntryHandle.

OVEventDbGetTreeLevel()Return the number of ancestor events that are correlated above corrEntry.

OVEventDbGetOVsnmpPdu()Create an OVsnmpPdu from an event packet.

Table 4-1 NNM Event Database API Functions (Continued)


Chapter 488


OVEventDbEventIdtoUuid()Convert OVeventId into OVsnmpUuid format.

OVEventDbUuidToEventId()Convert OVsnmpUuid into OVevent format.

Table 4-1 NNM Event Database API Functions (Continued)


Chapter 4 89

The NNM Event Database APIMemory Management

Memory ManagementIf 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;

Chapter 490

5 The OVSNMP Configuration API

Chapter 5 91

The OVSNMP Configuration API

This chapter describes the functions and data structures in the HP OVSNMP Configuration API. It includes descriptions of the following:

• the OVSNMP Configuration database

• OVSNMP Configuration API functions

• key data structures in the OVSNMP Configuration API, including each element and its use

Chapter 592

The OVSNMP Configuration APIThe OVSNMP Configuration Database

The OVSNMP Configuration DatabaseThe OVSNMP configuration database is a repository on the management station for the configuration information that controls the behavior of an SNMP session. The configuration 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 Configuration API provides programmer access to the SNMP configuration database. Three classes of configuration parameters are stored in the database:

• parameters for specific managed nodes

• parameters for wildcarded IP addresses

• parameters for a global default

Whenever the configuration parameters for a managed node are requested, they are obtained from these three classes of stored information. The resulting parameters and the associated IP address of the destination can be cached, allowing subsequent lookups to be performed more quickly.

Chapter 5 93

The OVSNMP Configuration APIThe OVSNMP Configuration API Functions

The OVSNMP Configuration API FunctionsThe thirty-two functions in the OVSNMP Configuration API fall into five categories: database access, resolution, editing, administration, and miscellaneous.

Table 5-1 SNMP Configuration API Functions


DATABASE ACCESS

OVsnmpConfOpen() Open the SNMP configuration database for subsequent access.

OVsnmpConfClose() Close the SNMP configuration database.

OVsnmpConfDbName() Obtain the pathname of the SNMP configuration database.

OVsnmpConfFileName() Obtain the pathname of the backwards compatibility (shadow) file that is associated with the SNMP configuration database.

RESOLUTION

OVsnmpConfResolveDest() Obtain the effective configuration parameters for a specified destination agent.

OVsnmpConfFreeDest() Deallocate all memory associated with the OVsnmpConfDest structure returned by OVsnmpConfResolveDest(3).

EDITING

OVsnmpConfReadNextEntry() Sequentially read specific node records from the SNMP configuration database.

OVsnmpConfReadEntry() Read a specific node record from the SNMP configuration database.

OVsnmpConfCreateEntry() Create a new specific node record in the SNMP configuration database. This operation will fail if a record already exists for the specified node.

Chapter 594


OVsnmpConfStoreEntry() Create or replace, as necessary, a specific node record in the SNMP configuration database.

OVsnmpConfDeleteEntry() Delete a specific node record from the SNMP configuration database.

OVsnmpConfAllocEntry() Allocate an OVsnmpConfEntry structure.

OVsnmpConfCopyEntry() Allocate and initialize an OVsnmpConfEntry structure with the values from the specified OVsnmpConfEntry structure.

OVsnmpConfParseEntry() Allocate and initialize an OVsnmpConfEntry structure with the values extracted from a configuration string in the format of an ovsnmp.conf(4) configuration file entry.

OVsnmpConfFreeEntry() Deallocate all memory associated with the specified OVsnmpConfEntry structure.

OVsnmpConfReadWcList() Read the list of IP address wildcard records from the SNMP configuration database. Since the semantics of wildcard records are partly dependent upon the order of the records in the database, these records can only be updated as a single list.

OVsnmpConfStoreWcList() Create or replace, as necessary, the list of IP address wildcard records in the SNMP configuration database.

OVsnmpConfAllocWcLis() Allocate memory for an OVsnmpConfWcList structure. This structure may then be inserted into the wildcard list obtained using OVsnmpConfReadWcList(3).

OVsnmpConfFreeWcList() Deallocate all memory associated with the specified list of OVsnmpConfWcList structures.

OVsnmpConfReadDefault() Read the global default record from the SNMP configuration database.

OVsnmpConfStoreDefault() Create or replace, as necessary, the global default record in the SNMP configuration database.

Table 5-1 SNMP Configuration API Functions (Continued)


Chapter 5 95


OVsnmpConfGetVersions() Determine which SNMP protocol versions are supported by an agent by reading the SNMP configuration database.

OVsnmpConfSetVersions() Store or modify the field in the SNMP configuration database that indicates the SNMP protocol versions, which are supported by a particular agent.

OVsnmpConfImportFile() Replace the contents of the SNMP configuration database with records extracted from configuration strings in the specified ovsnmp.conf configuration file.

OvsnmpConfExportFile() Dump the contents of the SNMP configuration database to the specified ovsnmp.conf configuration file.

ADMINISTRATION

OVsnmpConfReadCntl() Read the current SNMP configuration database administration record. This record contains options which control run-time caching and use of the backward compatibility configuration file.

OVsnmpConfStoreCntl() Update the current SNMP configuration database administration record. This enables you to modify the options which control runtime caching and use of the backward compatibility file.

MISCELLANEOUS

OVsnmpConfDeleteCache() Remove all entries from the SNMP configuration run-time cache. New entries accumulate in the cache as applications call OVsnmpOpen() and OVsnmpConfResolveDest().

OVsnmpConfReadNextDest() Sequentially read entries from the SNMP configuration run-time cache. This function is provided for troubleshooting only (such as dumping the contents of the cache for inspection.)



Chapter 596


OVsnmpConfPrintDest() Print the contents of an OVsnmpConfDest structure to stdout on UNIX systems or to the console window on Windows operating systems.

OVsnmpConfPrintEntry() Print the contents of an OVsnmpConfEntry structure to stdout on UNIX systems or to the console window on Windows operating systems.

OVsnmpConfPrintCntl() Print the contents of an OVsnmpConfCntl structure to stdout on UNIX systems or to the console window on Windows operating systems.



Chapter 5 97

The OVSNMP Configuration APIData Structures for the OVSNMP Configuration API

Data Structures for the OVSNMP Configuration API This section describes key data structures, including their purposes and relationships. Specific details about other parameters to SNMP functions are available in the online reference pages.

Header Files

The header file defines many data structures that are part of the OVSNMP configuration API. The only header file required to use the OVSNMP configuration API functions is $OV_HEADER/OV/OVsnmpConf.h1. See Table 3-5 for a list of all header files included in the OVSNMP API.

Data Structures

Table 5-2 describes the key data structures that are used with the OVSNMP Configuration API.

1. See the reference page for ov.envvars for details on the environment variable $OV_HEADER.

Table 5-2 SNMP Configuration API Data Structures

Data Structure Description

OVsnmpConfEntry This structure contains the parameters that make up an SNMP configuration record for a particular destination in the managed environment. It is also used as a substructure in the OVsnmpConfWcList and OVsnmpConfDest structures.

OVsnmpConfWcList This structure forms an element of a linked list used to represent the IP address wildcard list.

Chapter 598


The OVsnmpConfEntry Structure

The OVsnmpConfEntry structure is the principal data structure used for SNMP configuration. This structure contains the parameters that make up the SNMP configuration record for a particular destination in the managed environment. When used alone or in the OVsnmpConfWcList structure with the configuration editing function, some of the fields may not be filled in; that is, they are assigned a value that indicates use default. In this case the actual configuration value is determined at runtime by the OVsnmpConfResolveDest() function as part of the OVsnmpConfDest structure.

The OVsnmpConfEntry structure has the fields shown in Table 5-3:

OVsnmpConfDest This structure contains the fully-resolved configuration parameters for a particular destination in the managed environment. Additionally, it contains addressing information which is determined at run time instead of being stored in the configuration database.

OVsnmpConfCntl This structure contains administrative options which control how run-time caching and the backward compatibility configuration file are used by the OVSNMP API.

Table 5-2 SNMP Configuration API Data Structures (Continued)

Data Structure Description

Table 5-3 OVsnmpConfEntry Structure

Type Name Description

char * name The name of the destination for which the configuration parameters apply. This may be an IP hostname, an IP address, an IP address wildcard, or a non-SNMP entity that is proxied for.

char * community 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 field is not specified.

Chapter 5 99


The OVsnmpConfWcList Structure

The OVsnmpConfWcList structure is used to create a linked list of OVsnmpConfEntry structures that represent the IP address wildcard configuration. 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 configuration values, it searches the IP address wildcard list in order to fill in those defaulted values.

char * setCommunity The SNMP community name, which is used by the management application when issuing SNMP Set requests to the destination.

char * proxy The identity of a proxy for the destination. This may be an IP hostname or an IP address. If the destination is accessed directly, this field contains the value of SNMP_CONF_DONT_PROXY_STRING.

int timeout 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.

int retry The maximum number of retransmissions the OVSNMP API will attempt before generating a no response condition for an SNMP request.

int pollInterval The frequency, in seconds, at which netmon determines the status of the destination node. This field is not used by the OVSNMP API.

u_short remotePort The UDP port number on the destination or proxy node (as appropriate) where the SNMP agent on that node expects to receive SNMP requests for the destination. The standard SNMP port is 161. This field is generally used only for specialized proxy agents which do not listen to the standard SNMP port.

Table 5-3 OVsnmpConfEntry Structure (Continued)


Chapter 5100


In Figure 5-1, the fields of the OVsnmpConfWcList structure are shown in order. Note that the configuration parameters are contained in an OVsnmpConfEntry structure pointed to by the confEntry field.

Figure 5-1 OVsnmpConfWcList Structure

Table 5-4 describes the fields in the OVsnmpConfWcList data structure:

* next

* confEntry

*name

* next

* confEntry

*community

*setCommunity

*proxy

timeout

retry

pollInterval

remotePort

*name

*community

*setCommunity

*proxy

timeout

retry

pollInterval

remotePort

OVsnmpConfWcList OVsnmpConfWcList

OVsnmpConfEntry OVsnmpConfEntry

NULL

Table 5-4 OVsnmpConfWcList Structure

Type Field Name Description

struct SNMPconfwclist *

next A pointer to the next OVsnmpConfWcList entry in the IP address wildcard list. The value for this field should be NULL for the last entry in the list.

OVsnmpConfEntry * confEntry A pointer to the OVsnmpConfEntry structure that contains the configuration parameters for the IP Address wildcard entry.

Chapter 5 101


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 configuration 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 configuration database. The values assigned to the OVsnmpConfEntry portion of this structure are obtained from a combination of specific node, IP address wildcards and global default configuration records to determine an actual configuration value for each field.

The OVsnmpConfDest structure is returned by a call to OVsnmpConfResolveDest() and should be deallocated by a call to OVsnmpConfFreeDest().

In Figure 5-2 the fields of the OVsnmpConfDest structure are shown in order. The configuration parameters are contained in an OVsnmpConfEntry structure pointed to by the confEntry field.

Figure 5-2 OVsnmpConfDest Data Structure

*confEntry

isProxied

ipAddr*name

*community

*setCommunity

*proxy

timeout

retry

pollInterval

remotePort

ipAddrAge

agent name

agentAddr

OVsnmpConfDest

OVsnmpConfEntry

Chapter 5102


Table 5-5 describes the fields in the OVsnmpConfDest data structure.

Table 5-5 OVsnmpConfDest Data Structure

Type Field Name Description

OVsnmpConfEntry * confEntry A pointer to the OVsnmpConfEntry structure which contains the fully-resolved configuration parameters for the specified destination.

short isProxied A boolean flag indicating whether or not the IP address for this destination is that of the actual destination (FALSE) or that of a proxy node (TRUE).

struct sockaddr* agentAddr Pointer to the address of the SNMP agent for this destination. Supported address families are AF-INET and AF-IPX. By default, only AF_INET (udp/ip) destinations are returned. The SNMP_CONF_RESOLVE.ANYADDR flag must be specified as input to OVsnmpConfResolveDest() in order for both IP and IPX destinations to be returned. This is done for compatibility of existing IP-only applications.

u_long ipAddr The IP address of the peer entity to which SNMP requests should be sent for the specified destination. This field has been replaced by agentAddr. It is retained for backwards compatibility of existing applications. For IP agents, this value is the same as (sockaddr_in*)agentAddr→ sin_addr.s_addr. For IPX agents, this value is zero.

time_t ipAddrAge The date and time when the ipAddr field was last queried from the IP address name server. This value is obtained from time().

char * agentName The fully distinguished name of the nex_hop agent associated with the destination target.

Chapter 5 103


The OVsnmpConfCntl Structure

The OVsnmpConfCntl structure contains administrative options which control how run-time caching and the backward compatibility configuration file is used by the OVSNMP API. Its fields are shown in Table 5-6.

Cache Flags

The cache flag in the OVsnmpConfCntl structure may be set to one of the following:

• SNMP_CONF_CACHE_NONE

Run-time caching of SNMP configuration parameters and IP addresses is disabled. The information is recomputed each time a destination is referenced.

Table 5-6 OVsnmpConfCntl Structure


int ipAddrAge The age limit, in seconds, for IP address stored in the SNMP configuration run-time cache. This value is used by OVsnmpConfResolveDest() to determine when a cached IP address must be updated by consulting the system’s IP address name server.

cacheFlags_t cacheFlags The level of run-time cache enabled for the SNMP configuration database. By default, resolved configuration parameters and the IP address of previously referenced destinations are cached. This improves the performance of applications when the same destination is subsequently referenced.

compat3_2_t compatFlags The level of backward compatibility for SNMP Platform Release 3.2 that is enabled for the SNMP configuration database. This compatibility mode is disabled by default beginning with NNM Release 5.0.

Chapter 5104


• SNMP_CONF_CACHE_NOADDR

SNMP configuration parameters for previously referenced destinations are maintained in the SNMP configuration run-time cache. However, the IP address of those destinations is not maintained in the cache. The IP address is determined each time the destination is referenced by consulting the IP address name server.

• SNMP_CONF_CACHE_ALL

Both SNMP configuration parameters and the IP address of previously referenced destinations are maintained in the SNMP configuration run-time cache.

Compatibility Flags

The compatibility flag in the OVsnmpConfCntl structure may be set to one of the following:

• SNMP_CONF_SHADOW_NONE

The configuration file for release 3.2 backward compatibility is not maintained. This mode of operation should only be used if all OVSNMP API-based applications installed and running on the system have been linked with a later release of the OVSNMP API.

• SNMP_CONF_SHADOW_32ONLY

Only the subset of entries in the SNMP configuration database, which are configured to use the default SNMP port for communications, are maintained in the backward compatibility file. This will optimize performance of Release 3.2-based applications. However, if the xnmsnmpconf -import command is subsequently used with the resulting shadow file, some information in the SNMP configuration database will be lost.

• SNMP_CONF_SHADOW_ALL

All entries in the SNMP configuration database are maintained in the Release 3.2-compatible configuration file. This mode of operation ensures absolute consistency between the SNMP configuration database and the compatibility configuration file. However, this mode may cause unnecessary performance degradation of Release 3.2-based applications if there are many proxy entries which use a non-default SNMP port configured in the SNMP configuration database.

Chapter 5 105


Chapter 5106

6 Integrating with Logging and Tracing

Chapter 6 107

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 file. For example, an agent might enter a log message when a particular value is set. A key attribute of each incident is its severity, which is one of four levels ranging from INFORMATIVE to DISASTER.

Tracing, on the other hand, is used to trace step-by-step the execution of your program. For example, trace messages are typically written at the entry and exit points of each function.

Chapter 6108

Integrating with Logging and TracingOverview of Logging and Tracing

Overview of Logging and Tracing

HP-UX, Solaris, and Linux

Logging and tracing have different objectives:

Logging Logging is generally provided for the benefit 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 configure, filter, 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 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 files is typically understood only by the developer, or by trained field 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.

The OVuTL API is provided to let you integrate your application with the common logging and tracing facility called nettl. This facility uses daemon processes to receive log and trace data from network applications (including the platform itself), and to direct that data to its appropriate destination.

For more information about the nettl subsystem, see the nettl (1M) manpage, as well as other manpages to which it refers.

Chapter 6 109

Integrating with Logging and TracingOverview 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 filter 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

Chapter 6110

Integrating with Logging and TracingThe OVuTL Application Programming Interface

The OVuTL Application Programming InterfaceThere are three functions in the OVuTL API:

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.

Table 6-1 Functions in the OVuTL API


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

OVuLog() Enters a log message in the log file. By default this is $NETFMT_LOG_FILE (HP-UX, Solaris, and Linux) or Event Viewer (Windows).

OVuTrace() Enters a trace message in the trace file. By default this is $NETFMT_TRC_FILE (HP-UX, Solaris, and Linux) or Event Viewer (Windows).

Chapter 6 111

Integrating with Logging and TracingThe OVuTL Application Programming Interface

Chapter 6112

7 Integrating with Process Management

Chapter 7 113

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 find when it “wakes up,” and to control other related aspects of your interaction with NNM.

This chapter covers

• a brief overview of process management in the HP OpenView platforms

• the OVsPMD application programming interface (OVsPMD API)

• guidelines for constructing the first and second lines of a Local Registration File

• guidelines for integrating your application with NNM’s automated backup

NOTE The Local Registration File (LRF) is an important file for your process. This chapter discusses only the first and second line of that file, since these lines pertain to process management. Any additional lines in this file are not relevant to Network Node Manager.

Chapter 7114

Integrating with Process ManagementProcess Management for HP OpenView Applications

Process Management for HP OpenView ApplicationsFrom 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 NNM’s databases, log files, and configuration files 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” file, or SUF. The SUF is constructed by the ovaddobj command, which adds startup information each time it is run, based on the Local Registration File that it reads.

Chapter 7 115


NOTE On Windows operating systems, ovspmd is a “service.” Refer to your Windows operating system documentation for details on services.

Figure 7-1 Process Management

Figure 7-1 illustrates how the ovspmd process operates. Note that the diagram shows three kinds of processes:

Well-behaved Processes

A well-behaved process uses the OVsPMD API — the topic of the next section — to communicate with ovspmd. It sends ovspmd status information regarding successful and unsuccessful initialization, normal and abnormal termination, and pause and resume information if configured to do so. ovspmd considers a “well-behaved” process to have initialized successfully only when it explicitly reports that it has. A “well-behaved” process also exits when it receives the command OVS_CMD_EXIT from ovspmd. If the process fails to respond, the exit command is escalated to

Administrative Commands:

ovstart, ovstop, ovpause,ovresume,ovstatus

Responses

Requests

LRF ovaddobjcommand

ovsuf

ovsnmpdTracing &LoggingSubsystem

Well-behavedProcess

Well-behavedProcess

Non-well-behavedProcess

DaemonProcess

Chapter 7116


SIGTERM, and eventually to SIGKILL. It will respond to OVS_CMD_PAUSE and OVS_CMD_RESUME commands if it is configured to receive them.

The status information passed by the managed process to ovspmd is used by ovstart, ovstop, ovstatus, ovpause or ovresume, if currently running. The last message received from each managed process is saved, and forwarded, on request, to ovstatus. The messages received from “well-behaved” processes are also logged using the nettl logging and tracing facility.

Non-well-behaved Process

ovspmd can also manage object managers that do not use the OVsPMD API (“non-well-behaved” processes) only if they do not go into the background of their own accord (see OVs_DAEMON which follows). Since a “non-well-behaved” process returns no status messages, ovspmd considers such processes to have initialized successfully if the process has not exited within the lrf specified timeout interval.

During shutdown, the ovspmd process sends SIGTERM to non-well- behaved processes to notify them of the need to terminate. Non-well-behaved processes that fail to terminate within the configured timeout are sent SIGKILL.

Daemon Process

Managed processes that go into the background cannot be managed either with a communication channel or with signals. ovspmd can start such a process, but cannot stop or report meaningful status about it, since it has neither a communication channel nor a process ID for it.

However, you can run a script or program to stop the daemon. Refer to “Field 7: Daemon Stop Command” on page 126.

You need to decide which type of process to create.

1. If you are writing a new program, you will probably want to use the OVsPMD API and create a well-behaved process. This is by far the best choice.

Chapter 7 117


2. If you have an existing process that does not go into the background, you can decide to not modify it, and declare it a non-well-behaved process. This may be expedient, but it is less than ideal. It would be better to take a little time to incorporate simple calls to the OVsPMD API and create a well-behaved process.

3. If you have an existing process that does go into the background, you can decide to not modify it, and declare it a daemon process. This too may be expedient, but results in a poorly integrated process.

4. If you want your process to receive pause and resume notification, your process must be well-behaved.

To decide what to do, you may want to understand something about the OVsPMD API, the topic of the next section.

Chapter 7118

Integrating with Process ManagementThe OVsPMD Application Programming Interface

The OVsPMD Application Programming InterfaceTo create a well-behaved process, you need to use the OVsPMD API, which has these functions:

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 complete—and regardless of whether it was successful or not—you 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()).

Table 7-1 Functions in the OVsPMD API


OVsInit() Indicates that the process is beginning its initialization phase. Returns a file descriptor (communication channel) for communicating with ovspmd.

OVsInitComplete() Indicates that the process has finished its initialization phase.

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

OVsDone() Informs ovspmd that the process is terminating normally. One parameter is a text message used to indicate the reason for termination.

OVsResponse() Responds to pause and resume commands issued by ovspmd.

Chapter 7 119

Integrating with Process ManagementThe OVsPMD Application Programming Interface

3. Your process’s control thread should be organized around a select() loop, waiting for input from managers or from the managed object. Select for reading on the file descriptor returned by OVsInit().

4. When select() indicates the ovspmd file descriptor is readable, use OVsReceive() to get the command from ovspmd. OVS_CMD_EXIT means your process should “clean up”, call OVsDone(), and exit. OVS_CMD_PAUSE means your process should suspend data processing. OVS_CMD_RESUME means your process can resume data processing.

5. If your process exits on its own initiative (that is, without instructions from ovspmd), call OVsDone(), indicating in the message parameter the reason for termination. This message will be logged by ovspmd along with other exit information.

6. Never go into the background (fork and exit in the parent); the child process cannot be managed by ovspmd.

Chapter 7120

Integrating with Process ManagementThe Local Registration File

The Local Registration FileEach process must have an associated Local Registration File, or LRF. The LRF is a specially formatted ASCII file 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 first 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 first 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 Description

First Specifies the process name, and the pathname of its executable file.

Second Specifies process management information, which is described next.

Chapter 7 121


General Syntax

Each line in an LRF contains two or more fields. Each field is terminated by a colon, including the last field. Some fields are optional; it is recommended that you still include the colon terminator for the missing fields.

The number symbol (#) indicates the beginning of a comment, which continues to the end of the line. White space (spaces, tab characters, and newlines) is not permitted within any field, nor are any multibyte characters. In the first two lines of the LRF, only printable ASCII characters are allowed (values between decimal 32 and 126). The colon (:), comma (,), backslash (\), and number sign (#) can only appear as terminator characters, as noted above and in later syntax descriptions.

NOTE You must put a backslash in front of the colon that specifies the drive specification on the Windows operating systems. This prevents the colon in the path from being interpreted as a field terminator.

First Line of the LRF

The first line of the LRF specifies the name and location of the process:

Field 1: Name

Specifies the name of the process being registered. You are responsible for ensuring the uniqueness of the process name.

For example, you could append your company’s name:

IPMgr_A.017.0_MegaCorp_International

Table 7-3 First Line of the LRF

Field Syntax Default

1: Name A character string for the process name.

None (must be specified).

2: Path A character string. None (must be specified).

Chapter 7122


The name must be the same name used in the session parameter to the mp_bind() function call, and is the name used when invoking ovstart, ovstop, ovstatus, and ovisrunning.

Field 2: Path

Specifies the location of the process executable code. Specify the full (absolute) pathname. If you have set up universal path names, you can specify the partial pathname relative to the path install_dir\BIN or $OV_BIN. Note that if a directory is not specified for the executable, install_dir\BIN or $OV_BIN is assumed.

NOTE You must put a backslash in front of the colon that specifies the drive specification on Windows operating systems. This prevents the colon in the path from being interpreted as a field terminator. For example,

IPMgr_A.017.0_MegaCorp_International:C\:install_dir\bin\netmon:

LRF Line One Example

Following are examples of the first line of a hypothetical LRF on HP-UX, Solaris, or Linux. The process executable is located in $OV_BIN/MEGA/ip_mgr.

IPMgr_A.017.0_MegaCorp_International:MEGA/ip_mgr:

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

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

The following is an example of the first line of a hypothetical LRF on Windows. The process executable is located in C:install_dir\bin\MEGA\ip_mgr.

IPMgr_A.017.0_MegaCorp_International:C\:install_dir\bin\MEGA\ip_mgr:

Second Line of the Local Registration File

The second line of the LRF specifies process management options.

Chapter 7 123


There are seven fields in the second line of the LRF. Each field is terminated by a colon (:). The following Table 7-4 describes each field in turn. Following the table is a complete description of each field.

Field 1: Initial Start Flag

This flag indicates whether or not the process is to be launched when the ovstart command is issued without arguments. Possible values for this field: OVs_YES_START and OVs_NO_START.

• The OVs_YES_START flag means the process will be started by the ovstart command.

• The OVs_NO_START flag means the process will not be started by the ovstart command.

Processes that use OVs_NO_START must be explicitly started by name (for example, ovstart process_name).

Table 7-4 Second Line of the LRF&

Field Syntax Default

1: Initial Start Flag

A character string; optional.

OVs_NO_START

2: Dependencies A series of character strings, separated by commas; optional.

None (that is, can be started at any time).

3: Arguments A series of character strings, separated by commas; optional.

None (no arguments required).

4: Behavior A character string; optional.

OVs_NON_WELL_BEHAVED

5: Timeout An integer; optional. 5 seconds.

6: Pause A character string; optional.

NOPAUSE

7: Daemon Stop A character string; optional

Empty string

Chapter 7124


Field 2: Dependencies

This is a list of process names, separated by commas, that must already be running before your process can be started. ovspmd uses this information to determine the order in which to start processes. Use the names as they appear in the “Name” field of the pertinent LRFs.

Field 3: Arguments

The arguments specified in this field are passed to the process as it starts up, just as if a user had passed them from the command line. Commas or blanks can be used to separate multiple arguments in this field. For example, suppose the arguments field had this entry— “-i,-b,amazon:”. This would be equivalent to “-i -b amazon” on the command line.

Field 4: Behavior

This field specifies how the process will interact with ovspmd. Processes can be “well-behaved,” “non-well-behaved,” or “daemons,” as described earlier. Possible values for this field: OVs_WELL_BEHAVED, OVs_NON_WELL_BEHAVED, and OVs_DAEMON.

Field 5: Timeout

For “well-behaved” processes, this field is used to manage evident startup failures. There are two cases:

• Your process invokes OVsInitComplete() and returns OVS_RSP_FAILURE in the status code parameter, but fails to terminate before the timeout expires.

• Your process invokes OVsDone(), but fails to terminate before the timeout expires.

In either case, ovspmd terminates the process, sending it SIGTERM and if necessary, SIGKILL.

If your process is either “non-well-behaved,” or a “daemon,” ovspmd waits until the timeout expires before starting any process that lists your process in its “Dependencies” field. Also, after ovspmd sends your process SIGTERM, it waits until the timeout expires before sending it a SIGKILL signal.

Chapter 7 125


This field is also used as the PAUSE timeout. It specifies the amount of time a process has to respond to an OVS_CMD_PAUSE. If the process does not respond in time, the pause operation fails.

For “well-behaved” processes with Field 6 set to PAUSE, the timeout field is also used to manage a failure to respond to an OVs_CMD_PAUSE. A failure to respond within the timeout is processed as a PAUSE NACK.

Field 6: Pause

For “well-behaved” processes, this field is used to register for pause and resume messages. Possible values for this field include: PAUSE and NOPAUSE. The default is NOPAUSE: specifying NOPAUSE or leaving the field blank prevents ovspmd from sending pause and resume messages to your process.

A process that is dependent on one or more NNM processes must accurately specify these dependencies in its LRF to ensure that it is paused before and resumed after all processes on which it is dependent. For more information about backup refer to “Integration with NNM Automated Backup” on page 127.

Field 7: Daemon Stop Command

This field can be used only for OVS daemon processes. It follows the same rules as the PATH field in the first line. It identifies a command (script or executable) that is to be run to stop the OVS daemon process. It may contain optional parameters. If a specific path is not specified, \install_dir\BIN (Windows) or $OV_BIN (UNIX) is assumed. The command should return 0 for success; anything else for failure.

LRF Line Two Example

The following is an example of the second line of a hypothetical LRF:

OVs_YES_START:pmd,ovead:-v,-n:OVs_WELL_BEHAVED:15:NOPAUSE::

Chapter 7126

Integrating with Process ManagementIntegration with NNM Automated Backup

Integration with NNM Automated BackupThis section provides information about automated backup’s 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 benefits.

Chapter 7 127


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 first; 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

Chapter 7128


Figure 7-2 Backup

To guarantee the synchronization of the operational data, ovbackup.ovpl uses ovpause to issue a pause that is sent to every ovspmd process that has registered to receive pause notifications. (Refer to the ovspmd reference page for details.) After all processes have paused, ovbackup.ovpl creates a data snapshot by running any script found in the $OV_CONF/ovbackup/checkpoint/operational directory. Because all processes are paused when the snapshot is created, all data contained in the snapshot is guaranteed to be synchronized. As soon as the snapshot is created, ovresume is called, and all processes are released from the paused state.

Data Copy Stage

initiate backup

pause processes

copyoperational data to staging area

resume processes

copyanalytical data to staging area

copy data topermanent archive

copy data from permanent archive

Data Archive Stage

Data Restore Stage

Operational Phase

Analytical Phase

Chapter 7 129


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 benefit to integrating at all.

Chapter 7130


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 application’s behavior sensitive to the OVwEventSource parameter in the ovwMapClose callback. It is a way for an application to optimize its behavior by eliminating those actions that are necessary for responding to a real map close but not for responding to a paused system. This is what applications must do to receive PAUSE notification.

• Background process integration (integrating via services) is done by modifying a background process to receive and handle pause and resume notification. It is a way for a background process to change its behavior during backup or to act as a proxy to inform other processes of the paused state of the system so that those processes can change their behavior. This is how background processes or proxies receive PAUSE notification.

Evaluating An Application

To make it easy to integrate with automated backup this section provides the information to help you determine which means of integrating are relevant to your application. Then, you can focus on those sections of the documentation which provide the integration information needed by your application, while skipping the other sections.

For each decision tree, answer the question in the diamonds based on what you know about the internals of your application.

When you reach the end of each decision tree you will know if that form of integration is relevant to your application. The sections referenced at the end points of the decision trees are the parts of the documentation which provide additional information about how to integrate. Note that the three means of integrating are not mutually exclusive. For a particular application one, two, or all three may be appropriate.

Chapter 7 131


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 application’s data. The script may be integrated into the operational or analytical directory, depending on the relationship of the application’s data to the NNM operational data. If this applies to your application, refer to “Writing Backup Scripts” on page 135.

Figure 7-3 Decision Tree for Script Integration

Integration Via ovwMapClose Event

This type of integration applies to applications that use the OVw API and register with OVW via an application registration file.

ovwMapClose integration is done by making an application’s 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 application’s behavior when the value of the OVwEventSource indicates that the event

Does the application have its own data store?

Investigate script integration for the application. See Writing Backup Scripts.

There is no need for the application to provide scripts.NO

YES

Chapter 7132


triggering the callback is a pause rather than an actual map close. If this applies to your application, refer to “Integration via ovwMapClose” on page 137.

Figure 7-4 Decision Tree for ovwMapClose Event Integration

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.

Does the application register for the ovwMapClose event?

Consider ovwMapClose integration. See Integration Via ovwMapClose.

ovwMapClose integration is not relevant to the application.NO

YES

Chapter 7 133


Background process integration consists of 1) registering to receive pause and resume notification from ovspmd when backup takes place and 2) implementing the pause behavior that is appropriate for the background process. If this applies to your application, refer to “Integrating via Services (Background Processes)” on page 138.

Figure 7-5 Decision Tree for Background Process Integration

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

Does that background process have dependencies on other NNM background processes?

Does the background process access the application’s data store?NO

NO

NO

YESYES

YES

Background process integration does not apply.

Consider background process integration. See Integrating Via Services.

Chapter 7134


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

The four script points include:

Data Copy Stage

initiate backup




initiate restore

Data Archive Stage

Data Restore Stage

Ope

ratio

nal

Pha

seA

naly

tical

P

hase

pause system

resume system restore

operational data

restoreanalytical data

analyticalscripts

post-resumescripts

operationalscripts

pre-pausescripts

ovbackup.ovplruns:

administratorruns restorescript

Chapter 7 135


• 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 NNM’s 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 NNM’s 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.

Chapter 7136


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 notification 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. Specifically, 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 137


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

Integrating via Services (Background Processes)

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

Data Copy Stage

initiate backup



pause system

resume system

Integrating Application


initiate restore

Data Archive Stage

Data Restore Stage

restoreoperational data

restoreanalytical data

Resume communicationwith NNM

Placeapplication inappropriate state

Acknowledgeand respond

ovwMapOpen

ovwMapClose

ovwAckMapClose

Chapter 7138


it is dependent. For more information on well-behaved processes and how to use the LRF, refer to See “The Local Registration File” on page 121 and to the lrf (4) reference page.

To integrate with backup you must specify PAUSE in Field 6 of the LRF so that pause and resume messages will be sent to your service.

As Figure 7-8 shows, when ovbackup.ovpl executes ovpause, ovspmd sends notification (OVS_CMD_PAUSE) to all registered services. When your service receives this notification, it should stop all operations, flush data to disk if necessary, and acknowledge the pause request with OVsResponse(OVW_RSP_PAUSE_ACK, "Paused"). If your service cannot stop operations, the proper response is OVsResponse(OVW_RSP_PAUSE_NACK,"Text"). The text, which is sent to ovpause, should describe the reason for the negative acknowledgment.

Figure 7-8 Backup via Background Services

Data Copy Stage

initiate backup

pause processes


resume processes


well-behavedprocess

well-behavedprocess

OVS_CMD_PAUSE

OVS_RSP_PAUSE_ACK

OVS_CMD_RESUME

OVS_RSP_RESUME_ACK

Chapter 7 139


After NNM completes the dependent phase of its backup process, ovspmd sends notification (OVS_CMD_RESUME) to registered services. Your service should acknowledge the resume message using OVsResponse(OVS_RSP_RESUME_ACK "text").

If your service cannot resume operations, use OVsResponse(OVS_RSP_RESUME_NACK "text")

Care should be taken when choosing a timeout value for your process. If the timeout duration is too short, your process may cause the ovpause command to fail (and therefore cause ovbackup.ovpl to fail). If it is too long, the system could take too long to report a valid error with your process. Some of the ovw processes will have been paused already, and the user will be unable to interact with these subsystems. Remember that the timeout value is specified in seconds. Also keep in mind that some users may have slow machines.

Chapter 7140

Index

Aagent, 27agents

daemon, 117, 125non-well-behaved, 125well-behaved, 116

API architecture, 23applications

SNMPv2 style, 69ASN.1, 37, 76, 79

data representation, 37data types, 37

Bbackground, sending your process into, 120bilingual communication mode, 47BITS, 37blocking mode, 29, 55

Ccache flags, in OVsnmpConfCntl, 104callback

function, 73parameters, 73

ccitt(0), 35communications APIs

for communications, 58for manual retransmission, 58for message setup/management, 58for session management, 58in SNMP library, 58

communications modelagent process, 27manager process, 27SNMP, 27

compatibility flags, in OVsnmpConfCntl, 105compiling and linking, 66configuration API, 93

data structures, 98header files, 98

connectionless operation, 28conventions

typographical, 15correlated events

receiving, 53Correlation Log File Group, 85Counter, 37Counter32, 37Counter64, 37

Ddata structures, 66, 70, 98

memory management, 64data types

ASN.1, 37dot notation, 36

Eenterprise-specific MIB, 37environment variables

OV_HEADER, 67error codes, 48error values

macro for mapping, 69Event Log File Group, 85extended MIB, 37

Ffile descriptor for a session, 71flags, 104, 105foreign device

definition, 28

GGauge, 37Gauge32, 37Get Bulk Request, 32Get Next Request, 31Get Request, 31Get Response, 31

Hheader files, 67, 98

Iinclude files, 67, 98inform message, 30Inform Request, 32installing the SDK, 21INTEGER, 37Integer32, 37integration

with logging, 109with process management, 115with tracing, 109

interface behavior, 47IPAddress, 37IPX protocol, 52iso(1), 35

141

Index

Jjoint-iso-ccitt(2), 35

Llinking, with library, 66location transparency and proxies, 39logging

and OVuTL API, 109description of, 109severity levels, 109

LRF, 115agent name and location, 122and ovstart, ovstop, ovstatus, and

mp_bind(), 123and Process Management, 121contents of, 121general syntax, 122line 1 syntax, 122line 2 syntax, 124mandatory, 24

MManagement Information Base, 33manager, 27manual retransmission communications

APIs, 58memory management, 63message setup/management

communications APIs, 58MIB

enterprise-specific, 37extended, 37

MIB-II, 33MIB-II object definition

OID, 35

Nnaming tree, 35

ccitt(0), 35iso(1), 35joint-iso-ccitt(2), 35

NDBM Offset File Group, 85nettl, 109NetworkAddress, 37non-blocking mode, 29, 55notifications, 27, 30NT. See Windows

OOBJECT IDENTIFIER, 37object identifier, 35, 36OCTET STRING, 37OID, 35, 36OID, dot notation, 36OV_HEADER, 67ovaddobj, and SUF, 115OVEventDb API, 85OVEventDbClose, 87OVEventDbCorrEntryListGetNext, 88OVEventDbCorrEntryListGetNumElements

, 88OVEventDbEventIdtoUuid, 89OVEventDbEventListGetNext, 86, 88OVEventDbFindCorrelatedEvents, 86, 87OVEventDbFreeCorrEntry, 87OVEventDbFreeCorrEntryList, 88OVEventDbFreeEvent, 87OVEventDbFreeEventList, 88OVEventDbGetChildEvent, 88OVEventDbGetChildId, 88OVEventDbGetCorrelationTree, 86, 87OVEventDbGetCorrEventStatus, 88OVEventDbGetNumChildren, 88OVEventDbGetOVsnmpPdu, 88OVEventDbGetParentId, 88OVEventDbGetTreeLevel, 88OVEventDbIsEventCorrelated, 87OVEventDbOpenCorrLogforReading, 87OVEventDbOpenLogforReading, 87OVEventDbOpenStreamforReading, 87OVEventDbReadNextCorrEntry, 87OVEventDbReadNextEvent, 87OVEventDbUuidToEventId, 89OVsDone(), 119OVsInit(), 119OVsInitComplete(), 119OVSNMP API, 21

enhanced error codes, 49IPX support, 52memory management, 63multitransport interface, 52on Windows, 57protocol support, 45, 50protocol translations, 47

OVSNMP API, architecture, 23OVSNMP configuration API, 93

functions, 94OVsnmpAddNullVarBind, 58OVsnmpAddTypedVarBind, 58OVsnmpBlockingSend, 58

142

Index

OVsnmpCallback, 58OVsnmpCancel, 58OVsnmpClose, 58OVsnmpConfCntl structure

cache flags, 104compatibility flags, 105description of, 104

OVsnmpConfDest structure, 102OVsnmpConfEntry structure, 99OVsnmpConfWcList structure, 100OVsnmpCopyPdu, 58OVsnmpCreatePdu, 58OVsnmpErrString, 58OVsnmpEventOpen, 58OVsnmpFixPdu, 58OVsnmpFreePdu, 58OVsnmpGetRetryInfo, 58OVsnmpOpen, 52, 58OVsnmpPdu, 75, 79, 100, 102OVsnmpPdu structure, 54, 70, 75, 79OVsnmpRead, 58OVsnmpRecv, 58, 73OVsnmpSend, 58OVsnmpSession structure, 56, 71OVsnmpTrapOpen, 58OVsnmpVal, 70, 81OVsnmpVarBind, 70OVsnmpVarBind structure, 76, 79OVsnmpWEventOpen, 58OVsnmpWOpen, 58OVsnmpXCancel, 58OVsnmpXClose, 58OVsnmpXEventOpen, 58OVsnmpXOpen, 58OVsnmpXSend, 58OVsnmpXTrapOpen, 58ovspmd

diagram, 115process management daemon, 115

OVsPMD APIfunctions in, 119rules for use, 119

OVsReceive(), 119ovstart, 115ovstatus, 115ovstop, 115ovtrapd

on UNIX, 30on Windows, 30

OVuint64Add, 58OVuint64AddUInt32, 58OVuint64Assign, 58OVuint64Cmp, 58

OVuint64CmpUInt32, 58OVuint64Divide, 58OVuint64DivideUInt32, 58OVuint64FromStr, 58OVuint64Multiply, 58OVuint64MultiplyUInt32, 58OVuint64Shift, 58OVuint64Subtract, 58OVuint64SubtractUInt32, 58OVuint64ToStr, 58OVuLog(), 111OVuTL API

functions of, 111tracing and logging, 109

OVuTrace(), 111

PPDU

description of, 28trap, 76, 79

process management, 115ovspmd, 115OVsPMD API, 119ovstart, 115ovstatus, 115ovstop, 115

protocol support, 45protocols

SNMP, 31proxy

and location transparency, 39description of, 28

Rreferences to other documents, 40retransmission communications APIs, 58retransmissions, 55, 57RFC list, 40

Sselect(), 120select(2), 71session management communications APIs,

58session, sequence of communication, 29Set Request, 31SMI, 33

SNMPv1, 33SNMP

operations, 31

143

Index

SNMP Configuration APIdata structures, 98functions in, 94header files, 98

SNMP library, communications API functions in, 58

SNMP sessionsequence of actions, 29

SNMP_STD2OV_ERR, 58SNMPv1

operations, 31SNMPv1 protocol, 31, 45SNMPv2

operations, 32SNMPv2 Trap Request, 32SNMPv2C protocol, 31, 45Software Development Kit, 21startup file (SUF), 115Stream Log File Group, 85Structure of Management Information, 33structures, 98, 104

OVsnmpConfDest, 102OVsnmpConfEntry, 99OVsnmpConfWcList, 100OVsnmpPdu, 54, 75, 79OVsnmpSession, 71OVsnmpVarBind, 76, 79

TTimeticks, 37tracing

and OVuTL API, 109description of, 109

trap PDU, 76, 79Trap Request, 31trapd, 30traps, 27, 30, 76, 79

communication sequence, 30

UUDP, 28, 52User Datagram Protocol/Internet Protocol,

29

WWin32 message loop, 57Windows

IPX support, 52ported application support, 52traps, 30

WinSNMP API, 22

XX11 event loop, 57

144

Documents

Nnm751 Snmp Dev PDF