|
HP OpenVMS Systems Documentation |
|
HP TCP/IP Services for OpenVMS
|
| Previous | Contents | Index |
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:
The TCP/IP Services implementation of SNMP does not support the following defined MIB II groups:
|
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:
1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.22.1 |
iso.org.dod.internet.private.enterprises.dec.ema.SysObjectIds.DEC-OpenVMS.eSNMP |
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 |
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 |
d n hh:mm:ss |
ifInDiscards ifInErrors ifInNUcastPkts ifInOctets ifInUcastPkts ifInUnknownProtos ifOutErrors ifOutNUcastPkts ifOutOctets ifOutUcastPkts |
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:
To use this eSNMP API to create a subagent, you must have a C compiler running in your development environment. |
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:
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:
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.
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:
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:
After you have assigned names and OIDs to all of the objects in the MIB, create an ASN.1 source file using ASCII statements.
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.
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
|
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:
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 |