HP OpenVMS Systems Documentation

HP TCP/IP Services for OpenVMS
SNMP Programming and Reference

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

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

1.5 The eSNMP API

The TCP/IP Services 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.

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 ( VARBIND ) handling
• Object identifier (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 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, where subtree is the name from the original MIB definition file (for example, chess). The output files are described in more detail in Chapter 3.

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

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 specific 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.

Existing SNMP Version 1 MIB subagent executable files 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.
    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 files with the prefix TCPIP$ and UCX$ should be within a few seconds of each other, and only one version of each file should exist. Make sure both images include the file 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) files 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.

For information about prototypes and definitions for the routines in the eSNMP API, see the TCPIP$SNMP:ESNMP.H file.

Table 1-2 lists files that contain additional comments and documentation.

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)

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

2.1.1 Defining Host Resources MIB Implemented Objects

This section defines each of the implemented eSNMP objects. Table 2-1 provides a general RFC description and a specific OpenVMS description for each implemented object.

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

hrPartitionTable
hrPrinterTable
hrSWInstalled
hrSWInstalledTable

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

hrFSLastFullBackupDate
hrFSLastPartialBackupDate
hrStorageSize
hrSWRunStatus
hrSystemDate
hrSystemInitialLoadDevice
hrSystemInitialLoadParameters

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

• The hrDeviceTable includes all the devices known to the OpenVMS host 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 hrDeviceTable group have the following restrictions:
  • hrDeviceID is always null OID (0.0).
  • hrDeviceErrors is coded as follows:

    Code	Condition
    warning (3)	Error logging is in progress (OpenVMS UCB value UCB$M_ERLOGIP).
    running (2)	Software is valid and no error logging is in progress (OpenVMS UCB value UCB$M_VALID).
    unknown (1)	Any other OpenVMS status.

  
  The hrDeviceTable now includes template devices (for example, DNFS0 for NFS and DAD0 for virtual devices).
  For network devices, only the template devices (those with unit number 0) are displayed.
• hrFSMountPoint (1.3.6.1.2.1.25.3.8.1.2) is DNFSn. The device may change between restarts or after a dismount/mount procedure.
• In the hrFSTable group, if no file systems are mounted through NFS or no information is accessible, a "no such instance" status is returned for a get request. Browsers respond differently to this message. For example, 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 is the local DNFS device name.
  • hrFSRemoteMountPoint is the remote file system.
  • hrFSType is implemented as:
    • OID 1.3.6.1.2.1.25.3.9.1, for OpenVMS if the file system is not a UNIX style container file system.
    • hrFSNFS , OID 1.3.6.1.2.1.25.3.9.14, if the file system is a TCP/IP Services container file system or a UNIX host.
  • hrFSAccess , as defined in RFC 1514.
  • hrFSBootable is always HRM_FALSE (integer 2).
  • hrFSStorageIndex is always 0.
  • hrFSLastFullBackupDate is unknown time. This entry is encoded according to RFC 1514 as a hexadecimal value 00-00-01-01-00-00-00-00 (January 1, 0000).
  • hrFSLastPartialBackupDate is unknown time. This information is not available for OpenVMS systems. Instead, hexadecimal value 00-00-01-01-00-00-00-00 (January 1, 0000) applies.
• hrProcessorFrwID (OID prefix 1.3.6.1.2.1.25.3.3.1.1) is not implemented on 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 (firmware 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 hrDiskStorage table have the following restrictions:
  • hrDiskStorageMedia is always "unknown" (2).
  • hrDiskStorageRemoveble is always "false" (2). Note the incorrect spelling of "removable" in hrDiskStorageRemoveble (from RFC 1514).
• hrStorageType always contains the value of hrStorageFixedDisk (1.3.6.1.2.1.25.2.1.4).