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
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.
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.
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.
The following chapters are in this book:
You might find the following documents useful:
http://www.openvms.digital.com
This manual uses the following terminology:
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 |
|
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd. Nashua, NH 03062-2698 |
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).
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. |
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:
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:
Figure 1-1 illustrates master agent and subagent communication.
Figure 1-1 Master Agent - Subagent Communication
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.
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:
This chapter describes the eSNMP commands. Topics include:
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.
| 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 |
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:
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
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:
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:
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.
| 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 |
| 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. |
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.