Digital TCP/IP Services for OpenVMS

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:

Related Documents

You might find the following documents useful:

Terminology

This manual uses the following terminology:

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:

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:

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:

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:

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:

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


Chapter 2
The eSNMP Commands

This chapter describes the eSNMP commands. Topics include:

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:

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:

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:


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:

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