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.

Table 1-2 Files for Building a Subagent

File	Description
ESNMP.H	Header file used to create a subagent. Located in TCPIP$ESNMP.
GAWK.EXE	Interpreter for MIB converter.
MIB-CONVERTER.AWK	A UNIX based awk shell script that takes a MIB definition in ASN.1 notation and converts it to an .MY file.
RFC1213.MY	MIB II definitions.
RFC1231.MY	IEEE 802.5 Token Ring MIB definitions.
RFC1285.MY	FDDI MIB definitions.
RFC1442.MY	SNMP Version 2 Structure of Management Information (SMI) definitions.
SNMP-SMI.MY	SNMP Version 2 SMI definitions from RFC 1902 (replaces RFC 1442).
SNMP-TC.MY	SNMP Version 2 SMI definitions from RFC 1903 (replaces RFC 1443).
V2-TC.MY	SNMP Version 2 SMI definitions from RFC 1903 (superset of those in SNMP-TC.MY).
TCPIP$BUILD_CHESS.COM	Command file that builds the sample chess subagent.
TCPIP$CHESS_SUBAGENT.OPT	Options file for use in building the sample chess subagent.
*.C and *.H	Source code for chess example. Contains detailed documentation that explains how the code functions.
TCPIP$CHESS_SUBAGENT.EXE	Functioning chess example image.
TCPIP$ESNMP.OLB	Object library file containing routines used to create a subagent. Located in the directory pointed to by TCPIP$SNMP.
TCPIP$ESNMP_SHR.EXE	Shareable image containing routines used to create a subagent. Located in the directory pointed to by SYS$SHARE.
UCX$ESNMP_SHR.EXE	Copy of TCPIP$ESNMP_SHR.EXE, provided for compatibility with existing customer subagents linked under TCP/IP Services V4. x. Located in the directory pointed to by SYS$SHARE.
TCPIP$MIBCOMP.EXE TCPIP$MOSY.EXE TCPIP$SNMPI.EXE	Images associated with the MIB compiler. Located in SYS$SYSTEM.

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.

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.

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

Table 2-1 Host Resources MIB Objects

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.	SYSGEN parameter MAXPROCESSCNT.
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 numeric representation of the device class and type displayed 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 displayed 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 OpenVMS disk block).
hrStorageSize	The size of storage in this entry in hrStorageAllocationUnits.	The total number of blocks on a device displayed 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 displayed 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 numeric representation of the device class and type displayed 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 displayed 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 zero.	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.
hrProcessorFrwID	The product ID of the firmware associated with the processor.	An object identifier that corresponds to the console or PALcode 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, it is set to 1. (The SHOW DEVICE/FULL command displays "software write-locked.")
hrDiskStorageMedia	Indicates the storage device media type.	Indicates device type.
hrDiskStorageRemovable	Indicates whether the disk can be removed from the drive.	Indicates whether the disk can be removed from the drive.
hrDiskStorageCapacity	The total size of this long-term storage device.	Half of the value for total blocks displayed 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 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) 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).

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