[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP TCP/IP Services for OpenVMS
SNMP Programming and Reference


Previous Contents Index

2.2 Overview of MIB II

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.

Note

The TCP/IP Services implementation of SNMP does not support the following defined MIB II groups:
  • at (address translation) group
  • EGP (External Gateway Protocol) group
  • transmission group

2.2.2 Restrictions to MIB II Implementation

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 ( 232 - 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)


Chapter 3
Creating a Subagent Using the eSNMP API

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:

Note

To use this eSNMP API to create a subagent, you must have a C compiler running in your development environment.

3.1 Creating a MIB Specification

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

3.2.1 Assigning Object Identification Codes

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.

Note

Your organization may require you to register all newly assigned OIDs.

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.

Note

This manual assumes that you understand the OID naming structure used in SNMP. If not, refer to RFC 1902: Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMP Version 2).

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.

3.3.1 Writing the ASN.1 Input File

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

Note

Providing information about ASN.1 syntax and programming is beyond the scope of this guide. For more information about ASN.1 programming, refer to one or more of the documents on this subject provided by the International Organization for Standardization (ISO).

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.

Note

If you are familiar with processing on UNIX systems, you can use the UNIX utilities snmpi and mosy . See Section 3.3.2.1 for more information.

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


Previous Next Contents Index