# Digital TCP/IP Services for OpenVMS

# eSNMP Programming and Reference

# August 1996

Revision Information: This is a new manual.

Operating Systems: OpenVMS Alpha Version 6.1 and later OpenVMS VAX Version 6.1 and later

Software Version: Digital TCP/IP Services
for OpenVMS Version 4.1

Digital Equipment Corporation Maynard, Massachusetts

August 1996

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.

Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

© Digital Equipment Corporation 1996. All rights reserved.

The following are trademarks of Digital Equipment Corporation: \ACMS, Alpha AXP, DECdtm, DDCMP, DEC, DECnet, DECNIS, DECserver, DECsystem, DECwindows, DNA, InfoServer, LAT, OpenVMS, PATHWORKS, POLYCENTER, ULTRIX, VAX, VAXstation, VMS, VMScluster, and the DIGITAL logo.

The following are third-party trademarks:

CRAY is a registered trademark of Cray Research, Inc.
HP and Hewlett-Packard are registered trademarks of Hewlett-Packard Company.
IBM and OS/2 are registered trademarks of International Business Machines Corporation.
MS-DOS is a registered trademark of Microsoft Corporation.
Macintosh is a registered trademark of Apple Computer, Inc.
MultiNet is a registered trademark of TGV, Inc.
OSF/1 is a registered trademark of Open Software Foundation, Inc.
OSI is a registered trademark of CA Management, Inc.
PATHways is a registered trademark of The Wollongong Group.
PostScript is a registered trademark of Adobe Systems, Inc.
SCO is a trademark of Santa Cruz Operations, Inc.
Sun, NFS, and PC-NFS are registered trademarks of Sun Microsystems, Inc.
TCPware is a registered trademark of Process Software Corporation.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd.
All other trademarks and registered trademarks are the property of their respective holders.

This document is available on CD-ROM.

# Contents

# Preface

This book describes the Extensible Simple Network Management Protocol (eSNMP) provided with Digital TCP/IP Services for OpenVMS. This book also describes the eSNMP application programming interface (API) and provides instructions for building additional subagents to manage vendor-specific equipment.

# Intended Audience

This book is for OpenVMS system or network programmers who want to manage network software and to build eSNMP subagents to manage their own equipment and applications. The system programmers who use this book to create subagents are assumed to have an understanding of networking terminology and ASN.1 programming.

# Document Structure

The following chapters are in this book:

- Chapter 1 describes Digital's implementation of eSNMP provided with Digital TCP/IP Services for OpenVMS.
- Chapter 2 describes the eSNMP commands.
- Chapter 3 describes the groups and objects implemented with the Host Resources MIB and MIB-II that are provided with the eSNMP software.
- Chapter 4 describes how to use the eSNMP API to create a MIB subagent to manage entities or applications.
- Chapter 5 provides reference information about the eSNMP API routines.

# Related Documents

You might find the following documents useful:

- Internetworking with TCP/IP: Principles, Protocols, and Architecture, by Douglas Comer (order number ER--TCPIP--TM--001)
- Request for Comments (RFCs) 1155---1157, 1212---1215, 1441---1452, and 1514
- Digital TCP/IP Services for OpenVMS Installation and Configuration guide
- For additional information about Digital TCP/IP Services for OpenVMS product and services, access the Digital OpenVMS World Wide Web site. Use the following URL:

      http://www.openvms.digital.com

# Terminology

This manual uses the following terminology:

- Abbreviations for the products' names
  - Digital TCP/IP Services for OpenVMS is used to mean both:
    The Digital TCP/IP Services for OpenVMS Alphatm operating system product
    The Digital TCP/IP Services for OpenVMS VAXtm operating system product
- Software components
  - Auxiliary server is the TCP/IP implementation of the INETd function, system security, and other features.
  - NFStm is the TCP/IP implementation of the Network File System (NFS) protocols, including NFS server, NFS client, and PC-NFStm.
  - TN3270 means the Telnet software that emulates IBM 3270 model terminals.
- UNIXtm operating system
  UNIX refers to UNIX Version 4.3 of the Berkeley Software Distribution (BSD). The Digital UNIXtm and DEC OSF/1tm operating systems are fully compatible with UNIX BSD Version 4.3.
- Networking terms
  - Host and node both mean a system connected to an internet.
  - The term Internet means the network, as defined by RFC 1208, that consists of large networks using the TCP/IP protocol suite; provides universal connectivity, reaching the Defense Advanced Projects Research Agency (DARPA) Internet, MILNET, NSFnet, CERN, and many worldwide universities, government research labs, military installations, and business enterprises.
    The term internet means interconnected networks using the TCP/IP protocols, functioning as one, virtual network.

# Reader's Comments

Digital welcomes your comments on this manual or any of the Digital TCP/IP Services for OpenVMS documents. Send us your comments through any of the following channels:

Internet | openvmsdoc@zko.mts.dec.com
Fax | 603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail | OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

# How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

# Conventions

The name of OpenVMS AXP has been changed to OpenVMS Alpha. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha. All IP addresses in this book represent fictitious addresses. The following conventions apply to this book.

Convention | Meaning
--- | ---
UPPERCASE SPECIAL TYPE | Indicates OpenVMS system output or user input.
UPPERCASE TEXT | Indicates names of OpenVMS and TCP/IP commands, options, utilities, files, directories, hosts, and users.
lowercase special type | Indicates UNIX system output or user input, commands, options, files, directories, utilities, hosts, and users.
italic | Indicates a variable.
bold | Indicates a new term defined in the text.
`[Return]` | Indicates that you press the Return key.
`[Ctrl/]` x | Indicates that you press the Control key while you press the key noted by x.
[ ] | In command format descriptions, indicates optional elements. You can enter as many as you want.
{ } | In command format descriptions, indicates you must enter at least one listed element.

# Chapter 1
Overview

The Simple Network Management Protocol (SNMP) is the de facto industry standard for managing TCP/IP networks. The protocol defines 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.

Digital TCP/IP Services for OpenVMS (TCP/IP) provides support for SNMP with the Extensible Simple Network Management Protocol (eSNMP) software. Extensibility means that a single master agent can support any number of subagents. Digital's implementation of eSNMP includes a master agent, two subagents, and an application programming interface (API) used to build additional subagents

This chapter provides an overview of Digital's implementation of eSNMP. Topics include:

- eSNMP master agent and subagent architecture (Section 1.1)
- eSNMP API (Section 1.2)
- The MIB compiler (Section 1.3)

# 1.1 eSNMP Master Agent and Subagent Architecture

The eSNMP software manages network communication by having the master agent listen for requests and then passing the requests on to the appropriate subordinate agent called a subagent.

When a subagent starts, it tells the master agent the objects for which it is responsible. The master agent directs all requests for those objects to that subagent. Related objects are usually grouped together into a collection called a management information base (MIB). Generally, one subagent processes all the requests for a particular MIB.

Communication betweeen the master agent and its subagents is by means of a protocol based on the Distributed Protocol Interface (DPI V2) described in RFC 1592.

> Note

> DPI V2 is an experimental protocol with which Digital does not fully comply. Digital used DPI as the basis for agent/subagent communication to make future implementations of standard protocols easier. Digital plans to track and support standards that emerge in the area of eSNMP.

When a subagent starts, it establishes a connection to the master agent via a named socket. Communication between the master agent and subagent adhere to the following steps:

1. The subagent periodically sends a read to the master agent and waits for a request for information.
2. The master agent sends a request to the subagent (this completes the read).
3. The subagent processes the request.
4. The subagent sends the response to the master agent.
5. The subagent returns to the waiting state and periodically sends a read to the master agent.

Figure 1-1 illustrates master agent and subagent communication.

Figure 1-1 Master Agent - Subagent Communication

## 1.1.1 The MIB-II Subagent

The MIB-II subagent gathers the information necessary to manage TCP/IP-based internets. This implementation of eSNMP includes the following MIB-II groups:

- System --- provides overall information about the system.
- Interfaces --- provides information about each of the interfaces from the system to a subnetwork.
- AT (address translation, deprecated) --- describes the address translation table for internet-to-subnetwork address mapping.
- IP (Internet Protocol) --- provides information related to the implementation of IP on this system.
- ICMP (Internet Control Message Protocol) --- provides information related to the implementation of ICMP on this system.
- TCP (Transmission Control Protocol) --- provides information related to the implementation of TCP on this system.
- UDP (User Datagram Protocol) --- provides information related to the implementation of UDP on this system.
- SNMP (Simple Network Management Protocol) --- provides information related to the implementation of SNMP on this system.

The Internet community, through RFC 1213, has described MIB-II for monitoring and managing TCP/IP applications. Chapter 3 describes the MIB-II standard as implemented in the Digital TCP/IP Services for OpenVMS eSNMP software.

> Note

> The Digital TCP/IP Services for OpenVMS eSNMP software does not support either the External Gateway Protocol (EGP) or the transmission group.

## 1.1.2 The Host Resources MIB Subagent

The Internet community, through RFC 1514, has described a Host Resources MIB for monitoring and managing Internet host systems. The eSNMP software implements a portion of this standard. Remote systems can monitor several operating system parameters including:

- System uptime
- Number of system users
- Storage device information
- Printer information

Chapter 3 describes the Host Resources MIB as implemented in this version of eSNMP.

# 1.2 The eSNMP API

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

The eSNMP API includes routines that provide the following functions:

- Basic protocol data unit (PDU) handling
- Authentication handling
- Octet string handling
- Variable binding (varbind) handling
- Object identifier (OID) handling
- MIB interface
- Program control
- Clock control
- Terminal printing
- Access control (ACL) handling
- eSNMP packet transmission and reception

Chapter 4 and Chapter 5 review how to create subagents for vendor-specific applications that you want to manage with eSNMP.

# 1.3 The MIB Compiler

The MIB Compiler processes the statements in the ASN.1 file and generates modules that are used by the developer to create subagent routines. For every ASN.1 input file that is processed using the MIB compiler, two output files, a <subtree>_TBL.H file and a <subtree>_TBL.C file, are generated.

The <subtree>_TBL.H file is a header file that contains the following:

- A declaration of the subtree structure
- Index definitions for each MIB variable in the subtree
- Enumeration definitions for MIB variables with enumerated values
- MIB group data structure definitions
- Method routine function prototypes

The <subtree>_TBL.C file is an object file that contains the following:

- An array of integers representing the OIDs for each MIB variable
- An array of OBJECT structures
- An initialized SUBTREE structure

# Chapter 2
The eSNMP Commands

This chapter describes the eSNMP commands. Topics include:

- Overview of eSNMP commands (Section 2.1)
- The Get command (Section 2.2)
- The GetNext command (Section 2.3)
- The Set command (Section 2.4)

# 2.1 Overview of eSNMP Commands

When the eSNMP software receives a request from the network management station (NMS), the master agent exchanges commands with the subagent and then returns a response to the NMS. The user on the NMS or other connected entity does not see the command exchange between the master agent and the subagent. However, understanding the details of each command and its valid responses may help you determine what type of information can be obtained from eSNMP.

Table 2-1 shows the available commands in the Digital TCP/IP Services for OpenVMS implementation of eSNMP.

Table 2-1 eSNMP Command Set
Command | Description | From - To
--- | --- | ---
Get | Returns value of variable(s) | NMS¹ to agent
GetNext | Returns next value in a list of variables | NMS to agent
Set | Assigns a value to a variable | NMS to agent
Trap² | Transmits unsolicited information | Agent to NMS
Responses³ | Responses to commands | Agent to NMS

¹Network Management Station
²Supported but implemented by user on NMS
³Discussed as responeses to Get, GetNext, and Set commands

# 2.2 The Get Command

The eSNMP Get command initiates a network management query to a remote agent which returns a response. This command attempts to retrieve the items of management information. Figure 2-1 shows the PDU format for the Get command.

Figure 2-1 eSNMP Get Request/Response

The Get command request can generate a number of errors that are sent to the NMS from the master agent. Those errors include noSuchName, tooBig, and genErr. This set of errors is expanded through the use of error index numbering. The common errors that arise from the agent are presented below:

- Aggregate Error --- Indicates that a management station has mistakenly tried to retrieve a row object. The error returned is noSuchName with an error index that indicates the variable.
- Variable Error --- Indicates an attempt to retrieve a variable that cannot be retrieved. The error returned is genErr with the error index set.
- Set Error --- Indicates that the response PDU exceeds some limitation known to the agent. The error returned is tooBig with the error index set.
- Binding Error --- Indicates that the variable you have requested does not match what is in the MIB database.

# 2.3 The GetNext Command

The GetNext command attempts to retrieve object values for specified subtrees of the MIB. This GetNext command has run-off capability which exists when the master agent passes or infinitely returns routes creating a large amount of worthless data. Figure 2-2 shows the PDU format for the Get Next command.

Figure 2-2 eSNMP GetNext Request/Response

# 2.4 The Set Command

The Set command changes the value of an eSNMP variable by initiating a network management request to the remote management agent. When used on a table row that contains multiple variables, this command has multiple variables, one for each object, but only one object identifier (OID). Figure 2-3 shows the PDU format for the Set command.

Figure 2-3 eSNMP Set Request/Response

At the eSNMP protocol level, a management station issues a Set command that contains an arbitrary set of variable binding structures. If the agent detects that one or more of the variable binding structures refer to an object instance not currently available in that agent, eSNMP may either:

- Reject the eSNMP operation because it refers to a non-existent object instance. If this is done, eSNMP returns a response with the Error Status field set to noSuchName and the error index field set to the first empty reference.
- Accept the eSNMP operation and create a new object instance that corresponds to each of the object instances named in the variable bindings.

The Set command request can generate a number of errors that are sent to the NMS from the master agent. These errors include noSuchName, tooBig, badValue, and genErr. The set of errors is expanded through the use of error index numbering. The following are the common errors that arise from the agent:

- Variable Binding Error --- Arises when the variable binding field is not available for set operations. The noSuchName error is returned with an error index that indicates the variable.
- Variable Field Error --- Indicates that the variable binding field does not conform to the type, length, value (TLV) requirements. The badValue error is returned with the error index set to zero.
- Size Error --- Indicates that the response PDU exceeds a limitation known to the agent. The tooBig error is returned with the error index set to zero.
- General Set Error --- Indicates that a variable cannot be altered to match the request. The genErr error is returned with the error index set to zero.

# Chapter 3
The MIBs Provided with eSNMP

This chapter describes the two MIBs provided with the eSNMP master agent. The two MIBs are the Host Resources MIB and MIB-II. The Host Resources MIB manages operating system objects and MIB-II manages TCP/IP stack objects. Topics include:

- Overview of the Host Resources MIB (Section 3.1)
- Defining Host Resources MIB implemented objects (Section 3.2)
- Overview of MIB-II (Section 3.3)
- Defining MIB-II implemented objects (Section 3.4)

# 3.1 Overview of the Host Resources MIB

The Host Resources MIB defines a uniform set of objects useful for the management of host computers. The Host Resources MIB, as defined by Request for Comment (RFC) 1514, defines objects that are common across many computer system architectures. Digital's implementation of eSNMP includes 24 of these 151 objects. In addition, some objects in MIB-II also provide host management functionality.

# 3.2 Defining Host Resources MIB Implemented Objects

This section defines each of the 24 implemented eSNMP objects. Table 3-1 provides the data type and access level for each implemented object. Table 3-2 provides a general RFC description and an OpenVMS specific description for each implemented object.

> Note

> For objects that are not implemented, the Host Resources MIB returns a Nosuchobject error status.

Table 3-1 Host Resources MIB Data Type and Access Definition
Object Name | Data Type | Access
--- | --- | ---
hrSystemUptime | TimeTicks | Read only
hrSystemDate | DateAndTime | Read/write
hrSystemIntialLoadDevice | Integer | Read/write
hrSystemIntialLoadParameters | InternationalDisplayString | Read/write
hrSystemNumUsers | Gauge | Read only
hrSystemProcesses | Gauge | Read only
hrSystemMaxProcesses | Integer | Read only
hrMemorySize | Kbytes | Read only
hrStorageIndex | Integer | Read only
hrStorageType | Object Identifier | Read only
hrStorageDescr | DisplayString | Read only
hrStorageAllocationUnits | Integer | Read only
hrStorageSize | Integer | Read/write
hrStorageUsed | Integer | Read only
hrDeviceIndex | Integer | Read only
hrDeviceType | Object Identifier | Read only
hrDeviceDesc | DisplayString | Read only
hrDeviceStatus | Integer | Read only
hrDeviceErrors | Counter | Read only
hrProcessorFrwID | Protected | Read only
hrNetworkIfIndex | Integer | Read only
hrDiskStorageAccess | Integer | Read only
hrDiskStorageMedia | Integer | Read only
hrDiskStorageRemovable | Boolean | Read only
hrDiskStorageCapacity | Kbytes | Read only

Table 3-2 Host Resources MIB Descriptions
Object Name | RFC Description | OpenVMS Description
--- | --- | ---
hrSystemUptime | The amount of time since this host was last initialized. | Time since system boot in hundredths of a second.
hrSystemDate | The host's notion of the local date and time of day. | Date and time character string with coordinated universal time (UTC) information if available.
hrSystemIntialLoadDevice | Index of the hrDeviceEntry for configured initial operating system load. | Index of SYS$SYSDEVICE in the device table.
hrSystemIntialLoadParameters | Parameters supplied to the load device when requesting initial operating system configuration. | A string of boot parameters from the console (Alpha only).
hrSystemNumUsers | Number of user sessions for which the host is storing state information. | Number of processes that are neither owned by another process nor running detached.
hrSystemProcesses | Number of process contexts currently loaded or running on the system. | Number of processes listed using the SHOW SYSTEM command.
hrSystemMaxProcesses | Maximum number of process contexts the system can support or 0 if not applicable. | MAXPROCESSCNT SYSGEN parameter.
hrMemorySize | The amount of physical main memory contained in the host. | The amount of physical main memory contained in the host.
hrStorageIndex | A unique value for each logical storage area contained in the host. | Index of entry in hrStorageTable.
hrStorageType | The type of storage represented by this entry. | A numerical representation of the device class/type shown by the SHOW DEVICE /FULL command.
hrStorageDescr | A description of the type and instance of the storage described by this entry. | Character string device type shown by the SHOW DEVICE /FULL command.
hrStorageAllocationUnits | The size of the data objects allocated from this pool (in bytes). | Always 512 (the size of an ODS-II disk block).
hrStorageSize | The size of storage in this entry in hrStorageAllocationUnits. | The total number of blocks on a device shown by the SHOW DEVICE /FULL command.
hrStorageUsed | The allocated amount of storage in this entry in hrStorageAllocationUnits. | The total number of used blocks on a device that would be shown by the SHOW DEVICE /FULL command.
hrDeviceIndex | A unique value for each host or device constant between agent reinitialization. | Index of entry in hrDeviceTable.
hrDeviceType | An indication of the type of device. Some of these devices have corresponding entries in other tables. | In object identifier format, a numerical representation of the device class/type shown by the SHOW DEVICE /FULL command.
hrDeviceDesc | A text description of the device, including manufacturer and version number (service, optional). | Character string of the device type reported by the SHOW DEVICE /FULL command.
hrDeviceStatus | The current operational state of the device. | A numeric indication of the status of the device.
hrDeviceErrors | The number of errors detected on the device. The recommended initial value is 0. | The number of errors indicated by the SHOW DEVICE command. This value initializes at 0 when the device is recognized by the system instead of when the master agent is initialized.
hrProcessorFrwID | The product ID of the firmware associated with the processor. | An object identifier that corresponds to the console and/or PAL code version (Alpha only).
hrNetworkIfIndex | The value of the ifIndex that corresponds to this network device. | The value of the index in the interface table in the standard MIB that corresponds to this network device.
hrDiskStorageAccess | Indicates whether the storage device is read/write or read only. | This value is set to 2 if the device is read only, otherwise, set to 1 (SHOW DEVICE /FULL command displays "software write-locked.")
hrDiskStorageMedia | Indicates the storage device media type. | Indicates device type.
hrDiskStorageRemovable | Indicates whether the disk may be removed from the drive. | Indicates whether the disk may be removed from the drive.
hrDiskStorageCapacity | The total size of this long-term storage device. | Half of the value shown for total blocks by the SHOW DEVICE/FULL command.
hrSWRunIndex | A unique value for each software product running on the host. | Process ID.
hrSWRunPath | A description of the location where this software was loaded. | Fully qualified name of executable image.
hrSWRunStatus | The status of the software that is running. | The value (1) indicates the current process is running - CUR; (2) indicates the process is computable - COM; (3) indicates that you cannot run the process.
hrSWRunPerfCPU | The number in hundredths of a second of the total system's CPU resources consumed by this process. | Process elapsed CPU time in hundredths of a second.
hrSWRunPerfMem | The total amount of real system memory allocated to this process. | Process current working set, in kilobytes.

# 3.3 Overview of MIB-II

The Standard MIB (MIB-II) defines 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.

Next | Contents