Compaq AAR04BCTE User Manual

Download

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

Creating a Subagent Using the eSNMP API

This chapter describes how to use the eSNMP API to create a MIB subagent that manages entities or applications. Topics included in this chapter are:

• Creating a MIB speciﬁcation (Section 3.1)

• The structure of management information (Section 3.2)

• Creating a MIB source ﬁle (Section 3.3)

• Including the routines and building the subagent (Section 3.4)

• Including your subagents in startup and shutdown procedures (Section 3.5)

To use this eSNMP API to create a subagent, you must have a C compiler running in your development environment.

3.1 Creating a MIB Speciﬁcation

Note

The creation of a management information base (MIB) begins with data gathering. During this phase, the developer identiﬁes the information to manage, based on the entities that the network manager needs to examine and manipulate. Each resource that a MIB manages is represented by an object. After gathering the data, the developer uses Abstract Syntax Notation 1 (ASN.1) to specify the objects in the MIB.

3.2 The Structure of Management Information

The structure of management information (SMI), which is speciﬁed in RFCs 1155 and 1902, describes the general framework within which a MIB can be deﬁned and constructed. The SMI framework identiﬁes the data types that can be used in the MIB and how resources within the MIB are represented and named.

SMI avoids complex data types to simplify the task of implementation and to enhance interoperability. To provide a standard representation of management information, the SMI speciﬁes standard techniques for the following:

• Deﬁning the structure of a particular MIB

• Deﬁning individual objects, including the syntax and value of each object

• Encoding object values

Creating a Subagent Using the eSNMP API 3–1

Creating a Subagent Using the eSNMP API

3.2 The Structure of Management Information

3.2.1 Assigning Object Identiﬁcation Codes

Each object in a MIB is associated with an identiﬁer of the ASN.1 type, called an object identiﬁer (OID). OIDs are unique integers that follow a hierarchical naming convention.

Each OID has two parts:

• A preassigned portion that is always represented on the SMI tree as 1.3.6.1 or iso (1), org (3), dod (6), Internet (1).

• A developer-assigned portion for the private development of MIBs.

Your organization may require you to register all newly assigned OIDs.

In addition to an OID, you should also assign a name to each object to help with human interpretation.

3.2.2 MIB Subtrees

Understanding MIB subtrees is crucial to understanding the eSNMP API and how your subagent will work.

Note

This manual assumes that you understand the OID naming structure used in SNMP. If not, refer to RFC 1902: Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMP Version 2).

The information in SNMP is structured hierarchically like an inverted tree. Each node has a name and a number. Each node can also be identiﬁed by an OID, which is a concatenation of the subidentiﬁers (nonnegative numbers). These numbers are on the path from the root node down to that node in the tree. In this hierarchy, data is associated only with leaf nodes. (A leaf node represents a MIB variable that can have an instance and an associated value.)

An OID must be at least two subidentiﬁers and at most 128 subidentiﬁers in length. The subidentiﬁer ranges are:

• Subidentiﬁer 1 values range from 0 to 2, inclusive.

• Subidentiﬁer 2 values range from 0 to 39, inclusive.

• The remaining subidentiﬁer values can be any nonnegative number.

Figure 3–1 illustrates the SMI hierarchical tree arrangement as speciﬁed in RFCs 1155 and 1902.

3–2 Creating a Subagent Using the eSNMP API

Figure 3–1 MIB II in SMI Tree Structure

iso (1)

org (3)

dod (6)

internet (1)

directory (1)

mgmt (2)

Creating a Subagent Using the eSNMP API

3.2 The Structure of Management Information

mib2 (1)

experimental (3)

private (4)

enterprises (1)

system (1)

interfaces (2)

at (3) ip (4)

icmp (5)

tcp (6) udp (7) egp (8)

transmission (10)

snmp (11)

VM-0721A-AI

Creating a Subagent Using the eSNMP API 3–3

Creating a Subagent Using the eSNMP API

3.2 The Structure of Management Information

For example, the chess MIB provided with the sample code in the [TCPIP$EXAMPLES.SNMP] directory has an element with the name ‘‘chess.’’ The OID for the element chess is 1.3.6.1.4.1.36.2.15.2.99, which is derived from its position in the hierarchy of the tree:

iso(1)

org(3)

dod(6)

internet(1)

private(4)

enterprise(1)

digital(36)

ema(2)

sysobjects(15)

decosf(2)

chess(99)

Any node in the MIB hierarchy can deﬁne a MIB subtree. All elements in the subtree have an OID that starts with the OID of the subtree base. For example, if you deﬁne chess to be a MIB subtree base, the elements with the same preﬁx as the chess OID are all in the MIB subtree:

chess 1.3.6.1.4.1.36.2.15.2.99

chessProductID 1.3.6.1.4.1.36.2.15.2.99.1 chessMaxGames 1.3.6.1.4.1.36.2.15.2.99.2 chessNumGames 1.3.6.1.4.1.36.2.15.2.99.3 gameTable 1.3.6.1.4.1.36.2.15.2.99.4

gameEntry 1.3.6.1.4.1.36.2.15.2.99.4.1

gameIndex 1.3.6.1.4.1.36.2.15.2.99.4.1.1 gameDescr 1.3.6.1.4.1.36.2.15.2.99.4.1.2

gameNumMoves 1.3.6.1.4.1.36.2.15.2.99.4.1.3

gameStatus 1.3.6.1.4.1.36.2.15.2.99.4.1.4

moveTable 1.3.6.1.4.1.36.2.15.2.99.5

moveEntry 1.3.6.1.4.1.36.2.15.2.99.5.1

moveIndex 1.3.6.1.4.1.36.2.15.2.99.5.1.1 moveByWhite 1.3.6.1.4.1.36.2.15.2.99.5.1.2 moveByBlack 1.3.6.1.4.1.36.2.15.2.99.5.1.3 moveStatus 1.3.6.1.4.1.36.2.15.2.99.5.1.4

chessTraps 1.3.6.1.4.1.36.2.15.2.99.6

moveTrap 1.3.6.1.4.1.36.2.15.2.99.6.1

The base of this MIB subtree is registered with the master agent to tell it that this subagent handles all requests related to the elements in the subtree.

The master agent expects a subagent to handle all objects subordinate to the registered MIB subtree. This principle guides your choice of MIB subtrees. For example, registering a subtree of chess is reasonable because it is realistic to assume that the subagent could handle all requests for elements in this subtree. Registering an entire application-speciﬁc MIB usually makes sense because the particular application expects to handle all objects deﬁned in the application-speciﬁc MIB.

However, registering a subtree of SNMP (under MIB II) would be a mistake, because it is unlikely that the subagent is prepared to handle every deﬁned MIB object subordinate to SNMP (packet counts, errors, trapping, and so on).

A subagent can register as many MIB subtrees as it wants. It can register OIDs that overlap with other registrations by itself or with other subagents; however, it cannot register the same OID more than once. Subagents can register and unregister MIB subtrees at any time after communication with the master agent is established.

3–4 Creating a Subagent Using the eSNMP API

3.2 The Structure of Management Information

Normally, it is the nonleaf nodes that are registered as a subtree with the master agent. However, leaf nodes, or even speciﬁc instances, can be registered as a subtree.

The master agent delivers requests to the subagent that has the MIB subtree with the longest preﬁx and the highest priority.

3.3 Creating a MIB Source File

Creating the MIB source ﬁle requires the following four-step process:

1. Write the ASN.1 input ﬁles, as described in Section 3.3.1.

2. Process the input ﬁles with the MIB compiler, as described in Section 3.3.2.

3. Compile and link the routines, as described in Section 3.4.

4. Include the subagent, as described in Section 3.5.

3.3.1 Writing the ASN.1 Input File

After you have assigned names and OIDs to all of the objects in the MIB, create an ASN.1 source ﬁle using ASCII statements.

Creating a Subagent Using the eSNMP API

Note

Providing information about ASN.1 syntax and programming is beyond the scope of this guide. For more information about ASN.1 programming, refer to one or more of the documents on this subject provided by the International Organization for Standardization (ISO).

Instead of creating ASN.1 ﬁles yourself, you can create .MY ﬁles from existing ASCII ﬁles (for example, from RFCs) by using the MIB-converter facility provided with TCP/IP Services. This facility uses a UNIX OpenVMS as well as on appropriately conﬁgured UNIX systems. For details about the facility, see the MIB-CONVERTER.AWK ﬁle, which is located in the [.SNMP] subdirectory of TCPIP$EXAMPLES. Standard .MY ﬁles are also provided for your convenience.

The custom MIB deﬁnition ﬁles have the default extension .MY.

3.3.2 Processing the Input File with the MIB Compiler

Process your ASN.1 source ﬁles with the MIB compiler using the DCL command MIBCOMP.

Note

If you are familiar with processing on UNIX systems, you can use the UNIX utilities

snmpi

and

mosy

. See Section 3.3.2.1 for more information.

awk

script, which runs on

The compilation process produces two template C programming modules that are used in building the executable subagent code. When you run the compiler, specify all the ASN.1 source ﬁles for a given subagent. Whenever any of these source ﬁles are updated, you must repeat the compilation process.

The syntax for the MIBCOMP command is as follows:

MIBCOMP MIB-source-file "subtree" [/PREFIX=prefix-name] [/PRINT_TREE] [/SNMPV2]

Creating a Subagent Using the eSNMP API 3–5

Creating a Subagent Using the eSNMP API

3.3 Creating a MIB Source File

The parameters and qualiﬁers for the MIBCOMP command are as follows:

Parameter or Qualiﬁer Deﬁnition

MIB-source-ﬁle A comma-separated list of MIB deﬁnition ﬁles. The

subtree The text name for the root of your MIB deﬁnitions. This

/PREFIX=preﬁx-name The MIB compiler attaches the preﬁx-name string to the

/PRINT_TREE Displays the entire MIB subtree. /SNMPV2 Speciﬁes the use of SNMP Version 2 parsing rules.

standard extension is .MY, but you can specify any valid OpenVMS ﬁle name. You must specify the full ﬁle name.

parameter must be enclosed in quotation marks. This name is used in generating names for template C modules and also for the names of the ﬁles themselves: subtree_tbl.c and subtree_tbl.h.

beginning of all generated names.

The following is an example of processing the chess example ﬁles using the /PRINT_TREE qualiﬁer:

$ MIBCOMP RFC1442.MY,CHESS_MIB.MY "chess" /PRINT_TREE Processing RFC1442.MY

Processing CHESS_MIB.MY Dump of objects in lexical order

-- This file created by program ’snmpi -p’

ccitt 0 iso 1

internet 1.3.6.1

directory 1.3.6.1.1 mgmt 1.3.6.1.2 experimental 1.3.6.1.3 private 1.3.6.1.4

enterprises 1.3.6.1.4.1

dec 1.3.6.1.4.1.36

ema 1.3.6.1.4.1.36.2

sysobjectids 1.3.6.1.4.1.36.2.15

decosf 1.3.6.1.4.1.36.2.15.2

chess 1.3.6.1.4.1.36.2.15.2.99

chessProductID 1.3.6.1.4.1.36.2.15.2.99.1

ObjectID read-only

chessMaxGames 1.3.6.1.4.1.36.2.15.2.99.2

INTEGER read-only

chessNumGames 1.3.6.1.4.1.36.2.15.2.99.3

INTEGER read-only

gameTable 1.3.6.1.4.1.36.2.15.2.99.4

gameEntry 1.3.6.1.4.1.36.2.15.2.99.4.1

indexes: gameIndex

gameIndex

1.3.6.1.4.1.36.2.15.2.99.4.1.1 INTEGER read-write

gameDescr

1.3.6.1.4.1.36.2.15.2.99.4.1.2 DisplayString read-write

range: 0 to 255

gameNumMoves

1.3.6.1.4.1.36.2.15.2.99.4.1.3 INTEGER read-write

gameStatus

1.3.6.1.4.1.36.2.15.2.99.4.1.4 INTEGER read-write

3–6 Creating a Subagent Using the eSNMP API

Creating a Subagent Using the eSNMP API

3.3 Creating a MIB Source File

enum: complete 1 enum: underway 2

moveTable 1.3.6.1.4.1.36.2.15.2.99.5

moveEntry 1.3.6.1.4.1.36.2.15.2.99.5.1

indexes: gameIndex moveIndex

moveIndex

1.3.6.1.4.1.36.2.15.2.99.5.1.1 INTEGER read-write

moveByWhite

1.3.6.1.4.1.36.2.15.2.99.5.1.2 DisplayString read-write

moveByBlack

1.3.6.1.4.1.36.2.15.2.99.5.1.3 DisplayString read-write

moveStatus

1.3.6.1.4.1.36.2.15.2.99.5.1.4 INTEGER read-write

security 1.3.6.1.5 snmpV2 1.3.6.1.6

snmpDomains 1.3.6.1.6.1 snmpProxys 1.3.6.1.6.2 snmpModules 1.3.6.1.6.3

joint_iso_ccitt 2

-------------------------11 objects written to chess_tbl.c

11 objects written to chess_tbl.h

enum: delete 3

range: 0 to 255

enum: ok 1 enum: delete 2

3.3.2.1 UNIX Utilities Supplied with TCP/IP Services

For compatibility with UNIX, the TCP/IP Services for generating the C language code that deﬁnes the object tables. These UNIX utilities are supported on OpenVMS for compatibility with UNIXdeveloped procedures. For information about using these utilities, refer to the Compaq Tru64 UNIX Network Programmer’s Guide.

3.3.2.2 Object Tables

The MIBCOMP command is used to generate the C language code that deﬁnes the object tables from the MIBs. The object tables are deﬁned in the emitted ﬁles subtree_TBL.H and subtree_TBL.C, which are compiled into your subagent.

These modules are created by the MIBCOMP command or the UNIX utilities. Compaq recommends that you do not edit them. If the MIBs change or if a future version of the SNMP development utilities requires your object tables to be rebuilt, it is easier to rebuild and recompile the ﬁles if you did not edit them.

3.3.2.3 The subtree_TBL.H Output File

The subtree_TBL.H ﬁle contains the following sections:

1. A declaration of the subtree structure

2. Index deﬁnitions for each MIB variable in the subtree

3. Enumeration deﬁnitions for MIB variables with enumerated values

4. MIB group data structure deﬁnitions

mosy

and

snmpi

utilities are provided with

5. Method routine function prototypes The following sections describe each section of the subtree_TBL.H ﬁle.

Creating a Subagent Using the eSNMP API 3–7

Creating a Subagent Using the eSNMP API

3.3 Creating a MIB Source File

1. Declaration Section

The ﬁrst section of the subtree_TBL.H ﬁle is a declaration of the subtree structure. The subtree is automatically initialized by code in the subtree_TBL.C ﬁle. A pointer to this structure is passed to the register a subtree with the master agent. All access to the object table for this subtree is through this pointer. The declaration has the following form:

extern SUBTREE subtree_subtree;

2. Index Deﬁnitions Section

The second section of the subtree_TBL.H ﬁle contains index deﬁnitions for each MIB variable in the subtree of the form:

#define I_mib-variable nnn

These values are unique for each MIB variable in a subtree and are the index into the object table for this MIB variable. These values are also generally used to differentiate between variables that are implemented in the same method routine so they can be used in a switch operation.

3. Enumeration Deﬁnitions Section

The third section of the subtree_TBL.H ﬁle contains enumeration deﬁnitions for those integer MIB variables that are deﬁned with enumerated values, as follows:

esnmp_register

routine to

#define D_mib-variable_enumeration-name value

These deﬁnitions are useful because they describe the value that enumerated integer MIB variables may take on. For example:

/* enumerations for gameEntry group */

#define D_gameStatus_complete 1 #define D_gameStatus_underway 2 #define D_gameStatus_delete 3

4. MIB Group Data Structure Deﬁnitions Section

The fourth section of the subtree_TBL.H ﬁle contains data structure deﬁnitions of the following form:

typedef structxxx {

type mib-variable; . . .

char mib-variable_mark; . . .

} mib-group_type

The MIB compiler generates one of these data structures for each MIB group in the subtree. Each structure deﬁnition contains a ﬁeld representing each MIB variable in the group. In addition to the MIB variable ﬁelds, the structure includes a 1-byte mib-variable-mark ﬁeld for each variable. You can use these for maintaining status of a MIB variable. For example, the following is the group structure for the chess MIB:

3–8 Creating a Subagent Using the eSNMP API

Creating a Subagent Using the eSNMP API

3.3 Creating a MIB Source File

typedef struct _chess_type {

OID ches; int chessMaxGames; int chessNumGames;

char chessProductID_mark; char chessMaxGames_mark; char chessNumGames_mark;

} chess_type;

Although MIB group structures are provided for your use, you are not required to use them. You can use the structure that works best with your method routines.

5. Method Routine Prototypes Section

The ﬁfth section of the subtree_TBL.H ﬁle describes the method routine prototypes. Each MIB group within the subtree has a method routine prototype deﬁned. A MIB group is a collection of MIB variables that are leaf nodes and that share a common parent node.

There is always a function prototype for the method routine that handles the

GetNext

there is also a function prototype for the method routine that handles operations. Pointers to these routines appear in the subtree’s object table which is initialized in the subtree_TBL.C module. You must write method routines for each prototype that is deﬁned, as follows:

extern int mib-group get( METHOD *method ); extern int mib-group set( METHOD *method );

For example:

extern int chess_get( METHOD *method ); extern int chess_set( METHOD *method );

3.3.2.4 The subtree_TBL.C Output Files

The subtree_TBL.C ﬁle ﬁle contains the following sections:

1. An array of integers representing the OIDs for each MIB variable

2. An array of OBJECT structures

3. An initialized SUBTREE structure

4. Routines for allocating and freeing the The following sections describe each section of the subtree_TBL.C ﬁle.

1. Array of Integers Section

The ﬁrst section of the subtree_TBL.C ﬁle is an array of integers used to represent the OID of each MIB variable in the subtree. For example:

, and

GetBulk

operations. If the group contains any writable variables,

mib_group_type

Set

Get

static unsigned int elems[] = {

1, 3, 6, 1, 4, 1, 36, 2, 15, 2, 99, /* chess */ 1, 3, 6, 1, 4, 1, 36, 2, 15, 2, 99, 1, 0, /* chessProductID */

...

1, 3, 6, 1, 4, 1, 36, 2, 15, 2, 99, 5, 1, 4, 0, /* moveStatus */

};

The ﬁrst line represents the root of the tree; the other lines represent speciﬁc variables. The latter groups are all terminated by a zero, a programming convenience in internal implementations of API routines.

Creating a Subagent Using the eSNMP API 3–9

Creating a Subagent Using the eSNMP API

3.3 Creating a MIB Source File

2. Array of OBJECT Structures Section

The second section of the subtree_TBL.C ﬁle is an array of OBJECT structures. Each MIB variable within the subtree has one OBJECT. The chess example produces the following:

static OBJECT objects[] = {

{I_chessProductID ,{12, &elems[ 11]}, ESNMP_TYPE_ObjectId ,chess_get, NULL},

...

An OBJECT structure represents a MIB variable and has the following ﬁelds:

object_index

• which identiﬁes this variable (in the chess example,

•

oid

— The variable’s OID (points to a part of

This variable is of type OID, which is a structure containing two elements: the number of elements in the OID and a pointer to the correct starting place in the array of elements (

In the chess example, indicates that:

The OID has 12 integers separated by dots in the ASCII text representation (

The integer with index 11 in the array

•

type

— The variable’s eSNMP data type.

•

getfunc

no routine exists).

•

setfunc

no routine exists).

The master agent does not access object tables or MIB variables directly. It only maintains a registry of subtrees. When a request for a particular MIB variable arrives, it is processed as shown in the following steps (where the MIB variable is

mib_var

and the subtree is

— The constant I_mib-variable from the subtree_TBL.H ﬁle,

I_chessProductID

elems[ ]

oid

is designated by

in the chess example).

{12, &elemens[ 11]}

"1.3.6.1.4.1.36.2.15.2.99.2"

elems[ ]

— The address of the method routine to call for

subtree_1

)

is the ﬁrst element.

Get

requests (null if

Set

requests (null if

. This

1. The master agent ﬁnds in the register of subtrees. The authoritative region is determined as the registered MIB subtree that has the longest preﬁx and the highest priority.

2. The master agent sends a message to the subagent that registered

3. The subagent consults its list of registered subtrees and locates It searches the object table of

•

mib_var

• The ﬁrst object lexicographically after

4. The appropriate method routine is called. If the method routine completes successfully, the data is returned to the master agent. If the method routine fails when doing a fails when doing a object table of the table is exhausted. In either case, a response is returned.

5. If the master agent detects that routine, it recursively tries the subtree lexicographically after a subagent returns a value or the registry of subtrees is exhausted.

3–10 Creating a Subagent Using the eSNMP API

(for

Get

and

GetorSet GetNext

subtree_1

as the authoritative region for the

mib_var

subtree_1

Set

routines)

, an error is returned. If the method routine

, the code keeps trying subsequent objects in the

until either a method routine returns successfully or

subtree_1

and locates the following:

mib_var

could not return data on a

(for

NextorBulk

routines)

subtree_1

until

Creating a Subagent Using the eSNMP API

3.3 Creating a MIB Source File

3. Initialized Subtree Structure Section

The third section of the subtree_TBL.C ﬁle is the SUBTREE structure itself. A pointer to this structure is passed to the eSNMP library routine to register the subtree. It is through this pointer that the library routines ﬁnd the object structures. The following is an example of the chess subtree structure:

esnmp_register

SUBTREE chess_subtree = { "chess", "1.3.6.1.4.1.36.2.15.2.99",

{ 11, &elems[0] }, objects, I_moveStatus};

The following table describes the elements of the SUBTREE structure, the deﬁnition of each element in the header ﬁle (subtree_TBL.H)), and the element in the chess example:

Description

The name of the subtree’s base element.

The ASCII string representation of the subtree’s OID. This is what actually gets registered.

The OID structure for the base node of the subtree. This points back to the array of integers.

A pointer to the array of objects in the object table. It is indexed

I_xxxx

by the the subtree_TBL.H ﬁle.

The index of the last object in the object_TBL ﬁle. This is used to determine when the end of the table has been reached.

deﬁnitions found in

Header File Representation Example

name "chess"

dots "1.3.6.1.4.1.36.2.15.2.99"

oid 11, &elems[0] }

object_oid objects

last I_moveStatus

4. Routines Section

The ﬁnal section of the subtree_TBL.C ﬁle. contains short routines for allocating and freeing the

mib_group_type

. These are provided as a convenience and are

not a required part of the API.

3.4 Including the Routines and Building the Subagent

The MIB compiler does not generate code for implementing the method routines for your subagent. This includes code for processing requests as well as for generating traps. You must write this code yourself. See the CHESS_MIB.C module for an example.

To produce executable subagent code, follow these steps:

1. Compile the C modules generated by the MIB compiler, along with your implementation code. Use a command in the following format (derived from the sample provided for building the chess example in TCPIP$BUILD_ CHESS.COM):

$ CC /INCLUDE=TCPIP$SNMP /PREFIX=ALL /STANDARD=VAX CHESS_METHOD.C, _$ CHESS_MIB.C, CHESS_TBL.C

get,set

, and other SNMP

Creating a Subagent Using the eSNMP API 3–11

Creating a Subagent Using the eSNMP API

3.4 Including the Routines and Building the Subagent

Depending on the version of the Compaq C compiler you are using, you might see warnings that you can ignore. Portions of these warnings are as follows:

%CC-I-SIGNEDKNOWN In this declaration, DEC C recognizes the ANSI

%CC-I-INTRINSICINT In this statement, the return type for intrinsic

2. Link the object modules using a command and options in the following format (derived from the chess example):

$ LINK SYS$INPUT/OPTIONS CHESS_METHOD.OBJ CHESS_MIB.OBJ CHESS_TBL.OBJ SYS$SHARE:TCPIP$ESNMP_SHR.EXE/SHARE

To link with the eSNMP object library, enter the following command:

$ LINK SYS$INPUT/OPTIONS CHESS_METHOD.OBJ CHESS_MIB.OBJ CHESS_TBL.OBJ TCPIP$SNMP:TCPIP$ESNMP.OLB/LIBRARY TCPIP$LIBRARY:TCPIP$LIB.OLB/LIBRARY

Alternatively, you can link your subagent with the eSNMP API shareable image (TCPIP$ESNMP_SHR.EXE). The resulting executable image is smaller and can be run without relinking against any future versions of the shareable image. To link the example object with the shareable image, enter the following command:

keyword "signed". This differs from the VAX C behavior.

"strlen" is being changed from "size_t" to "int".

$ LINK SYS$INPUT/OPTIONS CHESS_METHOD.OBJ CHESS_MIB.OBJ CHESS_TBL.OBJ SYS$SHARE:TCPIP$ESNMP_SHR.EXE/SHARE

3.5 Including Extension Subagents in the Startup and Shutdown Procedures

You can add your custom subagents to the SNMP startup and shutdown procedures by editing the following ﬁles:

File Name Edit Required

TCPIP$EXTENSION_MIB_STARTUP.COM Edit the example lines to include an INSTALL

TCPIP$EXTENSION_MIB_RUN.COM Edit the example lines to include a RUN command

CREATE command for custom images that need to be installed, possibly with privileges. Remove extra example lines, and adjust the GOTO statement.

for custom images. Remove extra example lines, and adjust the GOTO statement.

3–12 Creating a Subagent Using the eSNMP API

Creating a Subagent Using the eSNMP API

3.5 Including Extension Subagents in the Startup and Shutdown Procedures

File Name Edit Required

TCPIP$EXTENSION_MIB_SHUTDOWN.COM Edit the example lines to:

• Include symbols for the detached processes that are running custom images. Use the same process names speciﬁed in TCPIP$EXTENSION_MIB_ RUN.COM.

• Modify the IF and THEN statements to include the new symbols.

• Include an INSTALL DELETE command for images installed in TCPIP$EXTENSION_MIB_ STARTUP.COM.

• Remove extra example lines, and adjust the GOTO statement.

Creating a Subagent Using the eSNMP API 3–13

TCP/IP Services includes the following programs, which are useful for testing applications and for analyzing SNMP problems:

• TCPIP$SNMP_REQUEST (MIB browser) (Section 4.1)

• TCPIP$SNMP_TRPSND (trap sender) (Section 4.2)

• TCPIP$SNMP_TRPRCV (trap receiver) (Section 4.2) These programs can be invoked by commands that are deﬁned by the

SYS$STARTUP:TCPIP$DEFINE_COMMANDS.COM command procedure. This chapter describes how to use the supplied SNMP utilities.

4.1 Using the MIB Browser

Using the SNMP Utilities

TCP/IP Services provides the client to handle single SNMP requests for reading and writing to a MIB. The browser sends SNMP Version 1 and SNMP Version 2 request PDUs to an agent and displays the agent’s response.

To run the MIB browser, follow these steps:

1. Deﬁne a foreign command for the program:

$ snmp_request == "$SYS$SYSTEM:TCPIP$SNMP_REQUEST"

Alternatively, you can run the SYS$MANAGER:TCPIP$DEFINE_ COMMANDS.COM procedure to deﬁne all the foreign commands available with TCP/IP Services.

2. Enter the command using the following format.

snmp_request agent "community" request_type [flags] variable [data-type value]

Section 4.1.1 describes the parameters. Section 4.1.2 describes the ﬂags.

snmp_request

MIB browser that acts as a simple

4.1.1 MIB Browser Parameters

Table 4–1 describes the

Table 4–1 snmp_request Command Parameters

Parameter Function

agent

snmp_request

The host name or IP address (in dot notation) of the managed node to query.

If you specify 0, 0.0.0.0., 127.0.0.1, or ‘‘localhost,’’ the server on the browser’s host is queried.

parameters.

(continued on next page)

Using the SNMP Utilities 4–1

Using the SNMP Utilities

4.1 Using the MIB Browser

Table 4–1 (Cont.) snmp_request Command Parameters

Parameter Function

"community"

request-type

variable

data-type

value

For

Set

requests, you can specify more than one group of the following:

•

variable-name

•

data-type

The community string to be used in the query. This parameter is case sensitive. Typically, agents are conﬁgured to permit read access to the community string "public". For accurate interpretation, be sure to enclose the name in quotation marks (" "). Note that if you do not use quotation marks, the name is changed to lowercase.

PDU type to send. Can be one of the following SNMP requests:

Get GetNext GetBulk

Set

An object identiﬁer (OID) in ASN.1 notation that is associated with an object in a MIB. For example:

$ snmp_request host1 "public" getnext -d 1.3.6.1.6.3.1.1.6

Data type of the value. This parameter can be speciﬁed for requests. The data types are described in Section 4.1.3.

The value to which to set the contents of the OID. This parameter is used for

set

Sends a Get-Request PDU. Sends a GetNext-Request PDU. Sends a GetBulk-Request PDU (SNMP Version 2

only). Sends a Set-Request PDU.

Set

requests.

•

value

For other requests, you can specify more than one variable name, except when you specify the-lor-tﬂag; these ﬂags are valid only with a request, for which only one OID is permitted.

4.1.2 MIB Browser Flags

Flags are speciﬁed in UNIX format. Because ﬂags and data types are case sensitive, you should always enter them in

the case that is speciﬁed. If a letter or value is speciﬁed as uppercase, you must enclose it in quotation marks. In general, if you use uppercase letters where lowercase is speciﬁed, the results are unpredictable. For example, the ﬂag functions correctly but the ﬂag must be lowercase.

If you do not specify a ﬂag, or if you specify an invalid ﬂag, a usage message is displayed. You must place the ﬂags after the

Table 4–2 describes the ﬂags for the

"-V2c"

does not, because the ﬂag character (v)

snmp_request

request-type

command.

parameter.

GetNextorGetBulk

"-v2C"

4–2 Using the SNMP Utilities

Table 4–2 Flags for the snmp_request Command

Flag Description

Using the SNMP Utilities

4.1 Using the MIB Browser

-d

-i max_ignores

Speciﬁes hexadecimal dump mode. Before displaying a return value, displays a hexadecimal dump of SNMP packets sent and received. For example:

$ snmp_request host1 "public" getnext -d -v 2c 1.3.6.1.6.3.1.1.6 Sent:

30290201 01040670 75626C69 63A11C02 0).....public...

047BE9C1 BD020100 02010030 0E300C06 .{.........0.0..

082B0601 06030101 060500 .+.........

Received:

30820033 02010104 06707562 6C6963A2 0..3.....public.

2602047B E9C1BD02 01000201 00308200 &..{.........0..

16308200 12060A2B 06010603 01010601 .0.....+........

00020478 D917FC ...x...

1.3.6.1.6.3.1.1.6.1.0 = 2027493372

Speciﬁes the number of times the MIB browser listens for a reply packet to a request if it receives an invalid packet (caused by an invalid packet identiﬁer, version, or SNMP version and command combination). Specify a positive integer for the value (max_ignores). If you specify a negative value, it will be converted to an unsigned positive integer. If you specify 0, no retries are attempted.

If, after an invalid reply packet is received, a valid reply packet is received, the ignore counter is reset to the value of max_ignores.

If a timeout occurs after an invalid packet is received, the packet is resent, the resend counter is decremented, and the ignore counter is reset to the value of max_ignores.

-i

You cannot use the to automatically increment the input OID and continue querying a server after a general SNMP error has occurred, as may happen with a faulty server. In this case, the query is terminated even though the end of the MIB selection has not been reached. You must manually increment the input OID to skip the error and continue with the query.

ﬂag when you perform a query with the-lor-tﬂags

(continued on next page)

Using the SNMP Utilities 4–3

Using the SNMP Utilities

4.1 Using the MIB Browser

Table 4–2 (Cont.) Flags for the snmp_request Command

Flag Description

-l

Speciﬁes loop mode. Note that this ﬂag is the letter l, not the number 1. Valid only if

0, and ﬂag Causes the master agent to traverse all the MIBs registered with the master

agent, starting at the ﬁrst OID after the one speciﬁed in the command. (Note that you can specify only one received one at a time, and for each one, the OID returned by the master agent is used in a subsequent request. Corresponds to the behavior of standard

The MIB browser reads and displays responses, and issues requests until the master agent has no more data, times out, or you press Ctrl/Y or Ctrl/C.

If speciﬁed with the values are ignored, and the behavior is identical to that of

When the last OID handled by the master agent is reached, you receive a response similar to the following for a query on OID 1.3.6.1.6.3.1.1.6.1 using SNMP Version 1:

request-typeisGetNextorGetBulk

is set to a number greater than 0).

variable-name

mibwalk

programs.

GetBulk

request, the-nand-mﬂags and associated

(where ﬂagnis set to

[OID].) Responses are

GetNext

1.3.6.1.6.3.1.1.6.1.0 = 693056825

- no such name - returned for variable 1

For a query using SNMP Version 2, the example response is:

1.3.6.1.6.3.1.1.6.1.0 = 693056825

1.3.6.1.6.3.1.1.6.1.0 = - end of mib view -

These examples assume that:

• OID 1.3.6.1.6.3.1.1.6.1.0 is the last OID supported on the target host.

• The target host is running an SNMP Version 2 agent.

-m max_repetitions

-n non_repeaters

-p port

-r max_retries

The statement the master agent.

Speciﬁes the number of repetitions requested for repeating variables. Applies only to the

Note that the resulting display can be confusing because the results for the repeater OIDs are interleaved. That is, the OIDs are displayed in alternate progression for faster memory throughput. If you specify specifying both the

Speciﬁes the number of variables for which no repetition is requested. Applies only to the specifying both the

Speciﬁes the port where the request is to be sent. If not speciﬁed, the request is sent to well-known SNMP port 161.

Speciﬁes the number of times the MIB browser resends a request packet if it times out before receiving a reply. Specify a positive integer for the value (max_retries). If you specify a negative value, it will be converted to an unsigned positive integer. If you specify 0, no retries are tried.

If, after a timeout and a resend, a reply packet is received, the resend counter is reset. After another timeout, the speciﬁed number of max_retries is sent.

end of mib view

GetBulk

-m

GetBulk

-m

and

and-nﬂags, the results are unpredictable.

request. If you specify

and-nﬂags, the results are unpredictable.

refers to OIDs for all MIBs registered with

GetNext

requests.

GetBulk

(continued on next page)

without

4–4 Using the SNMP Utilities

Table 4–2 (Cont.) Flags for the snmp_request Command

Flag Description

Using the SNMP Utilities

4.1 Using the MIB Browser

-s sleep_interval

-t

-v version

-w max_wait

Speciﬁes the number of seconds between iterations of sending a request (for the 1 second. This ﬂag is ignored if neither the speciﬁed.

The might be necessary when a server agent is starting up.

Speciﬁes tree mode. Valid only if (where ﬂagnis set to 0 and ﬂagmis set to a number greater than 0).

Similar to the subtree with the responses and issues requests until the agent has no more data for the speciﬁed subtree, times out, or is interrupted by a user.

Speciﬁes the SNMP version to use for sending the PDU. The versions are:

2cor1

space ( If

If you specify subagent, it is unlikely to respond.

Speciﬁes the maximum seconds the reply before timing out. Cannot be 0. The default is 3.

-r

-s

ﬂag is useful for specifying a time to wait between resends, which

(default). Not case sensitive. You can specify the ﬂag without a

-v2c

request_typeisgetbulk

The-i,-r, and-sﬂags apply to individual queries. If you specify the-lor ﬂags also, the values for the-i,-r, and-sﬂags are applied to each iteration.

4.1.3 MIB Browser Data Types

The

snmp_request

Table 4–3. These values apply to

and

ﬂag) and listening for a reply (for the-i) ﬂag. The default is

-r

ﬂag nor the-iﬂag are

request-typeisGetNextorGetBulk

-l

ﬂag. Directs the agent to perform a MIB walk for the

variable_name

and

-v1

-v 2c

to send a message to an SNMP Version 1 agent or

snmp_trapsnd

Set

as its root. The program reads and prints

, the version defaults to SNMP Version 2.

snmp_request

program waits for a

commands support the data types listed in

requests only.

-t

Table 4–3 Data Types for the snmp_request and snmp_trapsnd Commands

Data Type Value

Counter Counter64 Display string Gauge Integer IP address NULL Object identiﬁer Octet Opaque string Time ticks

For support of trap sender program (TCPIP$SNMP_TRAPSND.EXE) only. Properly deﬁned, MIB

variables of type Counter64 are not writable.

-c

-l

-D

-g

-i

-a

-N

-d

-o

-q

-t

Using the SNMP Utilities 4–5

Using the SNMP Utilities

4.1 Using the MIB Browser

Except for-l(Counter64), the data types are case sensitive. To preserve uppercase for display strings and NULL, enclose the value in double quotation marks. For example, ‘‘–D’’ or ‘‘–N’’.

On OpenVMS Alpha systems, you must specify the value of the-ldata type as a 64-bit integer. For example:

$ snmp_trapsnd 0.0 mynode 6 33 100 -h mynode -v2c _$ 1.3.6.1.2.1.1.4.0 "l" 1311768467294899695

On OpenVMS VAX systems, you must specify the value of the-ldata type as a 16-digit hexadecimal value. For example:

$ snmp_trapsnd 0.0 mynode 6 33 100 -h mynode -v2c _$ 1.3.6.1.2.1.1.4.0 "l" 0x1234567890ABCDEF

Note that alphabetic characters are not case sensitive when used with the-ldata type.

For more information about the data types, see RFCs 1155 and 1902.

Note

4.1.4 Command Examples for snmp_request

This section presents several examples of using the following

• The valid host name is

• The

• The command responses have been edited for readability.

Examples

1. The following example shows how to retrieve the value of the MIB II variable

snmp_request

command examples:

marley.dec.com "public" "address_list"

the host on which the

location

TCPIP> SET CONFIGURATION SNMP _TCPIP> /LOCATION=(FIRST="Falcon Building",SECOND="Los Angeles, CA")

sysDescr.0 (1.3.6.1.2.1.1.1.0)

(

variable_name

OID is returned by the subagent code that resides in the master agent.

$ snmp_request marley.dec.com "public" get 1.3.6.1.2.1.1.1.0

1.3.6.1.2.1.1.1.0 = marley.dec.com AlphaServer 2100 4/200 OpenVMS V7.1 Digital TCP/IP Services for OpenVMS

community is type Read, address 0.0.0.0.

community is type Read and Write, with write access for

snmp_request

has been speciﬁed as shown in the following command:

. The request is successful because the OID

) provided in the command line exists and is readable. This

snmp_request

program is running.

utility. In the

2. The following example shows how to retrieve two MIB II variables. This example is identical to the previous example, except that two OID values are input and two returned: instance 1 of that the ﬁrst value comes from the MIB II subagent (TCPIP$OS_MIBS) and the second comes from the Host Resources MIB subagent (TCPIP$HR_MIB).

4–6 Using the SNMP Utilities

ifDescr

and

hrSystemUptime

. Note

Using the SNMP Utilities

4.1 Using the MIB Browser

$ snmp_request marley.dec.com "public" get 1.3.6.1.2.1.2.2.1.2.1 _$ 1.3.6.1.2.1.25.1.1.0

1.3.6.1.2.1.2.2.1.2.1 = LO IP Interface: LO0, OpenVMS Adapter: <none>,

Loopback Port

1.3.6.1.2.1.25.1.1.0 = 6024942 = 0 d 16:44:9

3. The following example shows how to retrieve the next MIB II variable. This is similar to the command in example 1, except that a issued and

$ snmp_request marley.dec.com "public" getnext 1.3.6.1.2.1.1.1.0

1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1

sysObjectID.0

(1.3.6.1.2.1.1.2.0) is returned.

GetNext

request is

4. The following example shows how to use the SNMP Version 2 request to retrieve the MIB II variables

sysDescr.0 ifDescr

preﬁx 1.3.6.1.2.1.2.2.1.3).

$ snmp_request marley.dec.com "public" getbulk -n 2 -m 3 _$ 1.3.6.1.2.1.1.1 1.3.6.1.2.1.1.2 _$ 1.3.6.1.2.1.2.2.1.1 1.3.6.1.2.1.2.2.1.2 1.3.6.1.2.1.2.2.1.3

Warning: using version SNMPv2 for getbulk command.

1.3.6.1.2.1.1.1.0 = marley.dec.com AlphaStation 255/300

OpenVMS V7.1 Digital TCP/IP Services for OpenVMS

1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1

1.3.6.1.2.1.2.2.1.1.1 = 1

1.3.6.1.2.1.2.2.1.2.1 = LO IP Interface: LO0, OpenVMS Adapter: <none>,

Loopback Port

1.3.6.1.2.1.2.2.1.3.1 = 24

1.3.6.1.2.1.2.2.1.1.3 = 3

1.3.6.1.2.1.2.2.1.2.3 = WE IP Interface: WE0, OpenVMS Adapter: EWA0:,

PCI bus Ethernet Adapter

1.3.6.1.2.1.2.2.1.3.3 = 6

1.3.6.1.2.1.2.2.1.1.4 = 4

1.3.6.1.2.1.2.2.1.2.4 = WF IP Interface: WF0, OpenVMS Adapter: FWA0:,

DEFPA PCI bus FDDI Adapter

1.3.6.1.2.1.2.2.1.3.4 = 15

5. The following example shows how to use the (loop) ﬂag to retrieve all OIDs starting at the ﬁrst instance after the OID input and ﬁnishing at the end of the MIB view. Note that if an SNMP Version 2 agent is the server, the results using general, SNMP Version 1 agents do not support

(1.3.6.1.2.1.1.2.0), and for the ﬁrst three interfaces, the values of

(OIDs with the preﬁx 1.3.6.1.2.1.2.2.1.2) and

sysUpTime.0

(1.3.6.1.2.1.1.1.0) and

ifType

GetNext

getbulk

request with the

are identical (in

GetBulk

(OIDs with the

requests).

-l

$ snmp_request marley.dec.com "public" getnext -l 1.3.6.1.2.1.1.1.0

1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1

1.3.6.1.2.1.1.3.0 = 1280260 = 0 d 3:33:22

1.3.6.1.2.1.1.4.0 = Sam Spade

1.3.6.1.2.1.1.5.0 = marley.dec.com

1.3.6.1.2.1.1.6.0 = Falcon BuildingLos Angeles, CA

1.3.6.1.2.1.1.7.0 = 72

1.3.6.1.2.1.1.8.0 = 0 = 0 d 0:0:0 . . .

1.3.6.1.2.1.25.5.1.1.2.294 = 560

1.3.6.1.2.1.25.5.1.1.2.295 = 472

1.3.6.1.6.3.1.1.6.1.0 = 1296505215

- no such name - returned for variable 1

Using the SNMP Utilities 4–7

Using the SNMP Utilities

4.1 Using the MIB Browser

6. The following example uses the same command as in example 5, but it speciﬁes the-tﬂag instead of the-lﬂag. Only OIDs with the preﬁx matching the input OID are returned. Note that as with other request examples, the value for the input OID is not returned. If an SNMP Version 2 agent is the server, the results using

$ snmp_request marley.dec.com "public" getnext -t 1.3.6.1.2.1.1

1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1

1.3.6.1.2.1.1.3.0 = 1302232 = 0 d 3:37:2

1.3.6.1.2.1.1.4.0 = Sam Spade

1.3.6.1.2.1.1.5.0 = marley.dec.com

1.3.6.1.2.1.1.6.0 = Falcon BuildingLos Angeles, CA

1.3.6.1.2.1.1.7.0 = 72

1.3.6.1.2.1.1.8.0 = 0 = 0 d 0:0:0

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 = 0 = 0 d 0:0:0

1.3.6.1.2.1.1.9.1.4.2 = 0 = 0 d 0:0:0

getbulk

getnext

are identical.

7. The following example shows how to send a because the command line speciﬁes the correct type for the variable, and all the conditions for enabling

$ snmp_request marley.dec.com "address_list" _$ set 1.3.6.1.2.1.1.4.0 "D" "Richard Blaine"

1.3.6.1.2.1.1.4.0 = Richard Blaine

8. The following example shows how to display the contents of packets that are sent and received. Note that only the SNMP-speciﬁc portion of the UDP packets is displayed.

$ snmp_request marley.dec.com "public" get -d 1.3.6.1.2.1.1.4.0 Sent:

3082002D 02010004 06707562 6C6963A0 0..-.....public.

2002047B E9C1BD02 01000201 00308200 ..{.........0..

10308200 0C06082B 06010201 01040005 .0.....+........

00 .

Received:

3082003B 02010004 06707562 6C6963A2 0..;.....public.

2E02047B E9C1BD02 01000201 00308200 ...{.........0..

1E308200 1A06082B 06010201 01040004 .0.....+........

0E526963 68617264 20426C61 696E65 .Richard Blaine

1.3.6.1.2.1.1.4.0 = Richard Blaine

Set

requests are met on the server.

Set

request. The request succeeds

4.2 Using the Trap Sender and Trap Receiver Programs

TCP/IP Services provides the following programs that allow you to set up a simple client on your system to send and receive trap messages:

•

snmp_trapsnd

Sends SNMP Version 1 and SNMP Version 2 trap messages. Use only for testing or to send signiﬁcant state changes that occur on the managed node.

snmp_traprcv

• Listens for SNMP trap messages and displays any it receives.

4–8 Using the SNMP Utilities

(TCPIP$SNMP_TRAPSND.EXE)

(TCPIP$SNMP_TRAPRCV.EXE)

4.2 Using the Trap Sender and Trap Receiver Programs

By default, these programs use UDP port 162. However, you can specify another port with the-pﬂag or set up an SNMP-trap service that speciﬁes the port you want to use. Note, however, that the use of UDP port 162 is coded into standard MIBs.

Both programs support the use of the UDP (default) and TCP transports. However, the standard TCP/IP subagents and the Chess example use UDP only. Therefore, if you specify the command, the program uses TCP to process traps only from the trap sender program or from a user application written to use TCP.

The following sections explain how to enter commands for both programs. Because ﬂags and data types are case sensitive, you should always enter them in the case that is speciﬁed. If a letter or value is speciﬁed as uppercase, you must enclose it in quotation marks. In general, if you use uppercase letters where lowercase is speciﬁed, the results are unpredictable. For example, ﬂag functions correctly but ﬂag be lowercase.

"-V2c"

-tcp

ﬂag when you enter the

does not, because the ﬂag character (v) must

4.2.1 Entering Commands for the Trap Sender Program

The trap sender program lets you send SNMP Version 1 and SNMP Version 2 trap messages. You should use this program only when you want to test the client or when signiﬁcant state changes occur on the managed node.

Using the SNMP Utilities

snmp_traprcv

"-v2C"

The trap sender program encodes an SNMP Version 1 trap PDU (see RFCs 1155, 1156, 1157, and 1215) or an SNMP Version 2 trap PDU (see RFCs 1905 and 1908) into an SNMP message and sends it to the speciﬁed hosts. You use parameters and ﬂags to specify the data ﬁelds in the trap PDU.

Traps are uniquely identiﬁed in the PDU:

• SNMP Version 1 is identiﬁed by a combination of parameters.

• SNMP Version 2 is identiﬁed by the value of

To run the trap sender program, do the following:

1. Deﬁne a foreign command for the program:

$ snmp_trapsnd == "$SYS$SYSTEM:TCPIP$SNMP_TRAPSND"

Alternatively, you can run the SYS$MANAGER:TCPIP$DEFINE_ COMMANDS.COM procedure to deﬁne all the foreign commands available with TCP/IP Services.

2. Enter a command using the following format:

snmp_trapsnd enterprise agent generic-trap specific-trap timeticks [-v version] [-c community] [-d] [-h host] [-p port] [-tcp] [variable_name [data-type value]]

4.2.1.1 Trap Sender Parameters

Table 4–4 describes the but you can specify zero, as appropriate.

snmp_trapsnd

parameters. Each parameter is required,

snmpTrapOID

Using the SNMP Utilities 4–9

Using the SNMP Utilities

4.2 Using the Trap Sender and Trap Receiver Programs

Table 4–4 Parameters for the snmp_trapsnd Command

Parameter Description

enterprise

agent

generic-trap

For SNMP Version 1, speciﬁes the enterprise object identiﬁer (OID) on whose behalf the trap is being sent. For example, 1.3.6.1.4.1.1. If you specify 0 or 0.0, the null OID (0.0) is sent. Make sure that any OID you specify conforms to the OID rules.

-v2c

For SNMP Version 2, when speciﬁed with the

snmpTrapOID.0

For SNMP Version 1 traps. Speciﬁes the host name or IP address of the entity on whose behalf the trap is being generated. You can specify the name is the same as specifying 0, 0.0, 0.0.0, or 0.0.0.0. In these cases, the address

0.0.0.0 is sent as the agent address in the SNMP Version 1 trap PDU.

-v2c

If the For SNMP Version 1, speciﬁes the generic trap identiﬁer in the form of a number.

Must be one of the following values:

SNMP Version 1 Value Object

ﬂag is speciﬁed, this parameter is ignored.

ﬂag, represents the value of

local

, which

0 coldStart 1 warmStart 2 linkDown 3 linkUp 4 authenticationFailure 5 egpNeighborLoss 6 enterpriseSpecific

For SNMP Version 2, when the contain a valid OID or 0 as the value of

specific-trap

timeticks

variable_name | data-type value

For SNMP Version 1, speciﬁes the enterprise-speciﬁc trap number. A numeric value greater than 0 must be present but is ignored if the

generic-trap

if Speciﬁes the timestamp value associated with the generation of the trap

message. The timestamp value is the current time in units of TIMETICKS (1/100 of a second) since the sending SNMP entity started. A value of 0 causes

snmp_trapsnd

system was last booted. Speciﬁes a list of MIB variables to be included in the trap message. For a list of

supported values, including a value for the

is a value other than 6 (

to send the time in hundredths of a second since the operating

4.2.1.2 Trap Sender Flags

Table 4–5 describes the

snmp_trapsnd

Table 4–5 Flags for the snmp_trapsnd Command

Flag Description

-c community

-d

Speciﬁes a community string to be used when sending the trap. The default is public.

Displays a hexadecimal dump of the encoded packet.

-v2c

ﬂag is speciﬁed, this parameter must

snmpTrapOID

-v2c

enterpriseSpecific

Counter64

ﬂags.

data type, see Table 4–3.

(continued on next page)

ﬂag is present or

4–10 Using the SNMP Utilities

4.2 Using the Trap Sender and Trap Receiver Programs

Table 4–5 (Cont.) Flags for the snmp_trapsnd Command

Flag Description

Using the SNMP Utilities

-h host

-p port

-tcp

Speciﬁes the host name or IP address (in ASN.1 dot notation format) of the destination host to receive the trap message. The default is (127.0.0.1).

Speciﬁes a port number on the destination host where the message is to be sent. The default is UDP 162.

Speciﬁes that the TCP transport be used instead of the default UDP transport. If a connection cannot be established, the program displays the warning

connect - : connection refused

-v version

4.2.1.3 Trap Sender Examples

In the following

• The ﬁrst line is the

• The remainder is the display received when running the trap receiver

1. The following example generates a trap that originated on the

Speciﬁes the SNMP version to use for sending the PDU. The valid versions are or1(default). You can specify the ﬂag and value without including a space (for example,

program (

(speciﬁed by the Version 1). The the local host.

$ snmp_trapsnd 0.0 local 0 0 0 Message received from 127.0.0.1 SNMPv1-Trap-PDU: community - 7075626C 6963 public enterprise - 0.0

agent address - 0.0.0.0 trap type - Cold Start (0) timeticks - 51938978

snmp_traprcv

-v2c

and

-v1

snmp_trapsnd

command examples:

snmp_trapsnd

) without ﬂags included.

agent

-h host

parameter) using the default SNMP version (SNMP

parameter is not speciﬁed, so the trap will be sent to

localhost

command.

localhost

2. The following example generates the same trap as in example 1, except that it speciﬁes the use of SNMP Version 2.

$ snmp_trapsnd 0.0 local 0 0 0 "-v2c" Message received from 127.0.0.1 SNMPv2-Trap-PDU: community - 7075626C 6963 public sysUpTime.0 - 51938968 = 6 d 0:16:29

snmpTrapOID.0 - 0.0

3. The following example sends values to the node name

special

$ snmp_trapsnd 1.2.3 marley.dec.com 6 33 100 -c special -h mynode Message received from 16.20.208.68 SNMPv1-Trap-PDU:

community - 73706563 69616c special

mynode

with the community

Using the SNMP Utilities 4–11

Using the SNMP Utilities

4.2 Using the Trap Sender and Trap Receiver Programs

enterprise - 1.2.3 agent address - 6.20.208.53 trap type - Enterprise-specific (6) enterprise-specific value - (33) timeticks - 100

4.2.2 Entering Commands for the Trap Receiver Program

The trap receiver program lets you listen for, receive, and display SNMP trap messages. Until interrupted, the program continues to listen on the speciﬁed port.

If you enter commands using the default port number or another privileged port number, you must run the program from a privileged account.

To run the trap receiver program, do the following:

1. Deﬁne a foreign command for the program:

$ snmp_traprcv == "$SYS$SYSTEM:TCPIP$SNMP_TRAPRCV"

Alternatively, you can run SYS$MANAGER:TCPIP$DEFINE_ COMMANDS.COM to deﬁne all the foreign commands available with TCP/IP Services.

2. Enter a command using the following format:

snmp_traprcv [-d] [-tcp] [-p port]

4.2.2.1 Trap Receiver Flags

Table 4–6 describes the

Table 4–6 snmp_traprcv Command Flags

Flag Description

-d

-p port

-tcp

4.2.2.2 Setting Up an SNMP Trap Service

To set up an SNMP trap service for use with the trap receiver program, enter a management command in the following format:

SET SERVICE SNMP-TRAP /PROTOCOL=UDP /USER_NAME=TCPIP$SNMP /PROCESS_NAME=TCPIP$SNMP-TRAP /FILE=TCPIP$SYSTEM:TCPIP$SNMP-TRAP.COM

In this command, port 170 is used as an alternative for port 162, and traps that are received on port 162 are ignored.

If you omit the /PROTOCOL qualiﬁer or you use /PROTOCOL=TCP, the service uses the TCP transport. In this case, when you enter a command to run the trap receiver program, you must include the

Displays a hexadecimal and formatted dump of the received packet. Speciﬁes the port number on the local host on which to listen for trap

messages. The default is 162. Listens on the TCP port instead of the UDP (default) port. Reads only

a single PDU on an established connection, which is similar to the behavior using UDP.

snmp_traprcv

ﬂags.

-tcp

ﬂag.

With the SNMP trap service in place, the trap receiver program queries the service for the port number instead of using the default port 162. If you specify a privileged port number (less than 1024) with the /PORT qualiﬁer, make sure you install the trap receiver program with privileges, or run the program from an

4–12 Using the SNMP Utilities

4.2 Using the Trap Sender and Trap Receiver Programs

account that has SYSPRV privilege. Note that the port number must be greater than zero.

4.2.2.3 Trap Receiver Examples

1. The following example requests trap information on a system that does not have traps conﬁgured and does not have SYSPRV privilege or sufﬁcient privilege.

$ snmp_traprcv No snmp-trap service entry, using default port 162. bind - : permission denied

2. The example, supplied from a nonprivileged account, requests trap information in hexadecimal dump format on port 1026.

$ snmp_traprcv -d -p 1026 Message received from 127.0.0.1

3082002A 02010004 06707562 6C6963A4 0..*.....public.

1D060547 81AD4D01 40040000 00000201 ...G..M.@.......

00020100 4304032D AED23082 0000 ....C..-..0...

SNMPv1-Trap-PDU: community - 7075626C 6963 public enterprise - 0.0

agent address - 0.0.0.0 trap type - Cold Start (0) timeticks - 53325522

Using the SNMP Utilities

Using the SNMP Utilities 4–13

This chapter provides reference information about the following types of application programming interface (API) routines in the eSNMP developer’s kit:

• Interface routines (Section 5.1)

• Method routines (Section 5.2)

• Support routines (Section 5.3)

5.1 Interface Routines

The interface routines are for developers writing the portion of the application programming interface (API) that handles the connection between the agent and the subagent. The interface routines are listed Table 5–1 and described in the following pages.

Table 5–1 Interface Routines

Routine Function

eSNMP API Routines

esnmp_init

esnmp_register esnmp_unregister esnmp_register2 esnmp_unregister2 esnmp_capabilities

esnmp_uncapabilities

esnmp_poll esnmp_are_you_there

esnmp_trap esnmp_term esnmp_sysuptime

Initializes the subagent and initiates communication with the master agent.

Requests local registration of a MIB subtree. Cancels local registration of a MIB subtree. Requests cluster registration of a MIB subtree. Cancels cluster registration of a MIB subtree. Adds a subagent’s capabilities to the master agent’s

sysORTable

Removes a subagent’s capabilities from the master agent’s

sysORTable

Processes a pending request from the master agent. Requests a report from the master agent to indicate it is up

and running. Sends a trap message to the master agent. Sends a close message to the master agent. Converts UNIX system time into a value with the same

time base as

sysUpTime

eSNMP API Routines 5–1

eSNMP API Routines esnmp_init

esnmp_init

Initializes the Extensible SNMP (eSNMP) subagent and initiates communication with the master agent.

Format

int esnmp_init (int *socket,

Arguments

socket

The address of the integer that receives the socket descriptor used by eSNMP.

subagent_identiﬁer

The address of a null-terminated string that uniquely identiﬁes this subagent (usually a program name).

Description

char *subagent_identiﬁer );

Call this routine during program initialization or to restart the eSNMP protocol. If you are restarting, the subtree must be registered again.

You should attempt to create a unique subagent identiﬁer, perhaps using the program name not open communications with a subagent whose subagent identiﬁer is already in use.

This routine does not block waiting for a response from the master agent. After calling the that is to be handled by the subagent.

Return Values

ESNMP_LIB_NO_ CONNECTION

ESNMP_LIB_OK The

ESNMP_LIB_NOTOK Could not allocate memory for the subagent.

Example

argv[0]

esnmp_init

routine, call the

esnmp_init

and additional descriptive text. The master agent does

routine clears all registrations so each

esnmp_register

Could not initialize or communicate with the master agent. Try again after a delay.

esnmp_init

successfully.

#include <esnmp_h> int socket; status = esnmp_init(&socket, "gated");

routine for each subtree

routine has completed

5–2 eSNMP API Routines

esnmp_register

Requests local registration of a single MIB subtree. This indicates to the master agent that the subagent instantiates MIB variables within the registered MIB subtree.

Format

int esnmp_register ( subtree *subtree,

Arguments

subtree

A pointer to a subtree structure corresponding to the subtree to be handled. The code emitted by the MIB compiler ﬁles (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures. Refer to Chapter 3 for more information about these ﬁles.

eSNMP API Routines

esnmp_register

int timeout, int priority );

Note

Description

All memory pointed to by the subtree ﬁelds must have permanent storage since it is referenced by should use the data declarations emitted by the MIBCOMP program.

timeout

The number of seconds the master agent should wait for responses when requesting data in this subtree. This value must be between 0 (zero) and

300. If the value is 0, the default timeout is 3 seconds. Compaq recommends

that you use the default. For information about modifying the default subagent timeout value, refer to Section 6.2.

priority

The registration priority. The priority argument allows you to coordinate cooperating subagents to handle different conﬁgurations. The range is 1 to

255.

The entry with the largest number has the highest priority. The subagent that registers a subtree with the highest priority over a range of object identiﬁers gets all requests for that range of

Subtrees registered with the same priority are considered duplicate, and the registration is rejected by the master agent.

libesnmp

OIDs

for the duration of the program. You

Call the initialization routine Call the each subtree to be handled. At any time, subtrees can be unregistered by calling

esnmp_unregister

When restarting the eSNMP protocol by calling cleared. All subtrees must be reregistered.

esnmp_register

and then be reregistered by calling the

esnmp_init

function for each subtree structure corresponding to

prior to calling the

esnmp_register

esnmp_init

eSNMP API Routines 5–3

esnmp_register

, all registrations are

eSNMP API Routines esnmp_register

A subtree is identiﬁed by the base MIB name and the corresponding of the node that is the parent of all MIB variables contained in the subtree. For example: The MIB II subordinate to this have the same ﬁrst seven digits and are included in the subtree’s object table. The subtree can also be a single MIB object (a leaf node) or even a speciﬁc instance.

By registering a subtree, the subagent indicates that it will process eSNMP requests for all MIB variables (or a subagent should register the most fully qualiﬁed (longest) subtree that still contains its instrumented MIB variables.

The master agent does not permit a subagent to register the same subtree more than once. However, subagents can register subtrees with ranges that overlap the

OID

ranges of subtrees previously registered, and subagents can also register

subtrees registered by other subagents. For example, TCP/IP Services supports MIB II. In the eSNMP environment, the

os_mibs

TCP/IP Services also provides the

ipRouteEntry

These MIBs are registered at priority 1. Any subagent that registers at a higher priority (greater than 1) overrides these registrations.

A request for subagent. Requests for otheripvariables, such as

1.3.5.1.2.1.4.22.1.1) are passed to the

terminates or unregisters the

subagent registers the MIB II subtreeip(OID 1.3.6.1.2.1.4).

MIB subtree (OID 1.3.6.1.2.1.4.21.1).

IpRouteIfIndex

ipRouteIfIndex

subtree, which includes all region of requests for

tcp

subtree has an

will go to the

ipRouteEntry

ipRouteIfIndex

OIDof1.3.6.1.2.1.6

OIDs

) within that subtree’s range. Therefore,

gated

(OID 1.3.5.1.2.1.4.21.1.2) is passed to the

subagent, which registers the

ipNetToMediaIfIndex

os_mibs

ipRouteEntry

os_mibs

subagent. This occurs because the

subagent. If the

subtree, subsequent requests for

variables, is now the authoritative

OID

number

. All elements

gated

(OID

gated

subagent

Return Values

SNMP_LIB_OK The

ESNMP_LIB_BAD_REG The

ESNMP_LIB_LOST_ CONNECTION

Note that the return value indicates only the initiation of the request. The actual status returned in the master agent’s response will be returned in a subsequent call to the the

state

ﬁeld.

esnmp_register

successfully.

esnmp_init

timeout parameter is invalid, or the subtree has already been queued for registration.

The subagent has lost communications with the master agent.

routine has completed

routine has not been called, the

esnmp_poll

routine in

Example

#include <esnmp.h> #define RESPONSE_TIMEOUT 0 /* use the default time set

#define REGISTRATION_PRIORITY 10 /* priority at which subtrees

int status; extern SUBTREE ipRouteEntry_subtree;

in OPEN message */ will register */

5–4 eSNMP API Routines

eSNMP API Routines

esnmp_register

status = esnmp_register( &ipRouteEntry_subtree,

if (status != ESNMP_LIB_OK) {

printf ("Could not queue the ’ipRouteEntry’ \n"); printf ("subtree for registration\n");

}

RESPONSE_TIMEOUT, REGISTRATION_PRIORITY );

eSNMP API Routines 5–5

eSNMP API Routines esnmp_unregister

esnmp_unregister

Cancels registration of a MIB subtree previously registered with the master agent.

Format

int esnmp_unregister ( SUBTREE *subtree );

Arguments

subtree

Description

This routine can be called by the application code to tell the eSNMP subagent not to process requests for variables in this MIB subtree anymore. You can later reregister a MIB subtree, if needed, by calling the

esnmp_register

routine.

Return Values

SNMP_LIB_OK The

ESNMP_LIB_BAD_REG The MIB subtree was not registered. ESNMP_LIB_LOST_

CONNECTION

Example

esnmp_unregister

successfully.

The request to unregister the MIB subtree could not be sent. You should restart the protocol.

#include <esnmp.h> int status

extern SUBTREE ipRouteEntry_subtree; status = esnmp_unregister (&ipRouteEntry_subtree); switch (status) {

case ESNMP_LIB_OK:

printf ("The esnmp_unregister routine completed successfully.\n"); break;

case ESNMP_LIB_BAD_REG:

printf ("The MIB subtree was not registered.\n");

case ESNMP_LIB_LOST_CONNECTION:

printf ("%s%s%s\n", "The request to unregister the ",

"MIB subtree could not be sent. ", "You should restart the protocol.\n");

break; }

routine has completed

5–6 eSNMP API Routines

esnmp_register2

Requests registration of a single MIB subtree. This indicates to the master agent that the subagent instantiates MIB variables within the registered MIB subtree. The

esnmp_register2

Format

int esnmp_register2 ( ESNMP_REG *reg );

Arguments

reg

A pointer to an ESNMP_REG structure that contains the following ﬁelds:

Field Name Description

subtree A pointer to a subtree structure corresponding to the

priority The registration priority. The entry with the largest

timeout The number of seconds the master agent should wait

range_subid An integer value that, when nonzero, together with

eSNMP API Routines

esnmp_register2

routine offers extensions to the

MIB subtree to be handled. The subtree structures are externally declared and initialized in the code emitted by the MIBCOMP command (subtree_TBL.C and subtree_TBL.H, where subtree is the name of the MIB subtree). This code is taken directly from the MIB document.

All memory pointed to by this ﬁeld must have permanent storage since it is referenced by for the duration of the program. You should use the data declarations emitted by the MIBCOMP command.

number has the highest priority. The range is 1 to 255. The subagent that has registered a MIB subtree with the highest priority over a range of object identiﬁers gets all requests for that range of OIDs.

MIB subtrees that are registered with the same priority are considered duplicates, and the registration is rejected by the master agent.

The priority ﬁeld is a mechanism for cooperating subagents to handle different conﬁgurations.

for responses when requesting data in this MIB subtree. This value must be between zero and 300. If the value is zero, the default timeout (3 seconds) is used. You should use the default. For information about modifying the default timeout value, refer to Section 6.2.

the range_upper_bound ﬁeld speciﬁes a range instead of one of the MIB subtree’s OID subidentiﬁers. The range_subid ﬁeld speciﬁes the OID subidentiﬁer modiﬁed by the range_upper_bound ﬁeld.

esnmp_register

routine.

libesnmp

eSNMP API Routines 5–7

eSNMP API Routines esnmp_register2

Field Name Description

range_upper_bound An integer value that, with a nonzero range_subid

options An integer value that, when set to

state One of the following integer values that provides

reserved This ﬁeld is reserved for exclusive use by the eSNMP

ﬁeld, speciﬁes a range instead of one of the MIB subtree’s OID subidentiﬁers. The range_upper_bound ﬁeld provides the upper bound of the range and the range_subid ﬁeld provides the lower bound of the range, which is the MIB subtree’s OID subidentiﬁer.

ESNMP_REG_OPT_CLUSTER, indicates that the registration is valid clusterwide. When the value is set to zero, it indicates that the registration is valid for the local node.

the caller with asynchronous updates of the state of registration of this MIB subtree. After the return of

esnmp_poll

the parameter.

ESNMP_REG_STATE_ PENDING

ESNMP_REG_STATE_SENT The registration was

ESNMP_REG_STATE_DONE The registration

ESNMP_REG_STATE_ REGDUP

ESNMP_REG_STATE_ REGNOCLU

ESNMP_REG_STATE_REJ The master agent

library. The caller should not modify it.

routine, the caller can inspect this

The registration is currently held locally while waiting for connection to the master agent.

sent to the master agent.

was successfully acknowledged by the master agent.

The registration was rejected by the master agent because it was a duplicate.

The master agent does not support cluster registrations.

rejected the registration for other reasons.

Description

The initialization routine (

esnmp_register2

subtree structure corresponding to each MIB subtree that it will be handling. At any time, MIB subtrees can be unregistered by calling then can be reregistered by calling

5–8 eSNMP API Routines

esnmp_init

routine. The

) must be called prior to calling the

esnmp_register2

function must be called for each

esnmp_register2

esnmp_unregister2

and

eSNMP API Routines

esnmp_register2

When restarting the eSNMP protocol by calling registrations are cleared. All MIB subtrees must be reregistered.

A MIB subtree is identiﬁed by the base MIB variable name and its corresponding OID. This tuple represents the parent of all MIB variables that are contained in the MIB subtree; for example, the MIB II All elements subordinate to this (those that have the same ﬁrst 7 identiﬁers) are included in the subtree’s object table. A MIB subtree can also be a single MIB object (a leaf node) or even a speciﬁc instance.

By registering a MIB subtree, the subagent indicates that it will process SNMP requests for all MIB variables (or OIDs) within that MIB subtree’s region. Therefore, a subagent should register the most fully qualiﬁed (longest) MIB subtree that still contains its instrumented MIB variables.

A subagent using the subtree for the local node and for a cluster. To register the MIB subtree for both, you must call the ESNMP_REG_OPT_CLUSTER bit set in the options ﬁeld and once with the ESNMP_REG_OPT_CLUSTER bit clear in the options ﬁeld. Alternatively, you can register a MIB subtree for the cluster only or for the local node only, by setting or clearing the ESNMP_REG_OPT_CLUSTER bit, respectively, in the options ﬁeld.

A subagent can also register MIB subtrees that overlap the OID range of MIB subtrees that it previously registered or the OID ranges of MIB subtrees registered by other subagents.

esnmp_register2

tcp

routine can register the same MIB

esnmp_init

subtree has an OID of 1.3.6.1.2.1.6.

routine twice: once with the

, all MIB subtree

For example, consider the two subagents subagent registers theipMIB subtree (1.3.6.1.2.1.4), and the registers the registrations are made with the ESNMP_REG_OPT_CLUSTER bit set in the options ﬁeld. Requests foripMIB variables within

ipRouteIfIndex

for otheripvariables, such as passed to the the the all

ipRouteIfIndex

Return Values

SNMP_LIB_OK The

ESNMP_LIB_BAD_REG The

ESNMP_LIB_LOST_ CONNECTION

ipRouteEntry

(1.3.6.1.2.1.4.21.1.2), are passed to the

os_mibs ipRouteEntry os_mibs

ipRouteEntry

subagent. This occurs because theipMIB subtree, which includes

MIB variables, is now the authoritative region of requests for

os_mibs

MIB subtree (1.3.6.1.2.1.4.21.1). Both of these

and

ipRouteEntry

ipNetToMediaIfIndex

subagent. If the

MIB subtree, subsequent requests for

gated

subagent terminates or unregisters

(1.3.6.1.2.1.4.22.1.1), are

esnmp_register2

successfully.

esnmp_init

timeout

is not available, or this MIB subtree has already been queued for registration. A message is also in the log ﬁle.

The subagent lost communication with the master agent.

parameter is invalid, a registration slot

routine has not been called, the

gated

. The

os_mibs

gated

subagent. Requests

ipRouteIfIndex

routine has completed

subagent

, such as

go to

Note that the return value indicates only the initiation of the request. The actual status returned in the master agent’s response will be returned in a subsequent call to the

esnmp_poll

routine in the

state

ﬁeld.

eSNMP API Routines 5–9

eSNMP API Routines esnmp_register2

Example

#include <esnmp.h> #define RESPONSE_TIMEOUT 0 /* use the default time set

#define REGISTRATION_PRIORITY 10 /* priority at which the MIB #define RANGE_SUBID 7 /* the identifier position in #define RANGE_UPPER_BOUND 8 /* the identifier for egp, int status

extern SUBTREE ip_subtree; static ESNMP_REG esnmp_reg_for_ip2egp; /* retain this structure for

* initialize the ESNMP_REG structure

*/ memset(&esnmp_reg_for_ip2egp, 0, sizeof(ESNMP_REG)); esnmp_reg_for_ip2egp.subtree = &ip_subtree; esnmp_reg_for_ip2egp.priority = REGISTRATION_PRIORITY; esnmp_reg_for_ip2egp.timeout = RESPONSE_TIMEOUT; esnmp_reg_for_ip2egp.range_subid = RANGE_SUBID; esnmp_reg_for_ip2egp.range_upper_bound = RANGE_UPPER_BOUND;

status = esnmp_register2( &esnmp_reg_for_ip2egp ); if (status != ESNMP_LIB_OK) {

printf("Could not queue the ’ipRouteEntry’ \n"); printf("subtree for registration\n");

}

in esnmp_init message */ subtree will register */ oid->elements just after mib-2 */ under mib-2 */

a subsequent call to esnmp_unregister2 */

5–10 eSNMP API Routines

esnmp_unregister2

Cancels registration of a MIB subtree previously established with the master agent. Use this routine only when the MIB subtree was registered using the

esnmp_register2

Format

int esnmp_unregister2 ( ESNMP_REG *reg );

Arguments

reg

A pointer to the ESNMP_REG structure that was used when the

esnmp_register2

Description

This routine can be called by the application code to tell the eSNMP subagent to no longer process requests for variables in this MIB subtree. You can later reregister a MIB subtree, if needed, by calling the

routine.

routine was called.

eSNMP API Routines

esnmp_unregister2

esnmp_register2

routine.

Return Values

ESNMP_LIB_OK The routine completed successfully. ESNMP_LIB_BAD_REG The MIB subtree was not registered. ESNMP_LIB_LOST_

CONNECTION

Example

The request to unregister the MIB subtree could not be sent. You should restart the protocol.

#include <esnmp.h> int status

extern ESNMP_REG esnmp_reg_for_ip2egp; status = esnmp_unregister2( &esnmp_reg_for_ip2egp ); switch(status) {

case ESNMP_LIB_OK: printf("The esnmp_unregister2 routine completed successfully.\n"); break;

case ESNMP_LIB_BAD_REG: printf("The MIB subtree was not registered.\n"); break;

case ESNMP_LIB_LOST_CONNECTION: printf("%s%s%s\n", "The request to unregister the ",

"MIB subtree could not be sent. ", "You should restart the protocol.\n");

break;

}

eSNMP API Routines 5–11

eSNMP API Routines esnmp_capabilities

esnmp_capabilities

Format

Arguments

Description

Adds a subagent’s capabilities to the master agent’s is a conceptual table that contains an agent’s object resources, and is described in RFC 1907.

void esnmp_capabilities ( OID *agent_cap_id,

char *agent_cap_descr );

agent_cap_id

A pointer to an object identiﬁer that represents an authoritative agent capabilities identiﬁer. This value is used for the managed node.

agent_cap_descr

A pointer to a null-terminated character string describing value is used for the

This routine is called at any point after initializing eSNMP by a call to the

esnmp_init

routine.

sysORDescr

sysORID

object in the

sysORTable

for the managed node.

. The

sysORTable

agent_cap_id

for the

. This

5–12 eSNMP API Routines

esnmp_uncapabilities

eSNMP API Routines

esnmp_uncapabilities

Format

Arguments

Description

Removes a subagent’s capabilities from the master agent’s

void esnmp_uncapabilities ( OID *agent_cap_id );

agent_cap_id

A pointer to an object identiﬁer that represents an authoritative agent capabilities identiﬁer. This value is used for the managed node.

This routine is called if a subagent alters its capabilities dynamically. When a logical connection for a subagent is closed, the master agent automatically removes the related entries in

sysORTable

sysORID

object in the

sysORTable

for the

eSNMP API Routines 5–13

eSNMP API Routines esnmp_poll

esnmp_poll

Processes a pending message that was sent by the master agent.

Format

int esnmp_poll ( )

Description

This routine is called after the the eSNMP socket. (This socket was returned from the call to the routine.)

If a received message indicates a problem, an entry is made to the SNMP log ﬁle and an error status is returned.

If the received message is a request for SNMP data, the object table is checked and the appropriate method routines are called, as deﬁned by the developer of the subagent.

Return Values

ESNMP_LIB_OK The ESNMP_LIB_BAD_REG The master agent failed in a previous

ESNMP_LIB_DUPLICATE A duplicate subagent identiﬁer has already been

ESNMP_LIB_NO_ CONNECTION

ESNMP_LIB_CLOSE A ESNMP_LIB_NOTOK An eSNMP protocol error occurred and the

ESNMP_LIB_LOST_ CONNECTION

select( )

call has indicated data is ready on

esnmp_init

esnmp_poll

registration attempt. See the log ﬁle.

received by the master agent. The master agent’s

the connection after a delay. See the log ﬁle.

packet was discarded. Communication with the master agent was lost.

Restart the connection.

message was received.

routine completed successfully.

OPEN

request failed. Restart

5–14 eSNMP API Routines

esnmp_are_you_there

Requests the master agent to report immediately that it is up and functioning.

Format

int esnmp_are_you_there ( ) ;

Description

The

esnmp_are_you_there

routine is intended to cause the master agent to reply immediately. The response should be processed by calling the

If a response is not received within the timeout period, the application code should restart the eSNMP protocol by calling the are maintained by the eSNMP library.

Return Values

ESNMP_LIB_OK The request was sent. ESNMP_LIB_LOST_

CONNECTION

eSNMP API Routines

esnmp_are_you_there

routine does not block waiting for a response. The

esnmp_poll

The request cannot be sent because the master agent is down.

routine.

esnmp_init

routine. No timers

eSNMP API Routines 5–15

eSNMP API Routines esnmp_trap

esnmp_trap

Sends a trap message to the master agent.

Format

int esnmp_trap ( int *generic_trap,

Arguments

generic_trap

A generic trap code. Set this argument value to 0 (zero) for SNMPv2 traps.

speciﬁc_trap

A speciﬁc trap code. Set this argument value to 0 (zero) for SNMPv2 traps.

enterprise

An enterprise the NOTIFICATION-TYPE macro in the deﬁning MIB speciﬁcation. This value is passed as the value of SnmpTrapOID.0 in the SNMPv2-Trap-PDU.

int speciﬁc_trap, char *enterprise, varbind *vb )2;

OID

string in dot notation. Set to the object identiﬁer deﬁned by

A VARBIND list of data (a null pointer indicates no data).

Description

This function can be called any time. If the master agent is not running, traps are queued and sent when communication is possible.

The trap message is actually sent to the master agent after it responds to the

esnmp_register

agent is to call the The master agent formats the trap into an SNMP trap message and sends it to

management stations based on its current conﬁguration. The master agent does not respond to the content of the trap. However, the

master agent does return a value that indicates whether the trap was received successfully.

Return Values

ESNMP_LIB_OK The routine has completed successfully. ESNMP_LIB_LOST_

CONNECTION ESNMP_LIB_NOTOK Something failed and the message could not be

esnmp_init

routine. This occurs with every API call and for most

routines. The quickest process to send traps to the master

esnmp_init, esnmp_poll

, and

esnmp_trap

Could not send the trap message to master agent.

generated.

routines.

5–16 eSNMP API Routines

esnmp_term

Sends a close message to the master agent and shuts down the subagent.

Format

void esnmp_term (void) ;

Description

Subagents must call this routine when terminating so that the master agent can update its MIB registry quickly and so that resources used by eSNMP on behalf of the subagent can be released.

Return Values

eSNMP API Routines

esnmp_term

ESNMP_LIB_OK The

LIB_OK, even if the packet could not be sent.

esnmp_term

routine always returns ESNMP_

eSNMP API Routines 5–17

eSNMP API Routines esnmp_sysuptime

esnmp_sysuptime

Converts UNIX system time obtained from same time base as

Format

unsigned int esnmp_sysuptime ( struct timeval *timestamp );

Argument

timestamp

A pointer to

gettimeofday

A null pointer means return the current

Description

This routine provides a mechanism to convert UNIX timestamps into eSNMP

TimeTicks

timestamp was This routine can be used as a

master agent started) in hundredths of a second. The time base is obtained from the master agent in response to time will not be accurate.

Return Values

gettimeofday

sysUpTime

struct timeval

system call. The structure is deﬁned in

, which contains a value obtained from the

sysUpTime

. The function returns the value that

now

TimeTicks

esnmp_init

data type (the time since the eSNMP

, so calls to this function before that

into a value with the

include/sys/time.h

sysUpTime

held when the passed

Example

0 An error occurred because a

function failed. Otherwise, the time in hundredths of a second since the master agent started.

#include <sys/time.h> #include <esnmp.h> struct timeval timestamp;

gettimeofday(×tamp, NULL);

. . .

o_integer(vb, object, esnmp_sysuptime(×tamp));

gettimeofday

timestamp

contains

5–18 eSNMP API Routines

5.2 Method Routines

eSNMP API Routines

5.2 Method Routines

SNMP requests may contain many encoded MIB variables. The executing in a subagent matches each entry. The object table’s method routine is then called. Therefore, a method routine is called to service a single MIB variable. Since a single method routine can handle a number of MIB variables, the same method routine may be called several times during a single SNMP request.

The method routine calling interface contains the following functions:

*_get

•

*_set

—respond to —respond to

Get,GetNext Set

requests

VariableBinding

, and

GetBulk

requests

with an object table

libsnmp

code

eSNMP API Routines 5–19

eSNMP API Routines *_get Routine

*_get Routine

The *_get routine is a method routine for the speciﬁed MIB item, which is typically a MIB group (for example, example,

Format

int mib-group_get ( METHOD *method );

Arguments

method

A pointer to a METHOD structure that contains the following ﬁelds:

Field Name Description

action One of ESNMP_ACT_GET, ESNMP_ACT_

serial_num An integer number that is unique to this SNMP

repeat_cnt Used for

max_repetitions The maximum number of repetitions to

varbind A pointer to the VARBIND structure for

ifEntry

in MIB II).

system

GETNEXT, or ESNMP_ACT_GETBULK.

request. Each method routine called while servicing a single SNMP request receives the same value of serial_num. New SNMP requests are indicated by a new value of serial_num.

the current iteration number of a repeating VARBIND. This number increments from 1 to max_repetitions and is 0 (zero) for nonrepeating VARBIND structures.

perform. Used for (zero) for nonrepeating VARBIND structures. You can optimize subsequent processing by knowing the maximum number repeat calls will be made.

which you must ﬁll in the OID and data ﬁelds. Upon entry of the method routine, the method->varbind->name ﬁeld is the OID that was requested.

Upon exit of the method routine, the method->varbind ﬁeld contains the requested data, and the method->varbind->name ﬁeld is updated to reﬂect the actual instance OID for the returned VARBIND structure.

The support routines (

o_oid

to load data. The libsnmp routine is used to update the OID in the method->varbind->name ﬁeld.

in MIB II) or a table entry (for

GetBulk

only. This value indicates

GetBulk

only. This will be 0

o_integer,o_string

, and

o_octet

) are generally used

instance2oid

5–20 eSNMP API Routines

Description

eSNMP API Routines

*_get Routine

Field Name Description

object A pointer to the object table entry for

the MIB variable being referenced. The method->object->object_index ﬁeld is this object’s unique index within the object table (useful when one method routine services many objects).

The method->object->oid ﬁeld is the OID deﬁned for this object in the MIB. The instance requested is derived by comparing this OID with the OID in the request found in the method->varbind->name ﬁeld. The

oid2instance

function is useful for this.

These types of routines call whatever routine is speciﬁed for object table identiﬁed by the registered subtree.

This function is pointed to by some number of elements of the subagent object table. When a request arrives for an object, its method routine is called. The

*_get

Return Values

ESNMP_MTHD_noError The routine completed successfully. ESNMP_MTHD_

noSuchObject ESNMP_MTHD_

noSuchInstance ESNMP_MTHD_genErr A general processing error.

method routine is called in response to a

The requested object cannot be returned or does not exist.

The requested instance of an object cannot be returned or does not exist.

Get

request.

Get

operations in the

eSNMP API Routines 5–21

eSNMP API Routines *_set Routine

*_set Routine

The

*_set

group (for example, MIB II).

Format

int mib-group_set ( METHOD *method );

Arguments

method

A pointer to a METHOD structure that contains the following ﬁelds:

Field Name Description

action One of ESNMP_ACT_SET,

serial_num An integer number that is unique to this SNMP

varbind A pointer to the VARBIND structure that

object A pointer to the object table entry for

ﬂags A read-only integer bitmask set by the

method routine for a speciﬁed MIB item, which is typically a MIB

system

in MIB II) or a table entry (for example,

ESNMP_ACT_UNDO, or ESNMP_ACT_ CLEANUP.

request. Each method routine called while servicing a single SNMP request receives the same value as serial_num. New SNMP requests are indicated by a new value of serial_num.

contains the MIB variable’s supplied data value and name (OID). The instance information has already been extracted from the OID and placed in the method->row->instance ﬁeld.

the MIB variable being referenced. The method->object->object-index ﬁeld is this object’s unique index within the object table (useful when one method routine services many objects).

The method->object->oid ﬁeld is the OID deﬁned for this object in the MIB.

libesnmp

IN_ROW bit indicates that this call is the ﬁrst object to be set in the row. If set, the ESNMP_ LAST_IN_ROW bit indicates that this call is the last object to be set in the row. Only METHOD structures with the ESNMP_LAST_ IN_ROW bit set are passed to the method routines for commit, undo, and cleanup phases.

routine. If set, the ESNMP_FIRST_

ifEntry

5–22 eSNMP API Routines

eSNMP API Routines

*_set Routine

Field Name Description

row A pointer to a ROW_CONTEXT structure

(deﬁned in the ESNMP.H header ﬁle). All requests to the method routine that refer to the same group and that have the same instance number will be presented with the same row structure. The method routines can accumulate information in the row structures during requests for use during the commit and undo phases. The accumulated data can be released by the method routines during the cleanup phase.

The ROW_CONTEXT structure contains the following ﬁelds:

instance An address of an array

containing the instance OID for this conceptual row. The

libesnmp

array by subtracting the object OID from the requested variable binding OID.

instance_len The size of the

method->row->instance ﬁeld.

context A pointer to be used privately

by the method routine to reference data needed for processing this request.

save A pointer to be used privately

by the method routine to reference data needed for undoing this request.

state An integer to be used

privately by the method routine for holding any state information it requires.

routine builds this

Set

Description

The

libesnmp

object table identiﬁed by the registered subtree. This function is pointed to by some number of elements of the subagent object

table. When a request arrives for an object, its method routine is called. The

*_set

method routine is called in response to a

routines call whatever routine is speciﬁed for

Set

request.

eSNMP API Routines 5–23

Set

operations in the

eSNMP API Routines *_set Routine

Return Values

ESNMP_MTHD_noError The routine completed successfully. ESNMP_MTHD_notWritable The requested object cannot be set or was not

ESNMP_MTHD_wrongType The data type for the requested value is the

ESNMP_MTHD_ wrongLength

ESNMP_MTHD_ wrongEncoding

ESNMP_MTHD_wrongValue The requested value is out of range. ESNMP_MTHD_noCreation The requested instance can never be created. ESNMP_MTHD_

inconsistentName ESNMP_MTHD_

inconsistentValue ESNMP_MTHD_

resourceUnavailable ESNMP_MTHD_genErr A general processing error. ESNMP_MTHD_

commitFailed ESNMP_MTHD_undoFailed The undo phase failed.

implemented.

wrong type. The requested value is the wrong length.

The requested value is represented incorrectly.

The requested instance cannot currently be created.

The requested value is not consistent.

A failure due to some resource constraint.

The commit phase failed.

5.2.1 Processing *_set Routines

This following is the sequence of operations performed for

1. Every variable binding is parsed and its object is located in the object table. A METHOD structure is created for each VARBIND structure. These METHOD structures point to a ROW_CONTEXT structure, which is useful for handling these phases. Objects in the same conceptual row all point to the same ROW_ CONTEXT structure. This determination is made by checking the following:

• The referenced objects are in the same MIB group.

• The VARBIND structures have the same instance OIDs.

2. Each ROW_CONTEXT structure is loaded with the instance information for that conceptual row. The ROW_CONTEXT structure context and save ﬁelds are set to NULL, and the state ﬁeld is set to ESNMP_SET_UNKNOWN structure.

3. The method routine for each object is called and is passed its METHOD structure with an action code of ESNMP_ACT_SET.

If all method routines return success, a single method routine (the last one called for the row) is called for each row, with method->action equal to ESNMP_ACT_COMMIT.

*_set

routines

5–24 eSNMP API Routines

eSNMP API Routines

*_set Routine

If any row reports failure, all rows that were successfully committed are told to undo the phase. This is accomplished by calling a single method routine for each row (the same one that was called for the commit phase), with a method->action equal to ESNMP_ACT_UNDO.

4. Each row is released. The same single method routine for each row is called with a method->action equal to ESNMP_ACT_CLEANUP. This occurs for every row, regardless of the results of previous processing.

The action codes are processed as follows:

• ESNMP_ACT_SET Each object’s method routine is called during the SET phase, until all objects

are processed or a method routine returns an error status value. (This is the only phase during which each object’s method routine is called.) For variable bindings in the same conceptual row, method->row points to a common ROW_ CONTEXT.

The method->ﬂags bitmask has the ESNMP_LAST_IN_ROW bit set, if this is the last object being called for this ROW_CONTEXT. This enables you to do a ﬁnal consistency check, because you have seen every variable binding for this conceptual row.

The method routine’s job in this phase is to determine whether the request will work, to return the correct SNMP error code if it does not, and to prepare any context data it needs to actually perform the the COMMIT phase.

The method->row->context ﬁeld is private to the method routine; does not use it. A typical use is to store the address of an emitted structure that has been loaded with the data from the VARBIND for the conceptual row.

Set

request during

libesnmp

• ESNMP_ACT_COMMIT Even though several variable bindings may be in a conceptual row, only the

last one in order of the that point to a common row, only the last method routine is called.

This method routine must have available to it all necessary data and context to perform the operation. It must also save a snapshot of current data or whatever it needs to undo the method->row->save ﬁeld is intended to hold a pointer to whatever data is needed to accomplish this. A typical use is to store the address of a structure that has been loaded with the current data for the conceptual row. The structure is one that has been automatically generated by the MIBCOMP command.

The method->row->save ﬁeld is also private to the method routine; does not use it.

If this operation succeeds, return value of

If any errors were returned during the COMMIT phase, UNDO phase; if not, it enters the CLEANUP phase.

If the the UNDO phase may occur even if the

ESNMP_MTHD_commitFailed

Set

request spans multiple subagents and another subagent fails,

Set

request is processed. Of all the method routines

Set

operation, if required. The

ESNMP_MTHD_noError

; otherwise, return a

libesnmp

Note

Set

operation is successful

libesnmp

enters the

eSNMP API Routines 5–25

eSNMP API Routines *_set Routine

• ESNMP_ACT_UNDO For each conceptual row that was successfully committed, the same method

routine is called with method->action equal to ESNMP_ACT_UNDO. The ROW_CONTEXT structures that have not yet been called for the COMMIT phase are not called for the UNDO phase; they are called for CLEANUP phase.

The method routine should attempt to restore conditions to what they were before it executed the COMMIT phase. (This is typically done using the data pointed to by the method->row->save ﬁeld.)

If successful, return ESNMP_MTHD_noError; otherwise, return ESNMP_ MTHD_undoFail.

• ESNMP_ACT_CLEANUP Regardless of what else has happened, at this point each ROW_CONTEXT

participates in cleanup phase. The same method routine that was called for in the COMMIT phase is called with method->action equal to ESNMP_ACT_CLEANUP.

This indicates the end of processing for the should perform whatever cleanup is required; for instance, freeing dynamic memory that might have been allocated and stored in method->row->context and method->row->save ﬁelds, and so on.

The function return status value is ignored for the CLEANUP phase.

set

request. The method routine

5.2.2 Method Routine Applications Programming

You must write the code for the method routines declared in the subtree_TBL.H ﬁle. Each method routine has one argument, which is a pointer to the METHOD structure, as follows:

int mib_group_get(

The operations.

The

• Extract the instance portion of the requested OID. You can do this manually

• Determine the instance validity. The instance OID can be null or any length,

• Extract the data. Based on the instance OID and method->action ﬁeld,

METHOD *method int mib_group_set( METHOD *method );

Get

method routines are used to perform

Get

method routines perform the following tasks:

by comparing the method->object->oid ﬁeld (the object’s base OID) to the method->varbind->name ﬁeld (the requested OID). You can use the

oid2instance

depending on what was requested and how your object was selected. You may be able to reject the request immediately by checking on the instance OID.

determine what data, if any, is to be returned.

support routine to do this.

Get,GetNext

, and

GetBulk

5–26 eSNMP API Routines

eSNMP API Routines

*_set Routine

• Load the response OID back into the method routine’s VARBIND structure. Set the method->varbind ﬁeld with the OID of the actual MIB variable instance you are returning. This is usually accomplished by loading an array of integers with the instance OID you wish to return and calling the

instance2OID

• Load the response data back into the method routine’s VARBIND structure. Use one of the support routines with the corresponding data type to load the

method->varbind ﬁeld with the data to return:

•

o_integer

•

o_string

•

o_octet

•

o_oid

These routines make a copy of the data you specify. The manages any memory associated with copied data. The method routine must manage the original data’s memory.

The routine does any necessary conversions to the type deﬁned in the object table for the MIB variable and copies the converted data into the method->varbind ﬁeld. See Section 5.2.3 for information on data value representation.

support routine.

libesnmp

function

• Return the correct status value, as follows: ESNMP_MTHD_noError The routine completed successfully or

ESNMP_MTHD_noSuchInstance There is no such instance of the

ESNMP_MTHD_noSuchObject No such object exists. ESNMP_MTHD_ genErr An error occurred and the routine did

5.2.3 Value Representation

The values in a VARBIND structure for each data type are represented as follows. (Refer to the ESNMP.H ﬁle for a deﬁnition of the OCT and OID structures.)

• ESNMP_TYPE_Integer32 (varbind->value.sl ﬁeld) This is a 32-bit signed integer. Use the

value into the VARBIND structure. Note that the prototype for the value argument is unsigned long; therefore, you may need to cast this to a signed integer.

• ESNMP_TYPE_DisplayString, ESNMP_TYPE_Opaque ESNMP_TYPE_OctetString (varbind->value.oct ﬁeld)

This is an octet string. It is contained in the VARBIND structure as an OCT structure that contains a length and a pointer to a dynamically allocated character array.

no errors were found.

requested object.

not complete successfully.

o_integer

routine to insert an integer

eSNMP API Routines 5–27

eSNMP API Routines *_set Routine

The displaystring is different only in that the character array can be interpreted as ASCII text, but the octetstring can be anything. If the octetstring contains bits or a bit string, the OCT structure contains the following:

A length equal to the number of bytes needed to contain the value that is ((qty-bits -1)/8+1)

A pointer to a buffer containing the bits of the bitstring in the form bbbbb..bb, where the bb octets represent the bitstring itself, bit 0 comes ﬁrst, and so on. Any unused bits in the last octet are set to zero.

Use the structure, which is a buffer and a length. New space is allocated and the buffer is copied into the new space.

Use the is a pointer to an OCT structure. New space is allocated and the buffer pointed to by the OCT structure is copied.

• ESNMP_TYPE_ObjectId (varbind->value.oid and the varbind->name ﬁelds) This is an object identiﬁer. It is contained in the VARBIND structure as

an OID structure that contains the number of elements and a pointer to a dynamically allocated array of unsigned integers, one for each element.

The varbind->name ﬁeld is used to hold the object identiﬁer and the instance information that identiﬁes the MIB variable. Use the to extract the instance elements from an incoming OID on a request. Use the

instance2oid

variable’s base OID to set the VARBIND structure’s name ﬁeld when building a response.

Use the structure when the OID value to be returned as data is in the form of a pointer to an OID structure.

Use the when the OID value to be returned as data is in the form of a pointer to an ASCII string containing the OID in dot format; for example:

1.3.6.1.2.1.3.1.1.2.0.

o_string

o_octet

o_oid

routine to insert a value into the VARBIND structure, which

function to insert an object identiﬁer into the VARBIND

o_string

support routine to insert a value into the VARBIND

OID2Instance

function to combine the instance elements with the MIB

function to insert an OID into the VARBIND structure

function

• ESNMP_TYPE_NULL This is the NULL, or empty, type. This is used to indicate that there is no

value. The length is zero and the value in the VARBIND structure is zero ﬁlled.

The incoming VARBIND structures on a have this data type. A method routine should never return this value. An incoming

• ESNMP_TYPE_IpAddress (varbind->value.oct ﬁeld) This is an IP address. It is contained in the VARBIND structure in an OCT

structure that has a length of 4 and a pointer to a dynamically allocated buffer containing the 4 bytes of the IP address in network byte order.

Use the structure when the value is an unsigned integer in network byte order.

Use the structure when the value is a byte array (in network byte order). Use a length of 4.

5–28 eSNMP API Routines

Get,GetNext

Set

request never has this value in a VARBIND structure.

o_integer

o_string

function to insert an IP address into the VARBIND

, and

GetBulk

will

eSNMP API Routines

*_set Routine

• ESNMP_TYPE_Integer32 ESNMP_TYPE_Counter32 ESNMP_TYPE_<Gauge32 (varbind->value.ul ﬁeld)

The 32-bit counter and 32-bit gauge data types are stored in the VARBIND structure as an unsigned integer.

Use the structure.

• ESNMP_TYPE_TimeTicks (varbind->value.ul ﬁeld) The 32-bit

unsigned integer. Use the

structure.

• ESNMP_TYPE_Counter64 (varbind->value.ul64 ﬁeld) The 64-bit counter is stored in a VARBIND structure as an unsigned

longword, which, on an OpenVMS Alpha system, has a 64-bit value. Use the

VARBIND structure.

o_integer

timeticks

o_integer

function to insert an unsigned value into the VARBIND

type values are stored in the VARBIND structure as an

function to insert an unsigned value into the VARBIND

function to insert an unsigned longword (64 bits) into the

eSNMP API Routines 5–29

eSNMP API Routines

5.3 Support Routines

The support routines are provided as a convenience for developers writing method routines that handle speciﬁc MIB elements. The following support routines are provided:

Routine Function

o_integer o_octet o_oid o_string o_counter64 str2oid sprintoid instance2oid oid2instance inst2ip cmp_oid cmp_oid_prefix clone_oid free_oid clone_buf mem2oct cmp_oct clone_oct free_oct free_varbind_date set_debug_level is_debug_level ESNMP_LOG print_varbind set_select_limit _ _set_progname

_ _restore_progname _ _parse_progname

esnmp_cleanup

Loads an integer value. Loads an octet value. Loads an OID value. Loads a string value. Loads a Counter64 variable into the Converts a string OID to dot notation. Converts an OID into a string. Creates a full OID for a value. Extracts an instance and loads an array. Returns an IP address for an OID. Compares two OIDs. Compares an OID’s preﬁx. Makes a copy of an OID. Frees a buffer. Duplicates a buffer. Converts a string to an Compares two octets. Makes a copy of an Frees a buffer attached to an Frees the ﬁelds in the Sets the logging level. Tests the logging level. Directs log messages. Displays the Sets the error limit for SNMP client requests. Sets the program name to be displayed in log

messages. Resets the program name back to the previous name. Parses the application ﬁle name to determine the

program name. Closes a socket that is used by a subagent for

communicating with the master agent.

varbind

oct

structure.

oct

structure.

oct

VARBIND

and its structure.

varbind

structure.

5–30 eSNMP API Routines

o_integer

Format

Arguments

eSNMP API Routines

o_integer

Loads an integer value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure.

int o_integer ( VARBIND *vb,

OBJECT *obj, unsigned long value );

A pointer to the VARBIND structure that is supposed to receive the data.

obj

A pointer to the the VARBIND structure.

value

The value to be inserted into the VARBIND structure.

OBJECT

structure for the MIB variable associated with the

OID

The real type as deﬁned in the object structure must be one of the following; otherwise, an error is returned.

ESNMP_TYPE_Integer32 32-bit integer ESNMP_TYPE_Counter32 32-bit counter (unsigned) ESNMP_TYPE_Gauge32 32-bit gauge (unsigned) ESNMP_TYPE_TimeTicks 32-bit timeticks (unsigned) ESNMP_TYPE_UInteger32 32-bit integer (unsigned) ESNMP_TYPE_Counter64 64-bit counter (unsigned) ESNMP_TYPE_IpAddress Implicit octet string (4)

Return Values

ESNMP_MTHD_noError The routine completed successfully. ESNMP_MTHD_genErr An error has occurred.

Note

If the real type is integer is in network byte order and packages it into an octet string.

IpAddress

, then eSNMP assumes that the 4-byte

eSNMP API Routines 5–31

eSNMP API Routines o_integer

Example

#include <esnmp.h> #include "ip_tbl.h" <-- for ipNetToMediaEntry_type definition VARBIND *vb = method->varbind; OBJECT *object = method->object; ipNetToMediaEntry_type *data; : : assume buffer and structure member assignments occur here : switch(arg) { case I_atIfIndex: return o_integer(vb, object, data->ipNetToMediaIfIndex);

5–32 eSNMP API Routines

o_octet

Format

Arguments

eSNMP API Routines

o_octet

Loads an octet value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure.

int o_octet ( VARBIND *vb,

OBJECT *obj, unsigned long value );

A pointer to the VARBIND structure that is supposed to receive the data. If the original value in the vb ﬁeld is not null, this routine attempts to free it. So

if you dynamically allocate memory or issue the own VARBIND structure, ﬁll the structure with zeros before using it.

obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

malloc

command to allocate your

value

The value to be inserted into the VARBIND structure. The real type as deﬁned in the object structure must be one of the following;

otherwise, an error is returned. ESNMP_TYPE_OCTET_STRING Octet string (ASN.1)

ESNMP_TYPE_IpAddress Implicit octet string (4) (in octet form,

ESNMP_TYPE_DisplayString DisplayString (textual convention) ESNMP_TYPE_Opaque Implicit octet string

Return Values

ESNMP_MTHD_noError The routine completed successfully. ESNMP_MTHD_genErr An error occurred.

Example

network byte order)

case I_atPhysAddress: return o_octet(vb, object, &data->ipNetToMediaPhysAddress);

eSNMP API Routines 5–33

eSNMP API Routines o_oid

o_oid

Format

Arguments

Loads an function does not allocate the VARBIND structure.

int o_oid ( VARBIND *vb,

A pointer to the VARBIND structure that is supposed to receive the data. If the original value in the VARBIND structure is not null, this routine attempts

to free it. So if you dynamically allocate memory or issue the allocate your own VARBIND structure, ﬁll the structure with zeros before using it.

obj

A pointer to the OBJECT structure for the MIB variable associated with the in the VARBIND structure.

oid

The value to be inserted into the VARBIND structure as data. For more information about OID length and values, see Chapter 3.

OID

value into the VARBIND structure with the appropriate type. This

OBJECT *obj, OID *oid );

malloc

command to

OID

The real type as deﬁned in the object structure must be ESNMP_TYPE_OBJECT_ IDENTIFIER.

Return Values

ESNMP_MTHD_noError The routine completed successfully. ESNMP_MTHD_genErr An error occurred.

Example

case I_atObjectID:

return o_oid(vb, object, &data->ipNetToMediaObjectID);

5–34 eSNMP API Routines

o_string

Format

Arguments

eSNMP API Routines

o_string

Loads a string value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure.

int o_string ( VARBIND *vb,

OBJECT *obj, unsigned character *ptr, int len );

A pointer to the VARBIND structure that is supposed to receive the data. If the original value in the VARBIND structure is not null, this routine attempts

to free it. So if you dynamically allocate memory or issue the allocate your own VARBIND structure, ﬁll the structure with zeros before using it.

malloc

command to

obj

A pointer to the OBJECT structure for the MIB variable associated with the in the VARBIND structure.

ptr

The pointer to the buffer containing data to be inserted into the VARBIND structure as data.

len

The length of the data in buffer pointed to by ptr. The real type as deﬁned in the object structure must be one of the following;

otherwise, an error is returned. ESNMP_TYPE_OCTET_

STRING ESNMP_TYPE_IpAddress Implicit octet string (4) (in octet form, network

ESNMP_TYPE_DisplayString DisplayString (textual convention) ESNMP_TYPE_NsapAddress Implicit octet string ESNMP_TYPE_Opaque Implicit octet string ESNMP_TYPE_OBJECT_

IDENTIFIER

Return Values

OID

Octet string (ASN.1)

byte order)

Object identiﬁer (ASN.1) (in dot notation, for example: 1.3.4.6.3)

ESNMP_MTHD_noError The routine completed successfully. ESNMP_MTHD_genErr An error occurred.

eSNMP API Routines 5–35

eSNMP API Routines o_string

Example

case I_atPhysAddress:

return o_string(vb, object, data->ipNetToMediaPhysAddress.ptr,

data->ipNetToMediaPhysAddress.len);

5–36 eSNMP API Routines

o_counter64

Loads a counter64 value into the VARBIND structure.

Format

int o_counter64 ( VARBIND *vb,

Arguments

A pointer to the VARBIND structure that is supposed to receive the data.

obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

value

The 8-byte value to be inserted into the VARBIND structure, passed as an array of two integers.

eSNMP API Routines

o_counter64

OBJECT *obj, uint64 value ); (for Alpha) uint64_vax value ; (for VAX))

The real type as deﬁned in the object structure must be ESNMP_TYPE_Counter64. Otherwise, an error is returned.

Example

See the example for the

Return Values

ESNMP_MTHD_noError No error was generated. ESNMP_MTHD_genErr An error was generated.

o_integer

routine.

eSNMP API Routines 5–37

eSNMP API Routines str2oid

str2oid

Converts a null-terminated string

str2oid

Format

oid *str2oid ( oid *oid,

Arguments

oid

The value to be inserted as data into the VARBIND structure. For more information about OID length and values, see Chapter 3.

A null string or empty string returns an OID structure that has one element of zero.

Description

The routine dynamically allocates the buffer and inserts its pointer into the structure passed in the call. The caller must explicitly free this buffer. The can have a maximum of 128 elements.

Return Values

routine does not allocate an

char *s );

OID

in dot notation to an

OID

structure.

OID

structure. The

OID

Example

null An error occurred. Otherwise, the pointer to the

OID

structure (its ﬁrst argument) is returned.

include <esnmp.h> OID abc; if (stroid (&abc, "1.2.5.4.3.6") == NULL

DPRINTF((WARNING, "It did not work...\n");

5–38 eSNMP API Routines

sprintoid

eSNMP API Routines

sprintoid

Converts an

Format

char *sprintoid ( char *buffer,

Description

Return Values

The return value points to its ﬁrst argument.

Example

OID

into a null-terminated string.

oid *oid );

OID

can have up to 128 elements. A full-sized

#include <esnmp.h> #define SOMETHING_BIG 1024 OID abc; char buffer[SOMETHING_BIG]; : : assume abc gets initialized with some value : printf("dots=%s\n", sprintoid(buffer, &abc));

OID

can require a large buffer.

eSNMP API Routines 5–39

eSNMP API Routines instance2oid

instance2oid

Copies the object’s base OID and appends a copy of the instance array to make a complete OID for a value. This routine does not allocate an OID structure. It only allocates the array containing the elements.

Format

oid instance2oid ( oid *new,

Arguments

new

A pointer to the OID that is to receive the new OID value.

obj

A pointer to the object table entry for the MIB variable being obtained. The ﬁrst part of the new OID is the OID from this MIB object table entry.

object *obj, unsigned int *instance, int *len );

instance

A pointer to an array of OID obtained from the MIB object table entry to construct the new OID.

len

The number of elements in the

Description

The instance array may be created by values as a result of a

This routine dynamically allocates the buffer and inserts its pointer into the OID structure passed in the call. The caller must explicitly free the buffer.

You should point to the OID structure receiving the new values and then call the

instance2oid free_oid

inserted. Be sure the initial value of the new OID is all zeros. If you do not want the initial value freed, make sure the new OID structure is all zeros.

Return Values

null An error occurred. Otherwise, the pointer to the

instance

GetNext

routine. Previous values in the OID structure are freed (that is,

is called ﬁrst), and then the new values are dynamically allocated and

values. These values are appended to the base

instance

command (see Chapter 1).

OID structure (new) is returned.

array.

oid2instance

or constructed from key

5–40 eSNMP API Routines

Example

eSNMP API Routines

instance2oid

#include <esnmp.h> VARBIND *vb; <-- filled in OBJECT *object; <-- filled in unsigned int instance[6];

-- Construct the outgoing OID in a GETNEXT --

-- Instance is N.1.A.A.A.A where A’s are IP address -instance[0] = data->ipNetToMediaIfIndex; instance[1] = 1; for (i = 0; i < 4; i++) { instance[i+2]=((unsigned char *)(&data->ipNetToMediaNetAddress))[i]; } instance2oid(&vb->name, object, instance, 6);

eSNMP API Routines 5–41

eSNMP API Routines oid2instance

oid2instance

Extracts the instance values from an OID structure and copies them to the speciﬁed array of integers. The routine then returns the number of elements in the array.

Format

int oid2instance ( oid *oid,

Arguments

oid

A pointer to an incoming OID containing an instance or part of an instance.

obj

A pointer to the object table entry for the MIB variable.

object *obj, unsigned int *instance, int *max_len );

instance

A pointer to an array of unsigned integers where the index is placed.

max_len

The number of elements in the

Description

The instance values are the elements of an OID beyond those that identify the MIB variable. These elements identify a speciﬁc instance of a MIB value.

If there are more elements in the OID structure than speciﬁed by the parameter, the function copies the number of elements speciﬁed by and returns the total number of elements that would have been copied had there been space.

Return Values

Less than zero An error occurred. This is not returned if the

Zero No instance elements. Greater than zero The returned value indicates the number of

instance

array.

max_len

object was obtained by looking at this OID.

elements in the index. This could be larger than

max_len

the

parameter.

only

5–42 eSNMP API Routines

Compaq AAR04BCTE User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Figures

Tables

Intended Audience

Document Structure

Preface

Table 1 TCP/IP Services Documentation

Reader’s Comments

How to Order Additional Documentation

Conventions

Overview

1.1 SNMP Architecture

Figure 1–1 SNMP Architecture

1.2 Request Handling

Figure 1–2 eSNMP Data Flow

1.3 TCP/IP Services Components for SNMP

Table 1–1 SNMP Component Files

1.4 Writing an eSNMP Subagent

Table 1–2 Files for Building a Subagent

1.5 The eSNMP API

1.5.1 The SNMP Utilities

1.6 The MIB Compiler

1.7 SNMP Versions

1.7.1 Using Existing (SNMP Version 1) MIB Modules

1.8 For More Information

MIBs Provided with TCP/IP Services

2.1 Overview of the Host Resources MIB

Table 2–1 Host Resources MIB Objects

2.1.2 Restrictions to Host Resources MIB

2.2 Overview of MIB II

2.2.1 MIB II Implemented Groups

2.2.2 Restrictions to MIB II Implementation

Creating a Subagent Using the eSNMP API

3.2 The Structure of Management Information

3.2.2 MIB Subtrees

Figure 3–1 MIB II in SMI Tree Structure

3.3 Creating a MIB Source File

3.3.1 Writing the ASN.1 Input File

3.3.2 Processing the Input File with the MIB Compiler

3.4 Including the Routines and Building the Subagent

3.5 Including Extension Subagents in the Startup and Shutdown Procedures

4.1 Using the MIB Browser

Using the SNMP Utilities

4.1.1 MIB Browser Parameters

Table 4–1 snmp_request Command Parameters

4.1.2 MIB Browser Flags

Table 4–2 Flags for the snmp_request Command

4.1.3 MIB Browser Data Types

Table 4–3 Data Types for the snmp_request and snmp_trapsnd Commands

4.1.4 Command Examples for snmp_request

4.2 Using the Trap Sender and Trap Receiver Programs

4.2.1 Entering Commands for the Trap Sender Program

Table 4–4 Parameters for the snmp_trapsnd Command

Table 4–5 Flags for the snmp_trapsnd Command

4.2.2 Entering Commands for the Trap Receiver Program

Table 4–6 snmp_traprcv Command Flags

5.1 Interface Routines

Table 5–1 Interface Routines

eSNMP API Routines

esnmp_init

esnmp_register

esnmp_unregister

esnmp_register2

esnmp_unregister2

esnmp_capabilities

esnmp_uncapabilities

esnmp_poll

esnmp_are_you_there

esnmp_trap

esnmp_term

esnmp_sysuptime

5.2 Method Routines

*_get Routine

*_set Routine

5.2.1 Processing *_set Routines

5.2.2 Method Routine Applications Programming