Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference Order Number: AA–R04BC–TE January 2001 Revision/Update Information: This manual supersedes the DIGITAL TCP/IP Services for OpenVMS eSNMP Programming and Reference, Version 5.0. Software Version: Compaq TCP/IP Services for OpenVMS Version 5.1 Operating Systems: OpenVMS Alpha Versions 7.1, 7.2-1 OpenVMS VAX Versions 7.1, 7.
© 2001 Compaq Computer Corporation COMPAQ, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office. OpenVMS and Tru64 are trademarks of Compaq Information Technologies Group, L.P. in the United States and other countries. All other product names mentioned herein may be trademarks of their respective companies. Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii 1 Overview 1.1 1.2 1.3 1.4 1.5 1.5.1 1.6 1.7 1.7.1 1.8 SNMP Architecture . . . . . . . . . . . . . . . . . . . . . . . . . Request Handling . . . . . . . . . . . . . . . . . . . . . . . . . . TCP/IP Services Components for SNMP . . . . . . . . . Writing an eSNMP Subagent . . . . . . . . . . . . . . . . . . The eSNMP API . . . . . . . . . . . . . . . . . . . . . . .
Using the SNMP Utilities 4.1 Using the MIB Browser . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.1 MIB Browser Parameters . . . . . . . . . . . . . . . . . . . . . 4.1.2 MIB Browser Flags . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.3 MIB Browser Data Types . . . . . . . . . . . . . . . . . . . . . 4.1.4 Command Examples for snmp_request . . . . . . . . . . 4.2 Using the Trap Sender and Trap Receiver Programs . . . 4.2.1 Entering Commands for the Trap Sender Program . 4.2.1.
cmp_oid_prefix . . . . . clone_oid . . . . . . . . . free_oid . . . . . . . . . . clone_buf . . . . . . . . . mem2oct . . . . . . . . . . cmp_oct . . . . . . . . . . clone_oct . . . . . . . . . free_oct . . . . . . . . . . free_varbind_data . . set_debug_level . . . . is_debug_level . . . . . ESNMP_LOG . . . . . . _ _print_varbind . . . . set_select_limit . . . . . _ _set_progname . . . . _ _restore_progname . _ _parse_progname . . esnmp_cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preface The Compaq TCP/IP Services for OpenVMS product is the Compaq implementation of the TCP/IP networking protocol suite and internet services for OpenVMS Alpha and OpenVMS VAX systems. A layered software product, TCP/IP Services provides a comprehensive suite of functions and applications that support industry-standard protocols for heterogeneous network communications and resource sharing. This manual describes the features of the Simple Network Managment Protocol (SNMP) provided with TCP/IP Services.
Related Documents Table 1 lists the documents available with this version of TCP/IP Services. Table 1 TCP/IP Services Documentation Manual Contents DIGITAL TCP/IP Services for OpenVMS Concepts and Planning This manual provides conceptual information about networking and the TCP/IP protocol including a description of the Compaq implementation of the Berkeley Internet Name Domain (BIND) service and the Network File System (NFS).
Table 1 (Cont.) TCP/IP Services Documentation Manual Contents Compaq TCP/IP Services for OpenVMS Sockets API and System Services Programming This manual describes how to use the Sockets API and OpenVMS system services to develop network applications. Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference This manual describes the Simple Network Management Protocol (SNMP) and the SNMP application programming interface (eSNMP).
The following conventions are used in this manual. In addition, please note that all IP addresses are fictitious. Ctrl/x A sequence such as Ctrl/x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button. PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
Monospace text Monospace type indicates code examples and interactive screen displays. This typeface indicates UNIX system output or user input, commands, options, files, directories, utilities, hosts, and users. In the C programming language, this typeface identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
1 Overview The Simple Network Management Protocol (SNMP) is the de facto industry standard for managing TCP/IP networks. The protocol defines the role of a network management station (NMS) and the SNMP agent. SNMP allows remote users on an NMS to monitor and manage network entities such as hosts, routers, X terminals, and terminal servers.
Overview 1.1 SNMP Architecture Figure 1–1 SNMP Architecture Master Agent Subagent 1 Subagent 2 Subagent n eSNMP API SNMP/ASN.1 Library AgentX (TCP/IP V5.1) TCP/IP Kernel OpenVMS VM-0704A-AI The SNMP environment consists of the following elements: • The master agent, a process that runs on the host and handles SNMP requests from clients over the standard SNMP well-known port 161. • One or more subagents, each of which provides access to the MIB data specified in client requests.
Overview 1.2 Request Handling Figure 1–2 eSNMP Data Flow NMS1 Host 1 Subagent 1 Client 705 Master Agent Network Subagent 2 161 Subagent n NMS2 Host 2 Client 161 Master Agent Trap client Subagent 1 Legend: Flow of trap notification Flow of get/set request Flow of "are_you_there" message VM-0705A-AI The process of communication for a request is illustrated with dashed lines and includes the following steps: 1.
Overview 1.2 Request Handling The network management station sends an SNMP request to the master agent running on the host, using port 161. An SNMP request is made using one of the following commands: • Get • GetNext • GetBulk • Set Note TCP/IP Services does not support the standard SNMP Inform command. The request specifies the object identifer (OID) of the data to be accessed. For information about formatting get and set requests, refer to Section 5.2. Request formats are specified in RFC 1905.
Overview 1.3 TCP/IP Services Components for SNMP Table 1–1 (Cont.) SNMP Component Files File Location Function TCPIP$SNMP_TRAPRCV.EXE SYS$SYSTEM Utility for receiving trap messages. TCPIP$ESNMP_SHR.EXE SYS$SHARE Image file containing eSNMP application programming interface (API) routines. TCPIP$SNMP_STARTUP.COM SYS$STARTUP Command procedure that installs master and subagent images and runs TCPIP$SNMP_RUN.COM. TCPIP$SNMP_SYSTARTUP.
Overview 1.4 Writing an eSNMP Subagent 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.
Overview 1.
Overview 1.6 The MIB Compiler • 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 1.7 SNMP Versions 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.
Overview 1.7 SNMP Versions 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.
2 MIBs Provided with TCP/IP Services 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) 2.1 Overview of the Host Resources MIB The Host Resources MIB defines a uniform set of objects useful for the management of host computers.
MIBs Provided with TCP/IP Services 2.1 Overview of the Host Resources MIB Table 2–1 (Cont.) Host Resources MIB Objects Object Name RFC Description OpenVMS Description 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.
MIBs Provided with TCP/IP Services 2.1 Overview of the Host Resources MIB Table 2–1 (Cont.) Host Resources MIB Objects Object Name RFC Description OpenVMS Description 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.
MIBs Provided with TCP/IP Services 2.1 Overview of the Host Resources MIB hrFSLastFullBackupDate hrFSLastPartialBackupDate hrStorageSize hrSWRunStatus hrSystemDate hrSystemInitialLoadDevice hrSystemInitialLoadParameters Note For objects that are not implemented, the Host Resources MIB returns a NoSuchObject error status.
MIBs Provided with TCP/IP Services 2.1 Overview of the Host Resources MIB 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.
MIBs Provided with TCP/IP Services 2.2 Overview of MIB II 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.
MIBs Provided with TCP/IP Services 2.2 Overview of MIB II 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.2.1.1.9.1.2.2 1.3.6.1.2.1.1.9.1.3.1 1.3.6.1.2.1.1.9.1.3.2 1.3.6.1.2.1.1.9.1.4.1 1.3.6.1.2.1.1.9.1.4.2 = = = = = = 1.3.6.1.4.1.36.15.3.3.1.1 1.3.6.1.4.1.36.15.3.3.1.
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: • 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.
Creating a Subagent Using the eSNMP API 3.2 The Structure of Management Information 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).
Creating a Subagent Using the eSNMP API 3.
Creating a Subagent Using the eSNMP API 3.2 The Structure of Management Information 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.
Creating a Subagent Using the eSNMP API 3.2 The Structure of Management Information 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.
Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source File 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.
Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source File enum: complete enum: underway enum: delete 1 2 3 1.3.6.1.4.1.36.2.15.2.99.5 1.3.6.1.4.1.36.2.15.2.99.5.1 moveTable moveEntry 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.
Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source 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.
Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source File 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.
Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source File 2. Array of OBJECT Structures Section The second section of the subtree_TBL.C file is an array of OBJECT structures. Each MIB variable within the subtree has one OBJECT. The chess example produces the following: static OBJECT objects[] = { {I_chessProductID ...
Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source File 3. Initialized Subtree Structure Section The third section of the subtree_TBL.C file is the SUBTREE structure itself. A pointer to this structure is passed to the eSNMP library routine esnmp_register to register the subtree. It is through this pointer that the library routines find the object structures. The following is an example of the chess subtree structure: SUBTREE chess_subtree = { "chess", "1.3.6.1.4.1.36.2.15.2.
Creating a Subagent Using the eSNMP API 3.4 Including the Routines and Building the Subagent Depending on the version of the Compaq C compiler you are using, you might see warnings that you can ignore. Portions of these warnings are as follows: %CC-I-SIGNEDKNOWN In this declaration, DEC C recognizes the ANSI keyword "signed". This differs from the VAX C behavior. %CC-I-INTRINSICINT In this statement, the return type for intrinsic "strlen" is being changed from "size_t" to "int". 2.
Creating a Subagent Using the eSNMP API 3.5 Including Extension Subagents in the Startup and Shutdown Procedures File Name Edit Required TCPIP$EXTENSION_MIB_SHUTDOWN.COM Edit the example lines to: • Include symbols for the detached processes that are running custom images. Use the same process names specified in TCPIP$EXTENSION_MIB_ RUN.COM. • Modify the IF and THEN statements to include the new symbols. • Include an INSTALL DELETE command for images installed in TCPIP$EXTENSION_MIB_ STARTUP.COM.
4 Using the SNMP Utilities TCP/IP Services includes the following programs, which are useful for testing applications and for analyzing SNMP problems: • TCPIP$SNMP_REQUEST (MIB browser) (Section 4.1) • TCPIP$SNMP_TRPSND (trap sender) (Section 4.2) • TCPIP$SNMP_TRPRCV (trap receiver) (Section 4.2) These programs can be invoked by commands that are defined by the SYS$STARTUP:TCPIP$DEFINE_COMMANDS.COM command procedure. This chapter describes how to use the supplied SNMP utilities. 4.
Using the SNMP Utilities 4.1 Using the MIB Browser Table 4–1 (Cont.) snmp_request Command Parameters Parameter Function "community" The community string to be used in the query. This parameter is case sensitive. Typically, agents are configured to permit read access to the community string "public". For accurate interpretation, be sure to enclose the name in quotation marks (" "). Note that if you do not use quotation marks, the name is changed to lowercase. request-type PDU type to send.
Using the SNMP Utilities 4.1 Using the MIB Browser Table 4–2 Flags for the snmp_request Command Flag Description -d Specifies hexadecimal dump mode. Before displaying a return value, displays a hexadecimal dump of SNMP packets sent and received. For example: $ snmp_request host1 "public" getnext -d -v 2c 1.3.6.1.6.3.1.1.6 Sent: 30290201 01040670 75626C69 63A11C02 047BE9C1 BD020100 02010030 0E300C06 082B0601 06030101 060500 0).....public... .{.........0.0.. .+.........
Using the SNMP Utilities 4.1 Using the MIB Browser Table 4–2 (Cont.) Flags for the snmp_request Command Flag Description -l Specifies loop mode. Note that this flag is the letter l, not the number 1. Valid only if request-type is GetNext or GetBulk (where flag 0, and flag m is set to a number greater than 0). n is set to Causes the master agent to traverse all the MIBs registered with the master agent, starting at the first OID after the one specified in the command.
Using the SNMP Utilities 4.1 Using the MIB Browser Table 4–2 (Cont.) Flags for the snmp_request Command Flag Description -s sleep_interval Specifies the number of seconds between iterations of sending a request (for the -r flag) and listening for a reply (for the -i) flag. The default is 1 second. This flag is ignored if neither the -r flag nor the -i flag are specified. The -s flag is useful for specifying a time to wait between resends, which might be necessary when a server agent is starting up.
Using the SNMP Utilities 4.1 Using the MIB Browser Note Except for -l (Counter64), the data types are case sensitive. To preserve uppercase for display strings and NULL, enclose the value in double quotation marks. For example, ‘‘–D’’ or ‘‘–N’’. On OpenVMS Alpha systems, you must specify the value of the -l data type as a 64-bit integer. For example: $ snmp_trapsnd 0.0 mynode 6 33 100 -h mynode -v2c _$ 1.3.6.1.2.1.1.4.
Using the SNMP Utilities 4.1 Using the MIB Browser $ snmp_request marley.dec.com "public" get 1.3.6.1.2.1.2.2.1.2.1 _$ 1.3.6.1.2.1.25.1.1.0 1.3.6.1.2.1.2.2.1.2.1 = LO IP Interface: LO0, OpenVMS Adapter: , Loopback Port 1.3.6.1.2.1.25.1.1.0 = 6024942 = 0 d 16:44:9 3. The following example shows how to retrieve the next MIB II variable. This is similar to the command in example 1, except that a GetNext request is issued and sysObjectID.0 (1.3.6.1.2.1.1.2.0) is returned. $ snmp_request marley.dec.
Using the SNMP Utilities 4.1 Using the MIB Browser 6. The following example uses the same command as in example 5, but it specifies the -t flag instead of the -l flag. Only OIDs with the prefix matching the input OID are returned. Note that as with other getnext request examples, the value for the input OID is not returned. If an SNMP Version 2 agent is the server, the results using getbulk are identical. $ snmp_request marley.dec.com "public" getnext -t 1.3.6.1.2.1.1 1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.
Using the SNMP Utilities 4.2 Using the Trap Sender and Trap Receiver Programs By default, these programs use UDP port 162. However, you can specify another port with the -p flag or set up an SNMP-trap service that specifies the port you want to use. Note, however, that the use of UDP port 162 is coded into standard MIBs. Both programs support the use of the UDP (default) and TCP transports. However, the standard TCP/IP subagents and the Chess example use UDP only.
Using the SNMP Utilities 4.2 Using the Trap Sender and Trap Receiver Programs Table 4–4 Parameters for the snmp_trapsnd Command Parameter Description enterprise For SNMP Version 1, specifies the enterprise object identifier (OID) on whose behalf the trap is being sent. For example, 1.3.6.1.4.1.1. If you specify 0 or 0.0, the null OID (0.0) is sent. Make sure that any OID you specify conforms to the OID rules. For SNMP Version 2, when specified with the snmpTrapOID.0. agent For SNMP Version 1 traps.
Using the SNMP Utilities 4.2 Using the Trap Sender and Trap Receiver Programs Table 4–5 (Cont.) Flags for the snmp_trapsnd Command Flag Description -h host Specifies the host name or IP address (in ASN.1 dot notation format) of the destination host to receive the trap message. The default is localhost (127.0.0.1). -p port Specifies a port number on the destination host where the message is to be sent. The default is UDP 162.
Using the SNMP Utilities 4.2 Using the Trap Sender and Trap Receiver Programs enterprise - 1.2.3 agent address - 6.20.208.53 trap type - Enterprise-specific (6) enterprise-specific value - (33) timeticks - 100 4.2.2 Entering Commands for the Trap Receiver Program The trap receiver program lets you listen for, receive, and display SNMP trap messages. Until interrupted, the program continues to listen on the specified port.
Using the SNMP Utilities 4.2 Using the Trap Sender and Trap Receiver Programs account that has SYSPRV privilege. Note that the port number must be greater than zero. 4.2.2.3 Trap Receiver Examples 1. The following example requests trap information on a system that does not have traps configured and does not have SYSPRV privilege or sufficient privilege. $ snmp_traprcv No snmp-trap service entry, using default port 162. bind - : permission denied 2.
5 eSNMP API Routines This chapter provides reference information about the following types of application programming interface (API) routines in the eSNMP developer’s kit: • Interface routines (Section 5.1) • Method routines (Section 5.2) • Support routines (Section 5.3) 5.1 Interface Routines The interface routines are for developers writing the portion of the application programming interface (API) that handles the connection between the agent and the subagent.
eSNMP API Routines esnmp_init esnmp_init Initializes the Extensible SNMP (eSNMP) subagent and initiates communication with the master agent. Format int esnmp_init (int *socket, char *subagent_identifier ) ; Arguments socket The address of the integer that receives the socket descriptor used by eSNMP. subagent_identifier The address of a null-terminated string that uniquely identifies this subagent (usually a program name).
eSNMP API Routines esnmp_register esnmp_register Requests local registration of a single MIB subtree. This indicates to the master agent that the subagent instantiates MIB variables within the registered MIB subtree. Format int esnmp_register ( subtree *subtree, int timeout, int priority ) ; Arguments subtree A pointer to a subtree structure corresponding to the subtree to be handled. The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.
eSNMP API Routines esnmp_register A subtree is identified by the base MIB name and the corresponding OID number of the node that is the parent of all MIB variables contained in the subtree. For example: The MIB II tcp subtree has an OID of 1.3.6.1.2.1.6. All elements subordinate to this have the same first seven digits and are included in the subtree’s object table. The subtree can also be a single MIB object (a leaf node) or even a specific instance.
eSNMP API Routines esnmp_register status = esnmp_register( &ipRouteEntry_subtree, RESPONSE_TIMEOUT, REGISTRATION_PRIORITY ); if (status != ESNMP_LIB_OK) { printf ("Could not queue the ’ipRouteEntry’ \n"); printf ("subtree for registration\n"); } eSNMP API Routines 5–5
eSNMP API Routines esnmp_unregister esnmp_unregister Cancels registration of a MIB subtree previously registered with the master agent. Format int esnmp_unregister ( SUBTREE *subtree ) ; Arguments subtree A pointer to a subtree structure corresponding to the subtree to be handled. The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures. Refer to Chapter 3 for more information about these files.
eSNMP API Routines esnmp_register2 esnmp_register2 Requests registration of a single MIB subtree. This indicates to the master agent that the subagent instantiates MIB variables within the registered MIB subtree. The esnmp_register2 routine offers extensions to the esnmp_register routine.
eSNMP API Routines esnmp_register2 Field Name Description range_upper_bound An integer value that, with a nonzero range_subid field, specifies a range instead of one of the MIB subtree’s OID subidentifiers. The range_upper_bound field provides the upper bound of the range and the range_subid field provides the lower bound of the range, which is the MIB subtree’s OID subidentifier. An integer value that, when set to ESNMP_REG_OPT_CLUSTER, indicates that the registration is valid clusterwide.
eSNMP API Routines esnmp_register2 When restarting the eSNMP protocol by calling esnmp_init, all MIB subtree registrations are cleared. All MIB subtrees must be reregistered. A MIB subtree is identified by the base MIB variable name and its corresponding OID. This tuple represents the parent of all MIB variables that are contained in the MIB subtree; for example, the MIB II tcp subtree has an OID of 1.3.6.1.2.1.6.
eSNMP API Routines esnmp_register2 Example #include
eSNMP API Routines esnmp_unregister2 esnmp_unregister2 Cancels registration of a MIB subtree previously established with the master agent. Use this routine only when the MIB subtree was registered using the esnmp_register2 routine. Format int esnmp_unregister2 ( ESNMP_REG *reg ) ; Arguments reg A pointer to the ESNMP_REG structure that was used when the esnmp_register2 routine was called.
eSNMP API Routines esnmp_capabilities esnmp_capabilities Adds a subagent’s capabilities to the master agent’s sysORTable. The sysORTable is a conceptual table that contains an agent’s object resources, and is described in RFC 1907. Format void esnmp_capabilities ( OID *agent_cap_id, char *agent_cap_descr ) ; Arguments agent_cap_id A pointer to an object identifier that represents an authoritative agent capabilities identifier.
eSNMP API Routines esnmp_uncapabilities esnmp_uncapabilities Removes a subagent’s capabilities from the master agent’s sysORTable. Format void esnmp_uncapabilities ( OID *agent_cap_id ) ; Arguments agent_cap_id A pointer to an object identifier that represents an authoritative agent capabilities identifier. This value is used for the sysORID object in the sysORTable for the managed node. Description This routine is called if a subagent alters its capabilities dynamically.
eSNMP API Routines esnmp_poll esnmp_poll Processes a pending message that was sent by the master agent. Format int esnmp_poll ( ) Description This routine is called after the select( ) call has indicated data is ready on the eSNMP socket. (This socket was returned from the call to the esnmp_init routine.) If a received message indicates a problem, an entry is made to the SNMP log file and an error status is returned.
eSNMP API Routines esnmp_are_you_there esnmp_are_you_there Requests the master agent to report immediately that it is up and functioning. Format int esnmp_are_you_there ( ) ; Description The esnmp_are_you_there routine does not block waiting for a response. The routine is intended to cause the master agent to reply immediately. The response should be processed by calling the esnmp_poll routine.
eSNMP API Routines esnmp_trap esnmp_trap Sends a trap message to the master agent. Format int esnmp_trap ( int *generic_trap, int specific_trap, char *enterprise, varbind *vb ) 2 ; Arguments generic_trap A generic trap code. Set this argument value to 0 (zero) for SNMPv2 traps. specific_trap A specific trap code. Set this argument value to 0 (zero) for SNMPv2 traps. enterprise An enterprise OID string in dot notation.
eSNMP API Routines esnmp_term esnmp_term Sends a close message to the master agent and shuts down the subagent. Format void esnmp_term (void) ; Description Subagents must call this routine when terminating so that the master agent can update its MIB registry quickly and so that resources used by eSNMP on behalf of the subagent can be released. Return Values ESNMP_LIB_OK The esnmp_term routine always returns ESNMP_ LIB_OK, even if the packet could not be sent.
eSNMP API Routines esnmp_sysuptime esnmp_sysuptime Converts UNIX system time obtained from gettimeofday into a value with the same time base as sysUpTime. Format unsigned int esnmp_sysuptime ( struct timeval *timestamp ) ; Argument timestamp A pointer to struct timeval, which contains a value obtained from the gettimeofday system call. The structure is defined in include/sys/time.h. A null pointer means return the current sysUpTime.
eSNMP API Routines 5.2 Method Routines 5.2 Method Routines SNMP requests may contain many encoded MIB variables. The libsnmp code executing in a subagent matches each VariableBinding with an object table entry. The object table’s method routine is then called. Therefore, a method routine is called to service a single MIB variable. Since a single method routine can handle a number of MIB variables, the same method routine may be called several times during a single SNMP request.
eSNMP API Routines *_get Routine *_get Routine The *_get routine is a method routine for the specified MIB item, which is typically a MIB group (for example, system in MIB II) or a table entry (for example, ifEntry in MIB II). Format int mib-group_get ( METHOD *method ) ; Arguments method A pointer to a METHOD structure that contains the following fields: Field Name Description action One of ESNMP_ACT_GET, ESNMP_ACT_ GETNEXT, or ESNMP_ACT_GETBULK. An integer number that is unique to this SNMP request.
eSNMP API Routines *_get Routine Field Name Description object A pointer to the object table entry for the MIB variable being referenced. The method->object->object_index field is this object’s unique index within the object table (useful when one method routine services many objects). The method->object->oid field is the OID defined for this object in the MIB. The instance requested is derived by comparing this OID with the OID in the request found in the method->varbind->name field.
eSNMP API Routines *_set Routine *_set Routine The *_set method routine for a specified MIB item, which is typically a MIB group (for example, system in MIB II) or a table entry (for example, ifEntry in MIB II). Format int mib-group_set ( METHOD *method ) ; Arguments method A pointer to a METHOD structure that contains the following fields: Field Name Description action One of ESNMP_ACT_SET, ESNMP_ACT_UNDO, or ESNMP_ACT_ CLEANUP. An integer number that is unique to this SNMP request.
eSNMP API Routines *_set Routine Field Name Description row A pointer to a ROW_CONTEXT structure (defined in the ESNMP.H header file). All Set requests to the method routine that refer to the same group and that have the same instance number will be presented with the same row structure. The method routines can accumulate information in the row structures during Set requests for use during the commit and undo phases. The accumulated data can be released by the method routines during the cleanup phase.
eSNMP API Routines *_set Routine Return Values ESNMP_MTHD_noError ESNMP_MTHD_notWritable ESNMP_MTHD_wrongType ESNMP_MTHD_ wrongLength ESNMP_MTHD_ wrongEncoding ESNMP_MTHD_wrongValue ESNMP_MTHD_noCreation ESNMP_MTHD_ inconsistentName ESNMP_MTHD_ inconsistentValue ESNMP_MTHD_ resourceUnavailable ESNMP_MTHD_genErr ESNMP_MTHD_ commitFailed ESNMP_MTHD_undoFailed The routine completed successfully. The requested object cannot be set or was not implemented. The data type for the requested value is the wrong type.
eSNMP API Routines *_set Routine If any row reports failure, all rows that were successfully committed are told to undo the phase. This is accomplished by calling a single method routine for each row (the same one that was called for the commit phase), with a method->action equal to ESNMP_ACT_UNDO. 4. Each row is released. The same single method routine for each row is called with a method->action equal to ESNMP_ACT_CLEANUP. This occurs for every row, regardless of the results of previous processing.
eSNMP API Routines *_set Routine • ESNMP_ACT_UNDO For each conceptual row that was successfully committed, the same method routine is called with method->action equal to ESNMP_ACT_UNDO. The ROW_CONTEXT structures that have not yet been called for the COMMIT phase are not called for the UNDO phase; they are called for CLEANUP phase. The method routine should attempt to restore conditions to what they were before it executed the COMMIT phase.
eSNMP API Routines *_set Routine • Load the response OID back into the method routine’s VARBIND structure. Set the method->varbind field with the OID of the actual MIB variable instance you are returning. This is usually accomplished by loading an array of integers with the instance OID you wish to return and calling the instance2OID support routine. • Load the response data back into the method routine’s VARBIND structure.
eSNMP API Routines *_set Routine The displaystring is different only in that the character array can be interpreted as ASCII text, but the octetstring can be anything. If the octetstring contains bits or a bit string, the OCT structure contains the following: A length equal to the number of bytes needed to contain the value that is ((qty-bits - 1)/8 + 1) A pointer to a buffer containing the bits of the bitstring in the form bbbbb..
eSNMP API Routines *_set Routine • ESNMP_TYPE_Integer32 ESNMP_TYPE_Counter32 ESNMP_TYPE_value.ul field) The 32-bit counter and 32-bit gauge data types are stored in the VARBIND structure as an unsigned integer. Use the o_integer function to insert an unsigned value into the VARBIND structure. • ESNMP_TYPE_TimeTicks (varbind->value.ul field) The 32-bit timeticks type values are stored in the VARBIND structure as an unsigned integer.
eSNMP API Routines 5.3 Support Routines 5.3 Support Routines The support routines are provided as a convenience for developers writing method routines that handle specific MIB elements.
eSNMP API Routines o_integer o_integer Loads an integer value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure. Format int o_integer ( VARBIND *vb, OBJECT *obj, unsigned long value ); Arguments vb A pointer to the VARBIND structure that is supposed to receive the data. obj A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure. value The value to be inserted into the VARBIND structure.
eSNMP API Routines o_integer Example #include #include "ip_tbl.
eSNMP API Routines o_octet o_octet Loads an octet value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure. Format int o_octet ( VARBIND *vb, OBJECT *obj, unsigned long value ); Arguments vb A pointer to the VARBIND structure that is supposed to receive the data. If the original value in the vb field is not null, this routine attempts to free it.
eSNMP API Routines o_oid o_oid Loads an OID value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure. Format int o_oid ( VARBIND *vb, OBJECT *obj, OID *oid ); Arguments vb A pointer to the VARBIND structure that is supposed to receive the data. If the original value in the VARBIND structure is not null, this routine attempts to free it.
eSNMP API Routines o_string o_string Loads a string value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure. Format int o_string ( VARBIND *vb, OBJECT *obj, unsigned character *ptr, int len ); Arguments vb A pointer to the VARBIND structure that is supposed to receive the data. If the original value in the VARBIND structure is not null, this routine attempts to free it.
eSNMP API Routines o_string Example #include #include "ip_tbl.h" <-- for ipNetToMediaEntry_type definition VARBIND *vb = method->varbind; OBJECT *object = method->object; ipNetToMediaEntry_type *data; : : assume buffer and structure member assignments occur here : switch(arg) { case I_atPhysAddress: return o_string(vb, object, data->ipNetToMediaPhysAddress.ptr, data->ipNetToMediaPhysAddress.
eSNMP API Routines o_counter64 o_counter64 Loads a counter64 value into the VARBIND structure. Format int o_counter64 ( VARBIND *vb, OBJECT *obj, uint64 value ); (for Alpha) uint64_vax value ; (for VAX)) Arguments vb A pointer to the VARBIND structure that is supposed to receive the data. obj A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure. value The 8-byte value to be inserted into the VARBIND structure, passed as an array of two integers.
eSNMP API Routines str2oid str2oid Converts a null-terminated string OID in dot notation to an OID structure. The str2oid routine does not allocate an OID structure. Format oid *str2oid ( oid *oid, char *s ); Arguments oid The value to be inserted as data into the VARBIND structure. For more information about OID length and values, see Chapter 3. s A null string or empty string returns an OID structure that has one element of zero.
eSNMP API Routines sprintoid sprintoid Converts an OID into a null-terminated string. Format char *sprintoid ( char *buffer, oid *oid ); Description An OID can have up to 128 elements. A full-sized OID can require a large buffer. Return Values The return value points to its first argument. Example #include
eSNMP API Routines instance2oid instance2oid Copies the object’s base OID and appends a copy of the instance array to make a complete OID for a value. This routine does not allocate an OID structure. It only allocates the array containing the elements. Format oid instance2oid ( oid *new, object *obj, unsigned int *instance, int *len ); Arguments new A pointer to the OID that is to receive the new OID value. obj A pointer to the object table entry for the MIB variable being obtained.
eSNMP API Routines instance2oid Example #include VARBIND *vb; <-- filled in OBJECT *object; <-- filled in unsigned int instance[6]; -- Construct the outgoing OID in a GETNEXT --- Instance is N.1.A.A.A.
eSNMP API Routines oid2instance oid2instance Extracts the instance values from an OID structure and copies them to the specified array of integers. The routine then returns the number of elements in the array. Format int oid2instance ( oid *oid, object *obj, unsigned int *instance, int *max_len ); Arguments oid A pointer to an incoming OID containing an instance or part of an instance. obj A pointer to the object table entry for the MIB variable.
eSNMP API Routines oid2instance Example #include OID *incoming = &method->varbind->name; OBJECT *object = method->object; int instLength; unsigned int instance[6]; -- in a GET operation --- Expected Instance is N.1.A.A.A.A where A’s are IP address -instLength = oid2instance(incoming, object, instance, 6); if (instLength != 6) return ESNMP_MTHD_noSuchInstance; The N will be in instance[0] and the IP address will be in instance[2], instance[3], instance[4], and instance[5].
eSNMP API Routines inst2ip inst2ip Returns an IP address derived from an OID instance. Format int inst2ip ( unsigned int *instance, int *length, unsigned int *ipaddr, int *exact, int *carry ); Arguments instance A pointer to an array of unsigned int containing the instance numbers returned by the oid2instance routine to be converted to an IP address. The range for elements is between zero and 255. Using the EXACT mode, the routine returns 1 if an element is out of range.
eSNMP API Routines inst2ip Description Use the EXACT mode for evaluating an instance for Get and Set operations. For GetNext and GetBulk operations, use the NEXT mode. When using NEXT mode, this routine assumes that the search for data will be performed using greater than or equal to matches. Return Values Carry value is 0 Carry value is 1 The routine completed successfully. For EXACT match, an error occurred. For NEXT match, there was a carry. (If there was a carry, the returned ipaddr is 0.
eSNMP API Routines inst2ip The search key consists of a number and two ipaddr values. These are represented in the instance part of the OID as n.A.A.A.A.B.B.B.B, where: • n is a single value integer. • The A.A.A.A portion makes up one IP address. • The B.B.B.B portion makes up a second IP address. If all elements are given, the total length of the search key is 9. In this case, you perform the operation as follows: • Convert the least significant part of the key (that is, the B.B.B.
eSNMP API Routines cmp_oid cmp_oid Compares two OID structures. Format int cmp_oid ( oid *q, oid *p ); Description This routine does an element-by-element comparison, from the most significant element (element 0) to the least significant element. If all other elements are equal, the OID with the least number of elements is considered less. Return Values -1 0 1 The OID q is less than OID p. The OID q is in OID p. The OID q is greater than OID p.
eSNMP API Routines cmp_oid_prefix cmp_oid_prefix Compares an OID against a prefix. Format int cmp_oid_prefix ( oid *q, oid *prefix ); Description A prefix could be the OID on an object in the object table. The elements beyond the prefix are the instance information. This routine does an element-by-element comparison, from the most significant element (element 0) to the least significant element.
eSNMP API Routines clone_oid clone_oid Makes a copy of the OID. This routine does not allocate an OID structure. Format oid clone_oid ( oid *new, oid *oid ); Arguments new A pointer to the OID structure that is to receive the copy. oid A pointer to the OID structure where the data is to be obtained. Description This routine dynamically allocates the buffer and inserts its pointer into the OID structure received. The caller must explicitly free this buffer.
eSNMP API Routines free_oid free_oid Frees the OID structure’s buffer. This routine does not deallocate the OID structure itself; it deallocates the elements buffer attached to the structure. Format void free_oid ( oid *oid ); Description This routine frees the buffer pointed to by the OID->elements field and zeros the field and the NELEM structure. Example include OID oid; : : assume oid was assigned a value (perhaps with clone_oid() : and we are now finished with it.
eSNMP API Routines clone_buf clone_buf Duplicates a buffer in a dynamically allocated space. Format char clone_buf ( char *str, int *len ); Arguments str A pointer to the buffer to be duplicated. len The number of bytes to be copied. Description One extra byte is always allocated at the end and is filled with zeros. If the length is less than zero, the duplicate buffer length is set to zero. A buffer pointer is always returned, unless there is a malloc error. Return Values Null A malloc error.
eSNMP API Routines mem2oct mem2oct Converts a string (a buffer and length) to an oct structure with the new buffer’s address and length. Format oct *mem2oct ( oct *new, char *buffer, int *len ); Arguments new A pointer to the oct structure receiving the data. buffer Pointer to the buffer to be converted. len Length of buffer to be converted. Description The mem2oct routine dynamically allocates the buffer and inserts its pointer into the oct structure. The caller must explicitly free this buffer.
eSNMP API Routines cmp_oct cmp_oct Compares two octet strings. Format int cmp_oct ( oct *oct1, oct *oct2 ); Arguments oct1 Pointer to the first octet string. oct2 Pointer to the second octet string. Description The two octet strings are compared byte-by-byte to determine the length of the shortest octet string. If all bytes are equal, the lengths are compared. An octet with a null pointer is considered the same as a zero-length octet.
eSNMP API Routines clone_oct clone_oct Makes a copy of the data in an oct structure. This routine does not allocate an oct structure; it allocates the buffer pointed to by the oct structure. Format oct clone_oct ( oct *new, oct *old ); Arguments new A pointer to the oct structure receiving the data. old A pointer to the oct structure where the data is to be obtained.
eSNMP API Routines free_oct free_oct Frees the buffer attached to an oct structure. This routine does not deallocate the oct structure; it deallocates the buffer to which the oct structure points. Format void free_oct ( oct *oct ); Description This routine frees the dynamically allocated buffer to which the oct structure points, and zeros the pointer and length on the oct structure. If the oct structure is already null, this routine does nothing.
eSNMP API Routines free_varbind_data free_varbind_data Frees the dynamically allocated fields in the VARBIND structure. However, this routine does not deallocate the VARBIND structure itself; it deallocates the name and data buffers to which the VARBIND structure points. Format void free_varbind_data ( varbind *vb ); Description This routine performs a free_oid (vb->name) operation. If indicated by the vb->type field, it then frees the vb->value data using either the free_oct or the free_oid routine.
eSNMP API Routines set_debug_level set_debug_level Sets the logging level, which dictates what log messages are generated. The program or module calls the routine during program initialization in response to run-time options. Format void set_debug_level ( int stat, unsigned integer null ); Arguments stat The logging level. The following values can be set individually or in combination: Level Meaning ERROR WARNING Used when a bad error occurred; requires a restart.
eSNMP API Routines is_debug_level is_debug_level Tests the logging level to see whether the specified logging level is set. You can test the logging levels as follows: Level Meaning ERROR WARNING Used when a bad error occurs, requiring restart. Used when a packet cannot be handled; this also implies ERROR. Used when tracing all packets; this also implies ERROR and WARNING. TRACE Format int is_debug_level ( int type ); Return Values TRUE FALSE Example #include
eSNMP API Routines ESNMP_LOG ESNMP_LOG This is an error declaration C macro defined in the ESNMP.H header file. It gathers the information that it can obtain and sends it to the log. Format ESNMP_LOG ( level, format, ... ); Description The esnmp_log routine is called using the ESNMP_LOG macro, which uses the helper routine esnmp_logs to format part of the text. Do not use these functions without the ESNMP_LOG macro.
eSNMP API Routines _ _print_varbind _ _print_varbind Displays the VARBIND and its contents. This routine is used for debugging purposes. To use this routine, you must set the debug level to TRACE. Output is sent to the specified file. Format _ _print_varbind ( VARBIND *vb, int indent ); Arguments vb The pointer to the VARBIND structure to be displayed. If the vb pointer is NULL, no output is generated. indent The number of bytes of white space to place before each line of output.
eSNMP API Routines set_select_limit set_select_limit Sets the eSNMP select error limit. For more information, see Section 6.1. Format set_select_limit ( char *progname ); Arguments progname The subagent name. This argument is valid with DPI versions only. With AgentX, the argument is NULL because subagents do not get names. Return Values ESNMP_MTHD_noError ESNMP_MTHD_genErr No error was generated. An error was generated.
eSNMP API Routines _ _set_progname _ _set_progname Specifies the program name that will be displayed in log messages. This routine should be called from the main during program initialization. It needs to be called only once. Format _ _set_progname ( char *prog ); Arguments prog The program name as taken from argv[0], or some other identification for entity-calling logging routines. Example #include "esnmp.
eSNMP API Routines _ _restore_progname _ _restore_progname Restores the program name from the second application of the set. This routine should be called only after the _ _set_progname routine has been called. You can use this to restore the most recent program name only. Format _ _restore_progname ( ); Example #include "esnmp.
eSNMP API Routines _ _parse_progname _ _parse_progname Parses the full file specification to extract only the file name and file extension. Format _ _parse_progname ( file-specification ); Arguments file-specification The full file specification for the subagent. Example #include "esnmp.h" static char Progname[100]; sprintf (Progname, "%s%.
eSNMP API Routines esnmp_cleanup esnmp_cleanup Closes open sockets that are used by the subagent for communicating with the master agent. Format esnmp_cleanup ( ); Example #include "esnmp.h" int rc = ESNMP_LIB_OK; rc = esnmp_cleanup(); Return Values ESNMP_LIB_NOTOK ESNMP_LIB_OK There was no socket. Success.
6 Troubleshooting eSNMP Problems The eSNMP modules provided with TCP/IP Services include troubleshooting features that are useful in controlling the way your subagent works. This chapter describes: • How to modify the subagent error limit (Section 6.1) • How to modify the default subagent timeout value (Section 6.2) • Log files (Section 6.3) For additional information about troubleshooting SNMP problems, see the Compaq TCP/IP Services for OpenVMS Tuning and Troubleshooting guide. 6.
Troubleshooting eSNMP Problems 6.2 Modifying the Subagent Timeout The TCPIP$ESNMP_DEFAULT_TIMEOUT value is from 0 to 60 seconds. (You should use 0 only for testing purposes, such as simulating problems on a heavily loaded host or network.) If the value you specify contains nonnumeric digits or is outside the allowed range, the default value of 3 seconds is used.
Troubleshooting eSNMP Problems 6.3 Log Files TCP/IP Services does not support writing log files to locations other than the SYS$SYSDEVICE:[TCPIP$SNMP] directory. The log files contain startup and event information and additional messages, depending on the logging level specified for an agent.
Index A F AgentX protocol, 1–2 API functionality, 1–6 ASN.
M Management information base (MIB), 1–1 Master agent, 1–1 mem2oct support routine, 5–52 method routines routine reference, 5–19 to 5–24 MIB browser, 4–1 command examples, 4–6 command flags, 4–2 command parameters, 4–1 data types, 4–5 using, 4–1 MIBCOMP command example, 3–6 command syntax, 3–5 MIB compiler functionality, 1–7 MIB II, 2–5 groups supported under TCP/IP Services, 2–6 ifTable, 2–7 objects defined under TCP/IP Services, 2–6 restrictions to definition, 2–6 sysObjectID, 2–6 sysORTable, 2–7 sysORTab
Trap sender (cont’d) command parameters, 4–9 running, 4–9 Troubleshooting features, 6–1 U UNIX utilities, 3–7 W Writing subagents compiling, 3–5 creating source files, 3–5 including in startup and shutdown, 3–12 linking and building, 3–11 object tables, 3–7 using ASN.
