Compaq AAR04BCTE User Manual

CompaqTCP/IPServicesfor OpenVMS

SNMPProgramming and Reference

Order Number: AA–R04BC–TE

January 2001

Revision/Update Information: This manual supersedes the DIGITAL

TCP/IP Services for OpenVMS eSNMP Programming and Reference, Version

5.0.

Software Version: Compaq TCP/IP Services for OpenVMS

Version 5.1

Operating Systems: OpenVMS Alpha Versions 7.1, 7.2-1

OpenVMS VAX Versions 7.1, 7.2

Compaq Computer Corporation Houston, Texas

© 2001 Compaq Computer Corporation COMPAQ, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Ofﬁce. OpenVMS and Tru64 are trademarks of Compaq Information Technologies Group, L.P. in the United

States and other countries. All other product names mentioned herein may be trademarks of their respective companies. Conﬁdential computer software. Valid license from Compaq 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.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK6530

This document is available on CD-ROM.

This document was prepared using DECdocument, Version 3.3-1b.

Preface ............................................................ vii

1 Overview

1.1 SNMP Architecture . . ........................................ 1–1

1.2 Request Handling . . . ........................................ 1–2

1.3 TCP/IP Services Components for SNMP . . . ....................... 1–4

1.4 Writing an eSNMP Subagent . . . ................................ 1–5

1.5 The eSNMP API............................................. 1–6

1.5.1 The SNMP Utilities ....................................... 1–7

1.6 The MIB Compiler . . . ........................................ 1–7

1.7 SNMP Versions ............................................. 1–8

1.7.1 Using Existing (SNMP Version 1) MIB Modules . . ............... 1–8

1.8 For More Information ........................................ 1–9

2 MIBs Provided with TCP/IP Services

2.1 Overview of the Host Resources MIB ............................. 2–1

2.1.1 Deﬁning Host Resources MIB Implemented Objects .............. 2–1

2.1.2 Restrictions to Host Resources MIB ........................... 2–3

2.2 Overview of MIB II . . ........................................ 2–5

2.2.1 MIB II Implemented Groups ................................ 2–6

2.2.2 Restrictions to MIB II Implementation . ....................... 2–6

3 Creating a Subagent Using the eSNMP API

3.1 Creating a MIB Speciﬁcation . . . ................................ 3–1

3.2 The Structure of Management Information . ....................... 3–1

3.2.1 Assigning Object Identiﬁcation Codes . . ....................... 3–2

3.2.2 MIB Subtrees ............................................ 3–2

3.3 Creating a MIB Source File .................................... 3–5

3.3.1 Writing the ASN.1 Input File ................................ 3–5

3.3.2 Processing the Input File with the MIB Compiler . ............... 3–5

3.3.2.1 UNIX Utilities Supplied with TCP/IP Services ............... 3–7

3.3.2.2 Object Tables . ........................................ 3–7

3.3.2.3 The subtree_TBL.H Output File ........................... 3–7

3.3.2.4 The subtree_TBL.C Output Files . . . ....................... 3–9

3.4 Including the Routines and Building the Subagent . . . ............... 3–11

3.5 Including Extension Subagents in the Startup and Shutdown

Procedures . ................................................ 3–12

iii

4 Using the SNMP Utilities

4.1 Using the MIB Browser ....................................... 4–1

4.1.1 MIB Browser Parameters. . . ................................ 4–1

4.1.2 MIB Browser Flags ....................................... 4–2

4.1.3 MIB Browser Data Types . . . ................................ 4–5

4.1.4 Command Examples for snmp_request . ....................... 4–6

4.2 Using the Trap Sender and Trap Receiver Programs . . ............... 4–8

4.2.1 Entering Commands for the Trap Sender Program ............... 4–9

4.2.1.1 Trap Sender Parameters ................................ 4–9

4.2.1.2 Trap Sender Flags ..................................... 4–10

4.2.1.3 Trap Sender Examples . . ................................ 4–11

4.2.2 Entering Commands for the Trap Receiver Program .............. 4–12

4.2.2.1 Trap Receiver Flags .................................... 4–12

4.2.2.2 Setting Up an SNMP Trap Service. . ....................... 4–12

4.2.2.3 Trap Receiver Examples . ................................ 4–13

5 eSNMP API Routines

5.1 Interface Routines . . . ........................................ 5–1

esnmp_init . ................................................ 5–2

esnmp_register .............................................. 5–3

esnmp_unregister............................................ 5–6

esnmp_register2 ............................................. 5–7

esnmp_unregister2 . . . ........................................ 5–11

esnmp_capabilities . . . ........................................ 5–12

esnmp_uncapabilities . ........................................ 5–13

esnmp_poll . ................................................ 5–14

esnmp_are_you_there . ........................................ 5–15

esnmp_trap ................................................ 5–16

esnmp_term ................................................ 5–17

esnmp_sysuptime ............................................ 5–18

5.2 Method Routines ............................................ 5–19

*_get Routine ............................................... 5–20

*_set Routine ............................................... 5–22

5.2.1 Processing *_set Routines . . ................................ 5–24

5.2.2 Method Routine Applications Programming ..................... 5–26

5.2.3 Value Representation ...................................... 5–27

5.3 Support Routines . . . ........................................ 5–30

o_integer . . ................................................ 5–31

o_octet .................................................... 5–33

o_oid...................................................... 5–34

o_string . . . ................................................ 5–35

o_counter64 ................................................ 5–37

str2oid .................................................... 5–38

sprintoid. . . ................................................ 5–39

instance2oid ................................................ 5–40

oid2instance ................................................ 5–42

inst2ip .................................................... 5–44

cmp_oid . . . ................................................ 5–47

cmp_oid_preﬁx .............................................. 5–48

clone_oid . . ................................................ 5–49

free_oid . . . ................................................ 5–50

clone_buf . . ................................................ 5–51

mem2oct. . . ................................................ 5–52

cmp_oct . . . ................................................ 5–53

clone_oct . . ................................................ 5–54

free_oct . . . ................................................ 5–55

free_varbind_data . . . ........................................ 5–56

set_debug_level ............................................. 5–57

is_debug_level .............................................. 5–58

ESNMP_LOG ............................................... 5–59

__print_varbind ............................................. 5–60

set_select_limit.............................................. 5–61

__set_progname ............................................. 5–62

__restore_progname . . ........................................ 5–63

__parse_progname . . . ........................................ 5–64

esnmp_cleanup .............................................. 5–65

6 Troubleshooting eSNMP Problems

6.1 Modifying the Subagent Error Limit ............................. 6–1

6.2 Modifying the Subagent Timeout ................................ 6–1

6.3 Log Files . . ................................................ 6–2

Index

Figures

1–1 SNMP Architecture ....................................... 1–2

1–2 eSNMP Data Flow ........................................ 1–3

3–1 MIB II in SMI Tree Structure ............................... 3–3

Tables

1 TCP/IP Services Documentation ............................. viii

1–1 SNMP Component Files .................................... 1–4

1–2 Files for Building a Subagent ............................... 1–6

2–1 Host Resources MIB Objects ................................ 2–1

4–1 snmp_request Command Parameters . . . ....................... 4–1

4–2 Flags for the snmp_request Command . . ....................... 4–3

4–3 Data Types for the snmp_request and snmp_trapsnd Commands .... 4–5

4–4 Parameters for the snmp_trapsnd Command .................... 4–10

4–5 Flags for the snmp_trapsnd Command . ....................... 4–10

4–6 snmp_traprcv Command Flags............................... 4–12

5–1 Interface Routines ........................................ 5–1

The Compaq TCP/IP Services for OpenVMS product is the Compaq implementation of the TCP/IP networking protocol suite and internet services for OpenVMS Alpha and OpenVMS VAX systems.

A layered software product, TCP/IP Services provides a comprehensive suite of functions and applications that support industry-standard protocols for heterogeneous network communications and resource sharing.

This manual describes the features of the Simple Network Managment Protocol (SNMP) provided with TCP/IP Services. It also describes the extensible SNMP (eSNMP) application programming interface (API) and development environment.

See the Compaq TCP/IP Services for OpenVMS Installation and Conﬁguration manual for information about installing, conﬁguring, and starting this product.

Intended Audience

This manual is for experienced OpenVMS and UNIX system managers and assumes a working knowledge of TCP/IP networking, TCP/IP terminology, and some familiarity with the TCP/IP Services product.

Document Structure

Preface

This manual contains the following chapters:

• Chapter 1 describes the implementation of eSNMP provided with Compaq TCP/IP Services for OpenVMS.

• Chapter 2 describes the groups and objects implemented with the Host Resources MIB and MIB II that are provided with the eSNMP software.

• Chapter 3 describes how to use the eSNMP API to create a MIB subagent to manage entities or applications.

• Chapter 4 describes the trap sender, trap receiver, and MIB browser utilities provided with TCP/IP Services.

• Chapter 5 provides reference information about the eSNMP API routines.

• Chapter 6 describes some troubleshooting aids provided with TCP/IP Services.

vii

Table 1 TCP/IP Services Documentation

Manual Contents

DIGITAL TCP/IP Services for OpenVMS Concepts and Planning

Compaq TCP/IP Services for OpenVMS Release Notes

Compaq TCP/IP Services for OpenVMS Installation and Conﬁguration

DIGITAL TCP/IP Services for OpenVMS User’s Guide

Compaq TCP/IP Services for OpenVMS Management

Compaq TCP/IP Services for OpenVMS Management Command Reference

Compaq TCP/IP Services for OpenVMS Management Commands Quick Reference Card

Compaq TCP/IP Services for OpenVMS UNIX Commands Quick Reference Card

DIGITAL TCP/IP Services for OpenVMS ONC RPC Programming

This manual provides conceptual information about networking and the TCP/IP protocol including a description of the Compaq implementation of the Berkeley Internet Name Domain (BIND) service and the Network File System (NFS). It outlines general planning issues to consider before conﬁguring your system to use the TCP/IP Services software.

This manual also describes the manuals in the documentation set, provides a glossary of terms and acronyms for the TCP/IP Services software product, and documents how to contact the InterNIC Registration Service to register domains and access Request for Comments (RFCs).

This text ﬁle describes new features and changes to the software including installation, upgrade, conﬁguration, and compatibility information. These notes also describe new and existing software problems and restrictions, and software and documentation corrections.

Print this text ﬁle at the beginning of the installation procedure and read it before you install TCP/IP Services.

This manual explains how to install and conﬁgure the TCP/IP Services layered application product.

This manual describes how to use the applications available with TCP/IP Services such as remote ﬁle operations, email, TELNET, TN3270, and network printing. This manual explains how to use these services to communicate with systems on private internets or on the worldwide Internet.

This manual describes how to conﬁgure and manage the TCP/IP Services product.

Use this manual with the Compaq TCP/IP Services for OpenVMS Management Command Reference manual.

This manual describes the TCP/IP Services management commands.

Use this manual with the Compaq TCP/IP Services for OpenVMS Management manual.

This reference card lists the TCP/IP management commands by component and describes the purpose of each command.

This reference card contains inforomation about commonly performed network management tasks and their corresponding TCP/IP management and Compaq Tru64 UNIX command formats.

This manual presents an overview of high-level programming using open network computing remote procedure calls (ONC RPC). This manual also describes the RPC programming interface and how to use the RPCGEN protocol compiler to create applications.

(continued on next page)

viii

Table 1 (Cont.) TCP/IP Services Documentation

Manual Contents

Compaq TCP/IP Services for OpenVMS Sockets API and System Services Programming

Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference

Compaq TCP/IP Services for OpenVMS Tuning and Troubleshooting

Compaq TCP/IP Services for OpenVMS Guide to IPv6

For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:

http://www.openvms.compaq.com/

For a comprehensive overview of the TCP/IP protocol suite. you might ﬁnd the book Internetworking with TCP/IP: Principles, Protocols, and Architecture,by Douglas Comer, useful.

Reader’s Comments

This manual describes how to use the Sockets API and OpenVMS system services to develop network applications.

This manual describes the Simple Network Management Protocol (SNMP) and the SNMP application programming interface (eSNMP). It describes the subagents provided with TCP/IP Services, utilities provided for managing subagents, and how to build your own subagents.

This manual provides information about how to isolate the causes of network problems and how to tune the TCP/IP Services software for the best performance.

This manual describes the IPv6 environment, the roles of systems in this environment, the types and function of the different IPv6 addresses, and how to conﬁgure TCP/IP Services to access the 6bone network.

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet openvmsdoc@compaq.com Mail Compaq Computer Corporation

OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How to Order Additional Documentation

Visit the following World Wide Web address for information about how to order additional documentation:

http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

Conventions

The name TCP/IP Services means both:

• Compaq TCP/IP Services for OpenVMS Alpha

• Compaq TCP/IP Services for OpenVMS VAX

The name UNIX refers to the Compaq Tru64 UNIX operating system.

The following conventions are used in this manual. In addition, please note that all IP addresses are ﬁctitious.

Ctrl/x A sequence such as Ctrl/x indicates that you must hold down

PF1 x A sequence such as PF1 x indicates that you must ﬁrst press

Return

. . . A horizontal ellipsis in examples indicates one of the following

. . .

( ) In command format descriptions, parentheses indicate that you

[ ] In command format descriptions, brackets indicate optional

| In command format descriptions, vertical bars separate choices

{ } In command format descriptions, braces indicate required

bold text This typeface represents the introduction of a new term. It

italic text Italic text indicates important information, complete titles

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine,

the key labeled Ctrl while you press another key or a pointing device button.

and release the key labeled PF1 and then press and release another key or a pointing device button.

In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)

In the HTML version of this document, this convention appears as brackets, rather than a box.

possibilities:

• Additional optional arguments in a statement have been omitted.

• The preceding item or items can be repeated one or more times.

• Additional parameters, values, or other information can be entered.

A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

must enclose choices in parentheses if you specify more than one.

choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory speciﬁcations and for a substring speciﬁcation in an assignment statement.

within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.

choices; you must choose at least one of the items listed. Do not type the braces on the command line.

also represents the name of an argument, an attribute, or a reason.

of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER=name), and in command parameters in text (where dd represents the predeﬁned code for the device type).

the name of a ﬁle, or the abbreviation for a system privilege.

Monospace text

- A hyphen at the end of a command format description,

numbers All numbers in text are assumed to be decimal unless

Monospace type indicates code examples and interactive screen displays.

This typeface indicates UNIX system output or user input, commands, options, ﬁles, directories, utilities, hosts, and users.

In the C programming language, this typeface identiﬁes the following elements: keywords, the names of independently compiled external functions and ﬁles, syntax summaries, and references to variables or identiﬁers introduced in an example.

command line, or code line indicates that the command or statement continues on the following line.

otherwise noted. Nondecimal radixes—binary, octal, or hexadecimal—are explicitly indicated.

Overview

The Simple Network Management Protocol (SNMP) is the de facto industry standard for managing TCP/IP networks. The protocol deﬁnes the role of a network management station (NMS) and the SNMP agent. SNMP allows remote users on an NMS to monitor and manage network entities such as hosts, routers, X terminals, and terminal servers.

TCP/IP Services provides support for SNMP Version 2, using the Extensible Simple Network Management Protocol (eSNMP) architecture, under which a single master agent can support any number of subagents. The TCP/IP Services implementation of eSNMP includes a master agent, two subagents, an application programming interface (API), tools used to build additional subagents, startup and shutdown procedures, and text-based conﬁguration ﬁles.

This chapter provides an overview of the Compaq implementation of eSNMP. Topics include:

• eSNMP master agent and subagent architecture (Section 1.1)

• The procedure for handling SNMP requests (Section 1.2)

• The components of the TCP/IP Services software kit that implement SNMP (Section 1.3)

• The ﬁles useful in developing your own subagent (Section 1.4)

• The eSNMP API (Section 1.5)

• The management information base (MIB) compiler (Section 1.6)

• The impact of running SNMP Version 1 subagents against the SNMP Version 2 implementation provided with TCP/IP Services (Section 1.7)

• Sources of additional information about implementing subagents (Section 1.8)

1.1 SNMP Architecture

Figure 1–1 illustrates the SNMP architecture.

Overview 1–1

Overview

1.1 SNMP Architecture

Figure 1–1 SNMP Architecture

Master Agent

SNMP/ASN.1

Library

Subagent 1 Subagent 2 Subagent n

eSNMP API

AgentX (TCP/IP V5.1)

TCP/IP Kernel

OpenVMS

VM-0704A-AI

The SNMP environment consists of the following elements:

• The master agent, a process that runs on the host and handles SNMP requests from clients over the standard SNMP well-known port 161.

• One or more subagents, each of which provides access to the MIB data speciﬁed in client requests. In the TCP/IP Services implementation, the master agent contains two resident subagents, one that handles a subset of MIB II variables, and another that handles the Host Resources MIB. These MIBs are described in Chapter 2.

• The SNMP ASN.1 library, used by the master agent to interpret ASN.1 messages.

• The eSNMP API, the application programming interface that provides routines for programming your own subagents. This API runs on the AgentX routines, which are internal to the SNMP architecture.

• The TCP/IP kernel running on the OpenVMS operating system. The master agent and subagents communicate by means of the AgentX

protocol, which is based on RFC 2741.

For information about conﬁguring and managing the SNMP service, refer to the Compaq TCP/IP Services for OpenVMS Management guide.

1.2 Request Handling

The eSNMP software manages network communication by having the master agent listen for requests and then passes the requests to the appropriate subagent.

Figure 1–2 illustrates communication between the master agent and subagents.

1–2 Overview

Figure 1–2 eSNMP Data Flow

Overview

1.2 Request Handling

NMS1

NMS2

Client

Trap

client

Network

Host 1

Master Agent

161

Host 2

161

Master Agent

Subagent 1

705

Subagent 2

Subagent n

Subagent 1

Legend:

Flow of trap notification Flow of get/set request

Flow of "are_you_there" message

VM-0705A-AI

The process of communication for a request is illustrated with dashed lines and includes the following steps:

1. The network management station (NMS) (sometimes called the client), originates SNMP requests to obtain and set information.

Note

The client component is not provided with TCP/IP Services. To provide access to MIBs and to test SNMP communication, TCP/IP

Services provides the following utilities:

• MIB browser

• Trap sender

• Trap receiver

These utilities are described in Chapter 4.

Overview 1–3

Overview

1.2 Request Handling

The network management station sends an SNMP request to the master agent running on the host, using port 161. An SNMP request is made using one of the following commands:

•

Get

•

GetNext

•

GetBulk

•

Set

Note

TCP/IP Services does not support the standard SNMP

The request speciﬁes the object identifer (OID) of the data to be accessed. For information about formatting Request formats are speciﬁed in RFC 1905.

2. The master agent sends the request to the subagent that registered the subtree containing the OID.

The subagent receives communications from the master agent over the socket that was assigned when the subagent registered the subtree.

3. The appropriate subagent processes the request.

4. The subagent sends the response message to the master agent using the port that was assigned when the subagent registered the MIB.

When they are idle, subagents periodically send a message to port 705 to ensure that the master agent is still running. In Figure 1–2, subagent 1 is sending the

esnmp_are_you_there

trap

A subagent n is generating a trap for the trap client on NMS 2.

The

is generated by the subagent and sent to the client. In Figure 1–2,

trap

and

esnmp_are_you_there

message.

get

and

routines are described in Section 5.1.

1.3 TCP/IP Services Components for SNMP

Inform

set

requests, refer to Section 5.2.

command.

Table 1–1 lists the components of SNMP and the command procedures for managing SNMP that are supplied with TCP/IP Services.

Table 1–1 SNMP Component Files

File Location Function

TCPIP$ESNMP_SERVER.EXE SYS$SYSTEM Master agent image. TCPIP$OS_MIBS.EXE SYS$SYSTEM MIB II subagent image. TCPIP$HR_MIB.EXE SYS$SYSTEM Host Resources MIB

TCPIP$SNMP_REQUEST.EXE SYS$SYSTEM Simple MIB browser. TCPIP$SNMP_TRAPSND.EXE SYS$SYSTEM Utility for sending trap

1–4 Overview

subagent image.

messages.

(continued on next page)

1.3 TCP/IP Services Components for SNMP

Table 1–1 (Cont.) SNMP Component Files

File Location Function

Overview

TCPIP$SNMP_TRAPRCV.EXE SYS$SYSTEM Utility for receiving trap

TCPIP$ESNMP_SHR.EXE SYS$SHARE Image ﬁle containing eSNMP

TCPIP$SNMP_STARTUP.COM SYS$STARTUP Command procedure

TCPIP$SNMP_SYSTARTUP.COM SYS$STARTUP Command procedure

TCPIP$SNMP_RUN.COM TCPIP$SYSTEM Command procedure that

TCPIP$SNMP_SHUTDOWN.COM SYS$STARTUP Command procedure that

TCPIP$SNMP_SYSHUTDOWN.COM SYS$STARTUP Command procedure

TCPIP$EXTENSION_MIB_STARTUP.COM SYS$SYSDEVICE:[TCPIP$SNMP]

TCPIP$EXTENSION_MIB_ SHUTDOWN.COM

TCPIP$EXTENSION_MIB_RUN.COM SYS$SYSDEVICE:[TCPIP$SNMP]

SYS$SYSDEVICE:[TCPIP$SNMP]

messages.

application programming interface (API) routines.

that installs master and subagent images and runs TCPIP$SNMP_RUN.COM.

initiated by TCPIP$SNMP_ STARTUP.COM. Provided for site-speciﬁc customizations, such as parameter settings.

starts the master agent and subagents.

stops the master agent and subagents.

initiated by TCPIP$SNMP_ SHUTDOWN.COM. Provided for site-speciﬁc customization, such as parameter settings.

Command procedure invoked by TCPIP$SNMP_ SYSTARTUP.COM to start custom subagents.

Command procedure invoked by TCPIP$SNMP_ SYSHUTDOWN.COM to stop custom subagents.

Command procedure invoked by TCPIP$SNMP_ SYSTARTUP.COM when the service is enabled and starts detached processes to run subagents.

1.4 Writing an eSNMP Subagent

Table 1–2 lists the ﬁles that are available to help you develop MIBs and subagents. Except where noted, the ﬁles are located in the directory pointed to by TCPIP$SNMP_EXAMPLES.

Overview 1–5

Overview

1.4 Writing an eSNMP Subagent

Table 1–2 Files for Building a Subagent

File Description

ESNMP.H Header ﬁle used to create a subagent. Located in

GAWK.EXE Interpreter for MIB converter. MIB-CONVERTER.AWK A UNIX based

RFC1213.MY MIB II deﬁnitions. RFC1231.MY IEEE 802.5 Token Ring MIB deﬁnitions. RFC1285.MY FDDI MIB deﬁnitions. RFC1442.MY SNMP Version 2 Structure of Management

SNMP-SMI.MY SNMP Version 2 SMI deﬁnitions from RFC 1902

SNMP-TC.MY SNMP Version 2 SMI deﬁnitions from RFC 1903

V2-TC.MY SNMP Version 2 SMI deﬁnitions from RFC 1903

TCPIP$BUILD_CHESS.COM Command ﬁle that builds the sample chess

TCPIP$CHESS_SUBAGENT.OPT Options ﬁle for use in building the sample chess

*.C and *.H Source code for chess example. Contains detailed

TCPIP$CHESS_SUBAGENT.EXE Functioning chess example image. TCPIP$ESNMP.OLB Object library ﬁle containing routines used to

TCPIP$ESNMP_SHR.EXE Shareable image containing routines used to

UCX$ESNMP_SHR.EXE Copy of TCPIP$ESNMP_SHR.EXE, provided for

TCPIP$MIBCOMP.EXE TCPIP$MOSY.EXE TCPIP$SNMPI.EXE

TCPIP$ESNMP.

awk

deﬁnition in ASN.1 notation and converts it to an .MY ﬁle.

Information (SMI) deﬁnitions.

(replaces RFC 1442).

(replaces RFC 1443).

(superset of those in SNMP-TC.MY).

subagent.

documentation that explains how the code functions.

create a subagent. Located in the directory pointed to by TCPIP$SNMP.

create a subagent. Located in the directory pointed to by SYS$SHARE.

compatibility with existing customer subagents linked under TCP/IP Services V4.x. Located in the directory pointed to by SYS$SHARE.

Images associated with the MIB compiler. Located in SYS$SYSTEM.

shell script that takes a MIB

For information about building a subagent on an OpenVMS system, see Chapter 3.

1.5 The eSNMP API

The Compaq TCP/IP Services for OpenVMS implementation of the eSNMP architecture includes an API that provides programmers with many eSNMP routines they would otherwise have to develop themselves.

The eSNMP API includes interface routines, method routines, and support routines.

1–6 Overview

Overview

1.5 The eSNMP API

Interface routines handle the basic subagent operations, such as:

• Subagent initialization and termination

• Registration

• Polling of the master agent

• Trap sending

• UNIX system time conversion

• Adding and removing subagent capabilities registered with the master agent The support routines allow the subagent to manipulate the data in the response

to the request, and include the following:

• Basic protocol data unit (PDU) handling

• Authentication handling

• Octet string handling

• Variable binding (

• Object identiﬁer (OID) handling

• Buffer handling Chapter 5 describes the API routines in more detail. To create a subagent, the programmer must provide modules to implement the

method routines, as described in Chapter 3.

1.5.1 The SNMP Utilities

To provide quick access to information in the MIBs, and to test SNMP operation, TCP/IP Services provides the following utilities:

• TCPIP$SNMP_REQUEST.EXE, a MIB browser that allows you to retrieve and update objects from the MIBs.

• TCPIP$SNMP_TRPSND.EXE, a trap sender that generates traps (messages that require no response).

• TCPIP$SNMP_TRPRCV.EXE, a trap receiver (or ‘‘listener’’) that is used to detect trap messages.

For information about using the SNMP utilities, see Chapter 4.

1.6 The MIB Compiler

The MIB compiler processes the statements in an ASN.1 ﬁle and generates modules that are used by the developer to create subagent routines. For every ASN.1 input ﬁle that is processed using the MIB compiler, two output ﬁles, a subtree_TBL.H ﬁle and a subtree_TBL.C ﬁle, are generated, where subtree is the name from the original MIB deﬁnition ﬁle (for example, chess). The output ﬁles are described in more detail in Chapter 3.

VARBIND

) handling

The subtree_TBL.H ﬁle is a header ﬁle that contains the following:

• A declaration of the subtree structure

• Index deﬁnitions for each MIB variable in the subtree

• Enumeration deﬁnitions for MIB variables with enumerated values

• MIB group data structure deﬁnitions

Overview 1–7

Overview

1.6 The MIB Compiler

• Method routine function prototypes

The subtree_TBL.C ﬁle is an object ﬁle that contains the following:

• An array of integers representing the OIDs for each MIB variable

• An array of OBJECT structures

• An initialized SUBTREE structure

1.7 SNMP Versions

The extensible SNMP software supports SNMP Version 2, based on RFCs 1901 through 1908, including:

• The SNMP Version 2 structure of management information for SNMP Version 2 (SMI Version 2) and textual conventions.

• The eSNMP library API (SNMP Version 2), variable binding exceptions, and error codes.

• SNMP Version 1 and SNMP Version 2 requests. Both versions are handled by the master agent. SNMP Version 2 speciﬁc information from the subagent is mapped, when necessary, to SNMP Version 1 adherent data (according to RFC 2089). For example, if a management application makes a request using SNMP Version 1 PDUs, the master agent replies using SNMP Version 1 PDUs, mapping any SNMP Version 2 SMI items received from subagents. In most cases, subagents created with a previous version of the eSNMP API do not require any code changes and do not have to be recompiled. The circumstances under which recoding or recompiling are required are described in Section 1.7.1.

1.7.1 Using Existing (SNMP Version 1) MIB Modules

Existing SNMP Version 1 MIB subagent executable ﬁles should be compatible with the current SNMP Version 2 master agent without the need to recompile and relink, with the following exceptions:

• Any program that relies on TCP/IP Services Version 4.1 or 4.2 kernel data structures or access functions may run but may not return valid data. Such programs should be rewritten.

• Programs linked against UCX$ACCESS_SHR.EXE, UCX$IPC_SHR.EXE, or other older shareable images (except for UCX$ESNMP_SHR.EXE, which is described in the next list item) may not run even when relinked. You may need to either rewrite or both rewrite and recompile such programs. Note that the Chess example image (UCX$CHESS_SUBAGENT.EXE) has been updated and renamed TCPIP$CHESS_SUBAGENT.EXE.

• For programs linked against certain versions of UCX$ESNMP_SHR.EXE: – Images associated with the following versions of TCP/IP Services will run

correctly without the need to relink them:

Version 4.1 ECO 9 and later Version 4.2 ECO 1 and later

The installation of TCP/IP Services provides a backward-compatible version of UCX$ESNMP_SHR.EXE in the SYS$SHARE directory. Do not delete this image.

1–8 Overview

Overview

1.7 SNMP Versions

If you have problems running images linked against an older version of UCX$ESNMP_SHR.EXE, verify that the version in SYS$SHARE is the latest by entering the following DCL command:

$ DIRECTORY/DATE SYS$SHARE:*$ESNMP_SHR.EXE

The creation dates of the ﬁles with the preﬁx TCPIP$ and UCX$ should be within a few seconds of each other, and only one version of each ﬁle should exist. Make sure both images include the ﬁle protection W:RE.

– You should relink and perhaps recompile images associated with ECOs for

Version 4.1 or 4.2 other than those discussed in the previous list item.

Images linked against object library (.OLB) ﬁles may not need to be relinked, although you can relink them against the shareable images in this version of the product to decrease the image size. Relinking against the shareable image allows you to take advantage of updated versions of the eSNMP API without the need to relink. Some images linked against the current version of TCP/IP Services may run under Versions 4.1 and 4.2, but this backward compatibility is not supported and may not work in future versions of TCP/IP Services.

If an existing subagent does not execute properly, relink it against this version of TCP/IP Services to produce a working image. Some subagents (such as the OpenVMS Server MIB) require a minimum version of OpenVMS as well as a minimum version of TCP/IP Services.

1.8 For More Information

This manual provides the OpenVMS information required for implementing eSNMP subagents and ensuring their proper operation in that environment.

The eSNMP software for OpenVMS is derived from the Compaq Tru64 UNIX product. For information about the architecture and for details about the eSNMP API, refer to the UNIX documentation at the following URL:

http://www.compaq.com/unix

For information about prototypes and deﬁnitions for the routines in the eSNMP API, see the TCPIP$SNMP:ESNMP.H ﬁle. Table 1–2 lists ﬁles that contain additional comments and documentation.

Overview 1–9

MIBs Provided with TCP/IP Services

This chapter describes how MIBs are implemented on OpenVMS. The MIBs provided with TCP/IP Services are:

• The Host Resources MIB, which manages operating system objects (Section 2.1)

• MIB II, which manages TCP/IP kernel objects (Section 2.2)

2.1 Overview of the Host Resources MIB

The Host Resources MIB deﬁnes a uniform set of objects useful for the management of host computers. The Host Resources MIB, described by RFC 1514, deﬁnes objects that are common across many computer system architectures. The TCP/IP Services implementation of SNMP includes many of these deﬁned objects. In addition, some objects in MIB II provide host management functionality.

2.1.1 Deﬁning Host Resources MIB Implemented Objects

This section deﬁnes each of the implemented eSNMP objects. Table 2–1 provides a general RFC description and a speciﬁc OpenVMS description for each implemented object.

Table 2–1 Host Resources MIB Objects

Object Name RFC Description OpenVMS Description

hrSystemUptime The amount of time since this

host was last initialized.

hrSystemDate The host’s notion of the local

date and time of day.

hrSystemIntialLoadDevice Index of the hrDeviceEntry

for conﬁgured initial operating system load.

hrSystemIntialLoadParameters Parameters supplied to the

load device when requesting initial operating system conﬁguration.

hrSystemNumUsers Number of user sessions for

which the host is storing state information.

Time since system boot (in hundredths of a second).

Date and time character string with Coordinated Universal Time (UTC) information if available.

Index of SYS$SYSDEVICE in the device table.

A string of boot parameters from the console (Alpha only).

Number of processes that are neither owned by another process nor running detached.

(continued on next page)

MIBs Provided with TCP/IP Services 2–1

MIBs Provided with TCP/IP Services

2.1 Overview of the Host Resources MIB

Table 2–1 (Cont.) Host Resources MIB Objects

Object Name RFC Description OpenVMS Description

hrSystemProcesses Number of process contexts

currently loaded or running on the system.

hrSystemMaxProcesses Maximum number of process

contexts the system can support, or 0 if not applicable.

hrMemorySize The amount of physical main

memory contained in the host.

hrStorageIndex A unique value for each

logical storage area contained in the host.

hrStorageType The type of storage

represented by this entry.

hrStorageDescr A description of the type

and instance of the storage described by this entry.

hrStorageAllocationUnits The size of the data objects

allocated from this pool (in bytes).

hrStorageSize The size of storage

in this entry in hrStorageAllocationUnits.

hrStorageUsed The allocated amount of

storage in this entry in hrStorageAllocationUnits.

hrDeviceIndex A unique value for each host

or device constant between agent reinitialization.

hrDeviceType An indication of the type of

device. Some of these devices have corresponding entries in other tables.

hrDeviceDesc A text description of

the device, including manufacturer and version number (service, optional).

hrDeviceStatus The current operational state

of the device.

hrDeviceErrors The number of errors

detected on the device. The recommended initial value is zero.

hrProcessorFrwID The product ID of the

ﬁrmware associated with the processor.

Number of processes listed using the SHOW SYSTEM command.

SYSGEN parameter MAXPROCESSCNT.

The amount of physical main memory contained in the host.

Index of entry in hrStorageTable.

A numeric representation of the device class and type displayed by the SHOW DEVICE/FULL command.

Character string device type displayed by the SHOW DEVICE/FULL command.

Always 512 (the size of an OpenVMS disk block).

The total number of blocks on a device displayed by the SHOW DEVICE/FULL command.

The total number of used blocks on a device displayed by the SHOW DEVICE/FULL command.

Index of entry in hrDeviceTable.

In object identiﬁer format, a numeric representation of the device class and type displayed by the SHOW DEVICE/FULL command.

Character string of the device type displayed by the SHOW DEVICE/FULL command.

A numeric indication of the status of the device.

The number of errors indicated by the SHOW DEVICE command. This value is initialized to zero when the device is recognized by the system instead of when the master agent is initialized.

An object identiﬁer that corresponds to the console or PALcode version (Alpha only).

(continued on next page)

2–2 MIBs Provided with TCP/IP Services

MIBs Provided with TCP/IP Services

2.1 Overview of the Host Resources MIB

Table 2–1 (Cont.) Host Resources MIB Objects

Object Name RFC Description OpenVMS Description

hrNetworkIfIndex The value of the ifIndex that

corresponds to this network device.

hrDiskStorageAccess Indicates whether the storage

device is read/write or read only.

hrDiskStorageMedia Indicates the storage device

media type.

hrDiskStorageRemovable Indicates whether the disk

can be removed from the drive.

hrDiskStorageCapacity The total size of this long-

term storage device.

hrSWRunIndex A unique value for each

software product running on the host.

hrSWRunPath A description of the location

where this software was loaded.

hrSWRunStatus The status of the software

that is running.

The value of the index in the interface table in the standard MIB that corresponds to this network device.

This value is set to 2 if the device is read only; otherwise, it is set to 1. (The SHOW DEVICE/FULL command displays ‘‘software write-locked.’’)

Indicates device type.

Indicates whether the disk can be removed from the drive.

Half of the value for total blocks displayed by the SHOW DEVICE/FULL command.

Process ID.

Fully qualiﬁed name of executable image.

The values and the associated status of each are:

• 1 indicates that the current process is running (CUR)

• 2 indicates that the process is computable (COM)

hrSWRunPerfCPU The number (in hundredths

hrSWRunPerfMem The total amount of real

of a second) of the total system’s CPU resources consumed by this process.

system memory allocated to this process.

2.1.2 Restrictions to Host Resources MIB

SNMP requests are not implemented for the following Host Resources MIB objects:

hrPartitionTable hrPrinterTable hrSWInstalled hrSWInstalledTable

SNMP objects:

set

requests are not implemented for the following Host Resources MIB

• 3 indicates that you cannot run the process.

Process elapsed CPU time (in hundredths of a second).

Process current working set (in kilobytes).

MIBs Provided with TCP/IP Services 2–3

MIBs Provided with TCP/IP Services

2.1 Overview of the Host Resources MIB

hrFSLastFullBackupDate hrFSLastPartialBackupDate hrStorageSize hrSWRunStatus hrSystemDate hrSystemInitialLoadDevice hrSystemInitialLoadParameters

For objects that are not implemented, the Host Resources MIB returns a

NoSuchObject

TCP/IP Services supports the objects in the Host Resources MIB as follows:

error status.

Note

• The

hrDeviceTable

except those with the following characteristics:

Off line Remote UCB marked delete-on-zero-reference-count Mailbox device Device with remote terminal (DEV$M_RTT characteristic) Template terminal-class device LAT device (begins with _LT) Virtual terminal device (begins with _VT) Pseudoterminal device (begins with _FT)

Data items in the –

hrDeviceID

–

hrDeviceErrors

Code Condition

warning (3) Error logging is in progress (OpenVMS UCB value UCB$M_

running (2) Software is valid and no error logging is in progress (OpenVMS

unknown (1) Any other OpenVMS status.

includes all the devices known to the OpenVMS host

hrDeviceTable

is always null OID (0.0).

is coded as follows:

ERLOGIP).

UCB value UCB$M_VALID).

group have the following restrictions:

The

hrDeviceTable

NFS and DAD0 for virtual devices). For network devices, only the template devices (those with unit number 0)

are displayed.

•

hrFSMountPoint

between restarts or after a dismount/mount procedure.

• In the no information is accessible, a

get

2–4 MIBs Provided with TCP/IP Services

hrFSTable

request. Browsers respond differently to this message. For example,

now includes template devices (for example, DNFS0 for

(1.3.6.1.2.1.25.3.8.1.2) is DNFSn. The device may change

group, if no ﬁle systems are mounted through NFS or

"no such instance"

status is returned for a

MIBs Provided with TCP/IP Services

2.1 Overview of the Host Resources MIB

TCPIP$SNMP_REQUEST.EXE responds with no output and returns directly to the DCL prompt.

After an NFS mount, the following information is returned in response to a

Get

request. The data items implemented for OpenVMS (refer to RFC 1514)

are: –

hrFSIndex

–

hrFSMountPoint

–

hrFSRemoteMountPoint

–

hrFSType

• OID 1.3.6.1.2.1.25.3.9.1, for OpenVMS if the ﬁle system is not a UNIX style container ﬁle system.

•

hrFSNFS

Services container ﬁle system or a UNIX host.

–

hrFSAccess

–

hrFSBootable

–

hrFSStorageIndex

is the local DNFS device name.

is the remote ﬁle system.

is implemented as:

, OID 1.3.6.1.2.1.25.3.9.14, if the ﬁle system is a TCP/IP

, as deﬁned in RFC 1514.

is always HRM_FALSE (integer 2).

is always 0.

hrFSLastFullBackupDate

–

according to RFC 1514 as a hexadecimal value 00-00-01-01-00-00-00-00 (January 1, 0000).

–

hrFSLastPartialBackupDate

available for OpenVMS systems. Instead, hexadecimal value 00-00-01-0100-00-00-00 (January 1, 0000) applies.

•

hrProcessorFrwID

OpenVMS VAX. On this type of system, it returns standard null OID (0.0). For example:

1.3.6.1.2.1.25.3.3.1.1.1 = 0.0

For OpenVMS Alpha (ﬁrmware version 5.56-7), the response is shown in the following example:

1.3.6.1.2.1.25.3.3.1.1.1 = 1.3.6.1.2.1.25.3.3.1.1.1.5.56.7

• Data items in the –

hrDiskStorageMedia hrDiskStorageRemoveble

–

of ‘‘removable’’ in

•

hrStorageType

(1.3.6.1.2.1.25.2.1.4).

(OID preﬁx 1.3.6.1.2.1.25.3.3.1.1) is not implemented on

hrDiskStorage

hrDiskStorageRemoveble

always contains the value of

is unknown time. This entry is encoded

is unknown time. This information is not

table have the following restrictions:

is always ‘‘unknown’’ (2).

is always ‘‘false’’ (2). Note the incorrect spelling

(from RFC 1514).

hrStorageFixedDisk

2.2 Overview of MIB II

The Standard MIB (MIB II) described in RFC 1213 deﬁnes a set of objects useful for managing TCP/IP Internet entities. MIB II supports network monitoring and managing from the Transport layer down to the Physical layer of the TCP/IP internet stack. This MIB also provides information on how connections are established and how packets are routed through the Internet. For more information about MIB architecture, see Section 3.2.

MIBs Provided with TCP/IP Services 2–5

MIBs Provided with TCP/IP Services

2.2 Overview of MIB II

2.2.1 MIB II Implemented Groups

A group is a subdivision of a MIB that deﬁnes a subtree. SNMP as implemented by TCP/IP Services supports the following groups:

•

system (1)

•

interfaces (2)

•

Internet Protocol (4)

•

ICMP (5)

•

TCP (6)

•

UDP (7)

•

SNMP (11)

In the SNMP group (1.3.6.1.2.1.11), data elements with the status noted as obsolete in RFC 1907 are not implemented.

The TCP/IP Services implementation of SNMP does not support the following deﬁned MIB II groups:

Note

•

(address translation) group

•

EGP

(External Gateway Protocol) group

•

transmission

group

2.2.2 Restrictions to MIB II Implementation

SNMP requests are not implemented for the following MIB II objects:

ipRouteMetric1 - ipRouteMetric5 tcpMaxConn

SNMP

ipDefaultTTL ipRouteAge ipRouteDest ipRouteIfIndex ipRouteMask ipRouteNextHop ipRouteType

The TCP/IP Services implementation of SNMP includes the following MIB II objects:

•

set

requests are not implemented for the following MIB II group objects:

sysObjectID

1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.22.1

is returned in the following format:

where 1.3.6.1.4.1.36.2.15.13.22.1 corresponds to:

iso.org.dod.internet.private.enterprises.dec.ema.SysObjectIds.DEC-OpenVMS.eSNMP

• The

2–6 MIBs Provided with TCP/IP Services

sysORTable

1907 for details.

elements are under OID preﬁx 1.3.6.1.2.1.1.9.1. See RFC

MIBs Provided with TCP/IP Services

2.2 Overview of MIB II

When both the TCPIP$OS_MIBS and TCPIP$HR_MIB subagents are running, a noted, the OIDs conform to RFC 1907.

1.3.6.1.2.1.1.9.1.2.1 = 1.3.6.1.4.1.36.15.3.3.1.1

1.3.6.1.2.1.1.9.1.2.2 = 1.3.6.1.4.1.36.15.3.3.1.2

1.3.6.1.2.1.1.9.1.3.1 = Base o/s agent (OS_MIBS) capabilities

1.3.6.1.2.1.1.9.1.3.2 = Base o/s agent (HR_MIB) capabilities

1.3.6.1.2.1.1.9.1.4.1 = 31 = 0 d 0:0:0

1.3.6.1.2.1.1.9.1.4.2 = 36 = 0 d 0:0:0

This example is from the MIB browser (TCPIP$SNMP_REQUEST.EXE).

get

request on the

sysORTable

is as follows. Except where

• Under certain conditions, a subagent makes a duplicate entry in when it restarts. For example:

1.3.6.1.2.1.1.9.1.2.1 = 1.3.6.1.4.1.36.15.3.3.1.1

1.3.6.1.2.1.1.9.1.2.2 = 1.3.6.1.4.1.36.15.3.3.1.2

1.3.6.1.2.1.1.9.1.2.1 = Base o/s agent (OS_MIBS) capabilities

1.3.6.1.2.1.1.9.1.2.2 = Base o/s agent (OS_MIBS) capabilities

1.3.6.1.2.1.1.9.1.4.1 = 3256 = 0 d 0:0:32

1.3.6.1.2.1.1.9.1.4.2 = 3256 = 0 d 0:0:32

In this example, the TCPIP$OS_MIBS subagent made two entries with different ID numbers (OIDs with the preﬁx 1.3.6.1.2.1.1.9.1.2) that may show different translates the value received (in hundredths of a second) to the following, dropping any fractions of seconds:

d nhh:mm:ss

In this format, n represents the number of days, hh represents the number of hours, mm represents the number of minutes, and ss represents the number of seconds.

The HR_MIB subagent has not yet successfully started and registered its capabilities. If it starts, its entries in this example would use the next available index number.

• On systems running versions of the operating system prior to OpenVMS

7.1-2, counters for the MIB II the maximum value ( like the gauge type and remain at the maximum value until cleared by an external event, such as a system reboot. The following counters are affected:

sysORUpTime

2320

(1.3.6.1.2.1.1.9.1.4). The

), as deﬁned in RFC 1155. Instead, they behave

ifTable

snmp_request

do not wrap back to 9 after reaching

sysORTable

program

ifInDiscards ifInErrors ifInNUcastPkts ifInOctets ifInUcastPkts ifInUnknownProtos ifOutErrors ifOutNUcastPkts ifOutOctets ifOutUcastPkts

Note that for SNMP Version 2, these counters are data type Counter32. The following

ifTable

ifOutDiscards ifOutQLen

members are always -1 for OpenVMS:

(Counter32)

(Gauge32)

MIBs Provided with TCP/IP Services 2–7

+ 102 hidden pages