Compaq TCP/IP Services for
OpenVMS
SNMP Programming and
Reference
Order Number:
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,
Compaq Computer Corporation
Houston, Texas
?? 2001 Compaq Computer Corporation
COMPAQ, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Of???ce.
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.
Con???dential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor???s standard commercial license.
Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.
ZK6530
This document is available on
This document was prepared using DECdocument, Version
3.5Including Extension Subagents in the Startup and Shutdown
iii
4 Using the SNMP Utilities
5 eSNMP API Routines
iv
v
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
This manual describes the features of the Simple Network Managment Protocol (SNMP) provided with TCP/IP Services. It also describes the extensible SNMP (eSNMP) application programming interface (API) and development environment.
See the Compaq TCP/IP Services for OpenVMS Installation and Con???guration manual for information about installing, con???guring, and starting this product.
Intended Audience
This manual is for experienced OpenVMS and UNIX system managers and assumes a working knowledge of TCP/IP networking, TCP/IP terminology, and some familiarity with the TCP/IP Services product.
Document Structure
This manual contains the following chapters:
???Chapter 1 describes the implementation of eSNMP provided with Compaq TCP/IP Services for OpenVMS.
???Chapter 2 describes the groups and objects implemented with the Host Resources MIB and MIB II that are provided with the eSNMP software.
???Chapter 3 describes how to use the eSNMP API to create a MIB subagent to manage entities or applications.
???Chapter 4 describes the trap sender, trap receiver, and MIB browser utilities provided with TCP/IP Services.
???Chapter 5 provides reference information about the eSNMP API routines.
???Chapter 6 describes some troubleshooting aids provided with TCP/IP Services.
vii
Related Documents
Table 1 lists the documents available with this version of TCP/IP Services.
Table 1 TCP/IP Services Documentation
Compaq TCP/IP Services for OpenVMS Management
This manual describes how to con???gure and manage the TCP/IP Services product.
Use this manual with the Compaq TCP/IP Services for OpenVMS Management Command Reference manual.
Compaq TCP/IP Services for OpenVMS Management Command Reference
Compaq TCP/IP Services for OpenVMS Management Commands Quick Reference Card
This manual describes the TCP/IP Services management commands.
Use this manual with the Compaq TCP/IP Services for OpenVMS Management manual.
This reference card lists the TCP/IP management commands by component and describes the purpose of each command.
Compaq TCP/IP Services for OpenVMS UNIX Commands Quick Reference Card
This reference card contains inforomation about commonly performed network management tasks and their corresponding TCP/IP management and Compaq Tru64 UNIX command formats.
viii
Table 1 (Cont.) TCP/IP Services Documentation
Compaq TCP/IP Services for OpenVMS Sockets API and System Services Programming
Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference
Compaq TCP/IP Services for OpenVMS Tuning and Troubleshooting
Compaq TCP/IP Services for OpenVMS Guide to IPv6
This manual describes how to use the Sockets API and OpenVMS system services to develop network applications.
This manual describes the Simple Network Management Protocol (SNMP) and the SNMP application programming interface (eSNMP). It describes the subagents provided with TCP/IP Services, utilities provided for managing subagents, and how to build your own subagents.
This manual provides information about how to isolate the causes of network problems and how to tune the TCP/IP Services software for the best performance.
This manual describes the IPv6 environment, the roles of systems in this environment, the types and function of the different IPv6 addresses, and how to con???gure TCP/IP Services to access the 6bone network.
For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:
http://www.openvms.compaq.com/
For a comprehensive overview of the TCP/IP protocol suite. you might ???nd the book Internetworking with TCP/IP: Principles, Protocols, and Architecture, by Douglas Comer, useful.
Reader???s Comments
Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:
How to Order Additional Documentation
Visit the following World Wide Web address for information about how to order additional documentation:
http://www.openvms.compaq.com/
If you need help deciding which documentation best meets your needs, call
Conventions
The name TCP/IP Services means both:
???Compaq TCP/IP Services for OpenVMS Alpha
???Compaq TCP/IP Services for OpenVMS VAX
The name UNIX refers to the Compaq Tru64 UNIX operating system.
ix
The following conventions are used in this manual. In addition, please note that all IP addresses are ???ctitious.
x
xi
1
Overview
The Simple Network Management Protocol (SNMP) is the de facto industry standard for managing TCP/IP networks. The protocol de???nes 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.
TCP/IP Services provides support for SNMP Version 2, using the Extensible Simple Network Management Protocol (eSNMP) architecture, under which a single master agent can support any number of subagents. The TCP/IP Services implementation of eSNMP includes a master agent, two subagents, an application programming interface (API), tools used to build additional subagents, startup and shutdown procedures, and
This chapter provides an overview of the Compaq implementation of eSNMP. Topics include:
???eSNMP master agent and subagent architecture (Section 1.1)
???The procedure for handling SNMP requests (Section 1.2)
???The components of the TCP/IP Services software kit that implement SNMP (Section 1.3)
???The ???les useful in developing your own subagent (Section 1.4)
???The eSNMP API (Section 1.5)
???The management information base (MIB) compiler (Section 1.6)
???The impact of running SNMP Version 1 subagents against the SNMP Version 2 implementation provided with TCP/IP Services (Section 1.7)
???Sources of additional information about implementing subagents (Section 1.8)
1.1SNMP Architecture
Figure
Overview
Overview
1.1 SNMP Architecture
Figure
TCP/IP Kernel
OpenVMS
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
???One or more subagents, each of which provides access to the MIB data speci???ed in client requests. In the TCP/IP Services implementation, the master agent contains two resident subagents, one that handles a subset of MIB II variables, and another that handles the Host Resources MIB. These MIBs are described in Chapter 2.
???The SNMP ASN.1 library, used by the master agent to interpret ASN.1 messages.
???The eSNMP API, the application programming interface that provides routines for programming your own subagents. This API runs on the AgentX routines, which are internal to the SNMP architecture.
???The TCP/IP kernel running on the OpenVMS operating system.
The master agent and subagents communicate by means of the AgentX protocol, which is based on RFC 2741.
For information about con???guring and managing the SNMP service, refer to the
Compaq TCP/IP Services for OpenVMS Management guide.
1.2 Request Handling
The eSNMP software manages network communication by having the master agent listen for requests and then passes the requests to the appropriate subagent.
Figure
Overview
1.2 Request Handling
Figure
NMS1
Client
Host 1
Host 2
Flow of trap notification
Flow of get/set request
Flow of "are_you_there" message
The process of communication for a request is illustrated with dashed lines and includes the following steps:
1.The network management station (NMS) (sometimes called the client), originates SNMP requests to obtain and set information.
Note
The client component is not provided with TCP/IP Services.
To provide access to MIBs and to test SNMP communication, TCP/IP Services provides the following utilities:
???MIB browser
???Trap sender
???Trap receiver
These utilities are described in Chapter 4.
Overview
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 speci???es 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 speci???ed in RFC 1905.
2.The master agent sends the request to the subagent that registered the subtree containing the OID.
The subagent receives communications from the master agent over the socket that was assigned when the subagent registered the subtree.
3.The appropriate subagent processes the request.
4.The subagent sends the response message to the master agent using the port that was assigned when the subagent registered the MIB.
When they are idle, subagents periodically send a message to port 705 to ensure that the master agent is still running. In Figure
A trap is generated by the subagent and sent to the client. In Figure
The trap and esnmp_are_you_there routines are described in Section 5.1.
1.3 TCP/IP Services Components for SNMP
Table
Table
Overview 1.3 TCP/IP Services Components for SNMP
Table
SYSTARTUP.COM when the service is enabled and starts detached processes to run subagents.
1.4 Writing an eSNMP Subagent
Table
TCPIP$SNMP_EXAMPLES.
Overview
Overview
1.4 Writing an eSNMP Subagent
Table
For information about building a subagent on an OpenVMS system, see Chapter 3.
1.5 The eSNMP API
The Compaq TCP/IP Services for OpenVMS implementation of the eSNMP architecture includes an API that provides programmers with many eSNMP routines they would otherwise have to develop themselves.
The eSNMP API includes interface routines, method routines, and support routines.
Overview
1.5 The eSNMP API
Interface routines handle the basic subagent operations, such as:
???Subagent initialization and termination
???Registration
???Polling of the master agent
???Trap sending
???UNIX system time conversion
???Adding and removing subagent capabilities registered with the master agent
The support routines allow the subagent to manipulate the data in the response to the request, and include the following:
???Basic protocol data unit (PDU) handling
???Authentication handling
???Octet string handling
???Variable binding (VARBIND) handling
???Object identi???er (OID) handling
???Buffer handling
Chapter 5 describes the API routines in more detail.
To create a subagent, the programmer must provide modules to implement the method routines, as described in Chapter 3.
1.5.1 The SNMP Utilities
To provide quick access to information in the MIBs, and to test SNMP operation, TCP/IP Services provides the following utilities:
???TCPIP$SNMP_REQUEST.EXE, a MIB browser that allows you to retrieve and update objects from the MIBs.
???TCPIP$SNMP_TRPSND.EXE, a trap sender that generates traps (messages that require no response).
???TCPIP$SNMP_TRPRCV.EXE, a trap receiver (or ??????listener??????) that is used to detect trap messages.
For information about using the SNMP utilities, see Chapter 4.
1.6 The MIB Compiler
The MIB compiler processes the statements in an ASN.1 ???le and generates modules that are used by the developer to create subagent routines. For every ASN.1 input ???le that is processed using the MIB compiler, two output ???les, a subtree_TBL.H ???le and a subtree_TBL.C ???le, are generated, where subtree is the name from the original MIB de???nition ???le (for example, chess). The output ???les are described in more detail in Chapter 3.
The subtree_TBL.H ???le is a header ???le that contains the following:
???A declaration of the subtree structure
???Index de???nitions for each MIB variable in the subtree
???Enumeration de???nitions for MIB variables with enumerated values
???MIB group data structure de???nitions
Overview
Overview
1.6The MIB Compiler
???Method routine function prototypes
The subtree_TBL.C ???le is an object ???le 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.7SNMP 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.
???The eSNMP library API (SNMP Version 2), variable binding exceptions, and error codes.
???SNMP Version 1 and SNMP Version 2 requests. Both versions are handled by the master agent. SNMP Version 2 speci???c information from the subagent is mapped, when necessary, to SNMP Version 1 adherent data (according
to RFC 2089). For example, if a management application makes a request using SNMP Version 1 PDUs, the master agent replies using SNMP Version 1 PDUs, mapping any SNMP Version 2 SMI items received from subagents. In most cases, subagents created with a previous version of the eSNMP API do not require any code changes and do not have to be recompiled. The circumstances under which recoding or recompiling are required are described in Section 1.7.1.
1.7.1Using Existing (SNMP Version 1) MIB Modules
Existing SNMP Version 1 MIB subagent executable ???les should be compatible with the current SNMP Version 2 master agent without the need to recompile and relink, with the following exceptions:
???Any program that relies on TCP/IP Services Version 4.1 or 4.2 kernel data structures or access functions may run but may not return valid data. Such programs should be rewritten.
???Programs linked against UCX$ACCESS_SHR.EXE, UCX$IPC_SHR.EXE, or other older shareable images (except for UCX$ESNMP_SHR.EXE, which is described in the next list item) may not run even when relinked. You may need to either rewrite or both rewrite and recompile such programs. Note that the Chess example image (UCX$CHESS_SUBAGENT.EXE) has been updated and renamed TCPIP$CHESS_SUBAGENT.EXE.
???For programs linked against certain versions of UCX$ESNMP_SHR.EXE:
???Images associated with the following versions of TCP/IP Services will run correctly without the need to relink them:
Version 4.1 ECO 9 and later
Version 4.2 ECO 1 and later
The installation of TCP/IP Services provides a
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 ???les with the pre???x TCPIP$ and UCX$ should be within a few seconds of each other, and only one version of each ???le should exist. Make sure both images include the ???le protection W:RE.
???You should relink and perhaps recompile images associated with ECOs for Version 4.1 or 4.2 other than those discussed in the previous list item.
Images linked against object library (.OLB) ???les may not need to be relinked, although you can relink them against the shareable images in this version of the product to decrease the image size. Relinking against the shareable image allows you to take advantage of updated versions of the eSNMP API without the need to relink. Some images linked against the current version of TCP/IP Services may run under Versions 4.1 and 4.2, but this backward compatibility is not supported and may not work in future versions of TCP/IP Services.
If an existing subagent does not execute properly, relink it against this version of TCP/IP Services to produce a working image. Some subagents (such as the OpenVMS Server MIB) require a minimum version of OpenVMS as well as a minimum version of TCP/IP Services.
1.8 For More Information
This manual provides the OpenVMS information required for implementing eSNMP subagents and ensuring their proper operation in that environment.
The eSNMP software for OpenVMS is derived from the Compaq Tru64 UNIX product. For information about the architecture and for details about the eSNMP API, refer to the UNIX documentation at the following URL:
http://www.compaq.com/unix
For information about prototypes and de???nitions for the routines in the eSNMP API, see the TCPIP$SNMP:ESNMP.H ???le. Table
Overview
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.1Overview of the Host Resources MIB
The Host Resources MIB de???nes a uniform set of objects useful for the management of host computers. The Host Resources MIB, described by RFC 1514, de???nes objects that are common across many computer system architectures. The TCP/IP Services implementation of SNMP includes many of these de???ned objects. In addition, some objects in MIB II provide host management functionality.
2.1.1 De???ning Host Resources MIB Implemented Objects
This section de???nes each of the implemented eSNMP objects. Table
Table
Time since system boot (in hundredths of a second).
Date and time character string with Coordinated Universal Time (UTC) information if available.
Index of SYS$SYSDEVICE in the device table.
hrSystemIntialLoadParameters Parameters supplied to the load device when requesting initial operating system con???guration.
A string of boot parameters from the console (Alpha only).
Number of processes that are neither owned by another process nor running detached.
(continued on next page)
MIBs Provided with TCP/IP Services
MIBs Provided with TCP/IP Services
2.1 Overview of the Host Resources MIB
Table
Number of processes listed using the SHOW SYSTEM command.
SYSGEN parameter MAXPROCESSCNT.
The amount of physical main memory contained in the host.
Index of entry in hrStorageTable.
A numeric representation of the device class and type displayed by the SHOW DEVICE/FULL command.
Character string device type displayed by the SHOW DEVICE/FULL command.
Always 512 (the size of an OpenVMS disk block).
The total number of blocks on a device displayed by the SHOW DEVICE/FULL command.
The total number of used blocks on a device displayed by the SHOW DEVICE/FULL command.
Index of entry in hrDeviceTable.
In object identi???er format, a numeric representation of the device class and type displayed by the SHOW DEVICE/FULL command.
Character string of the device type displayed by the SHOW DEVICE/FULL command.
A numeric indication of the status of the device.
The number of errors indicated by the SHOW DEVICE command. This value is initialized to zero when the device is recognized by the system instead of when the master agent is initialized.
An object identi???er that corresponds to the console or PALcode version (Alpha only).
(continued on next page)
MIBs Provided with TCP/IP Services 2.1 Overview of the Host Resources MIB
Table
The value of the index in the interface table in the standard MIB that corresponds to this network device.
This value is set to 2 if the device is read only; otherwise, it is set to 1. (The SHOW DEVICE/FULL command displays ??????software
Indicates device type.
Indicates whether the disk can be removed from the drive.
Half of the value for total blocks displayed by the SHOW DEVICE/FULL command.
Process ID.
Fully quali???ed name of executable image.
The values and the associated status of each are:
???1 indicates that the current process is running (CUR)
???2 indicates that the process is computable (COM)
???3 indicates that you cannot run the process.
Process elapsed CPU time (in hundredths of a second).
Process current working set (in kilobytes).
2.1.2 Restrictions to Host Resources MIB
SNMP requests are not implemented for the following Host Resources MIB objects:
hrPartitionTable hrPrinterTable hrSWInstalled hrSWInstalledTable
SNMP set requests are not implemented for the following Host Resources MIB objects:
MIBs Provided with TCP/IP Services
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.
TCP/IP Services supports the objects in the Host Resources MIB as follows:
???The hrDeviceTable includes all the devices known to the OpenVMS host except those with the following characteristics:
Off line
Remote
UCB marked
Mailbox device
Device with remote terminal (DEV$M_RTT characteristic)
Template
LAT device (begins with _LT)
Virtual terminal device (begins with _VT)
Pseudoterminal device (begins with _FT)
Data items in the hrDeviceTable group have the following restrictions:
???hrDeviceID is always null OID (0.0).
???hrDeviceErrors is coded as follows:
warning (3) Error logging is in progress (OpenVMS UCB value UCB$M_ ERLOGIP).
running (2) Software is valid and no error logging is in progress (OpenVMS UCB value UCB$M_VALID).
unknown (1) Any other OpenVMS status.
The hrDeviceTable now includes template devices (for example, DNFS0 for NFS and DAD0 for virtual devices).
For network devices, only the template devices (those with unit number 0) are displayed.
???hrFSMountPoint (1.3.6.1.2.1.25.3.8.1.2) is DNFSn. The device may change between restarts or after a dismount/mount procedure.
???In the hrFSTable group, if no ???le systems are mounted through NFS or no information is accessible, a "no such instance" status is returned for a get request. Browsers respond differently to this message. For example,
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 ???le system.
???hrFSType is implemented as:
???OID 1.3.6.1.2.1.25.3.9.1, for OpenVMS if the ???le system is not a UNIX style container ???le system.
???hrFSNFS, OID 1.3.6.1.2.1.25.3.9.14, if the ???le system is a TCP/IP Services container ???le system or a UNIX host.
???hrFSAccess, as de???ned in RFC 1514.
???hrFSBootable is always HRM_FALSE (integer 2).
???hrFSStorageIndex is always 0.
???hrFSLastFullBackupDate is unknown time. This entry is encoded according to RFC 1514 as a hexadecimal value
???hrFSLastPartialBackupDate is unknown time. This information is not available for OpenVMS systems. Instead, hexadecimal value
???hrProcessorFrwID (OID pre???x 1.3.6.1.2.1.25.3.3.1.1) is not implemented on OpenVMS VAX. On this type of system, it returns standard null OID (0.0). For example:
1.3.6.1.2.1.25.3.3.1.1.1 = 0.0
For OpenVMS Alpha (???rmware version
1.3.6.1.2.1.25.3.3.1.1.1 = 1.3.6.1.2.1.25.3.3.1.1.1.5.56.7
???Data items in the hrDiskStorage table have the following restrictions:
???hrDiskStorageMediais always ??????unknown?????? (2).
???hrDiskStorageRemoveble is always ??????false?????? (2). Note the incorrect spelling of ??????removable?????? in hrDiskStorageRemoveble (from RFC 1514).
???hrStorageType always contains the value of hrStorageFixedDisk
(1.3.6.1.2.1.25.2.1.4).
2.2Overview of MIB II
The Standard MIB (MIB II) described in RFC 1213 de???nes 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.
MIBs Provided with TCP/IP Services
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 de???nes 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 de???ned MIB II groups:
???at (address translation) group
???EGP (External Gateway Protocol) group
???transmission group
2.2.2Restrictions 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:
???The sysORTable elements are under OID pre???x 1.3.6.1.2.1.1.9.1. See RFC 1907 for details.
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.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 pre???x 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
the maximum value (232 1), as de???ned 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
ifOutDiscards (Counter32) ifOutQLen (Gauge32)
MIBs Provided with TCP/IP Services
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 speci???cation (Section 3.1)
???The structure of management information (Section 3.2)
???Creating a MIB source ???le (Section 3.3)
???Including the routines and building the subagent (Section 3.4)
???Including your subagents in startup and shutdown procedures (Section 3.5)
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 Speci???cation
The creation of a management information base (MIB) begins with data gathering. During this phase, the developer identi???es 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 speci???ed in RFCs 1155 and 1902, describes the general framework within which a MIB can be de???ned and constructed. The SMI framework identi???es 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 speci???es standard techniques for the following:
???De???ning the structure of a particular MIB
???De???ning individual objects, including the syntax and value of each object
???Encoding object values
Creating a Subagent Using the eSNMP API
Creating a Subagent Using the eSNMP API
3.2 The Structure of Management Information
3.2.1 Assigning Object Identi???cation Codes
Each object in a MIB is associated with an identi???er of the ASN.1 type, called an object identi???er (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
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 identi???ed by an OID, which is a concatenation of the subidenti???ers (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 subidenti???ers and at most 128 subidenti???ers in length. The subidenti???er ranges are:
???Subidenti???er 1 values range from 0 to 2, inclusive.
???Subidenti???er 2 values range from 0 to 39, inclusive.
???The remaining subidenti???er values can be any nonnegative number.
Figure
Creating a Subagent Using the eSNMP API
3.2 The Structure of Management Information
Figure
iso (1)
org (3)
dod (6)
internet (1)
directory (1)
mgmt (2)
mib2 (1)
system (1)
interfaces (2)
at (3)
ip (4)
icmp (5)
tcp (6)
udp (7)
egp (8)
transmission (10)
snmp (11)
experimental (3)
private (4)
enterprises (1)
Creating a Subagent Using the eSNMP API
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 de???ne a MIB subtree. All elements in the subtree have an OID that starts with the OID of the subtree base. For example, if you de???ne chess to be a MIB subtree base, the elements with the same pre???x as the chess OID are all in the MIB subtree:
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
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 de???ned 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.
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 speci???c instances, can be registered as a subtree.
The master agent delivers requests to the subagent that has the MIB subtree with the longest pre???x and the highest priority.
3.3 Creating a MIB Source File
Creating the MIB source ???le requires the following
1.Write the ASN.1 input ???les, as described in Section 3.3.1.
2.Process the input ???les 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.1Writing 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 ???le 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 ???les yourself, you can create .MY ???les from existing ASCII ???les (for example, from RFCs) by using the
the [.SNMP] subdirectory of TCPIP$EXAMPLES. Standard .MY ???les are also provided for your convenience.
The custom MIB de???nition ???les have the default extension .MY.
3.3.2 Processing the Input File with the MIB Compiler
Process your ASN.1 source ???les 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 ???les for a given subagent. Whenever any of these source ???les are updated, you must repeat the compilation process.
The syntax for the MIBCOMP command is as follows:
MIBCOMP
Creating a Subagent Using the eSNMP API
Creating a Subagent Using the eSNMP API
3.3 Creating a MIB Source File
The parameters and quali???ers for the MIBCOMP command are as follows:
The following is an example of processing the chess example ???les using the /PRINT_TREE quali???er:
$ MIBCOMP RFC1442.MY,CHESS_MIB.MY "chess" /PRINT_TREE
Processing RFC1442.MY
Processing CHESS_MIB.MY
Dump of objects in lexical order
Creating a Subagent Using the eSNMP API
3.3 Creating a MIB Source File
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 de???nes 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
Compaq Tru64 UNIX Network Programmer???s Guide.
3.3.2.2 Object Tables
The MIBCOMP command is used to generate the C language code that de???nes the object tables from the MIBs. The object tables are de???ned in the emitted ???les 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. Compaq 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 ???les if you did not edit them.
3.3.2.3 The subtree_TBL.H Output File
The subtree_TBL.H ???le contains the following sections:
1.A declaration of the subtree structure
2.Index de???nitions for each MIB variable in the subtree
3.Enumeration de???nitions for MIB variables with enumerated values
4.MIB group data structure de???nitions
5.Method routine function prototypes
The following sections describe each section of the subtree_TBL.H ???le.
Creating a Subagent Using the eSNMP API
Creating a Subagent Using the eSNMP API
3.3 Creating a MIB Source File
1. Declaration Section
The ???rst section of the subtree_TBL.H ???le is a declaration of the subtree structure. The subtree is automatically initialized by code in the subtree_TBL.C ???le. 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 De???nitions Section
The second section of the subtree_TBL.H ???le contains index de???nitions for each MIB variable in the subtree of the form:
#define
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 De???nitions Section
The third section of the subtree_TBL.H ???le contains enumeration de???nitions for those integer MIB variables that are de???ned with enumerated values, as follows:
#define
These de???nitions are useful because they describe the value that enumerated integer MIB variables may take on. For example:
4. MIB Group Data Structure De???nitions Section
The fourth section of the subtree_TBL.H ???le contains data structure de???nitions of the following form:
typedef structxxx {
type
.
.
.
char
.
.
.
}
The MIB compiler generates one of these data structures for each MIB group in the subtree. Each structure de???nition contains a ???eld representing each MIB variable in the group. In addition to the MIB variable ???elds, the structure includes a
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 ???fth section of the subtree_TBL.H ???le describes the method routine prototypes. Each MIB group within the subtree has a method routine prototype de???ned. 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 de???ned, as follows:
extern int
For example:
extern int chess_get( METHOD *method ); extern int chess_set( METHOD *method );
3.3.2.4 The subtree_TBL.C Output Files
The subtree_TBL.C ???le ???le contains the following sections:
1.An array of integers representing the OIDs for each MIB variable
2.An array of OBJECT structures
3.An initialized SUBTREE structure
4.Routines for allocating and freeing the mib_group_type
The following sections describe each section of the subtree_TBL.C ???le.
1. Array of Integers Section
The ???rst section of the subtree_TBL.C ???le is an array of integers used to represent the OID of each MIB variable in the subtree. For example:
1, 3, 6, 1, 4, 1, 36, 2, 15, 2, 99, 1, 0, /* chessProductID */
. . .
1, 3, 6, 1, 4, 1, 36, 2, 15, 2, 99, 5, 1, 4, 0, /* moveStatus */
};
The ???rst line represents the root of the tree; the other lines represent speci???c variables. The latter groups are all terminated by a zero, a programming convenience in internal implementations of API routines.
Creating a Subagent Using the eSNMP API
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 ???le is an array of OBJECT structures. Each MIB variable within the subtree has one OBJECT. The chess example produces the following:
An OBJECT structure represents a MIB variable and has the following ???elds:
???object_index ??? The constant
???oid ??? The variable???s OID (points to a part of elems[ ]).
This variable is of type OID, which is a structure containing two elements: the number of elements in the OID and a pointer to the correct starting place in the array of elements (elems[ ] in the chess example).
In the chess example, oid is designated by {12, &elemens[ 11]}. This indicates that:
The OID has 12 integers separated by dots in the ASCII text representation ("1.3.6.1.4.1.36.2.15.2.99.2")
The integer with index 11 in the array elems[ ] is the ???rst element.
???type ??? The variable???s eSNMP data type.
???getfunc ??? The address of the method routine to call for Get requests (null if no routine exists).
???setfunc ??? The address of the method routine to call for Set requests (null if no routine exists).
The master agent does not access object tables or MIB variables directly. It only maintains a registry of subtrees. When a request for a particular MIB variable arrives, it is processed as shown in the following steps (where the MIB variable is mib_var and the subtree is subtree_1):
1.The master agent ???nds subtree_1 as the authoritative region for the mib_var in the register of subtrees. The authoritative region is determined as the registered MIB subtree that has the longest pre???x and the highest priority.
2.The master agent sends a message to the subagent that registered subtree_1.
3.The subagent consults its list of registered subtrees and locates subtree_1. It searches the object table of subtree_1 and locates the following:
???mib_var (for Get and Set routines)
???The ???rst object lexicographically after mib_var (for Next or Bulk routines)
4.The appropriate method routine is called. If the method routine completes successfully, the data is returned to the master agent. If the method routine fails when doing a Get or Set, an error is returned. If the method routine fails when doing a GetNext, the code keeps trying subsequent objects in the object table of subtree_1 until either a method routine returns successfully or the table is exhausted. In either case, a response is returned.
5.If the master agent detects that subtree_1 could not return data on a Next routine, it recursively tries the subtree lexicographically after subtree_1 until a subagent returns a value or the registry of subtrees is exhausted.
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 ???le 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 ???nd 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.99",
{ 11, &elems[0] }, objects, I_moveStatus};
The following table describes the elements of the SUBTREE structure, the de???nition of each element in the header ???le (subtree_TBL.H)), and the element in the chess example:
The OID structure for the base node of the subtree. This points back to the array of integers.
4. Routines Section
The ???nal section of the subtree_TBL.C ???le. contains short routines for allocating and freeing the mib_group_type. These are provided as a convenience and are not a required part of the API.
3.4 Including the Routines and Building the Subagent
The MIB compiler does not generate code for implementing the method routines for your subagent. This includes code for processing get, set, and other SNMP requests as well as for generating traps. You must write this code yourself. See the CHESS_MIB.C module for an example.
To produce executable subagent code, follow these steps:
1.Compile the C modules generated by the MIB compiler, along with your implementation code. Use a command in the following format (derived from the sample provided for building the chess example in TCPIP$BUILD_ CHESS.COM):
$ CC /INCLUDE=TCPIP$SNMP /PREFIX=ALL /STANDARD=VAX CHESS_METHOD.C, - _$ CHESS_MIB.C, CHESS_TBL.C
Creating a Subagent Using the eSNMP API
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:
keyword "signed". This differs from the VAX C behavior.
2.Link the object modules using a command and options in the following format (derived from the chess example):
$ LINK SYS$INPUT/OPTIONS
CHESS_METHOD.OBJ
CHESS_MIB.OBJ
CHESS_TBL.OBJ
SYS$SHARE:TCPIP$ESNMP_SHR.EXE/SHARE
To link with the eSNMP object library, enter the following command:
$ LINK SYS$INPUT/OPTIONS
CHESS_METHOD.OBJ
CHESS_MIB.OBJ
CHESS_TBL.OBJ
TCPIP$SNMP:TCPIP$ESNMP.OLB/LIBRARY
TCPIP$LIBRARY:TCPIP$LIB.OLB/LIBRARY
Alternatively, you can link your subagent with the eSNMP API shareable image (TCPIP$ESNMP_SHR.EXE). The resulting executable image is smaller and can be run without relinking against any future versions of the shareable image. To link the example object with the shareable image, enter the following command:
$ LINK SYS$INPUT/OPTIONS
CHESS_METHOD.OBJ
CHESS_MIB.OBJ
CHESS_TBL.OBJ
SYS$SHARE:TCPIP$ESNMP_SHR.EXE/SHARE
3.5Including Extension Subagents in the Startup and Shutdown Procedures
You can add your custom subagents to the SNMP startup and shutdown procedures by editing the following ???les:
Creating a Subagent Using the eSNMP API 3.5 Including Extension Subagents in the Startup and Shutdown Procedures
Creating a Subagent Using the eSNMP API
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 de???ned by the SYS$STARTUP:TCPIP$DEFINE_COMMANDS.COM command procedure.
This chapter describes how to use the supplied SNMP utilities.
4.1 Using the MIB Browser
TCP/IP Services provides the snmp_request MIB browser that acts as a simple client to handle single SNMP requests for reading and writing to a MIB. The browser sends SNMP Version 1 and SNMP Version 2 request PDUs to an agent and displays the agent???s response.
To run the MIB browser, follow these steps:
1.De???ne a foreign command for the program:
$ snmp_request == "$SYS$SYSTEM:TCPIP$SNMP_REQUEST"
Alternatively, you can run the SYS$MANAGER:TCPIP$DEFINE_ COMMANDS.COM procedure to de???ne all the foreign commands available with TCP/IP Services.
2.Enter the command using the following format.
snmp_request agent "community" request_type [flags] variable
Section 4.1.1 describes the parameters. Section 4.1.2 describes the ???ags.
4.1.1 MIB Browser Parameters
Table
Table
Using the SNMP Utilities
Using the SNMP Utilities
4.1 Using the MIB Browser
For Set requests, you can specify more than one group of the following:
???
???
???value
For other requests, you can specify more than one variable name, except when you specify the
4.1.2 MIB Browser Flags
Flags are speci???ed in UNIX format.
Because ???ags and data types are case sensitive, you should always enter them in the case that is speci???ed. If a letter or value is speci???ed as uppercase, you must enclose it in quotation marks. In general, if you use uppercase letters where lowercase is speci???ed, the results are unpredictable. For example, the ???ag
If you do not specify a ???ag, or if you specify an invalid ???ag, a usage message is displayed. You must place the ???ags after the
Table
If, after an invalid reply packet is received, a valid reply packet is received, the ignore counter is reset to the value of max_ignores.
If a timeout occurs after an invalid packet is received, the packet is resent, the resend counter is decremented, and the ignore counter is reset to the value of max_ignores.
You cannot use the
(continued on next page)
Using the SNMP Utilities
Using the SNMP Utilities
4.1 Using the MIB Browser
Table
Speci???es the number of times the MIB browser resends a request packet if it times out before receiving a reply. Specify a positive integer for the value (max_retries). If you specify a negative value, it will be converted to an unsigned positive integer. If you specify 0, no retries are tried.
If, after a timeout and a resend, a reply packet is received, the resend counter is reset. After another timeout, the speci???ed number of max_retries is sent.
(continued on next page)
The
4.1.3 MIB Browser Data Types
The snmp_request and snmp_trapsnd commands support the data types listed in Table
Table
1For support of trap sender program (TCPIP$SNMP_TRAPSND.EXE) only. Properly de???ned, MIB variables of type Counter64 are not writable.
Using the SNMP Utilities
Using the SNMP Utilities
4.1 Using the MIB Browser
Note
Except for
On OpenVMS Alpha systems, you must specify the value of the
$ snmp_trapsnd 0.0 mynode 6 33 100
On OpenVMS VAX systems, you must specify the value of the
$ snmp_trapsnd 0.0 mynode 6 33 100
Note that alphabetic characters are not case sensitive when used with the
For more information about the data types, see RFCs 1155 and 1902.
4.1.4 Command Examples for snmp_request
This section presents several examples of using the snmp_request utility. In the following snmp_request command examples:
???The valid host name is marley.dec.com.
???The "public" community is type Read, address 0.0.0.0.
???The "address_list" community is type Read and Write, with write access for the host on which the snmp_request program is running.
???The location has been speci???ed as shown in the following command:
TCPIP> SET CONFIGURATION SNMP -
_TCPIP> /LOCATION=(FIRST="Falcon Building",SECOND="Los Angeles, CA")
???The command responses have been edited for readability.
Examples
1.The following example shows how to retrieve the value of the MIB II variable sysDescr.0 (1.3.6.1.2.1.1.1.0). The request is successful because the OID (variable_name) provided in the command line exists and is readable. This OID is returned by the subagent code that resides in the master agent.
$ snmp_request marley.dec.com "public" get 1.3.6.1.2.1.1.1.0
1.3.6.1.2.1.1.1.0 = marley.dec.com AlphaServer 2100 4/200 OpenVMS V7.1 Digital TCP/IP Services for OpenVMS
2.The following example shows how to retrieve two MIB II variables. This example is identical to the previous example, except that two OID values are input and two returned: instance 1 of ifDescr and hrSystemUptime. Note that the ???rst value comes from the MIB II subagent (TCPIP$OS_MIBS) and the second comes from the Host Resources MIB subagent (TCPIP$HR_MIB).
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: <none>, 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.com "public" getnext 1.3.6.1.2.1.1.1.0 1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1
4.The following example shows how to use the SNMP Version 2 GetBulk request to retrieve the MIB II variables sysUpTime.0 (1.3.6.1.2.1.1.1.0) and sysDescr.0 (1.3.6.1.2.1.1.2.0), and for the ???rst three interfaces, the values of ifDescr (OIDs with the pre???x 1.3.6.1.2.1.2.2.1.2) and ifType (OIDs with the pre???x 1.3.6.1.2.1.2.2.1.3).
$ snmp_request marley.dec.com "public" getbulk
Warning: using version SNMPv2 for getbulk command. 1.3.6.1.2.1.1.1.0 = marley.dec.com AlphaStation 255/300
OpenVMS V7.1 Digital TCP/IP Services for OpenVMS 1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1 1.3.6.1.2.1.2.2.1.1.1 = 1
1.3.6.1.2.1.2.2.1.2.1 = LO IP Interface: LO0, OpenVMS Adapter: <none>, Loopback Port
1.3.6.1.2.1.2.2.1.3.1 = 24 1.3.6.1.2.1.2.2.1.1.3 = 3
1.3.6.1.2.1.2.2.1.2.3 = WE IP Interface: WE0, OpenVMS Adapter: EWA0:, PCI bus Ethernet Adapter
1.3.6.1.2.1.2.2.1.3.3 = 6 1.3.6.1.2.1.2.2.1.1.4 = 4
1.3.6.1.2.1.2.2.1.2.4 = WF IP Interface: WF0, OpenVMS Adapter: FWA0:, DEFPA PCI bus FDDI Adapter
1.3.6.1.2.1.2.2.1.3.4 = 15
5.The following example shows how to use the GetNext request with the
$ snmp_request marley.dec.com "public" getnext
1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1 1.3.6.1.2.1.1.3.0 = 1280260 = 0 d 3:33:22 1.3.6.1.2.1.1.4.0 = Sam Spade 1.3.6.1.2.1.1.5.0 = marley.dec.com
1.3.6.1.2.1.1.6.0 = Falcon BuildingLos Angeles, CA 1.3.6.1.2.1.1.7.0 = 72
1.3.6.1.2.1.1.8.0 = 0 = 0 d 0:0:0
.
.
.
1.3.6.1.2.1.25.5.1.1.2.294 = 560 1.3.6.1.2.1.25.5.1.1.2.295 = 472 1.3.6.1.6.3.1.1.6.1.0 = 1296505215
- no such name - returned for variable 1
Using the SNMP Utilities
Using the SNMP Utilities
4.1Using the MIB Browser
6.The following example uses the same command as in example 5, but it speci???es the
$ snmp_request marley.dec.com "public" getnext
1.3.6.1.2.1.1.2.0= 1.3.6.1.4.1.36.2.15.13.7.1
1.3.6.1.2.1.1.3.0= 1302232 = 0 d 3:37:2
1.3.6.1.2.1.1.4.0= Sam Spade
1.3.6.1.2.1.1.5.0= marley.dec.com
1.3.6.1.2.1.1.6.0= Falcon BuildingLos Angeles, CA
1.3.6.1.2.1.1.7.0= 72
1.3.6.1.2.1.1.8.0= 0 = 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.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 = 0 = 0 d 0:0:0
1.3.6.1.2.1.1.9.1.4.2 = 0 = 0 d 0:0:0
7.The following example shows how to send a Set request. The request succeeds because the command line speci???es the correct type for the variable, and all the conditions for enabling Set requests are met on the server.
$ snmp_request marley.dec.com "address_list" - _$ set 1.3.6.1.2.1.1.4.0 "D" "Richard Blaine"
1.3.6.1.2.1.1.4.0= Richard Blaine
8.The following example shows how to display the contents of packets that are sent and received. Note that only the
$ snmp_request marley.dec.com "public" get
1.3.6.1.2.1.1.4.0= Richard Blaine
4.2Using the Trap Sender and Trap Receiver Programs
TCP/IP Services provides the following programs that allow you to set up a simple client on your system to send and receive trap messages:
???snmp_trapsnd (TCPIP$SNMP_TRAPSND.EXE)
Sends SNMP Version 1 and SNMP Version 2 trap messages. Use only for testing or to send signi???cant state changes that occur on the managed node.
???snmp_traprcv (TCPIP$SNMP_TRAPRCV.EXE)
Listens for SNMP trap messages and displays any it receives.
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
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. Therefore, if you specify the
The following sections explain how to enter commands for both programs. Because ???ags and data types are case sensitive, you should always enter them in the case that is speci???ed. If a letter or value is speci???ed as uppercase, you must enclose it in quotation marks. In general, if you use uppercase letters where lowercase is speci???ed, the results are unpredictable. For example, ???ag
4.2.1 Entering Commands for the Trap Sender Program
The trap sender program lets you send SNMP Version 1 and SNMP Version 2 trap messages. You should use this program only when you want to test the client or when signi???cant state changes occur on the managed node.
The trap sender program encodes an SNMP Version 1 trap PDU (see RFCs 1155, 1156, 1157, and 1215) or an SNMP Version 2 trap PDU (see RFCs 1905 and 1908) into an SNMP message and sends it to the speci???ed hosts. You use parameters and ???ags to specify the data ???elds in the trap PDU.
Traps are uniquely identi???ed in the PDU:
???SNMP Version 1 is identi???ed by a combination of parameters.
???SNMP Version 2 is identi???ed by the value of snmpTrapOID. To run the trap sender program, do the following:
1.De???ne a foreign command for the program:
$ snmp_trapsnd == "$SYS$SYSTEM:TCPIP$SNMP_TRAPSND"
Alternatively, you can run the SYS$MANAGER:TCPIP$DEFINE_ COMMANDS.COM procedure to de???ne all the foreign commands available with TCP/IP Services.
2.Enter a command using the following format:
snmp_trapsnd enterprise agent
4.2.1.1Trap Sender Parameters
Table
Using the SNMP Utilities
Using the SNMP Utilities
4.2 Using the Trap Sender and Trap Receiver Programs
Table
For SNMP Version 1, speci???es the generic trap identi???er in the form of a number. Must be one of the following values:
4.2.1.2 Trap Sender Flags
Table
Table
Speci???es a community string to be used when sending the trap. The default is public.
(continued on next page)
4.2.1.3 Trap Sender Examples
In the following snmp_trapsnd command examples:
???The ???rst line is the snmp_trapsnd command.
???The remainder is the display received when running the trap receiver program (snmp_traprcv) without ???ags included.
1.The following example generates a trap that originated on the localhost (speci???ed by the agent parameter) using the default SNMP version (SNMP Version 1). The
2.The following example generates the same trap as in example 1, except that it speci???es the use of SNMP Version 2.
$ snmp_trapsnd 0.0 local 0 0 0
Message received from 127.0.0.1
sysUpTime.0 - 51938968 = 6 d 0:16:29 snmpTrapOID.0 - 0.0
3.The following example sends values to the node mynode with the community name special.
$ snmp_trapsnd 1.2.3 marley.dec.com 6 33 100
Using the SNMP Utilities
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 -
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 speci???ed port.
If you enter commands using the default port number or another privileged port number, you must run the program from a privileged account.
To run the trap receiver program, do the following:
1.De???ne a foreign command for the program:
$ snmp_traprcv == "$SYS$SYSTEM:TCPIP$SNMP_TRAPRCV"
Alternatively, you can run SYS$MANAGER:TCPIP$DEFINE_ COMMANDS.COM to de???ne all the foreign commands available with TCP/IP Services.
2.Enter a command using the following format: snmp_traprcv
4.2.2.1Trap Receiver Flags
Table
Table
4.2.2.2 Setting Up an SNMP Trap Service
To set up an SNMP trap service for use with the trap receiver program, enter a management command in the following format:
SET SERVICE
In this command, port 170 is used as an alternative for port 162, and traps that are received on port 162 are ignored.
If you omit the /PROTOCOL quali???er or you use /PROTOCOL=TCP, the service uses the TCP transport. In this case, when you enter a command to run the trap receiver program, you must include the
With the SNMP trap service in place, the trap receiver program queries the service for the port number instead of using the default port 162. If you specify a privileged port number (less than 1024) with the /PORT quali???er, make sure you install the trap receiver program with privileges, or run the program from an
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.3Trap Receiver Examples
1.The following example requests trap information on a system that does not have traps con???gured and does not have SYSPRV privilege or suf???cient privilege.
$ snmp_traprcv
No
2.The example, supplied from a nonprivileged account, requests trap information in hexadecimal dump format on port 1026.
$ snmp_traprcv
Message received from 127.0.0.1
Using the SNMP Utilities
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.1Interface 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. The interface routines are listed Table
Table
eSNMP API Routines
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_identi???er ) ;
Arguments
socket
The address of the integer that receives the socket descriptor used by eSNMP.
subagent_identi???er
The address of a
Description
Call this routine during program initialization or to restart the eSNMP protocol. If you are restarting, the esnmp_init routine clears all registrations so each subtree must be registered again.
You should attempt to create a unique subagent identi???er, perhaps using the program name argv[0] and additional descriptive text. The master agent does not open communications with a subagent whose subagent identi???er is already in use.
This routine does not block waiting for a response from the master agent. After calling the esnmp_init routine, call the esnmp_register routine for each subtree that is to be handled by the subagent.
Return Values
Example
#include <esnmp_h> int socket;
status = esnmp_init(&socket, "gated");
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 ???les (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures. Refer to Chapter 3 for more information about these ???les.
Note
All memory pointed to by the subtree ???elds must have permanent storage since it is referenced by libesnmp for the duration of the program. You should use the data declarations emitted by the MIBCOMP program.
timeout
The number of seconds the master agent should wait for responses when requesting data in this subtree. This value must be between 0 (zero) and 300. If the value is 0, the default timeout is 3 seconds. Compaq recommends that you use the default. For information about modifying the default subagent timeout value, refer to Section 6.2.
priority
The registration priority. The priority argument allows you to coordinate cooperating subagents to handle different con???gurations. The range is 1 to 255.
The entry with the largest number has the highest priority. The subagent that registers a subtree with the highest priority over a range of object identi???ers gets all requests for that range of OIDs.
Subtrees registered with the same priority are considered duplicate, and the registration is rejected by the master agent.
Description
Call the initialization routine esnmp_init prior to calling the esnmp_register. Call the esnmp_register function for each subtree structure corresponding to each subtree to be handled. At any time, subtrees can be unregistered by calling esnmp_unregister and then be reregistered by calling the esnmp_register.
When restarting the eSNMP protocol by calling esnmp_init, all registrations are cleared. All subtrees must be reregistered.
eSNMP API Routines
eSNMP API Routines esnmp_register
A subtree is identi???ed 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 ???rst 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 speci???c instance.
By registering a subtree, the subagent indicates that it will process eSNMP requests for all MIB variables (or OIDs) within that subtree???s range. Therefore, a subagent should register the most fully quali???ed (longest) subtree that still contains its instrumented MIB variables.
The master agent does not permit a subagent to register the same subtree more than once. However, subagents can register subtrees with ranges that overlap the OID ranges of subtrees previously registered, and subagents can also register subtrees registered by other subagents.
For example, TCP/IP Services supports MIB II. In the eSNMP environment, the os_mibs subagent registers the MIB II subtree ip (OID 1.3.6.1.2.1.4).
TCP/IP Services also provides the gated subagent, which registers the ipRouteEntry MIB subtree (OID 1.3.6.1.2.1.4.21.1).
These MIBs are registered at priority 1. Any subagent that registers at a higher priority (greater than 1) overrides these registrations.
A request for IpRouteIfIndex (OID 1.3.5.1.2.1.4.21.1.2) is passed to the gated subagent. Requests for other ip variables, such as ipNetToMediaIfIndex (OID 1.3.5.1.2.1.4.22.1.1) are passed to the os_mibs subagent. If the gated subagent terminates or unregisters the ipRouteEntry subtree, subsequent requests for ipRouteIfIndex will go to the os_mibs subagent. This occurs because the ip subtree, which includes all ipRouteEntry variables, is now the authoritative region of requests for ipRouteIfIndex.
Return Values
Note that the return value indicates only the initiation of the request. The actual status returned in the master agent???s response will be returned in a subsequent call to the esnmp_poll routine in the state ???eld.
Example
int status;
extern SUBTREE ipRouteEntry_subtree;
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
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 ???les (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures. Refer to Chapter 3 for more information about these ???les.
Description
This routine can be called by the application code to tell the eSNMP subagent not to process requests for variables in this MIB subtree anymore. You can later reregister a MIB subtree, if needed, by calling the esnmp_register routine.
Return Values
Example
#include <esnmp.h> int status
extern SUBTREE ipRouteEntry_subtree;
status = esnmp_unregister (&ipRouteEntry_subtree);
switch (status) { case ESNMP_LIB_OK:
printf ("The esnmp_unregister routine completed successfully.\n"); break;
case ESNMP_LIB_BAD_REG:
printf ("The MIB subtree was not registered.\n");
case ESNMP_LIB_LOST_CONNECTION:
printf ("%s%s%s\n", "The request to unregister the ", "MIB subtree could not be sent. ", "You should restart the protocol.\n");
break;
}
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.
Format
int esnmp_register2 ( ESNMP_REG *reg ) ;
Arguments
reg
A pointer to an ESNMP_REG structure that contains the following ???elds:
eSNMP API Routines
eSNMP API Routines esnmp_register2
Description
The initialization routine (esnmp_init) must be called prior to calling the esnmp_register2 routine. The esnmp_register2 function must be called for each subtree structure corresponding to each MIB subtree that it will be handling. At any time, MIB subtrees can be unregistered by calling esnmp_unregister2 and then can be reregistered by calling esnmp_register2.
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 identi???ed 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. All elements subordinate to this (those that have the same ???rst 7 identi???ers) are included in the subtree???s object table. A MIB subtree can also be a single MIB object (a leaf node) or even a speci???c instance.
By registering a MIB subtree, the subagent indicates that it will process SNMP requests for all MIB variables (or OIDs) within that MIB subtree???s region. Therefore, a subagent should register the most fully quali???ed (longest) MIB subtree that still contains its instrumented MIB variables.
A subagent using the esnmp_register2 routine can register the same MIB subtree for the local node and for a cluster. To register the MIB subtree for both, you must call the esnmp_register2 routine twice: once with the ESNMP_REG_OPT_CLUSTER bit set in the options ???eld and once with the
ESNMP_REG_OPT_CLUSTER bit clear in the options ???eld. Alternatively, you can register a MIB subtree for the cluster only or for the local node only, by setting or clearing the ESNMP_REG_OPT_CLUSTER bit, respectively, in the options ???eld.
A subagent can also register MIB subtrees that overlap the OID range of MIB subtrees that it previously registered or the OID ranges of MIB subtrees registered by other subagents.
For example, consider the two subagents os_mibs and gated. The os_mibs subagent registers the ip MIB subtree (1.3.6.1.2.1.4), and the gated subagent registers the ipRouteEntry MIB subtree (1.3.6.1.2.1.4.21.1). Both of these registrations are made with the ESNMP_REG_OPT_CLUSTER bit set in the options ???eld. Requests for ip MIB variables within ipRouteEntry, such as ipRouteIfIndex (1.3.6.1.2.1.4.21.1.2), are passed to the gated subagent. Requests for other ip variables, such as ipNetToMediaIfIndex (1.3.6.1.2.1.4.22.1.1), are passed to the os_mibs subagent. If the gated subagent terminates or unregisters the ipRouteEntry MIB subtree, subsequent requests for ipRouteIfIndex go to the os_mibs subagent. This occurs because the ip MIB subtree, which includes all ipRouteEntry MIB variables, is now the authoritative region of requests for ipRouteIfIndex.
Return Values
Note that the return value indicates only the initiation of the request. The actual status returned in the master agent???s response will be returned in a subsequent call to the esnmp_poll routine in the state ???eld.
eSNMP API Routines
eSNMP API Routines esnmp_register2
Example
extern SUBTREE ip_subtree;
static ESNMP_REG esnmp_reg_for_ip2egp; /* retain this structure for a subsequent call to esnmp_unregister2 */
/*
* initialize the ESNMP_REG structure */
memset(&esnmp_reg_for_ip2egp, 0, sizeof(ESNMP_REG));
esnmp_reg_for_ip2egp.range_upper_bound = RANGE_UPPER_BOUND;
status = esnmp_register2( &esnmp_reg_for_ip2egp ); if (status != ESNMP_LIB_OK) {
printf("Could not queue the ???ipRouteEntry??? \n"); printf("subtree for registration\n");
}
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.
Description
This routine can be called by the application code to tell the eSNMP subagent to no longer process requests for variables in this MIB subtree. You can later reregister a MIB subtree, if needed, by calling the esnmp_register2 routine.
Return Values
Example
#include <esnmp.h> int status
extern ESNMP_REG esnmp_reg_for_ip2egp;
status = esnmp_unregister2( &esnmp_reg_for_ip2egp );
switch(status) { case ESNMP_LIB_OK:
printf("The esnmp_unregister2 routine completed successfully.\n"); break;
case ESNMP_LIB_BAD_REG:
printf("The MIB subtree was not registered.\n"); break;
case ESNMP_LIB_LOST_CONNECTION:
printf("%s%s%s\n", "The request to unregister the ", "MIB subtree could not be sent. ", "You should restart the protocol.\n");
break;
}
eSNMP API Routines
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 identi???er that represents an authoritative agent capabilities identi???er. This value is used for the sysORID object in the sysORTable for the managed node.
agent_cap_descr
A pointer to a
Description
This routine is called at any point after initializing eSNMP by a call to the esnmp_init routine.
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 identi???er that represents an authoritative agent capabilities identi???er. 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. When a logical connection for a subagent is closed, the master agent automatically removes the related entries in sysORTable.
eSNMP API Routines
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 ???le and an error status is returned.
If the received message is a request for SNMP data, the object table is checked and the appropriate method routines are called, as de???ned by the developer of the subagent.
Return Values
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.
If a response is not received within the timeout period, the application code should restart the eSNMP protocol by calling the esnmp_init routine. No timers are maintained by the eSNMP library.
Return Values
eSNMP API Routines
eSNMP API Routines esnmp_trap
esnmp_trap
Sends a trap message to the master agent.
Format
int esnmp_trap ( int *generic_trap, int speci???c_trap, char *enterprise, varbind *vb ) 2 ;
Arguments
generic_trap
A generic trap code. Set this argument value to 0 (zero) for SNMPv2 traps.
speci???c_trap
A speci???c trap code. Set this argument value to 0 (zero) for SNMPv2 traps.
enterprise
An enterprise OID string in dot notation. Set to the object identi???er de???ned by the
vb
A VARBIND list of data (a null pointer indicates no data).
Description
This function can be called any time. If the master agent is not running, traps are queued and sent when communication is possible.
The trap message is actually sent to the master agent after it responds to the esnmp_init routine. This occurs with every API call and for most esnmp_register routines. The quickest process to send traps to the master agent is to call the esnmp_init, esnmp_poll, and esnmp_trap routines.
The master agent formats the trap into an SNMP trap message and sends it to management stations based on its current con???guration.
The master agent does not respond to the content of the trap. However, the master agent does return a value that indicates whether the trap was received successfully.
Return Values
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 API Routines
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 de???ned in include/sys/time.h.
A null pointer means return the current sysUpTime.
Description
This routine provides a mechanism to convert UNIX timestamps into eSNMP TimeTicks. The function returns the value that sysUpTime held when the passed timestamp was now.
This routine can be used as a TimeTicks data type (the time since the eSNMP master agent started) in hundredths of a second. The time base is obtained from the master agent in response to esnmp_init, so calls to this function before that time will not be accurate.
Return Values
#include <sys/time.h> #include <esnmp.h> struct timeval timestamp;
gettimeofday(×tamp, NULL);
.
.
.
o_integer(vb, object, esnmp_sysuptime(×tamp));
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.
The method routine calling interface contains the following functions:
???
???
eSNMP API Routines
eSNMP API Routines
*_get Routine
*_get Routine
The *_get routine is a method routine for the speci???ed 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
Arguments
method
A pointer to a METHOD structure that contains the following ???elds:
Description
These types of routines call whatever routine is speci???ed for Get operations in the object table identi???ed by the registered subtree.
This function is pointed to by some number of elements of the subagent object table. When a request arrives for an object, its method routine is called. The *_get method routine is called in response to a Get request.
Return Values
eSNMP API Routines
eSNMP API Routines
*_set Routine
*_set Routine
The *_set method routine for a speci???ed 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
Arguments
method
A pointer to a METHOD structure that contains the following ???elds:
Description
The libesnmp routines call whatever routine is speci???ed for Set operations in the object table identi???ed by the registered subtree.
This function is pointed to by some number of elements of the subagent object table. When a request arrives for an object, its method routine is called. The *_set method routine is called in response to a Set request.
eSNMP API Routines
eSNMP API Routines
*_set Routine
Return Values
5.2.1 Processing *_set Routines
This following is the sequence of operations performed for *_set routines
1.Every variable binding is parsed and its object is located in the object table. A METHOD structure is created for each VARBIND structure. These METHOD structures point to a ROW_CONTEXT structure, which is useful for handling these phases. Objects in the same conceptual row all point to the same ROW_ CONTEXT structure. This determination is made by checking the following:
???The referenced objects are in the same MIB group.
???The VARBIND structures have the same instance OIDs.
2.Each ROW_CONTEXT structure is loaded with the instance information for that conceptual row. The ROW_CONTEXT structure context and save ???elds are set to NULL, and the state ???eld is set to ESNMP_SET_UNKNOWN structure.
3.The method routine for each object is called and is passed its METHOD structure with an action code of ESNMP_ACT_SET.
If all method routines return success, a single method routine (the last one called for the row) is called for each row, with
ESNMP_ACT_COMMIT.
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
4.Each row is released. The same single method routine for each row is called with a
The action codes are processed as follows:
???ESNMP_ACT_SET
Each object???s method routine is called during the SET phase, until all objects are processed or a method routine returns an error status value. (This is the only phase during which each object???s method routine is called.) For variable bindings in the same conceptual row,
CONTEXT.
The
The method routine???s job in this phase is to determine whether the Set request will work, to return the correct SNMP error code if it does not, and to prepare any context data it needs to actually perform the Set request during the COMMIT phase.
The
???ESNMP_ACT_COMMIT
Even though several variable bindings may be in a conceptual row, only the last one in order of the Set request is processed. Of all the method routines that point to a common row, only the last method routine is called.
This method routine must have available to it all necessary data and context to perform the operation. It must also save a snapshot of current data or whatever it needs to undo the Set operation, if required. The
The
If this operation succeeds, return ESNMP_MTHD_noError; otherwise, return a value of ESNMP_MTHD_commitFailed.
If any errors were returned during the COMMIT phase, libesnmp enters the UNDO phase; if not, it enters the CLEANUP phase.
Note
If the Set request spans multiple subagents and another subagent fails, the UNDO phase may occur even if the Set operation is successful
eSNMP API Routines
eSNMP API Routines
*_set Routine
???ESNMP_ACT_UNDO
For each conceptual row that was successfully committed, the same method routine is called with
The method routine should attempt to restore conditions to what they were before it executed the COMMIT phase. (This is typically done using the data pointed to by the
If successful, return ESNMP_MTHD_noError; otherwise, return ESNMP_ MTHD_undoFail.
???ESNMP_ACT_CLEANUP
Regardless of what else has happened, at this point each ROW_CONTEXT participates in cleanup phase. The same method routine that was
called for in the COMMIT phase is called with
ESNMP_ACT_CLEANUP.
This indicates the end of processing for the set request. The method routine should perform whatever cleanup is required; for instance, freeing dynamic memory that might have been allocated and stored in
The function return status value is ignored for the CLEANUP phase.
5.2.2Method Routine Applications Programming
You must write the code for the method routines declared in the subtree_TBL.H ???le. Each method routine has one argument, which is a pointer to the METHOD structure, as follows:
int mib_group_get(
METHOD *method int mib_group_set(
METHOD *method );
The Get method routines are used to perform Get, GetNext, and GetBulk operations.
The Get method routines perform the following tasks:
???Extract the instance portion of the requested OID. You can do this manually by comparing the
the
???Determine the instance validity. The instance OID can be null or any length, depending on what was requested and how your object was selected. You may be able to reject the request immediately by checking on the instance OID.
???Extract the data. Based on the instance OID and
eSNMP API Routines
*_set Routine
???Load the response OID back into the method routine???s VARBIND structure. Set the
???Load the response data back into the method routine???s VARBIND structure.
Use one of the support routines with the corresponding data type to load the
???o_integer
???o_string
???o_octet
???o_oid
These routines make a copy of the data you specify. The libesnmp function manages any memory associated with copied data. The method routine must manage the original data???s memory.
The routine does any necessary conversions to the type de???ned in the object table for the MIB variable and copies the converted data into the
???Return the correct status value, as follows:
5.2.3 Value Representation
The values in a VARBIND structure for each data type are represented as follows. (Refer to the ESNMP.H ???le for a de???nition of the OCT and OID structures.)
???ESNMP_TYPE_Integer32
This is a
???ESNMP_TYPE_DisplayString, ESNMP_TYPE_Opaque ESNMP_TYPE_OctetString
This is an octet string. It is contained in the VARBIND structure as an OCT structure that contains a length and a pointer to a dynamically allocated character array.
eSNMP API Routines
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
A pointer to a buffer containing the bits of the bitstring in the form bbbbb..bb, where the bb octets represent the bitstring itself, bit 0 comes ???rst, and so on. Any unused bits in the last octet are set to zero.
Use the o_string support routine to insert a value into the VARBIND structure, which is a buffer and a length. New space is allocated and the buffer is copied into the new space.
Use the o_octet routine to insert a value into the VARBIND structure, which is a pointer to an OCT structure. New space is allocated and the buffer pointed to by the OCT structure is copied.
???ESNMP_TYPE_ObjectId
This is an object identi???er. It is contained in the VARBIND structure as an OID structure that contains the number of elements and a pointer to a dynamically allocated array of unsigned integers, one for each element.
The
Use the o_oid function to insert an object identi???er into the VARBIND structure when the OID value to be returned as data is in the form of a pointer to an OID structure.
Use the o_string function to insert an OID into the VARBIND structure when the OID value to be returned as data is in the form of a pointer to an ASCII string containing the OID in dot format; for example: 1.3.6.1.2.1.3.1.1.2.0.
???ESNMP_TYPE_NULL
This is the NULL, or empty, type. This is used to indicate that there is no value. The length is zero and the value in the VARBIND structure is zero ???lled.
The incoming VARBIND structures on a Get, GetNext, and GetBulk will have this data type. A method routine should never return this value. An incoming Set request never has this value in a VARBIND structure.
???ESNMP_TYPE_IpAddress
This is an IP address. It is contained in the VARBIND structure in an OCT structure that has a length of 4 and a pointer to a dynamically allocated buffer containing the 4 bytes of the IP address in network byte order.
Use the o_integer function to insert an IP address into the VARBIND structure when the value is an unsigned integer in network byte order.
Use the o_string function to insert an IP address into the VARBIND structure when the value is a byte array (in network byte order). Use a length of 4.
eSNMP API Routines
*_set Routine
???ESNMP_TYPE_Integer32 ESNMP_TYPE_Counter32 ESNMP_TYPE_<Gauge32
The
Use the o_integer function to insert an unsigned value into the VARBIND structure.
???ESNMP_TYPE_TimeTicks
The
Use the o_integer function to insert an unsigned value into the VARBIND structure.
???ESNMP_TYPE_Counter64
The
Use the o_integer function to insert an unsigned longword (64 bits) into the VARBIND structure.
eSNMP API Routines
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 speci???c MIB elements. The following support routines are provided:
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.
The real type as de???ned in the object structure must be one of the following; otherwise, an error is returned.
Note
If the real type is IpAddress, then eSNMP assumes that the
Return Values
eSNMP API Routines
eSNMP API Routines o_integer
Example
#include <esnmp.h>
#include "ip_tbl.h"
ipNetToMediaEntry_type *data;
:
: assume buffer and structure member assignments occur here
:
switch(arg) { case I_atIfIndex:
return o_integer(vb, object,
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 ???eld is not null, this routine attempts to free it. So if you dynamically allocate memory or issue the malloc command to allocate your own VARBIND structure, ???ll the structure with zeros before using it.
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.
The real type as de???ned in the object structure must be one of the following; otherwise, an error is returned.
Return Values
Example
#include <esnmp.h>
#include "ip_tbl.h"
:
: assume buffer and structure member assignments occur here
:
switch(arg) {
case I_atPhysAddress:
return o_octet(vb, object,
eSNMP API Routines
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. So if you dynamically allocate memory or issue the malloc command to allocate your own VARBIND structure, ???ll the structure with zeros before using it.
obj
A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.
oid
The value to be inserted into the VARBIND structure as data. For more information about OID length and values, see Chapter 3.
The real type as de???ned in the object structure must be ESNMP_TYPE_OBJECT_
IDENTIFIER.
Return Values
#include <esnmp.h>
#include "ip_tbl.h"
ipNetToMediaEntry_type *data;
:
: assume buffer and structure member assignments occur here
:
switch(arg) {
case I_atObjectID:
return o_oid(vb, object,
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. So if you dynamically allocate memory or issue the malloc command to allocate your own VARBIND structure, ???ll the structure with zeros before using it.
obj
A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.
ptr
The pointer to the buffer containing data to be inserted into the VARBIND structure as data.
len
The length of the data in buffer pointed to by ptr.
The real type as de???ned in the object structure must be one of the following; otherwise, an error is returned.
Return Values
eSNMP API Routines
eSNMP API Routines o_string
Example
#include <esnmp.h>
#include "ip_tbl.h"
ipNetToMediaEntry_type *data;
:
: assume buffer and structure member assignments occur here
:
switch(arg) {
case I_atPhysAddress:
return o_string(vb, object,
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
The real type as de???ned in the object structure must be
ESNMP_TYPE_Counter64. Otherwise, an error is returned.
Example
See the example for the o_integer routine.
Return Values
eSNMP API Routines
eSNMP API Routines str2oid
str2oid
Converts a
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.
Description
The routine dynamically allocates the buffer and inserts its pointer into the OID structure passed in the call. The caller must explicitly free this buffer. The OID can have a maximum of 128 elements.
Return Values
include <esnmp.h> OID abc;
if (stroid (&abc, "1.2.5.4.3.6") == NULL DPRINTF((WARNING, "It did not work...\n");
eSNMP API Routines
sprintoid
sprintoid
Converts an OID into a
Format
char *sprintoid ( char *buffer, oid *oid );
Description
An OID can have up to 128 elements. A
Return Values
The return value points to its ???rst argument.
Example
#include <esnmp.h> #define SOMETHING_BIG 1024 OID abc;
char buffer[SOMETHING_BIG];
:
: assume abc gets initialized with some value
:
printf("dots=%s\n", sprintoid(buffer, &abc));
eSNMP API Routines
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. The ???rst part of the new OID is the OID from this MIB object table entry.
instance
A pointer to an array of instance values. These values are appended to the base OID obtained from the MIB object table entry to construct the new OID.
len
The number of elements in the instance array.
Description
The instance array may be created by oid2instance or constructed from key values as a result of a GetNext command (see Chapter 1).
This routine dynamically allocates the buffer and inserts its pointer into the OID structure passed in the call. The caller must explicitly free the buffer.
You should point to the OID structure receiving the new values and then call the instance2oid routine. Previous values in the OID structure are freed (that is, free_oid is called ???rst), and then the new values are dynamically allocated and inserted. Be sure the initial value of the new OID is all zeros. If you do not want the initial value freed, make sure the new OID structure is all zeros.
Return Values
eSNMP API Routines
instance2oid
Example
instance[1] = 1;
for (i = 0; i < 4; i++) {
instance[i+2]=((unsigned char
}
eSNMP API Routines
eSNMP API Routines oid2instance
oid2instance
Extracts the instance values from an OID structure and copies them to the speci???ed 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.
instance
A pointer to an array of unsigned integers where the index is placed.
max_len
The number of elements in the instance array.
Description
The instance values are the elements of an OID beyond those that identify the MIB variable. These elements identify a speci???c instance of a MIB value.
If there are more elements in the OID structure than speci???ed by the max_len parameter, the function copies the number of elements speci???ed by max_len only and returns the total number of elements that would have been copied had there been space.
Return Values
eSNMP API Routines
oid2instance
Example
#include <esnmp.h>
unsigned int 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
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. Using the NEXT mode, a value greater than 255 causes that element to over???ow. In this case, the value is set to 0 and the next most signi???cant element is incremented; therefore, it returns a lexically equivalent value of the next possible ipaddr.
length
The number of elements in the instance array. Instances beyond the fourth are ignored. If the length is less than four, the missing values are assumed to be zero. A negative length results in an ipaddr value of zero. For an exact match (such as Get), there must be exactly four elements.
ipAddr
A pointer indicating where to return the IP address value. This routine is in network byte order (the most signi???cant element is ???rst).
exact
Can either be TRUE or FALSE.
TRUE means do an EXACT match. If any element is greater than 255 or if there are not exactly four elements, a value of 1 is returned. The carry argument is ignored.
FALSE means do a NEXT match. That is, the lexically next IP address is returned, if the carry value is set and the length is at least four. If there are fewer than four elements, this function assumes the missing values are zero. If any one element contains a value greater than 255, the value is zeroed and the next most signi???cant element is incremented. Returns a 1 (one) only when there is a carry from the most signi???cant (the ???rst) value.
carry
Adds to the IP address on a NEXT match. If you are trying to determine the next possible IP address, pass in a one. Otherwise, pass in a zero. A length of less than 4 cancels the carry.
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
Examples
1.The following example converts an instance to an IP address for a Get operation, which is an EXACT match.
#include <esnmp.h>
if (instLength == 6 && !inst2ip(&instance[2], 4, &ip_addr, TRUE,0)) { iface = (int) instance[0];
}
else
return ESNMP_MTHD_noSuchInstance;
2.The following example shows a GetNext operation in which there is only one key or in which the ipaddr value is the least signi???cant part of the key. This is a NEXT match; therefore, a value of 1 is passed back for the carry value.
#include <esnmp.h>
unsigned int instance[6]; unsigned int ip_addr; int iface;
iface = (instLength < 1) ? 0 :(int) instance[0];
iface += inst2ip(&instance[2], instLength - 2, &ip_addr, FALSE, 1);
3.In the following example, the search key consists of multiple parts. If you are doing a GetNext operation, you must ???nd the next possible value for the search key, so that you can perform a cascaded
eSNMP API Routines
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 signi???cant part of the key (that is, the B.B.B.B portion), by calling the inst2ip routine, passing it a 1 for the carry and (length - 5) for the length.
???If the conversion of the B.B.B.B portion generates a carry (that is, returns 1), you pass it to the next most signi???cant part of the key.
???Convert the A.A.A.A portion by calling the inst2ip routine, passing it (length - 1) for the length and the carry returned from the conversion of the B.B.B.B portion.
???The most signi???cant element n is a number; therefore, add the carry from the A.A.A.A conversion to the number. If the result over???ows, then the search key is not valid.
#include <esnmp.h>
instLength = oid2instance(incoming, object, instance, 9); iface = (instLength < 1) ? 0 :(int) instance[0];
carry = inst2ip(&instance[1], instLength - 1, &ip_addrB, FALSE, 1); carry = inst2ip(&instance[5], instLength - 5, &ip_addrA, FALSE, carry); iface += carry;
if (iface > carry) {
}
eSNMP API Routines
cmp_oid
cmp_oid
Compares two OID structures.
Format
int cmp_oid ( oid *q, oid *p );
Description
This routine does an
Return Values
eSNMP API Routines
eSNMP API Routines cmp_oid_pre???x
cmp_oid_pre???x
Compares an OID against a pre???x.
Format
int cmp_oid_pre??? x ( oid *q, oid *pre???x );
Description
A pre???x could be the OID on an object in the object table. The elements beyond the pre???x are the instance information.
This routine does an
Return Values
Example
#include <esnmp.h> OID *q;
OBJECT *object;
if (cmp_oid_prefix(q,
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.
Point to the OID structure that is to receive the new OID values and call this routine. Any previous value in the new OID structure is freed (using the
free_oid routine) and the new values are dynamically allocated and inserted. To preserve an existing OID structure, initialize the new OID structure with zeros.
If the old OID structure is null or contains a null pointer to its element buffer, a new OID of [0.0] is generated.
Return Values
Example
#include <esnmp.h> OID oid1;
OID oid2;
:
: assume oid1 gets assigned a value
:
memset(&oid2, 0, sizeof(OID));
if (clone_oid(&oid2, &oid1) == NULL) DPRINTF((WARNING, "It did not work\n"));
eSNMP API Routines
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
Example
include <esnmp.h> OID oid;
:
:assume oid was assigned a value (perhaps with clone_oid()
:and we are now finished with it.
:
free_oid(&oid);
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 ???lled 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
#include <esnmp.h>
char *str = "something nice"; char *copy;
copy = clone_buf(str, strlen(str));
eSNMP API Routines
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.
This routine does not allocate an oct structure and does not free data previously pointed to in the oct structure before making the assignment.
Return Values
#include <esnmp.h> char buffer;
int len; OCT abc;
...buffer and len are initialized to something...
memset(&abc, 0, sizeof(OCT));
if (mem2oct(&abc, buffer, len) == NULL) DPRINTF((WARNING,"It did not work...\n"));
eSNMP API Routines
cmp_oct
cmp_oct
Compares two octet strings.
Format
int cmp_oct ( oct *oct1, oct *oct2 );
Arguments
oct1
Pointer to the ???rst octet string.
oct2
Pointer to the second octet string.
Description
The two octet strings are compared
Return Values
Example
#include <esnmp.h> OCT abc, efg;
...abc and efg are initialized to something...
if (cmp_oct(&abc, &efg) > 0)
DPRINTF((WARNING,"octet abc is larger than efg...\n"));
eSNMP API Routines
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.
Description
The clone_oct routine dynamically allocates the buffer, copies the data, and updates the oct structure with the buffer???s address and length. The caller must free this buffer.
The previous value of the buffer on the new oct structure is freed prior to the new buffer being allocated. If you do not want the old value freed, initialize the new oct structure before cloning.
Return Values
#include <esnmp.h> OCT octet1;
OCT octet2;
:
: assume octet1 gets assigned a value
:
memset(&octet2, 0, sizeof(OCT));
if (clone_oct(&octet2, &octet1) == NULL) DPRINTF((WARNING, "It did not work\n"));
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.
If the buffer attached to the oct structure is already null, this routine sets the length ???eld of the oct structure to zero.
Example
#include <esnmp.h> OCT octet;
:
:assume octet was assigned a value (perhaps with mem2oct()
:and we are now finished with it.
:
free_oct(&octet);
eSNMP API Routines
eSNMP API Routines free_varbind_data
free_varbind_data
Frees the dynamically allocated ???elds 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
Example
#include <esnmp.h> VARBIND *vb;
vb = (VARBIND*)malloc(sizeof(VARBIND));
:
: some processing that uses vb occurs here
:
free_varbind_data(vb); free(vb);
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
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:
null
This parameter is not used by OpenVMS. It is supplied for compatibility with UNIX.
Description
The logging level will be ERROR, WARNING, or TRACE.
If you specify TRACE, all three types of errors are generated. If you specify ERROR, only error messages are generated. If you specify WARNING, both error and warning messages are generated.
To specify logging levels for the messages in your subagent, use the ESNMP_LOG routine.
Example
#include <esnmp.h>
if
} else { set_debug_level(WARNING,NULL);
}
eSNMP API Routines
eSNMP API Routines is_debug_level
is_debug_level
Tests the logging level to see whether the speci???ed logging level is set. You can test the logging levels as follows:
Format
int is_debug_level ( int type );
Return Values
#include <esnmp.h>
if (is_debug_level(TRACE)) dump_packet();
eSNMP API Routines
ESNMP_LOG
ESNMP_LOG
This is an error declaration C macro de???ned in the ESNMP.H header ???le. 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. For example:
#define ESNMP_LOG(level, x) if (is_debug_level(level)) { \ esnmp_log(level, esnmp_logs x, __LINE__, __FILE__);}
Where:
???x is a text string; for example, a printf statement.
???level is one of the following:
For more information about con???guration options for logging and tracing, refer to the Compaq TCP/IP Services for OpenVMS Management guide.
Example
#include <esnmp.h>
ESNMP_LOG( ERROR, ("Cannot open file %s\n", file));
eSNMP API Routines
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 speci???ed ???le.
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 API Routines
eSNMP API Routines _ _set_progname
_ _set_progname
Speci???es 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 identi???cation for
Example
#include "esnmp.h" __set_progname(argv[0]);
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.h" __restore_progname();
eSNMP API Routines
eSNMP API Routines _ _parse_progname
_ _parse_progname
Parses the full ???le speci???cation to extract only the ???le name and ???le extension.
Format
_ _parse_progname (
Arguments
The full ???le speci???cation for the subagent.
Example
#include "esnmp.h"
static char Progname[100];
sprintf (Progname, "%s%.8X", __parse_progname(prog), getpid());
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 API Routines
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 ???les (Section 6.3)
For additional information about troubleshooting SNMP problems, see the
Compaq TCP/IP Services for OpenVMS Tuning and Troubleshooting guide.
6.1 Modifying the Subagent Error Limit
In certain circumstances, some subagent programs might enter a loop where a select( ) call repeatedly returns a
You can de???ne the logical name TCPIP$SNMP_SELECT_ERROR_LIMIT to modify the number of times a
The valid TCPIP$SNMP_SELECT_ERROR_LIMIT values range from 1 to less than 232 1 (default 100). When de???ning the error limit, remember:
???Do not use commas when de???ning the number.
???If you de???ned the limit as 0, no limit is set.
???A de???ned value greater than or equal to 4000000000 triggers warning messages.
For example, to de???ne TCPIP$SNMP_SELECT_ERROR_LIMIT to limit the number of times a
$ DEFINE/SYSTEM TCPIP$SNMP_SELECT_ERROR_LIMIT 1000
6.2 Modifying the Subagent Timeout
You can de???ne the logical name TCPIP$ESNMP_DEFAULT_TIMEOUT to modify the default time allowed (3 seconds) before timeout occurs because of the lack of response by the subagent to the master agent. The ability to de???ne the timeout is especially useful for slower systems and systems with heavy network traf???c. The logical name is translated at startup time.
Troubleshooting eSNMP Problems
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.
For example, to de???ne TCPIP$ESNMP_DEFAULT_TIMEOUT to time out after 6 seconds of inactivity between the master agent and subagents, enter the following command:
$ DEFINE/SYSTEM TCPIP$ESNMP_DEFAULT_TIMEOUT 6
When a subagent registers with the master agent, it can specify a value that overrides the value you set with logical name TCPIP$ESNMP_DEFAULT_ TIMEOUT. The standard MIB II and Host Resources MIB subagents use the default value of 3 seconds. Refer to the description of the esnmp_register routine for more information.
6.3 Log Files
All output redirected from SYS$OUTPUT for the SNMP agent process is logged to *.LOG ???les in the SYS$SYSDEVICE:[TCPIP$SNMP] directory. Output redirected from SYS$ERROR is logged to *.ERR ???les in the same directory.
Output redirected from SYS$OUTPUT for the agent process is logged to the following ???les:
???TCPIP$ESNMP.LOG (for the master agent)
???TCPIP$OS_MIBS.LOG (for the MIB II)
???TCPIP$HR_MIB.LOG (for the Host Resources MIB)
Output redirected from SYS$ERROR is logged to the following ???les:
???TCPIP$ESNMP.ERR (for the master agent)
???TCPIP$OS_MIBS.ERR (for the MIB II)
???TCPIP$HR_MIB.ERR (for the Host Resources MIB)
Data is ???ushed to the log ???les when the corresponding process terminates. Each invocation of the TCPIP$SNMP_RUN.COM procedure purges these ???les, retaining at least the last seven versions (the exact number depends on the value of the CLUSTER_NODES system parameter).
The log ???les are located in the SYS$SYSDEVICE:[TCPIP$SNMP] directory along with the TCPIP$SNMP_CONF.DAT ???le, which is a text representation of the SNMP con???guration data generated by the master agent during startup.
The contents of the SNMP log ???les are written to SYS$SYSDEVICE:[TCPIP$SNMP] when the process stops or when you stop
it (for example, by entering the STOP/ID=xxx command). After a process restarts, it creates a new version of the ???les. If a process executes without errors, *.ERR ???les might not be created.
Writing to SYS$OUTPUT and SYS$ERROR from custom subagents is controlled by quali???ers on the RUN command in the TCPIP$EXTENSION_MIB_RUN.COM procedure. See Chapter 3 for information about including extension subagent commands in the startup procedure.
Custom subagents that do not write to SYS$OUTPUT and SYS$ERROR might not produce a .LOG or .ERR ???le.
Troubleshooting eSNMP Problems
6.3 Log Files
TCP/IP Services does not support writing log ???les to locations other than the SYS$SYSDEVICE:[TCPIP$SNMP] directory.
The log ???les contain startup and event information and additional messages, depending on the logging level speci???ed for an agent. The SNMP logging facility uses three logging levels:
???TRACE (logs trace, warning, and error messages)
???WARNING (logs warning and error messages)
???ERROR
For the master agent and standard subagents, the logging level is WARNING. Log ???les for these processes include messages for WARNING and ERROR events. The chess example does not have a default log level. Therefore, no log messages appear. To specify a default log level for custom subagents, you can use the standard API call set_debug_level (see Chapter 5 for more information). Because the chess example subagent does not use a default, messages are captured only if you specify tracing. For information about getting trace logs, refer to the Compaq TCP/IP Services for OpenVMS Management guide.
Troubleshooting eSNMP Problems
A
AgentX protocol,
API functionality,
ASN.1 ???les,
C
C compiler,
tree structure,
cmp_oid_prefix support routine,
D
Default timeout value,
E
Error logs,
eSNMP, description,
ESNMP_LOG support routine,
esnmp_uncapabilities interface routine,
Extensibility,
Index
F
free_oct support routine,
G
*_get method routine,
MIB,
H
Header ???les,
Host Resources MIB,
objects implemented by TCP/IP Services,
hrDeviceTable,
I
ifTable,
inst2ip support routine,
L
Logging output,
M
Management information base (MIB),
mem2oct support routine,
routine reference,
command examples,
using,
MIBCOMP
command example,
MIB compiler functionality,
groups supported under TCP/IP Services,
objects de???ned under TCP/IP Services,
sysORTable,
MIBs
Host Resources,
provided with TCP/IP Services,
MIB speci???cations creating,
MIB variable ???elds,
O
Object identi???cation codes (See OIDs) Object library ???les,
Object tables,
oid2instance support routine,
assigning,
o_counter support routine,
P
R
_ _restore_progname support routine,
S
sysORTable object,
T
Timeout, default,
data types,
sending and receiving,
Trap receiver,
command parameters,
running,
command examples,
Trap sender (cont???d) command parameters,
Troubleshooting features,
U
UNIX utilities,
W
Writing subagents compiling,
creating source ???les,
including in startup and shutdown,
object tables,
using UNIX utilities,