HP OpenVMS systems documentation

The Standard MIB (MIB II) described in RFC 1213 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. For more information about MIB architecture, see Section 3.2.

2.2.1 MIB II Implemented Groups

A group is a subdivision of a MIB that defines a subtree. SNMP as implemented by TCP/IP Services supports the following groups:

• system (1)
• interfaces (2)
• Internet Protocol (4)
• ICMP (5)
• TCP (6)
• UDP (7)
• SNMP (11)
  In the SNMP group (1.3.6.1.2.1.11), data elements with the status noted as obsolete in RFC 1907 are not implemented.

SNMP requests are not implemented for the following MIB II objects:

ipRouteMetric1 - ipRouteMetric5 tcpMaxConn

SNMP set requests are not implemented for the following MIB II group objects:

ipDefaultTTL ipRouteAge ipRouteDest ipRouteIfIndex ipRouteMask ipRouteNextHop ipRouteType

The TCP/IP Services implementation of SNMP includes the following MIB II objects:

• sysObjectID is returned in the following format:

  1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.22.1

  
  where 1.3.6.1.4.1.36.2.15.13.22.1 corresponds to:

  iso.org.dod.internet.private.enterprises.dec.ema.SysObjectIds.DEC-OpenVMS.eSNMP

• The sysORTable elements are under OID prefix 1.3.6.1.2.1.1.9.1. See RFC 1907 for details.
  When both the TCPIP$OS_MIBS and TCPIP$HR_MIB subagents are running, a get request on the sysORTable is as follows. Except where noted, the OIDs conform to RFC 1907.

  1.3.6.1.2.1.1.9.1.2.1 = 1.3.6.1.4.1.36.15.3.3.1.1 1.3.6.1.2.1.1.9.1.2.2 = 1.3.6.1.4.1.36.15.3.3.1.2 1.3.6.1.2.1.1.9.1.3.1 = Base o/s agent (OS_MIBS) capabilities 1.3.6.1.2.1.1.9.1.3.2 = Base o/s agent (HR_MIB) capabilities 1.3.6.1.2.1.1.9.1.4.1 = 31 = 0 d 0:0:0 1.3.6.1.2.1.1.9.1.4.2 = 36 = 0 d 0:0:0

  
  This example is from the MIB browser (TCPIP$SNMP_REQUEST.EXE).

• Under certain conditions, a subagent makes a duplicate entry in sysORTable when it restarts. For example:

  1.3.6.1.2.1.1.9.1.2.1 = 1.3.6.1.4.1.36.15.3.3.1.1 1.3.6.1.2.1.1.9.1.2.2 = 1.3.6.1.4.1.36.15.3.3.1.2 1.3.6.1.2.1.1.9.1.2.1 = Base o/s agent (OS_MIBS) capabilities 1.3.6.1.2.1.1.9.1.2.2 = Base o/s agent (OS_MIBS) capabilities 1.3.6.1.2.1.1.9.1.4.1 = 3256 = 0 d 0:0:32 1.3.6.1.2.1.1.9.1.4.2 = 3256 = 0 d 0:0:32

  
  In this example, the TCPIP$OS_MIBS subagent made two entries with different ID numbers (OIDs with the prefix 1.3.6.1.2.1.1.9.1.2) that may show different sysORUpTime (1.3.6.1.2.1.1.9.1.4). The snmp_request program translates the value received (in hundredths of a second) to the following, dropping any fractions of seconds:

  d n hh:mm:ss

  
  In this format, n represents the number of days, hh represents the number of hours, mm represents the number of minutes, and ss represents the number of seconds.
  The HR_MIB subagent has not yet successfully started and registered its capabilities. If it starts, its entries in this example would use the next available index number.

• On systems running versions of the operating system prior to OpenVMS 7.1-2, counters for the MIB II ifTable do not wrap back to 9 after reaching the maximum value ( 2³² - 1 ), as defined in RFC 1155. Instead, they behave like the gauge type and remain at the maximum value until cleared by an external event, such as a system reboot. The following counters are affected:

  ifInDiscards ifInErrors ifInNUcastPkts ifInOctets ifInUcastPkts ifInUnknownProtos ifOutErrors ifOutNUcastPkts ifOutOctets ifOutUcastPkts

  
  Note that for SNMP Version 2, these counters are data type Counter32. The following ifTable members are always -1 for OpenVMS:

  ifOutDiscards (Counter32)
  ifOutQLen (Gauge32)

This chapter describes how to use the eSNMP API to create a MIB subagent that manages entities or applications. Topics included in this chapter are:

• Creating a MIB specification ( Section 3.1)
• The structure of management information ( Section 3.2)
• Creating a MIB source file ( Section 3.3)
• Including the routines and building the subagent ( Section 3.4)
• Including your subagents in startup and shutdown procedures ( Section 3.5)

The creation of a management information base (MIB) begins with data gathering. During this phase, the developer identifies the information to manage, based on the entities that the network manager needs to examine and manipulate. Each resource that a MIB manages is represented by an object. After gathering the data, the developer uses Abstract Syntax Notation 1 (ASN.1) to specify the objects in the MIB.

3.2 The Structure of Management Information

The structure of management information (SMI), which is specified in RFCs 1155 and 1902, describes the general framework within which a MIB can be defined and constructed. The SMI framework identifies the data types that can be used in the MIB and how resources within the MIB are represented and named.

SMI avoids complex data types to simplify the task of implementation and to enhance interoperability. To provide a standard representation of management information, the SMI specifies standard techniques for the following:

• Defining the structure of a particular MIB
• Defining individual objects, including the syntax and value of each object
• Encoding object values

Each object in a MIB is associated with an identifier of the ASN.1 type, called an object identifier (OID). OIDs are unique integers that follow a hierarchical naming convention.

Each OID has two parts:

• A preassigned portion that is always represented on the SMI tree as 1.3.6.1 or iso (1), org (3), dod (6), Internet (1).
• A developer-assigned portion for the private development of MIBs.

In addition to an OID, you should also assign a name to each object to help with human interpretation.

3.2.2 MIB Subtrees

Understanding MIB subtrees is crucial to understanding the eSNMP API and how your subagent will work.

The information in SNMP is structured hierarchically like an inverted tree. Each node has a name and a number. Each node can also be identified by an OID, which is a concatenation of the subidentifiers (nonnegative numbers). These numbers are on the path from the root node down to that node in the tree. In this hierarchy, data is associated only with leaf nodes. (A leaf node represents a MIB variable that can have an instance and an associated value.)

An OID must be at least two subidentifiers and at most 128 subidentifiers in length. The subidentifier ranges are:

• Subidentifier 1 values range from 0 to 2, inclusive.
• Subidentifier 2 values range from 0 to 39, inclusive.
• The remaining subidentifier values can be any nonnegative number.

Figure 3-1 illustrates the SMI hierarchical tree arrangement as specified in RFCs 1155 and 1902.

Figure 3-1 MIB II in SMI Tree Structure

For example, the chess MIB provided with the sample code in the [TCPIP$EXAMPLES.SNMP] directory has an element with the name "chess." The OID for the element chess is 1.3.6.1.4.1.36.2.15.2.99, which is derived from its position in the hierarchy of the tree:

iso(1) org(3) dod(6) internet(1) private(4) enterprise(1) digital(36) ema(2) sysobjects(15) decosf(2) chess(99)

Any node in the MIB hierarchy can define a MIB subtree. All elements in the subtree have an OID that starts with the OID of the subtree base. For example, if you define chess to be a MIB subtree base, the elements with the same prefix as the chess OID are all in the MIB subtree:

chess 1.3.6.1.4.1.36.2.15.2.99 chessProductID 1.3.6.1.4.1.36.2.15.2.99.1 chessMaxGames 1.3.6.1.4.1.36.2.15.2.99.2 chessNumGames 1.3.6.1.4.1.36.2.15.2.99.3 gameTable 1.3.6.1.4.1.36.2.15.2.99.4 gameEntry 1.3.6.1.4.1.36.2.15.2.99.4.1 gameIndex 1.3.6.1.4.1.36.2.15.2.99.4.1.1 gameDescr 1.3.6.1.4.1.36.2.15.2.99.4.1.2 gameNumMoves 1.3.6.1.4.1.36.2.15.2.99.4.1.3 gameStatus 1.3.6.1.4.1.36.2.15.2.99.4.1.4 moveTable 1.3.6.1.4.1.36.2.15.2.99.5 moveEntry 1.3.6.1.4.1.36.2.15.2.99.5.1 moveIndex 1.3.6.1.4.1.36.2.15.2.99.5.1.1 moveByWhite 1.3.6.1.4.1.36.2.15.2.99.5.1.2 moveByBlack 1.3.6.1.4.1.36.2.15.2.99.5.1.3 moveStatus 1.3.6.1.4.1.36.2.15.2.99.5.1.4 chessTraps 1.3.6.1.4.1.36.2.15.2.99.6 moveTrap 1.3.6.1.4.1.36.2.15.2.99.6.1

The base of this MIB subtree is registered with the master agent to tell it that this subagent handles all requests related to the elements in the subtree.

The master agent expects a subagent to handle all objects subordinate to the registered MIB subtree. This principle guides your choice of MIB subtrees. For example, registering a subtree of chess is reasonable because it is realistic to assume that the subagent could handle all requests for elements in this subtree. Registering an entire application-specific MIB usually makes sense because the particular application expects to handle all objects defined in the application-specific MIB.

However, registering a subtree of SNMP (under MIB II) would be a mistake, because it is unlikely that the subagent is prepared to handle every defined MIB object subordinate to SNMP (packet counts, errors, trapping, and so on).

A subagent can register as many MIB subtrees as it wants. It can register OIDs that overlap with other registrations by itself or with other subagents; however, it cannot register the same OID more than once. Subagents can register and unregister MIB subtrees at any time after communication with the master agent is established.

Normally, it is the nonleaf nodes that are registered as a subtree with the master agent. However, leaf nodes, or even specific instances, can be registered as a subtree.

The master agent delivers requests to the subagent that has the MIB subtree with the longest prefix and the highest priority.

3.3 Creating a MIB Source File

Creating the MIB source file requires the following four-step process:

1. Write the ASN.1 input files, as described in Section 3.3.1.
2. Process the input files with the MIB compiler, as described in Section 3.3.2.
3. Compile and link the routines, as described in Section 3.4.
4. Include the subagent, as described in Section 3.5.

After you have assigned names and OIDs to all of the objects in the MIB, create an ASN.1 source file using ASCII statements.

Instead of creating ASN.1 files yourself, you can create .MY files from existing ASCII files (for example, from RFCs) by using the MIB-converter facility provided with TCP/IP Services. This facility uses a UNIX awk script, which runs on OpenVMS as well as on appropriately configured UNIX systems. For details about the facility, see the MIB-CONVERTER.AWK file, which is located in the [.SNMP] subdirectory of TCPIP$EXAMPLES. Standard .MY files are also provided for your convenience.

The custom MIB definition files have the default extension .MY.

3.3.2 Processing the Input File with the MIB Compiler

Process your ASN.1 source files with the MIB compiler using the DCL command MIBCOMP.

The compilation process produces two template C programming modules that are used in building the executable subagent code. When you run the compiler, specify all the ASN.1 source files for a given subagent. Whenever any of these source files are updated, you must repeat the compilation process.

The syntax for the MIBCOMP command is as follows:

MIBCOMP MIB-source-file "subtree" [/PREFIX=prefix-name] [/PRINT_TREE] [/SNMPV2]

The parameters and qualifiers for the MIBCOMP command are as follows:

Parameter or Qualifier	Definition
MIB-source-file	A comma-separated list of MIB definition files. The standard extension is .MY, but you can specify any valid OpenVMS file name. You must specify the full file name.
subtree	The text name for the root of your MIB definitions. This parameter must be enclosed in quotation marks. This name is used in generating names for template C modules and also for the names of the files themselves: subtree_tbl.c and subtree_tbl.h.
/PREFIX= prefix-name	The MIB compiler attaches the prefix-name string to the beginning of all generated names.
/PRINT_TREE	Displays the entire MIB subtree.
/SNMPV2	Specifies the use of SNMP Version 2 parsing rules.

The following is an example of processing the chess example files using the /PRINT_TREE qualifier:

$ MIBCOMP RFC1442.MY,CHESS_MIB.MY "chess" /PRINT_TREE Processing RFC1442.MY Processing CHESS_MIB.MY Dump of objects in lexical order -- This file created by program 'snmpi -p' ccitt 0 iso 1 internet 1.3.6.1 directory 1.3.6.1.1 mgmt 1.3.6.1.2 experimental 1.3.6.1.3 private 1.3.6.1.4 enterprises 1.3.6.1.4.1 dec 1.3.6.1.4.1.36 ema 1.3.6.1.4.1.36.2 sysobjectids 1.3.6.1.4.1.36.2.15 decosf 1.3.6.1.4.1.36.2.15.2 chess 1.3.6.1.4.1.36.2.15.2.99 chessProductID 1.3.6.1.4.1.36.2.15.2.99.1 ObjectID read-only chessMaxGames 1.3.6.1.4.1.36.2.15.2.99.2 INTEGER read-only chessNumGames 1.3.6.1.4.1.36.2.15.2.99.3 INTEGER read-only gameTable 1.3.6.1.4.1.36.2.15.2.99.4 gameEntry 1.3.6.1.4.1.36.2.15.2.99.4.1 indexes: gameIndex gameIndex 1.3.6.1.4.1.36.2.15.2.99.4.1.1 INTEGER read-write gameDescr 1.3.6.1.4.1.36.2.15.2.99.4.1.2 DisplayString read-write range: 0 to 255 gameNumMoves 1.3.6.1.4.1.36.2.15.2.99.4.1.3 INTEGER read-write gameStatus 1.3.6.1.4.1.36.2.15.2.99.4.1.4 INTEGER read-write enum: complete 1 enum: underway 2 enum: delete 3 moveTable 1.3.6.1.4.1.36.2.15.2.99.5 moveEntry 1.3.6.1.4.1.36.2.15.2.99.5.1 indexes: gameIndex moveIndex moveIndex 1.3.6.1.4.1.36.2.15.2.99.5.1.1 INTEGER read-write moveByWhite 1.3.6.1.4.1.36.2.15.2.99.5.1.2 DisplayString read-write range: 0 to 255 moveByBlack 1.3.6.1.4.1.36.2.15.2.99.5.1.3 DisplayString read-write range: 0 to 255 moveStatus 1.3.6.1.4.1.36.2.15.2.99.5.1.4 INTEGER read-write enum: ok 1 enum: delete 2 security 1.3.6.1.5 snmpV2 1.3.6.1.6 snmpDomains 1.3.6.1.6.1 snmpProxys 1.3.6.1.6.2 snmpModules 1.3.6.1.6.3 joint_iso_ccitt 2 -------------------------- 11 objects written to chess_tbl.c 11 objects written to chess_tbl.h

3.3.2.1 UNIX Utilities Supplied with TCP/IP Services

For compatibility with UNIX, the mosy and snmpi utilities are provided with TCP/IP Services for generating the C language code that defines the object tables. These UNIX utilities are supported on OpenVMS for compatibility with UNIX-developed procedures. For information about using these utilities, refer to the hp Tru64 UNIX Network Programmer's Guide.

3.3.2.2 Object Tables

The MIBCOMP command is used to generate the C language code that defines the object tables from the MIBs. The object tables are defined in the emitted files subtree_TBL.H and subtree_TBL.C, which are compiled into your subagent.

These modules are created by the MIBCOMP command or the UNIX utilities. HP recommends that you do not edit them. If the MIBs change or if a future version of the SNMP development utilities requires your object tables to be rebuilt, it is easier to rebuild and recompile the files if you did not edit them.

3.3.2.3 The subtree_TBL.H Output File

The subtree_TBL.H file contains the following sections:

1. A declaration of the subtree structure
2. Index definitions for each MIB variable in the subtree
3. Enumeration definitions for MIB variables with enumerated values
4. MIB group data structure definitions
5. Method routine function prototypes

The following sections describe each section of the subtree_TBL.H file.

1. Declaration Section

The first section of the subtree_TBL.H file is a declaration of the subtree structure. The subtree is automatically initialized by code in the subtree_TBL.C file. A pointer to this structure is passed to the esnmp_register routine to register a subtree with the master agent. All access to the object table for this subtree is through this pointer. The declaration has the following form:

extern SUBTREE subtree_subtree;

2. Index Definitions Section

The second section of the subtree_TBL.H file contains index definitions for each MIB variable in the subtree of the form:

#define I_mib-variable nnn

These values are unique for each MIB variable in a subtree and are the index into the object table for this MIB variable. These values are also generally used to differentiate between variables that are implemented in the same method routine so they can be used in a switch operation.

3. Enumeration Definitions Section

The third section of the subtree_TBL.H file contains enumeration definitions for those integer MIB variables that are defined with enumerated values, as follows:

#define D_mib-variable_enumeration-name value

These definitions are useful because they describe the value that enumerated integer MIB variables may take on. For example:

/* enumerations for gameEntry group */ #define D_gameStatus_complete 1 #define D_gameStatus_underway 2 #define D_gameStatus_delete 3

4. MIB Group Data Structure Definitions Section

The fourth section of the subtree_TBL.H file contains data structure definitions of the following form:

typedef structxxx { type mib-variable; . . . char mib-variable_mark; . . . } mib-group_type

The MIB compiler generates one of these data structures for each MIB group in the subtree. Each structure definition contains a field representing each MIB variable in the group. In addition to the MIB variable fields, the structure includes a 1-byte mib-variable-mark field for each variable. You can use these for maintaining status of a MIB variable. For example, the following is the group structure for the chess MIB:

typedef struct _chess_type { OID ches; int chessMaxGames; int chessNumGames; char chessProductID_mark; char chessMaxGames_mark; char chessNumGames_mark; } chess_type;

Although MIB group structures are provided for your use, you are not required to use them. You can use the structure that works best with your method routines.

5. Method Routine Prototypes Section

The fifth section of the subtree_TBL.H file describes the method routine prototypes. Each MIB group within the subtree has a method routine prototype defined. A MIB group is a collection of MIB variables that are leaf nodes and that share a common parent node.

There is always a function prototype for the method routine that handles the Get , GetNext , and GetBulk operations. If the group contains any writable variables, there is also a function prototype for the method routine that handles Set operations. Pointers to these routines appear in the subtree's object table which is initialized in the subtree_TBL.C module. You must write method routines for each prototype that is defined, as follows:

extern int mib-group get( METHOD *method ); extern int mib-group set( METHOD *method );

For example:

extern int chess_get( METHOD *method ); extern int chess_set( METHOD *method );