Compaq AAR04BCTE User Manual

Compaq TCP/IP Services forOpenVMSSNMP Programming andReferenceOrder Number: AA–R04BC–TEJanuary 2001Revision/Update Information: This manual supersedes

The following conventions are used in this manual. In addition, please note thatall IP addresses are fictitious.Ctrl/x A sequence such as Ctrl/x indica

eSNMP API Routinesoid2instanceoid2instanceExtracts the instance values from an OID structure and copies them to thespecified array of integers. The rou

eSNMP API Routinesoid2instanceExample#include <esnmp.h>OID *incoming = &method->varbind->name;OBJECT *object = method->object;int i

eSNMP API Routinesinst2ipinst2ipReturns an IP address derived from an OID instance.Formatint inst2ip ( unsigned int *instance,int *length,unsigned int

eSNMP API Routinesinst2ipDescriptionUse the EXACT mode for evaluating an instance forGetandSetoperations. ForGetNextandGetBulkoperations, use the NEXT

eSNMP API Routinesinst2ipThe search key consists of a number and two ipaddr values. These arerepresented in the instance part of the OID as n.A.A.A.A.

eSNMP API Routinescmp_oidcmp_oidCompares two OID structures.Formatint cmp_oid ( oid *q,oid *p );DescriptionThis routine does an element-by-element com

eSNMP API Routinescmp_oid_prefixcmp_oid_prefixCompares an OID against a prefix.Formatint cmp_oid_prefix ( oid *q,oid *prefix );DescriptionA prefix could be

eSNMP API Routinesclone_oidclone_oidMakes a copy of the OID. This routine does not allocate an OID structure.Formatoid clone_oid ( oid *new,oid *oid )

eSNMP API Routinesfree_oidfree_oidFrees the OID structure’s buffer. This routine does not deallocate the OIDstructure itself; it deallocates the eleme

eSNMP API Routinesclone_bufclone_bufDuplicates a buffer in a dynamically allocated space.Formatchar clone_buf ( char *str,int *len );ArgumentsstrA poi

Monospace textMonospace type indicates code examples and interactive screendisplays.This typeface indicates UNIX system output or user input,commands,

eSNMP API Routinesmem2octmem2octConverts a string (a buffer and length) to anoctstructure with the new buffer’saddress and length.Formatoct *mem2oct (

eSNMP API Routinescmp_octcmp_octCompares two octet strings.Formatint cmp_oct ( oct *oct1,oct *oct2 );Argumentsoct1Pointer to the first octet string.oct

eSNMP API Routinesclone_octclone_octMakes a copy of the data in anoctstructure. This routine does not allocate anoctstructure; it allocates the buffer

eSNMP API Routinesfree_octfree_octFrees the buffer attached to anoctstructure. This routine does not deallocatetheoctstructure; it deallocates the buf

eSNMP API Routinesfree_varbind_datafree_varbind_dataFrees the dynamically allocated fields in the VARBIND structure. However, thisroutine does not deal

eSNMP API Routinesset_debug_levelset_debug_levelSets the logging level, which dictates what log messages are generated. Theprogram or module calls the

eSNMP API Routinesis_debug_levelis_debug_levelTests the logging level to see whether the specified logging level is set. You cantest the logging levels

eSNMP API RoutinesESNMP_LOGESNMP_LOGThis is an error declaration C macro defined in the ESNMP.H header file. Itgathers the information that it can obtai

eSNMP API Routines__print_varbind__print_varbindDisplays the VARBIND and its contents. This routine is used for debuggingpurposes. To use this routine

eSNMP API Routinesset_select_limitset_select_limitSets the eSNMP select error limit. For more information, see Section 6.1.Formatset_select_limit ( ch

eSNMP API Routines__set_progname__set_prognameSpecifies the program name that will be displayed in log messages. This routineshould be called from the

eSNMP API Routines__restore_progname__restore_prognameRestores the program name from the second application of the set. This routineshould be called o

eSNMP API Routines__parse_progname__parse_prognameParses the full file specification to extract only the file name and file extension.Format_ _parse_progn

eSNMP API Routinesesnmp_cleanupesnmp_cleanupCloses open sockets that are used by the subagent for communicating with themaster agent.Formatesnmp_clean

6Troubleshooting eSNMP ProblemsThe eSNMP modules provided with TCP/IP Services include troubleshootingfeatures that are useful in controlling the way

Troubleshooting eSNMP Problems6.2 Modifying the Subagent TimeoutThe TCPIP$ESNMP_DEFAULT_TIMEOUT value is from 0 to 60 seconds. (Youshould use 0 only f

Troubleshooting eSNMP Problems6.3 Log FilesTCP/IP Services does not support writing log files to locations other than theSYS$SYSDEVICE:[TCPIP$SNMP] dir

IndexAAgentX protocol, 1–2API functionality, 1–6ASN.1 files, 3–5CC compiler, 3–1Chess exampletree structure, 3–4clone_bufsupport routine, 5–51clone_oct

1OverviewThe Simple Network Management Protocol (SNMP) is the de facto industrystandard for managing TCP/IP networks. The protocol defines the role of

MManagement information base (MIB), 1–1Master agent, 1–1mem2octsupport routine, 5–52method routinesroutine reference, 5–19 to 5–24MIB browser, 4–1comm

Trap sender (cont’d)command parameters, 4–9running, 4–9Troubleshooting features, 6–1UUNIX utilities, 3–7WWriting subagentscompiling, 3–5creating sourc

Overview1.1 SNMP ArchitectureFigure 1–1 SNMP ArchitectureMaster AgentSNMP/ASN.1LibraryeSNMP APIAgentX (TCP/IP V5.1)Subagent 1 Subagent 2 Subagent nTCP

Overview1.2 Request HandlingFigure 1–2 eSNMP Data FlowVM-0705A-AIClientTrapclientMaster AgentSubagent 1Subagent 2Subagent 1ClientMaster AgentSubagent

Overview1.2 Request HandlingThe network management station sends an SNMP request to the masteragent running on the host, using port 161. An SNMP reque

Overview1.3 TCP/IP Services Components for SNMPTable 1–1 (Cont.) SNMP Component FilesFile Location FunctionTCPIP$SNMP_TRAPRCV.EXE SYS$SYSTEM Utility f

Overview1.4 Writing an eSNMP SubagentTable 1–2 Files for Building a SubagentFile DescriptionESNMP.H Header file used to create a subagent. Located inTC

Overview1.5 The eSNMP APIInterface routines handle the basic subagent operations, such as:• Subagent initialization and termination• Registration• Pol

© 2001 Compaq Computer CorporationCOMPAQ, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.OpenVMS and Tru64 are trademarks

Overview1.6 The MIB Compiler• Method routine function prototypesThe subtree_TBL.C file is an object file that contains the following:• An array of integ

Overview1.7 SNMP VersionsIf you have problems running images linked against an older version ofUCX$ESNMP_SHR.EXE, verify that the version in SYS$SHARE

2MIBs Provided with TCP/IP ServicesThis chapter describes how MIBs are implemented on OpenVMS. The MIBsprovided with TCP/IP Services are:• The Host Re

MIBs Provided with TCP/IP Services2.1 Overview of the Host Resources MIBTable 2–1 (Cont.) Host Resources MIB ObjectsObject Name RFC Description OpenVM

MIBs Provided with TCP/IP Services2.1 Overview of the Host Resources MIBTable 2–1 (Cont.) Host Resources MIB ObjectsObject Name RFC Description OpenVM

MIBs Provided with TCP/IP Services2.1 Overview of the Host Resources MIBhrFSLastFullBackupDatehrFSLastPartialBackupDatehrStorageSizehrSWRunStatushrSys

MIBs Provided with TCP/IP Services2.1 Overview of the Host Resources MIBTCPIP$SNMP_REQUEST.EXE responds with no output and returns directlyto the DCL

MIBs Provided with TCP/IP Services2.2 Overview of MIB II2.2.1 MIB II Implemented GroupsA group is a subdivision of a MIB that defines a subtree. SNMP a

MIBs Provided with TCP/IP Services2.2 Overview of MIB IIWhen both the TCPIP$OS_MIBS and TCPIP$HR_MIB subagents arerunning, agetrequest on thesysORTabl

ContentsPreface ... vii1 Overview1.1 SNMP Architecture . . ...

3Creating a Subagent Using the eSNMP APIThis chapter describes how to use the eSNMP API to create a MIB subagent thatmanages entities or applications.

Creating a Subagent Using the eSNMP API3.2 The Structure of Management Information3.2.1 Assigning Object Identification CodesEach object in a MIB is as

Creating a Subagent Using the eSNMP API3.2 The Structure of Management InformationFigure 3–1 MIB II in SMI Tree StructureVM-0721A-AIiso (1)org (3)dod

Creating a Subagent Using the eSNMP API3.2 The Structure of Management InformationFor example, the chess MIB provided with the sample code in the[TCPI

Creating a Subagent Using the eSNMP API3.2 The Structure of Management InformationNormally, it is the nonleaf nodes that are registered as a subtree w

Creating a Subagent Using the eSNMP API3.3 Creating a MIB Source FileThe parameters and qualifiers for the MIBCOMP command are as follows:Parameter or

Creating a Subagent Using the eSNMP API3.3 Creating a MIB Source Fileenum: complete 1enum: underway 2enum: delete 3moveTable 1.3.6.1.4.1.36.2.15.2.99.

Creating a Subagent Using the eSNMP API3.3 Creating a MIB Source File1. Declaration SectionThe first section of the subtree_TBL.H file is a declaration

Creating a Subagent Using the eSNMP API3.3 Creating a MIB Source Filetypedef struct _chess_type {OID ches;int chessMaxGames;int chessNumGames;char che

4 Using the SNMP Utilities4.1 Using the MIB Browser ... 4–14.1.1 MIB Browser Parameters. . . ...

Creating a Subagent Using the eSNMP API3.3 Creating a MIB Source File2. Array of OBJECT Structures SectionThe second section of the subtree_TBL.C file

Creating a Subagent Using the eSNMP API3.3 Creating a MIB Source File3. Initialized Subtree Structure SectionThe third section of the subtree_TBL.C fil

Creating a Subagent Using the eSNMP API3.4 Including the Routines and Building the SubagentDepending on the version of the Compaq C compiler you are u

Creating a Subagent Using the eSNMP API3.5 Including Extension Subagents in the Startup and Shutdown ProceduresFile Name Edit RequiredTCPIP$EXTENSION_

4Using the SNMP UtilitiesTCP/IP Services includes the following programs, which are useful for testingapplications and for analyzing SNMP problems:• T

Using the SNMP Utilities4.1 Using the MIB BrowserTable 4–1 (Cont.) snmp_request Command ParametersParameter Function"community"The community

Using the SNMP Utilities4.1 Using the MIB BrowserTable 4–2 Flags for the snmp_request CommandFlag Description-dSpecifies hexadecimal dump mode. Before

Using the SNMP Utilities4.1 Using the MIB BrowserTable 4–2 (Cont.) Flags for the snmp_request CommandFlag Description-lSpecifies loop mode. Note that t

Using the SNMP Utilities4.1 Using the MIB BrowserTable 4–2 (Cont.) Flags for the snmp_request CommandFlag Description-s sleep_intervalSpecifies the num

cmp_oid_prefix ... 5–48clone_oid . . ... 5–49free_oid . . . ...

Using the SNMP Utilities4.1 Using the MIB BrowserNoteExcept for-l(Counter64), the data types are case sensitive. To preserveuppercase for display stri

Using the SNMP Utilities4.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.01.

Using the SNMP Utilities4.1 Using the MIB Browser6. The following example uses the same command as in example 5, but itspecifies the-tflag instead of th

Using the SNMP Utilities4.2 Using the Trap Sender and Trap Receiver ProgramsBy default, these programs use UDP port 162. However, you can specify anot

Using the SNMP Utilities4.2 Using the Trap Sender and Trap Receiver ProgramsTable 4–4 Parameters for the snmp_trapsnd CommandParameter Descriptionente

Using the SNMP Utilities4.2 Using the Trap Sender and Trap Receiver ProgramsTable 4–5 (Cont.) Flags for the snmp_trapsnd CommandFlag Description-h hos

Using the SNMP Utilities4.2 Using the Trap Sender and Trap Receiver Programsenterprise - 1.2.3agent address - 6.20.208.53trap type - Enterprise-specif

Using the SNMP Utilities4.2 Using the Trap Sender and Trap Receiver Programsaccount that has SYSPRV privilege. Note that the port number must be great

5eSNMP API RoutinesThis chapter provides reference information about the following types ofapplication programming interface (API) routines in the eSN

eSNMP API Routinesesnmp_initesnmp_initInitializes the Extensible SNMP (eSNMP) subagent and initiates communicationwith the master agent.Formatint esnm

eSNMP API Routinesesnmp_registeresnmp_registerRequests local registration of a single MIB subtree. This indicates to the masteragent that the subagent

eSNMP API Routinesesnmp_registerA subtree is identified by the base MIB name and the correspondingOIDnumberof the node that is the parent of all MIB va

eSNMP API Routinesesnmp_registerstatus = esnmp_register( &ipRouteEntry_subtree,RESPONSE_TIMEOUT,REGISTRATION_PRIORITY );if (status != ESNMP_LIB_OK

eSNMP API Routinesesnmp_unregisteresnmp_unregisterCancels registration of a MIB subtree previously registered with the masteragent.Formatint esnmp_unr

eSNMP API Routinesesnmp_register2esnmp_register2Requests registration of a single MIB subtree. This indicates to the master agentthat the subagent ins

eSNMP API Routinesesnmp_register2Field Name Descriptionrange_upper_bound An integer value that, with a nonzero range_subidfield, specifies a range inste

eSNMP API Routinesesnmp_register2When restarting the eSNMP protocol by callingesnmp_init, all MIB subtreeregistrations are cleared. All MIB subtrees m

eSNMP API Routinesesnmp_register2Example#include <esnmp.h>#define RESPONSE_TIMEOUT 0 /* use the default time setin esnmp_init message */#define

eSNMP API Routinesesnmp_unregister2esnmp_unregister2Cancels registration of a MIB subtree previously established with the masteragent. Use this routin

PrefaceThe Compaq TCP/IP Services for OpenVMS product is the Compaqimplementation of the TCP/IP networking protocol suite and internet servicesfor Ope

eSNMP API Routinesesnmp_capabilitiesesnmp_capabilitiesAdds a subagent’s capabilities to the master agent’ssysORTable. ThesysORTableis a conceptual tab

eSNMP API Routinesesnmp_uncapabilitiesesnmp_uncapabilitiesRemoves a subagent’s capabilities from the master agent’ssysORTable.Formatvoid esnmp_uncapab

eSNMP API Routinesesnmp_pollesnmp_pollProcesses a pending message that was sent by the master agent.Formatint esnmp_poll ( )DescriptionThis routine is

eSNMP API Routinesesnmp_are_you_thereesnmp_are_you_thereRequests the master agent to report immediately that it is up and functioning.Formatint esnmp_

eSNMP API Routinesesnmp_trapesnmp_trapSends a trap message to the master agent.Formatint esnmp_trap ( int *generic_trap,int specific_trap,char *enterpr

eSNMP API Routinesesnmp_termesnmp_termSends a close message to the master agent and shuts down the subagent.Formatvoid esnmp_term (void) ;DescriptionS

eSNMP API Routinesesnmp_sysuptimeesnmp_sysuptimeConverts UNIX system time obtained fromgettimeofdayinto a value with thesame time base assysUpTime.For

eSNMP API Routines5.2 Method Routines5.2 Method RoutinesSNMP requests may contain many encoded MIB variables. Thelibsnmpcodeexecuting in a subagent ma

eSNMP API Routines*_get Routine*_get RoutineThe *_get routine is a method routine for the specified MIB item, which istypically a MIB group (for exampl

eSNMP API Routines*_get RoutineField Name Descriptionobject A pointer to the object table entry forthe MIB variable being referenced. Themethod->ob

Related DocumentsTable 1 lists the documents available with this version of TCP/IP Services.Table 1 TCP/IP Services DocumentationManual ContentsDIGITA

eSNMP API Routines*_set Routine*_set RoutineThe*_setmethod routine for a specified MIB item, which is typically a MIBgroup (for example,systemin MIB II

eSNMP API Routines*_set RoutineField Name Descriptionrow A pointer to a ROW_CONTEXT structure(defined in the ESNMP.H header file). AllSetrequests to the

eSNMP API Routines*_set RoutineReturn ValuesESNMP_MTHD_noError The routine completed successfully.ESNMP_MTHD_notWritable The requested object cannot b

eSNMP API Routines*_set RoutineIf any row reports failure, all rows that were successfully committed are toldto undo the phase. This is accomplished b

eSNMP API Routines*_set Routine• ESNMP_ACT_UNDOFor each conceptual row that was successfully committed, the same methodroutine is called with method-&

eSNMP API Routines*_set Routine• Load the response OID back into the method routine’s VARBIND structure.Set the method->varbind field with the OID o

eSNMP API Routines*_set RoutineThe displaystring is different only in that the character array can beinterpreted as ASCII text, but the octetstring ca

eSNMP API Routines*_set Routine• ESNMP_TYPE_Integer32ESNMP_TYPE_Counter32ESNMP_TYPE_<Gauge32 (varbind->value.ul field)The 32-bit counter and 32-b

eSNMP API Routines5.3 Support Routines5.3 Support RoutinesThe support routines are provided as a convenience for developers writing methodroutines tha

eSNMP API Routineso_integero_integerLoads an integer value into the VARBIND structure with the appropriate type.This function does not allocate the VA

Table 1 (Cont.) TCP/IP Services DocumentationManual ContentsCompaq TCP/IP Services for OpenVMSSockets API and System ServicesProgrammingThis manual de

eSNMP API Routineso_integerExample#include <esnmp.h>#include "ip_tbl.h" <-- for ipNetToMediaEntry_type definitionVARBIND *vb = meth

eSNMP API Routineso_octeto_octetLoads an octet value into the VARBIND structure with the appropriate type. Thisfunction does not allocate the VARBIND

eSNMP API Routineso_oido_oidLoads anOIDvalue into the VARBIND structure with the appropriate type. Thisfunction does not allocate the VARBIND structur

eSNMP API Routineso_stringo_stringLoads a string value into the VARBIND structure with the appropriate type. Thisfunction does not allocate the VARBIN

eSNMP API Routineso_stringExample#include <esnmp.h>#include "ip_tbl.h" <-- for ipNetToMediaEntry_type definitionVARBIND *vb = metho

eSNMP API Routineso_counter64o_counter64Loads a counter64 value into the VARBIND structure.Formatint o_counter64 ( VARBIND *vb,OBJECT *obj,uint64 valu

eSNMP API Routinesstr2oidstr2oidConverts a null-terminated stringOIDin dot notation to anOIDstructure. Thestr2oidroutine does not allocate anOIDstruct

eSNMP API RoutinessprintoidsprintoidConverts anOIDinto a null-terminated string.Formatchar *sprintoid ( char *buffer,oid *oid );DescriptionAnOIDcan ha

eSNMP API Routinesinstance2oidinstance2oidCopies the object’s base OID and appends a copy of the instance array to makea complete OID for a value. Thi

eSNMP API Routinesinstance2oidExample#include <esnmp.h>VARBIND *vb; <-- filled inOBJECT *object; <-- filled inunsigned int instance[6];--