Home

Compaq AAR04BCTE Network Card User Manual

1. directory 1 system 1 interfaces 2 at 3 A icmp 5 tcp 6 udp 7 8 egp me KS lI 1 transmission 10 snmp 11 experimental 3 private 4 enterprises 1 VM 0721A Al Creating a Subagent Using the eSNMP API 3 3 Creating a Subagent Using the eSNMP API 3 2 The Structure of Management Information For example the chess MIB provided with the sample code in the TCPIP EXAMPLES SNMP directory has an element with the name chess The OID for the element chess is 1 3 6 1 4 1 36 2 15 2 99 which is derived from its position in the hierarchy of the tree iso 1 org 3 dod 6 internet 1 private 4 enterprise 1 digital 36 ema 2 sysobjects 15 decosf 2 chess 99 Any node in the MIB hierarchy can define a MIB subtree All elements in the subtree have an OID that starts with the OID of the subtree base For example if you define chess to be a MIB subtree base the elements with the same prefix as the chess OID are all in the MIB subtree chess 590 Le AS 3 E chessProduct ID oy GalvA el 3 6n2 15525 99 41 chessMaxGames LOO LOA TTB 621 52 5992 chessNumGames LS S E od 36025155 2 99 3 gameTable M36 clo41 3 6 2115 2 599 4 gameEntry po Oed she ls 3 6 215 299 54 4 game Index 3 657 4 153652 15 2 99 4 1 1 gameDescr 3 6 1 4 1 36 2 15 2 99 4 1 2 gameNumMoves 230 A 13 6 2 51552 99 4 1 3 gameStatus 3 6 1 4 1 36 2 15 2 99 4 1 4
2. 0 0 For OpenVMS Alpha firmware version 5 56 7 the response is shown in the following example P36 1e2e1e25 3 3sLelel Les soll sel s25 23 23 sli S566 e 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 e hrStorageType always contains the value of hrStorageFixedDisk 1 3 6 1 2 1 25 2 1 4 2 2 Overview of MIB Il The Standard MIB MIB II described in RFC 1213 defines a set of objects useful for managing TCP IP Internet entities MIB II supports network monitoring and managing from the Transport layer down to the Physical layer of the TCP IP internet stack This MIB also provides information on how connections are established and how packets are routed through the Internet For more information about MIB architecture see Section 3 2 MIBs Provided with TCP IP Services 2 5 MIBs Provided with TCP IP Services 2 2 Overview of MIB II 2 2 1 MIB Il Implemented Groups A group is a subdivision of a MIB that defines a subtree SNMP as implemented by TCP IP Services supports the following groups e system 1 e interfaces 2 e Internet Protocol 4 e ICMP 5 s TCP 6 UDP 7 e 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
3. eSNMP API Routines esnmp_init esnmp_init Format Arguments Description Initializes the Extensible SNMP eSNMP subagent and initiates communication with the master agent int esnmp_init int socket char subagent_identifier socket The address of the integer that receives the socket descriptor used by eSN MP subagent_identifier The address of a null terminated string that uniquely identifies this subagent usually a program name 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 identifier perhaps using the program name argv 0 and additional descriptive text The master agent does not open communications with a subagent whose subagent identifier 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 ESNMP_LIB_NO_ Could not initialize or communicate with the CONNECTION master agent Try again after a delay ESNMP_LIB_OK The esnmp_init routine has completed successfully ESNMP_LIB_ NOTOK Could not allocate memory for the subagent include lt esnmp_h gt int socket status esnmp_init amp socket gated 5 2 eSNMP A
4. Overview 1 7 Overview 1 6 The MIB Compiler Method routine function prototypes The subtree TBL C file is an object file that contains the following An array of integers representing the OIDs for each MIB variable An array of OBJ ECT structures An initialized SUBTREE structure 1 7 SNMP Versions The extensible SNMP software supports SNMP Version 2 based on RFCs 1901 through 1908 including The SNMP Version 2 structure of management information for SNMP Version 2 SMI Version 2 and textual conventions 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 specific 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 1 Using Existing SNMP Version 1 MIB Modules Existing SNMP Version 1 MIB subagent executable files should be compatible with the current SNMP Version 2 master agent without the ne
5. s OPEN request failed Restart CONNECTION the connection after a delay See the log file ESNMP_LIB_ CLOSE A CLOSE message was received ESNMP_LIB_NOTOK An eSNMP protocol error occurred and the packet was discarded ESNMP_LIB_LOST_ Communication with the master agent was lost CONNECTION Restart the connection 5 14 eSNMP API Routines 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_LIB OK The request was sent ESNMP_LIB_LOST_ The request cannot be sent because the master CONNECTION agent is down eSNMP API Routines 5 15 eSNMP API Routines esnmp_trap esnmp_trap Format Arguments Description Sends a trap message to the master agent int esnmp_trap int generic_trap int specific_trap char enterprise varbind vb 2 generic_trap A generic trap code Set this argument value to 0 zero for SNMP v2 traps specific_trap A spec
6. ASN 1 to specify the objects in the MIB 3 2 The Structure of Management Information The structure of management information SMI which is specified in RFCs 1155 and 1902 describes the general framework within which a MIB can be defined and constructed The SMI framework identifies the data types that can be used in the MIB and how resources within the MIB are represented and named SMI avoids complex data types to simplify the task of implementation and to enhance interoperability To provide a standard representation of management information the SMI specifies standard techniques for the following e Defining the structure of a particular MIB e Defining individual objects including the syntax and value of each object e Encoding object values Creating a Subagent Using the eSNMP API 3 1 Creating a Subagent Using the eSNMP API 3 2 The Structure of Management Information 3 2 1 Assigning Object Identification Codes Each object in a MIB is associated with an identifier of the ASN 1 type called an object identifier OID OIDs are unique integers that follow a hierarchical naming convention Each OID has two parts e 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 e A developer assigned portion for the private development of MIBs Note Your organization may require you to register all newly assigned OIDs In addition to an OID you should
7. handling e 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 e TCPIP SNMP_REQUEST EXE a MIB browser that allows you to retrieve and update objects from the MIBs e TCPIP SNMP_TRPSND EXE a trap sender that generates traps messages that require no response e 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 file and generates modules that are used by the developer to create subagent routines For every ASN 1 input file that is processed using the MIB compiler two output files a subtree TBL H file and a subtree TBL C file are generated where subtree is the name from the original MIB definition file for example chess The output files are described in more detail in Chapter 3 The subtree TBL H file is a header file that contains the following e A declaration of the subtree structure e Index definitions for each MIB variable in the subtree e Enumeration definitions for MIB variables with enumerated values e MIB group data structure definitions
8. have this data type A method routine should never return this value An incoming Set request never has this value in a VARBIND structure e ESNMP_TYPE_IpAddress varbind gt value oct field 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 Usea length of 4 5 28 eSNMP API Routines eSNMP API Routines set Routine ESNMP_TYPE_Integer32 ESNMP_TYPE_Counter32 ESNMP_TYPE_ lt Gauge32 varbind gt value ul field The 32 bit counter and 32 bit gauge data types are stored in the VARBIND structure as an unsigned integer Use the o_integer function to insert an unsigned value into the VARBIND structure ESNMP_TYPE_TimeTicks varbind gt valueul field The 32 bit timeticks type values are stored in the VARBIND structure as an unsigned integer Use the o_integer function to insert an unsigned value into the VARBIND structure ESNMP_TYPE_Counter64 varbind gt value ul64 field The 64 bit counter is stored in a VARBIND structure as an unsigned longword which on an OpenVMS Alpha system has a 64 bi
9. method 3 3 2 4 The subtree_TBL C Output Files The subtree TBL C file file contains the following sections 1 An array of integers representing the OIDs for each MIB variable 2 An array of OBJ ECT 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 file 1 Array of Integers Section The first section of the subtree TBL C fileis an array of integers used to represent the OID of each MIB variable in the subtree For example static unsigned int elems 1 3 6 1 4 1 36 2 15 2 99 chess 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 first line represents the root of the tree the other lines represent specific 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 3 9 Creating a Subagent Using the eSNMP API 3 3 Creating a MIB Source File 2 Array of OBJECT Structures Section The second section of the subtree TBL C file is an array of OBJ ECT structures Each MIB variable within the subtree has one OBJ ECT The chess example produces the following static OBJECT objects I_chessProduct ID 12 amp elems 11 ESNMP_TYPE_ObjectId chess_get NULL An OBJ ECT structure represents a MIB
10. no such name returned for variable 1 Using the SNMP Utilities 4 7 Using the SNMP Utilities 4 1 Using the MIB Browser 6 The following example uses the same command as in example 5 but it specifies the t flag instead of the 1 flag Only OIDs with the prefix matching the input OID are returned Note that as with other getnext request examples the value for the input OID is not returned If an SNMP Version 2 agent is the server the results using getbulk are identical snmp_request marley dec com public getnext t 1 3 6 1 2 1 1 26 1 Led 6ul Awl 3023 1o 1 34741 1302232 0 d 3 37 2 Sam Spade marley dec com Falcon BuildingLos Angeles CA 72 0 N i m e o s agent e o s agent 0 d 0 0 0 0 d 0 0 0 capabilities Tal 1 2 S capabilities OV OV OV OV OV OV OV OV OV OD AO Y o EHNEN M ow ow ow owt WWW WW WW WW W W W Ww OO 0 0 0 0 0 0 0 1 1 1 1 1 1 O O UOLO WO WO WO CO 1D O11 amp W DP I tnanwwa m w D ne NOM NOM NOM NOM NOM NOM NOM NOM NOM LOM LOMO PPO WMH I I tt toi il Or ie The following example shows how to send a Set request The request succeeds because the command line specifies 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 The following example sho
11. operating system load Parameters supplied to the load device when requesting initial operating system configuration Number of user sessions for which the host is storing state information 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 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 2 1 MIBs Provided with TCP IP Services 2 1 Overview of the Host Resources MIB Table 2 1 Cont Host Resources MIB Objects Object Name RFC Description OpenVMS Description hrSystemP rocesses hrSystemM axProcesses hrMemorySize hrStoragel ndex hrStorageType hrStorageDescr hrStorageAllocationU nits hrStorageSize hrStorageU sed hrDevicel ndex hrDeviceType hrDeviceDesc hrDeviceStatus hrDeviceErrors hrProcessorF rwl D Number of process contexts currently loaded or running on the system Maximum number of process contexts the system can support or 0 if not applicable The amount of physical main memory contained in the host A unique value for each logical storage area contained in the host The type of storage represented by this entry A description of the type and insta
12. reregister a MIB subtree if needed by calling the esnmp_register routine Return Values Example SNMP_LIB_OK The esnmp_unregister routine has completed successfully ESNMP_LIB_BAD_REG The MIB subtree was not registered ESNMP_LIB_LOST_ The request to unregister the MIB subtree could CONNECTION not be sent You should restart the protocol include lt esnmp h gt int status extern SUBTREE ipRouteEntry_subtree status esnmp_unregister amp 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 Ss s s n The request to unregister the MIB subtree could not be sent You should restart the protocol n break 5 6 eSNMP API Routines eSNMP API Routines esnmp_register2 esnmp_register2 Format Arguments 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 int esnmp_register2 ESNMP_REG reg reg A pointer to an ESNMP_REG structure that contains the following fields Field Name Description subtree priority timeout range subid A pointer to a subtree structure corresponding
13. specified by the agent parameter using the default SNMP version SNMP Version 1 The h host parameter is not specified so the trap will be sent to the local host snmp_trapsnd 0 0 local 0 0 0 Message received from 127 0 0 1 SNMPv1l Trap PDU community 7075626C 6963 public enterprise 0 0 agent address 0 0 0 0 trap type Cold Start 0 timeticks 51938978 The following example generates the same trap as in example 1 except that it specifies the use of SNMP Version 2 snmp_trapsnd 0 0 local 0 0 0 v2c Message received from 127 0 0 1 SNMPv2 Trap PDU community 7075626C 6963 public sysUpTime 0 51938968 6 d 0 16 29 snmpTrapOID 0 0 0 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 c special h mynode Message received from 16 20 208 68 SNMPv1l Trap PDU community 73706563 69616c special Using the SNMP Utilities 4 11 Using the SNMP Utilities 4 2 Using the Trap Sender and Trap Receiver Programs enterprise 1 2 3 agent address 6 20 208 53 trap type Enterprise specific 6 enterprise specific value 33 timeticks 100 4 2 2 Entering Commands for the Trap Receiver Program The trap receiver program lets you listen for receive and display SNMP trap messages Until interrupted the program continues to listen on the specified port If you enter commands using the default port number or anot
14. 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 LS 6 deel ls 98d 2a 1 356 AS o EES AS A TS 6 eles E ele 2s2 1 370 146 3615 23 3122 1 3 6 1 2 1 1 9 1 2 1 Base o s agent OS_MIBS capabilities 1 3 6 1 2 1 1 9 1 2 2 Base o s agent OS_MIBS capabilities 1 3 6 1 2 1 1 9 1 4 1 3256 0 d 0 0 32 1 3 6 1 2 1 1 9 1 4 2 3256 0 d 0 0 32 In this example the TCPIP OS_ MIBS subagent made two entries with different ID numbers OIDs with the prefix 1 3 6 1 2 1 1 9 1 2 that may show different sysORUpTime 1 3 6 1 2 1 1 9 1 4 The snmp_request program translates the value received in hundredths of a second to the following dropping any fractions of seconds d n hh mm ss In this format n represents the number of days hh represents the number of hours mm represents the number of minutes and ss represents the number of seconds The HR_MIB subagent has not yet successfully started and registered its capabilities If it starts its entries in this example would use the next available index number On systems running versions of the operating system prior to OpenVMS 7 1 2 counters for the MIB II ifTable do not wrap back to 9 after reaching the maximum value 232 1 as defined in RFC 1155 Instead they behave like the gauge type and remain at the maximum value until cleared b
15. 2 If you specify v 2c to send a message to an SNMP Version 1 agent or subagent it is unlikely to respond Specifies the maximum seconds the snmp_request program waits for a reply before timing out Cannot be 0 The default is 3 The i r and s flags apply to individual queries If you specify the 1 or t flags also the values for the i r and s flags are applied to each iteration 4 1 3 MIB Browser Data Types The snmp_request and snmp_trapsnd commands support the data types listed in Table 4 3 These values apply to Set requests only Table 4 3 Data Types for the snmp_request and snmp_trapsnd Commands Data Type Value Counter G Counter64 1 Display string D Gauge g Integer i IP address a NULL N Object identifier d Octet Opaque string q Time ticks t 1For support of trap sender program TCPIP SNMP_TRAPSND EXE only Properly defined MIB variables of type Counter64 are not writable Using the SNMP Utilities 4 5 Using the SNMP Utilities 4 1 Using the MIB Browser Note Except for 1 Counter64 the data types are case sensitive To preserve uppercase for display strings and NULL enclose the value in double quotation marks For example D or N On OpenVMS Alpha systems you must specify the value of the 1 data type as a 64 bit integer For example snmp_trapsnd 0 0 mynode 6 33 100 h mynode v2c 1 3 6 1 2 1 1 4 0 1 1311768467294899695 On Ope
16. Field Name Description action serial_num varbind object flags 5 22 eSNMP API Routines One of ESNMP_ACT_SET ESNMP_ACT_UNDO or ESNMP_ACT_ CLEANUP An integer number that is unique to this SNMP request Each method routine called while servicing a single SNMP request receives the same value as serial num New SNMP requests are indicated by a new value of serial_num A pointer to the VARBIND structure that contains the MIB variable s supplied data value and name OID The instance information has already been extracted from the OID and placed in the method gt row gt instance field A pointer to the object table entry for the MIB variable being referenced The method gt obj ect gt object index field is this object s unique index within the object table useful when one method routine services many objects The method gt object gt oid field is the OID defined for this object in the MIB A read only integer bitmask set by the libesnmp routine If set the ESNMP_FIRST_ IN_ROW bit indicates that this call is the first object to be set in the row If set the ESNMP_ LAST_IN_ROW bit indicates that this call is the last object to be set in the row Only METHOD structures with the ESNMP_LAST_ IN_ROW bit set are passed to the method routines for commit undo and cleanup phases Description eSNMP API Routines set Routine Field Name Description row A pointer toa ROW_CONTEXT structure def
17. 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 e The hrDeviceTable includes all the devices known to the OpenVMS host except those with the following characteristics Offline Remote UCB marked delete on zero reference count Mailbox device Device with remote terminal DEV M_RTT characteristic Template terminal class device 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 Code Condition 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 DNF SO for NFS and DADO for virtual devices For network devices only the template devices those with unit number 0 are displayed e hrFSMountPoint 1 3 6 1 2 1 25 3 8 1 2 is DNF Sn The device may change between restarts or after a dismount mount procedure e Inthe hrFSTable group if no file systems are mounted through NFS or no information is accessible a no such instance st
18. Note The TCP IP Services implementation of SNMP does not support the following defined MIB II groups e at address translation group e EGP External Gateway Protocol group e transmission group 2 2 2 Restrictions to MIB Il Implementation SNMP requests are not implemented for the following MIB II objects ipRouteMetricl ipRouteMetric5 tcpMaxConn SNMP set requests are not implemented for the following MIB II group objects ipDefaultTTL ipRouteAge ipRouteDest ipRoutelIfIndex ipRouteMask ipRouteNext Hop ipRouteType The TCP IP Services implementation of SNMP includes the following MIB II objects e sysObjectID is returned in the following format 1 3 6 1 2 1 1 2 0 1 3 6 1 4 1 36 2 15 13 22 1 where 1 3 6 1 4 1 36 2 15 13 22 1 corresponds to iso org dod internet private enterprises dec ema SysObjectIds DEC OpenVMS eSNMP e The sysORTable elements are under OID prefix 1 3 6 1 2 1 1 9 1 See RFC 1907 for details 2 6 MIBs Provided with TCP IP Services MIBs Provided with TCP IP Services 2 2 Overview of MIB Il 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 OI Ds conform to RFC 1907 18 cO i EA A Q Lela l E A E EE ESES S EE e S EA S O22 ES Ol aed 36 15 35 302 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 E E EA E Ol E o EO 1 3 6
19. RFC 1905 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 The appropriate subagent processes the request 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 1 2 subagent 1 is sending the esnmp_are_you_there message A trap is generated by the subagent and sent to the client In Figure 1 2 Subagent n is generating a trap for the trap client on NMS 2 The trap and esnmp_are_you_there routines are described in Section 5 1 1 3 TCP IP Services Components for SNMP Table 1 1 lists the components of SNMP and the command procedures for managing SNMP that are supplied with TCP IP Services Table 1 1 SNMP Component Files File Location Function TCPIP ESNMP_SERVER EXE SYS SYSTEM Master agent image TCPIP OS _ MIBS EXE SYS SYSTEM MIB II subagent image TCPIP HR_MIB EXE SYS SYSTEM Host Resources MIB subagent image TCPIP SNMP_REQUEST EXE SYS SYSTEM Simple MIB browser TCPIP SNMP_TRAPSND EXE SYS SYSTEM Utility for sending trap 1 4 Overview messages continued on next page Overview 1 3 TCP IP Services Components for SNMP Table 1 1 Con
20. 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 files in the SY S SYSDEVICE TCPIP SNMP directory Output redirected from SYS ERROR is logged to ERR files in the same directory Output redirected from SYS OUTPUT for the agent process is logged to the following files e TCPIP ESNMP LOG for the master agent e TCPIP OS MIBS LOG for the MIB II e TCPIP HR_MIB LOG for the Host Resources MIB Output redirected from SYS ERROR is logged to the following files e TCPIP ESNMP ERR for the master agent e TCPIP OS MIBS ERR for the MIB II e TCPIP HR_MIB ERR for the Host Resources MIB Data is flushed to the log files when the corresponding process terminates Each invocation of the TCPIP SNMP_RUN COM procedure purges these files retaining at least the last seven versions the exact number depends on the value of the CLUSTER_NODES system parameter The log files are located in the SYS SYSDEVICE TCPIP SNMP directory along with the TCPIP SNMP_CONF DAT file which is a text representation of the SNMP configuration data generated by the master agent during startup The contents of the SNMP log files are written to SY S SY SDEVICE TCPIP SNMP when the process stops or when you stop it for example by entering the STOP I D xxx command After a process restarts it creates a new version of the files If a
21. ail oreste POON ARG iaa ea a eee hea erie wth ae a is ene as ate aaa __ Parse prognamMe cee eee ESAMP Cl6ANUDs r shed rana be wads LE woke She eats Ee EA 6 Troubleshooting eSNMP Problems 6 1 6 2 6 3 Index Figures 4 6 Modifying the Subagent Error Limit 0 000 c cece eee Modifying the Subagent Timeout 0 00 cee es Logi FESR na BAIS ces atpe At Aide do ara AM de Sa Sige Aes aa Sead ERR wade are SNMP Architectures seirene le ok ee be env ee ls od eSNMP Data FIOQW cic beet de bee ea Pa ead Swe Aaa MIB II in SMI Tree Structure 0 a TCP IP Services Documentation aasa 0c cee ees SNMP Component Files 0 0 0 0 cece eee Files for Building a Subagent 0 000 es Host Resources MIB Objects 0 000 cece snmp_request Command ParametersS 00 0c eee eee Flags for the snmp_request Command 000 cee eee Data Types for the snmp_request and snmp_trapsnd Commands Parameters for the snmp _trapsnd Command Flags for the snmp_trapsnd Command 000 cee eee snmp_traprcv Command Flags 0 000 eee Interface Routines 1 eee teens 5 48 5 49 5 50 5 51 5 52 5 53 5 54 5 55 5 56 5 57 5 58 5 59 5 60 5 61 5 62 5 63 5 64 5 65 PPP N 1 2 1 3 3 3 Preface The Compaq TCP IP Services for OpenVMS product is the Compaq implementation of the TCP IP networking protocol suite and internet services
22. ain ba Se ee a Par ee OR ae str2oid Sprinto d ea eae Bode Bohs Sd ee eS he Bice Se Be Ba Bee MaE EEI DLE TAOko MAREE ants ee tee TAE ee EEA AT E oid2instanCer ira ace shaw Bee a E T E aes ae as inst2ip cmp_oid 4 1 4 1 4 2 4 5 4 6 4 8 4 9 4 9 4 10 4 11 4 12 4 12 4 12 4 13 5 1 5 2 5 3 5 6 5 7 5 11 5 12 5 13 5 14 5 15 5 16 5 17 5 18 5 19 5 20 5 22 5 24 5 26 5 27 5 30 5 31 5 33 5 34 5 35 5 37 5 38 5 39 5 40 5 42 5 44 5 47 CMP OLA PRET E aei aie ana dre Aa a ha Wee dee wen bie ee CLONE OG aie ed Bane tee len doe PE ae Oa ale ea Ge wa a Re i TCQIONG Sosa gnarieet anann Bian Pe a ts da A a 24 as ened eae done DUP ied nein Re Ca eR fa ee Be eee Dk eS hats CIP OCU ete aes assole a ahectaragat E U ateta a tnattay Agnew atta Sparta asiteua a Wied ER S CLOMENOGE 92 Ai densest ng aed aera Me ogi fag dota tied dadda a e gg 4A dence sated alas ae ttt FrEE O garit O E E OE alas Gee Baa le Ue SR Hale ale BER RS free var bind data aian esate ad Counties beatae G Saat haa Baad Set debug l vel ii wasiieaiete haa be aw wie eit tes we eee wt eect te a ISSGOCDUG level ninia siea with a ne ene Gog BR ene eG wh eat eA Gob eal ne coe A ESNMP OG oe 20 45 ented one lates ae adhe x AAR EGE w AOR E UR Sk JPrINt Var DIN si5 d ve Pade eae adden be ada ea bY ata belie Pade Set Selects iMIG iii fue Gate ge ns ee aa dae Rieder tee wy SEES PROGMNAMC a soba RAE E ets Aika te Aas ok died Ae a a acta fas
23. an EXACT match include lt esnmp h gt OID incoming OBJECT object int instLength unsigned int instance 6 unsigned int ip_addr int iface amp method gt varbind gt name method gt object The instance is N 1 A A A A where the A s are the IP address instLength oid2instance incoming object instance 6 if instLength 6 amp amp inst2ip amp instance 2 4 amp ip_addr TRUE 0 iface int instance 0 else return ESNMP_MTHD_noSuchInstance The following example shows a GetNext operation in which there is only one key or in which the ipaddr value is the least significant part of the key This is a NEXT match therefore a value of 1 is passed back for the carry value include lt esnmp h gt OID incoming amp method gt varbind gt name OBJECT object method gt object int instLength unsigned int instance 6 unsigned int ip_addr int iface The instance is N 1 A A A A where the A s are the IP address instLength oid2instance incoming object instance 6 iface instLength lt 1 0 int instance 0 iface inst2ip amp instance 2 instLength 2 amp ip_addr FALSE 1 In the following example the search key consists of multiple parts If you are doing a GetNext operation you must find the next possible value for the search key so that you can perform a cascaded greater than or equal to search eSNMP API Routines 5 45 eSNMP API Routines in
24. messages For example to define TCPIP SNMP_SELECT_ERROR_LIMIT to limit the number of times a 1 error value is returned to 1 000 enter the following command DEFINE SYSTEM TCPIPSSNMP_SELECT_ERROR_LIMIT 1000 6 2 Modifying the Subagent Timeout You can define 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 define the timeout is especially useful for slower systems and systems with heavy network traffic The logical name is translated at startup time Troubleshooting eSNMP Problems 6 1 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 define TCPIP ESNMP_DEFAULT_TIMEOUT to time out after 6 seconds of inactivity between the master agent and subagents enter the following command DEFINE SYSTEM TCPIPSESNMP_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
25. moveTable 23 Oe Wvd ole 36 02 155 2299 5 moveEntry 3163424 536 215522995 5 24 moveIndex 13 60144 1 3602415 2 99 5 1 1 moveByWhite so Oe SAN L362 15522 996 1 2 moveByBlack Pe Par e415 36 02 51 502 995 5 1 3 movestatus oO A ol 362 215 2599 0 LA chessTraps E Oc desl 36 25 1552 5996 moveTrap 2365 eA D3 621522599 56 1 The base of this MIB subtree is registered with the master agent to tell it that this subagent handles all requests related to the elements in the subtree The master agent expects a subagent to handle all objects subordinate to the registered MIB subtree This principle guides your choice of MIB subtrees For example registering a subtree of chess is reasonable because it is realistic to assume that the subagent could handle all requests for elements in this subtree Registering an entire application specific MIB usually makes sense because the particular application expects to handle all objects defined in the application specific MIB However registering a subtree of SNMP under MIB II would be a mistake because it is unlikely that the subagent is prepared to handle every defined MIB object subordinate to SNMP packet counts errors trapping and so on A subagent can register as many MIB subtrees as it wants It can register OIDs that overlap with other registrations by itself or with other subagents however it cannot register the same OID more than once Subagents can register and unregist
26. 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 specific instance of a MIB value If there are more elements in the OID structure than specified by the max_len parameter the function copies the number of elements specified by max_len only and returns the total number of elements that would have been copied had there been space Return Values Less than zero An error occurred This is not returned if the object was obtained by looking at this OID Zero No instance elements Greater than zero The returned value indicates the number of elements in the index This could be larger than the max_len parameter 5 42 eSNMP API Routines eSNMP API Routines oid2instance Example include lt esnmp h gt OID incoming amp method gt varbind gt name OBJECT object method gt object int instLength unsigned int instance 6 in a GET operation Expected Instance is N 1 A A A A where A s are IP address instLength oid2i
27. points to a common ROW _ CONTEXT The method gt flags bitmask has the ESNMP_LAST_IN_ROW bit set if this is the last object being called for this ROW_CONTEXT This enables you to doa final consistency check because you have seen every variable binding for this conceptual row 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 method gt row gt context field is private to the method routine Libesnmp does not use it A typical use is to store the address of an emitted structure that has been loaded with the data from the VARBIND for the conceptual row 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 method gt row gt save field is intended to hold a pointer to whatever data is needed to accomplish this A typical use is to store the address of a structure that has been loaded with the current data for the conceptual row The structure is one th
28. process executes without errors ERR files might not be created Writing to SYS OUTPUT and SYS ERROR from custom subagents is controlled by qualifiers 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 file 6 2 Troubleshooting eSNMP Problems Troubleshooting eSNMP Problems 6 3 Log Files TCP IP Services does not support writing log files to locations other than the SY S SY SDEVICE TCPIP SNMP directory The log files contain startup and event information and additional messages depending on the logging level specified for an agent The SNMP logging facility uses three logging levels e TRACE logs trace warning and error messages e WARNING logs warning and error messages e ERROR For the master agent and standard subagents the logging level is WARNING Log files 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 Comp
29. represents the introduction of a new term It also represents the name of an argument an attribute or a reason Italic text indicates important information complete titles of manuals or variables Variables include information that varies in system output Internal error number in command lines PRODUCER name and in command parameters in text where dd represents the predefined code for the device type Uppercase text indicates a command the name of a routine the name of a file or the abbreviation for a system privilege Monospace text numbers Monospace type indicates code examples and interactive screen displays This typeface indicates UNIX system output or user input commands options files directories utilities hosts and users In the C programming language this typeface identifies the following elements keywords the names of independently compiled external functions and files syntax summaries and references to variables or identifiers introduced in an example A hyphen at the end of a command format description command line or code line indicates that the command or statement continues on the following line All numbers in text are assumed to be decimal unless otherwise noted Nondecimal radixes binary octal or hexadecimal are explicitly indicated xi 1 Overview The Simple Network Management Protocol SNMP is the de facto industry standard for managing TCP IP networks The protocol d
30. the Trap Receiver Program Trap Receiver Flags 0 cece Setting Up an SNMP Trap Service 0 00 cee eee eee Trap Receiver Examples 0 000 cece eet 5 eSNMP API Routines 5 1 5 2 5 2 1 5 2 2 5 2 3 5 3 interface ROUTINES soc i eee dees aes a te Rare ee a Geo a bree esnmp_i Dilek Sater cengee sas toate ee rade A Conse atte E E a E aan ae a ESNMP FEOIStET sen a aai eka Aa iA deo Alek nee Gav A PE EA hale eA esnmp_unregister 0 0 ee ESNMp regist 23st rae Ake SPS eae eee ae Ak aol dees esnmp_unregister2 0 ee esnmp_capabilities 0 0 0 0 ee esnmp_uncapabilities 20 0 00 0 ESNIMP poliai ins Wea eS EE VE Ans Bea hak Bea wal esnmp_are you there 1 0 0 ee SHIM AU AP St contac eth Aen ei Bat edt ahs Coote eA Roast fn Rae ah E AS esa Bak tog a edd CSAMP EMM 2 6 ara a eae aad She apa eee Leave Whale a ata esnmp_sysuptime 6 ee Method ROUTINES a 2 cle ee sie ee dciats Seid So deado binned ate oo edeate wees Get ROULING ahg eas feet beta gente aden bead dense aa denn head Set ROUTINE satie es A Miu kde Gee wher Sie A a de Suan y BRS Sere Processing set Routines 0 0 cece es Method Routine Applications Programming s s sssaaa aaae Value Representation a naaa ee Support ROUTINES anme a ae en A Bt aaa as AAEE ot ath reais BA Ee DG O INtegE a s aaa a a aaa pad E a a a A o string o COUNTEFO4 erie bak Sei he EY
31. the eSNMP API see the TCPIP SNMP ESNMP H file Table 1 2 lists files that contain additional comments and documentation Overview 1 9 2 MIBs Provided with TCP IP Services This chapter describes how MIBs are implemented on OpenVMS The MIBs provided with TCP IP Services are e The Host Resources MIB which manages operating system objects Section 2 1 e MIB II which manages TCP IP kernel objects Section 2 2 2 1 Overview of the Host Resources MIB The Host Resources MIB defines a uniform set of objects useful for the management of host computers The Host Resources MIB described by RFC 1514 defines objects that are common across many computer system architectures The TCP IP Services implementation of SNMP includes many of these defined objects In addition some objects in MIB II provide host management functionality 2 1 1 Defining Host Resources MIB Implemented Objects This section defines each of the implemented eSNMP objects Table 2 1 provides a general RFC description and a specific OpenVMS description for each implemented object Table 2 1 Host Resources MIB Objects Object Name RFC Description OpenVMS Description hrSystemU ptime hrSystemDate hrSystemI ntialL oadDevice hrSystemI ntialL oadParameters hrSystemNumuU sers The amount of time since this host was last initialized The host s notion of the local date and time of day Index of the hrDeviceE ntry for configured initial
32. 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 specified number of max_retries is sent continued on next page Using the SNMP Utilities 4 1 Using the MIB Browser Table 4 2 Cont Flags for the snmp_request Command Flag Description s sleep_interval v version w max_wait Specifies the number of seconds between iterations of sending a request for the r flag and listening for a reply for the i flag The default is 1 second This flag is ignored if neither the r flag nor the i flag are specified The s flag is useful for specifying a time to wait between resends which might be necessary when a server agent is starting up Specifies tree mode Valid only if request type is GetNext or GetBulk where flag n is set to 0 and flag m is set to a number greater than 0 Similar to the 1 flag Directs the agent to perform a MIB walk for the subtree with the variable_name as its root The program reads and prints responses and issues requests until the agent has no more data for the specified subtree times out or is interrupted by a user Specifies the SNMP version to use for sending the PDU The versions are 2c or 1 default Not case sensitive You can specify the flag without a space v2c and v1 If request_type is getbulk the version defaults to SNMP Version
33. variable For example the following is the group structure for the chess MIB 3 8 Creating a Subagent Using the eSNMP API Creating a Subagent Using the eSNMP API 3 3 Creating a MIB Source File typedef struct _chess_type OID ches int chessMaxGames int chessNumGames char chessProductID_mark char chessMaxGames_mark char chessNumGames_mark chess_type Although MIB group structures are provided for your use you are not required to use them You can use the structure that works best with your method routines 5 Method Routine Prototypes Section The fifth section of the subtree TBL H file describes the method routine prototypes Each MIB group within the subtree has a method routine prototype defined A MIB group is a collection of MIB variables that are leaf nodes and that share a common parent node There is always a function prototype for the method routine that handles the Get GetNext and GetBulk operations If the group contains any writable variables there is also a function prototype for the method routine that handles Set operations Pointers to these routines appear in the subtree s object table which is initialized in the subtree TBL C module You must write method routines for each prototype that is defined as follows extern int mib group get METHOD method extern int mib group set METHOD method For example extern int chess_get METHOD method extern int chess_set METHOD
34. variable and has the following fields ob ject_index The constant _mib variable from the subtree TBL H file which identifies this variable in the chess example I_chessProduct ID 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 amp 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 Theinteger with index 11 in the array elems is the first 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 subt ree_1 1 The master agent finds subt ree_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 l
35. 1 3 5 using UNIX utilities 3 7 Index 3
36. 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 SYSSINPUT OPTIONS CHESS_METHOD OBJ CHESS_MIB OBJ CHESS_TBL OBJ SYSSSHARE TCPIPSESNMP_SHR EXE SHARE 3 5 Including 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 files File Name Edit Required TCPIP EXTENSION_MIB_STARTUP COM Edit the example lines to include an INSTALL CREATE command for custom images that need to be installed possibly with privileges Remove extra example lines and adjust the GOTO statement TCPIP EXTENSION_MIB_RUN COM Edit the example lines to include a RUN command for custom images Remove extra example lines and adjust the GOTO statement 3 12 Creating a Subagent Using the eSNMP API Creating a Subagent Using the eSNMP API 3 5 Including Extension Subagents in the Startup and Shutdown Procedures File Name Edit Required TCPIP EXTENSION_MIB_SHUTDOWN COM Edit the example lines to Include symbols for the detached processes that are running custom images Use the same process names specified in TCPIP EXTENSION_MIB_ RUN COM Modify the IF and THEN statements to i
37. Compag TCP IP Services for OpenVMS SNMP Programming and Reference Order Number AA RO4BC TE January 2001 Revision Update Information This manual supersedes the DIGITAL TCP IP Services for OpenVMS eSNMP Programming and Reference Version 5 0 Software Version Compaq TCP IP Services for OpenVMS Version 5 1 Operating Systems OpenVMS Alpha Versions 7 1 7 2 1 OpenVMS VAX Versions 7 1 7 2 Compaq Computer Corporation Houston Texas 2001 Compaq Computer Corporation COMPAQ VAX VMS and the Compaq logo Registered in U S Patent and Trademark Office OpenVMS and Tru64 are trademarks of Compaq Information Technologies Group L P in the United States and other countries All other product names mentioned herein may be trademarks of their respective companies Confidential computer software Valid license from Compaq required for possession use or copying Consistent with FAR 12 211 and 12 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 sh
38. Displays the varbind and its structure Sets the error limit for SNMP client requests Sets the program name to be displayed in log messages Resets the program name back to the previous name Parses the application file name to determine the program name Closes a socket that is used by a subagent for communicating with the master agent eSNMP API Routines eSNMP API Routines o_integer o_integer Format Arguments Loads an integer value into the VARBIND structure with the appropriate type This function does not allocate the VARBIND structure int o_integer VARBIND vb OBJECT obj unsigned long value 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 defined in the object structure must be one of the following otherwise an error is returned ESNMP_TYPE_Integer32 32 bit integer ESNMP_TYPE_Counter32 32 bit counter unsigned ESNMP_TYPE_Gauge32 32 bit gauge unsigned ESNMP_TYPE_TimeTicks 32 bit timeticks unsigned ESNMP_TYPE_UInteger32 32 bit integer unsigned ESNMP_TYPE_Counter64 64 bit counter unsigned ESNMP_TYPE_IpAddress Implicit octet string 4 Note If the real type is IpAddress then eSNMP assumes that the 4 byte integer is in network byte order and packages it into a
39. ECTION master agent 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 field Example include lt esnmp h gt define RESPONSE_TIMEOUT 0 use the default time set in OPEN message define REGISTRATION_PRIORITY 10 priority at which subtrees will register int status extern SUBTREE ipRouteEntry_subtree 5 4 eSNMP API Routines eSNMP API Routines esnmp_register status esnmp_register amp ipRouteEntry_subtree RESPONSE_TIMEOUT REGISTRATION_PRIORITY if status ESNMP_LIB_OK printf Could not queue the ipRouteEntry n printf subtree for registration n eSNMP API Routines 5 5 eSNMP API Routines esnmp_unregister esnmp_unregister Format Arguments Description Cancels registration of a MIB subtree previously registered with the master agent int esnmp_unregister SUBTREE subtree subtree A pointer to a subtree structure corresponding to the subtree to be handled The code emitted by the MIB compiler files subtree TBL C and subtree TBL H externally declare and initialize the subtree structures Refer to Chapter 3 for more information about these files 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
40. Each method routine called while servicing a single SNMP request receives the same value of serial num New SNMP requests are indicated by a new value of serial_num repeat_cnt Used for GetBulk only This value indicates the current iteration number of a repeating VARBIND This number increments from 1 to max _rep amp itions and is O zero for nonrepeating VARBIND structures max_repdtitions The maximum number of repetitions to perform Used for GetBulk only This will be O zero for nonrepeating VARBIND structures You can optimize subsequent processing by knowing the maximum number repeat calls will be made varbind A pointer to the VARBIND structure for which you must fill in the OID and data fields Upon entry of the method routine the method gt varbind gt name field is the OID that was requested Upon exit of the method routine the method gt varbind field contains the requested data and the method gt varbind gt name field is updated to reflect the actual instance OID for the returned VARBIND structure The support routines o_integer o_string o_oid and o_octet are generally used to load data The libsnmp instance2oid routine is used to update the OID in the method gt varbind gt name field eSNMP API Routines eSNMP API Routines get Routine Field Name Description object A pointer to the object table entry for the MIB variable being referenced The method gt obj ect gt obj ect_index field is
41. G routine include lt esnmp h gt if stremp t argv 1 set_debug_level TRACE NULL else set_debug_level WARNING NULL eSNMP API Routines 5 57 eSNMP API Routines is_debug_level is debug _level Tests the logging level to see whether the specified logging level is set You can test the logging levels as follows Level Meaning ERROR Used when a bad error occurs requiring restart WARNING Used when a packet cannot be handled this also implies ERROR TRACE Used when tracing all packets this also implies ERROR and WARNING Format int is_debug_level int type Return Values TRUE The requested level is set and the ESNMP_LOG will generate output or output will go to the specified destination FALSE The logging level is not set Example include lt esnmp h gt if is_debug_level TRACE dump_packet 5 58 eSNMP API Routines eSNMP API Routines ESNMP_LOG ESNMP_LOG Format Description Example This is an error declaration C macro defined in the ESNMP H header file It gathers the information that it can obtain and sends it to the log ESNMP_LOG level format 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 L
42. INE FILE_ Where e xisa text string for example a printf statement e levd is one of the following ERROR Declares an error condition WARNING Declares a warning TRACE Puts a message in the log file if trace is active For more information about configuration options for logging and tracing refer to the Compaq TCP IP Services for OpenVMS Management guide include lt esnmp h gt ESNMP_LOG ERROR Cannot open file s n file eSNMP API Routines 5 59 eSNMP API Routines __print_varbind __print_varbind Displays the VARBIND and its contents This routine is used for debugging purposes To use this routine you must set the debug level to TRACE Output is sent to the specified file Format __print_varbind VARBIND vb int indent Arguments vb The pointer to the VARBIND structure to be displayed If the vb pointer is NULL no output is generated indent The number of bytes of white space to place before each line of output 5 60 eSNMP API Routines eSNMP API Routines set_select_limit set_select_limit Sets the eSNMP select error limit For more information see Section 6 1 Format set_select_limit char progname Arguments progname The subagent name This argument is valid with DPI versions only With AgentX the argument is NULL because subagents do not get names Return Values ESNMP_MTHD_noError No error was generated ESNMP_MTHD_genErr An error was generated e
43. P H file for a definition of the OCT and OID structures ESNMP_TYPE_Integer32 varbind gt valuesl field This is a 32 bit signed integer Use the o_integer routine to insert an integer value into the VARBIND structure Note that the prototype for the value argument is unsigned long therefore you may need to cast this to a signed integer ESNMP_TYPE_DisplayString ESNMP_TYPE_ Opaque ESNMP_TYPE_OctetString varbind gt valueoct field 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 5 27 eSNMP API Routines set Routine The displaystring is different only in that the character array can be interpreted as ASCII text but the octetstring can be anything If the octetstring contains bits or a bit string the OCT structure contains the following A length equal to the number of bytes needed to contain the value that is qty bits 1 8 1 A pointer to a buffer containing the bits of the bitstring in the form bbbbb bb where the bb octets represent the bitstring itself bit 0 comes first 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 stru
44. P IP Services 2 1 restrictions to definition 2 3 hrDeviceTable 2 4 hrDiskStorage 2 5 hrFSMountPoint 2 4 hrFSTable 2 4 hrProcessorFrwlD 2 5 hrStorageType 2 5 ifTable 2 7 inst2ip support routine 5 44 instance2oid support routine 5 40 L Logging output 6 2 Index 1 R Management information base MIB 1 1 Master agent 1 1 mem2oct support routine 5 52 method routines routine reference 5 19 to 5 24 MIB browser 4 1 command examples 4 6 command flags 4 2 command parameters 4 1 data types 4 5 using 4 1 MIBCOMP command example 3 6 command syntax 3 5 MIB compiler functionality 1 7 MIB II 2 5 groups supported under TCP IP Services 2 6 ifTable 2 7 objects defined under TCP IP Services 2 6 restrictions to definition 2 6 sysObjectID 2 6 sysORTable 2 7 sysORTable object 2 6 tree structure 3 2 MIBs Host Resources 2 1 MIB II 2 5 provided with TCP IP Services 2 1 subtrees 3 2 MIB specifications creating 3 1 MIB variable fields 3 10 mosy utility 3 7 O __restore_progname support routine 5 63 RFCs 1155 2 7 3 1 3 2 4 6 1213 2 5 1514 2 1 2 5 1901 1908 1 8 1902 3 1 3 2 4 6 1907 2 6 2 7 2089 1 8 2741 1 2 S Object identification codes See Ol Ds Object library files 1 6 Object tables 3 7 oid2instance support routine 5 42 OIDs assigning 3 2 o_counter support routine 5 37 o_integer support routine 5 31 o_octet su
45. PI Routines eSNMP API Routines esnmp_register esnmp_ register Format Arguments Description 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 int esnmp_register subtree subtree int timeout int priority subtree A pointer to a subtree structure corresponding to the subtree to be handled The code emitted by the MIB compiler files subtree TBL C and subtree TBL H externally declare and initialize the subtree structures Refer to Chapter 3 for more information about these files Note All memory pointed to by the subtree fields 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 configurations The range is 1 to 255 The entry with the largest number has the highest priority The subagent that registers a subtr
46. SE 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 significant element is incremented Returns a 1 one only when there is a carry from the most significant the first 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 5 44 eSNMP API Routines Description eSNMP API Routines inst2ip Use the EXACT mode for evaluating an instance for Get and Set operations For GetNext and GetBulk operations use the NEXT mode When using NEXT mode this routine assumes that the search for data will be performed using greater than or equal to matches Return Values Carry value is 0 The routine completed successfully Carry valueis 1 For EXACT match an error occurred For NEXT Examples match there was a carry If there was a carry the returned ipaddr is 0 The following example converts an instance to an IP address for a Get operation which is
47. SNMP API Routines 5 61 eSNMP API Routines __set_progname __set_progname Specifies the program name that will be displayed in log messages This routine should be called from the main during program initialization It needs to be called only once Format __set_progname char prog Arguments prog The program name as taken from argv 0 or some other identification for entity calling logging routines Example include esnmp h __set_progname argv 0 5 62 eSNMP API Routines 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 5 63 eSNMP API Routines __parse_progname __parse_progname Parses the full file specification to extract only the file name and file extension Format __parse_progname file specification Arguments file specification The full file specification for the subagent Example include esnmp h static char Progname 100 sprintf Progname s 8X __parse_progname prog getpid 5 64 eSNMP API Routines eSNMP API Routines esnmp_cleanup esnmp_cleanup Closes open sockets that are used by the subagent for communicating with the maste
48. 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 method gt row gt context and method gt row gt save fields and so on The function return status value is ignored for the CLEANUP phase 5 2 2 Method Routine Applications Programming You must write the code for the method routines declared in the subtree TBL H file 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 Get Bulk 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 method gt object gt oid field the object s base OID to the method gt varbind gt name field the requested OID You can use the oid2instance support routine to do this 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 method gt action field determine what data if any is to be returned 5 26 eSNMP API Routines eSNMP API Routines set Ro
49. VARBIND structure that is supposed to receive the data obj A pointer to the OBJ ECT structure for the MIB variable associated with the OID in the VARBIND structure value The 8 byte value to be inserted into the VARBIND structure passed as an array of two integers The real type as defined in the object structure must be ESNMP_TYPE_Counter64 Otherwise an error is returned See the example for the o_integer routine Return Values ESNMP_MTHD_noError No error was generated ESNMP_MTHD_genErr An error was generated eSNMP API Routines 5 37 eSNMP API Routines str2oid str2oid Converts a null terminated string OID in dot notation to an OID structure The str2oid routine does not allocate an OID structure Format oid str2oid oid oid char s Arguments oid The value to be inserted as data into the VARBIND structure For more information about OID length and values see Chapter 3 s A null string or empty string returns an OID structure that has one element of zero 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 null An error occurred Otherwise the pointer to the OID structure its first argument is returned Example include lt esnmp h gt OID abc if stroid amp abc 1 2 5 4 3 6 NULL DPRINTF WARNING It did not
50. _ OCTET STRING Octet string ASN 1 ESNMP_TYPE_IpAddress Implicit octet string 4 in octet form network byte order ESNMP_TYPE_DisplayString DisplayString textual convention ESNMP_TYPE_Opaque Implicit octet string Return Values Example ESNMP_MTHD_noError The routine completed successfully ESNMP_MTHD_genErr An error occurred include lt esnmp h gt include ip_tbl h lt for ipNetToMediaEntry_type definition VARBIND kvb method gt varbind OBJECT object method gt object ipNetToMediaEntry_type data assume buffer and structure member assignments occur here switch arg case I_atPhysAddress return o_octet vb object amp data gt ipNetToMediaPhysAddress eSNMP API Routines 5 33 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 fill the structure with zeros before using it obj A pointer to the OBJ ECT structure for the MIB variable associated with the OID in the VARBIND structure oid The value to be inserted into the VARBIND structur
51. also assign a name to each object to help with human interpretation 3 2 2 MIB Subtrees Understanding MIB subtrees is crucial to understanding the eSNMP API and how your subagent will work Note This manual assumes that you understand the OID naming structure used in SNMP If not refer to RFC 1902 Structure of Management Information for Version 2 of the Simple Network Management Protocol SNMP Version 2 The information in SNMP is structured hierarchically like an inverted tree Each node has a name and a number Each node can also be identified by an OID which is a concatenation of the subidentifiers nonnegative numbers These numbers are on the path from the root node down to that node in the tree In this hierarchy data is associated only with leaf nodes A leaf node represents a MIB variable that can have an instance and an associated value An OID must be at least two subidentifiers and at most 128 subidentifiers in length The subidentifier ranges are e Subidentifier 1 values range from 0 to 2 inclusive e Subidentifier 2 values range from 0 to 39 inclusive e The remaining subidentifier values can be any nonnegative number Figure 3 1 illustrates the SMI hierarchical tree arrangement as specified in RFCs 1155 and 1902 3 2 Creating a Subagent Using the eSNMP API Creating a Subagent Using the eSNMP API 3 2 The Structure of Management Information Figure 3 1 MIB Il in SMI Tree Structure internet 1
52. alue whose behalf the trap is being generated You can specify the name local which is the same as specifying 0 0 0 0 0 0 or 0 0 0 0 In these cases the address 0 0 0 0 is sent as the agent address in the SNMP Version 1 trap PDU If the v2c flag is specified this parameter is ignored For SNMP Version 1 specifies the generic trap identifier in the form of a number Must be one of the following values SNMP Version 1 Value Object 0 coldStart warmStart linkDown linkUp authenticationFailure egpNeighborLoss Doe W NH FF enterpriseSpecific For SNMP Version 2 when the v2c flag is specified this parameter must contain a valid OID or 0 as the value of snmpTrapOID For SNMP Version 1 specifies the enterprise specific trap number A numeric value greater than 0 must be present but is ignored if the v2c flag is present or if generic trap is a value other than 6 enterpriseSpecific Specifies the timestamp value associated with the generation of the trap message The timestamp value is the current time in units of TIMETICKS 1 100 of a second since the sending SNMP entity started A value of 0 causes snmp_trapsnd to send the time in hundredths of a second since the operating system was last booted Specifies a list of MIB variables to be included in the trap message For a list of supported values including a value for the Counter64 data type see Table 4 3 4 2 1 2 Trap Sender Flags Table 4 5 describes t
53. aq TCP IP Services for OpenVMS Management guide Troubleshooting eSNMP Problems 6 3 A AgentX protocol 1 2 API functionality 1 6 ASN 1 files 3 5 C C compiler 3 1 Chess example tree structure 3 4 clone_buf support routine 5 51 clone_oct support routine 5 54 clone_oid support routine 5 49 cmp_oct support routine 5 53 cmp_oid support routine 5 47 cmp_oid_prefix support routine 5 48 D Default timeout value 6 1 E Error logs 6 2 eSNMP description 1 1 esnmp_are_you_there interface routine 5 15 esnmp_capabilites interface routine 5 12 esnmp_cleanup support routine 5 65 esnmp_init interface routine 5 2 ESNMP_LOG support routine 5 59 esnmp_poll interface routine 5 14 esnmp_register2 interface routine 5 7 esnmp_register interface routine 5 3 esnmp_sysuptime interface routine 5 18 esnmp_term interface routine 5 17 esnmp_trap interface routine 5 16 esnmp_uncapabilities interface routine 5 13 esnmp_unregister2 interface routine 5 11 esnmp_unregister interface routine 5 6 Event logging 6 2 Extensibility 1 1 Index F free_oct support routine 5 55 free_oid support routine 5 50 free_varbind_data support routine 5 56 G _get method routine 5 20 Groups MIB 2 6 H Header files 3 7 Host Resources MIB 2 1 hrDeviceTable 2 4 hrDiskStorage 2 5 hrFSMountPoint 2 4 hrFSTable 2 4 hrProcessorFrwID 2 5 hrStorageType 2 5 objects implemented by TC
54. arameters Section 4 1 2 describes the flags 4 1 1 MIB Browser Parameters Table 4 1 describes the snmp_request parameters Table 4 1 snmp_request Command Parameters Parameter Function agent The host name or IP address in dot notation of the managed node to query If you specify 0 0 0 0 0 127 0 0 1 or localhost the server on the browser s host is queried continued on next page Using the SNMP Utilities 4 1 Using the SNMP Utilities 4 1 Using the MIB Browser Table 4 1 Cont snmp_request Command Parameters Parameter Function community The community string to be used in the query This parameter is case sensitive Typically agents are configured to permit read access to the community string public For accurate interpretation be sure to enclose the name in quotation marks Note that if you do not use quotation marks the name is changed to lowercase request type PDU type to send Can be one of the following SNMP requests Get Sends a Get Request PDU GetNext Sends a GetN ext Request PDU GetBulk Sends a GetBulk Request PDU SNMP Version 2 only Set Sends a Set Request PDU variable An object identifier OID in ASN 1 notation that is associated with an object in a MIB For example snmp_request hostl public getnext d 1 3 6 1 6 3 1 1 6 data type Data type of the value This parameter can be specified for Set requests The data types are described in Section 4 1 3 value Th
55. ard MIBs Both programs support the use of the UDP default and TCP transports However the standard TCP IP subagents and the Chess example use UDP only Therefore if you specify the tcp flag when you enter the snmp_traprcv command the program uses TCP to process traps only from the trap sender program or from a user application written to use TCP The following sections explain how to enter commands for both programs Because flags and data types are case sensitive you should always enter them in the case that is specified If a letter or value is specified as uppercase you must enclose it in quotation marks In general if you use uppercase letters where lowercase is specified the results are unpredictable For example flag v2c functions correctly but flag V2c does not because the flag character v must be lowercase 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 significant 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 specified hosts You use parameters and flags to specify the data fields in the trap PDU Traps are uniquely identified in the PDU e SNMP Version 1 is identi
56. aster agent s sysORTable Format void esnmp_uncapabilities OID agent_cap_id Arguments agent_cap_id A pointer to an object identifier that represents an authoritative agent capabilities identifier This value is used for the sysORID object in the sysORTable for the managed node Description This routine is called if a subagent alters its capabilities dynamically When a logical connection for a subagent is closed the master agent automatically removes the related entries in sysORTable eSNMP API Routines 5 13 eSNMP API Routines esnmp_poll esnmp_poll Processes a pending message that was sent by the master agent Format int esnmp_poll Description This routine is called after the select call has indicated data is ready on the eSNMP socket This socket was returned from the call to the esnmp_init routine If a received message indicates a problem an entry is made to the SNMP log file and an error status is returned If the received message is a request for SNMP data the object table is checked and the appropriate method routines are called as defined by the developer of the subagent Return Values ESNMP_LIB OK The esnmp_poll routine completed successfully ESNMP_LIB_BAD_REG The master agent failed in a previous registration attempt See the log file ESNMP_LIB DUPLICATE A duplicate subagent identifier has already been received by the master agent ESNMP_LIB_ NO_ The master agent
57. at has been automatically generated by the MIBCOMP command The method gt row gt save field is also private to the method routine Libesnmp does not use it 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 5 25 eSNMP API Routines set Routine ESNMP_ACT_UNDO For each conceptual row that was successfully committed the same method routine is called with method gt action equal to ESNMP_ACT_UNDO The ROW_CONTEXT structures that have not yet been called for the COMMIT phase are not called for the UNDO phase they are called for CLEANUP phase The method routine should attempt to restore conditions to what they were before it executed the COMMIT phase This is typically done using the data pointed to by the method gt row gt save field If successful return ESNMP_MTHD_noError otherwise return ESNMP_ MTHD_undoF ail 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 method gt action equal to ESNMP_ACT_CLEANUP
58. atus is returned for a get request Browsers respond differently to this message For example 2 4 MIBs Provided with TCP IP Services MIBs Provided with TCP IP Services 2 1 Overview of the Host Resources MIB TCPIP SNMP_REQUEST EXE responds with no output and returns directly to the DCL prompt After an NFS mount the following information is returned in response to a Get request The data items implemented for OpenVMS refer to RFC 1514 are hrFSIndex hrFSMountPoint is the local DNFS device name hrFSRemoteMountPoint is the remote file system hrFSType is implemented as e OID 1 3 6 1 2 1 25 3 9 1 for OpenVMS if the file system is not a UNIX style container file system e hrFSNFS OID 1 3 6 1 2 1 25 3 9 14 if the file system is a TCP IP Services container file system or a UNIX host hrFSAccess aS defined 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 00 00 01 01 00 00 00 00 anuary 1 0000 hrFSLastPartialBackupDate is unknown time This information is not available for OpenVMS systems Instead hexadecimal value 00 00 01 01 00 00 00 00 J anuary 1 0000 applies e hrProcessorFrwID OID prefix 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 133601421425 53 3 1 1 1
59. bject Identification Codes 0 000 eee 3 2 3 2 2 MIB SUBER CES ia aait sua ato ma aa d eaa aiiai aha dane aun a age dildo 3 2 3 3 Creating a MIB SourceFile 0 0 00 eee 3 5 3 3 1 Writing the ASN 1 Input File 2 2 ccs 3 5 3 3 2 Processing the Input File with the MIB Compiler 3 5 3 3 2 1 UNIX Utilities Supplied with TCP IP Services 3 7 3 3 2 2 Object Tables n e244 fee eee ihe beens Bees deed eee 3 7 3 3 2 3 The subtree TBL H Output File 0 0 3 7 3 3 2 4 The subtree TBL C Output Files eee eee ee 3 9 3 4 Including the Routines and Building the Subagent 3 11 3 5 Including Extension Subagents in the Startup and Shutdown PHOGEQUKES Tai anaa Ria ed Aneta ge ao a S Gee aad 3 12 4 Using the SNMP Utilities 4 1 4 1 1 4 1 2 4 1 3 4 1 4 4 2 4 2 1 4 2 1 1 4 2 1 2 4 2 1 3 4 2 2 4 2 2 1 4 2 2 2 4 2 2 3 Using the MIB Browser 0000 cc eee eee MIB Browser Parameter S aya asye anera rira YE ee MIB Browser Flags auauua aaa MIB Browser Data TypeS 0 0 cee ee Command Examples for snmp_request 002 eee eee Using the Trap Sender and Trap Receiver Programs 005 Entering Commands for the Trap Sender Program Trap Sender Parameters 0 000 c cece eee eee eens Trap Sender Flags 00 cece eect ttt ttt tes Trap Sender ExamplesS 0000 cece eee eee Entering Commands for
60. cility provided with TCP IP Services This facility uses a UNIX awk script which runs on OpenVMS as well as on appropriately configured UNIX systems For details about the facility see the MIB CONVERTER AWK file which is located in the SNMP subdirectory of TCPIP EXAMPLES Standard MY files are also provided for your convenience The custom MIB definition files have the default extension MY 3 3 2 Processing the Input File with the MIB Compiler Process your ASN 1 source files with the MIB compiler using the DCL command MIBCOMP Note If you are familiar with processing on UNIX systems you can use the UNIX utilities snmpi and mosy See Section 3 3 2 1 for more information The compilation process produces two template C programming modules that are used in building the executable subagent code When you run the compiler specify all the ASN 1 source files for a given subagent Whenever any of these source files are updated you must repeat the compilation process The syntax for the MIBCOMP command is as follows MIBCOMP MIB source file subtree PREFIX prefix name PRINT_TREE SNMPV2 Creating a Subagent Using the eSNMP API 3 5 Creating a Subagent Using the eSNMP API 3 3 Creating a MIB Source File The parameters and qualifiers for the MIBCOMP command are as follows Parameter or Qualifier Definition M1B source file subtree PREFIX prefix name PRINT_TREE SNMPV2 A comma separated
61. cture Master Agent Subagent 1 Subagent 2 Subagent n eSNMP API SNMP ASN 1 Library AgentX TCP IP V5 1 TCP IP Kernel OpenVMS VM 0704A Al The SNMP environment consists of the following elements The master agent a process that runs on the host and handles SNMP requests from clients over the standard SNMP well known port 161 One or more subagents each of which provides access to the MIB data specified in client requests 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 configuring 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 1 2 Overview Figure 1 2 illust
62. cture which is a pointer to an OCT structure New space is allocated and the buffer pointed to by the OCT structure is copied e ESNMP_TYPE_Objectid varbind gt valueoid and the varbind gt name fields This is an object identifier It is contained in the VARBIND structure as an OID structure that contains the number of elements and a pointer toa dynamically allocated array of unsigned integers one for each element The varbind gt name field is used to hold the object identifier and the instance information that identifies the MIB variable Use the OID2Instance function to extract the instance elements from an incoming OID on a request Use the instance2oid function to combine the instance elements with the MIB variable s base OID to set the VARBIND structure s name field when building a response Use the o_oid function to insert an object identifier 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 filled The incoming VARBIND structures on a Get GetNext and GetBulk will
63. e which includes all ipRouteEntry MIB variables is now the authoritative region of requests for ipRoutelfIndex Return Values SNMP_LIB OK The esnmp_register2 routine has completed successfully ESNMP_LIB_BAD_REG The esnmp_init routine has not been called the timeout parameter is invalid a registration slot is not available or this MIB subtree has already been queued for registration A message is also in the log file ESNMP_LIB_ LOST _ The subagent lost communication with the CONNECTION master agent 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 field eSNMP API Routines 5 9 eSNMP API Routines esnmp_register2 Example include lt esnmp h gt define RESPONSE_TIMEOUT 0 use the default time set in esnmp_init message define REGISTRATION_PRIORITY 10 priority at which the MIB subtree will register define RANGE_SUBID 7 the identifier position in oid gt elements just after mib 2 define RANGE_UPPER_BOUND 8 the identifier for egp under mib 2 int status 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 Sesnmp_reg_for_ip2egp 0 sizeof ESNMP_REG esnmp_reg_for_
64. e VARBIND structure as data len The length of the data in buffer pointed to by ptr The real type as defined in the object structure must be one of the following otherwise an error is returned ESNMP_TYPE_OCTET_ Octet string ASN 1 STRING ESNMP_TYPE_IpAddress Implicit octet string 4 in octet form network byte order ESNMP_TYPE_DisplayString DisplayString textual convention ESNMP_TYPE_NsapAddress Implicit octet string ESNMP_TYPE_Opaque Implicit octet string ESNMP_TYPE_OBJ ECT _ Object identifier ASN 1 in dot notation for IDENTIFIER example 1 3 4 6 3 Return Values ESNMP_MTHD_noError The routine completed successfully ESNMP_MTHD_genErr An error occurred eSNMP API Routines 5 35 eSNMP API Routines o_string Example include lt esnmp h gt include ip_tbl h lt for ipNetToMediaEntry_type definition VARBIND kvb method gt varbind OBJECT object method gt object ipNetToMediaEntry_type data assume buffer and structure member assignments occur here switch arg case I_atPhysAddress return o_string vb object data gt ipNetToMediaPhysAddress ptr data gt ipNetToMediaPhysAddress len 5 36 eSNMP API Routines eSNMP API Routines o_counter64 o_counter64 Format Arguments Example Loads a counter64 value into the VARBIND structure int o_counter64 VARBIND vb OBJECT obj uint64 value for Alpha uint64_vax value for VAX vb A pointer to the
65. e as data For more information about OID length and values see Chapter 3 The real type as defined in the object structure must be ESNMP_TYPE_OBJ ECT __ IDENTIFIER Return Values Example ESNMP_MTHD_noError The routine completed successfully ESNMP_MTHD_genErr An error occurred include lt esnmp h gt include ip_tbl h lt for ipNetToMediaEntry_type definition VARBIND vb method gt varbind OBJECT object method gt object ipNetToMediaEntry_type data assume buffer and structure member assignments occur here switch arg case I_atObjectID return o_oid vb object amp data gt ipNetToMediaObjectID 5 34 eSNMP API Routines eSNMP API Routines o_string o_ string Format Arguments Loads a string value into the VARBIND structure with the appropriate type This function does not allocate the VARBIND structure int o_string VARBIND vb OBJECT obj unsigned character ptr int len 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 fill the structure with zeros before using it obj A pointer to the OBJ ECT 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 th
66. e files that are available to help you develop MIBs and subagents Except where noted the files are located in the directory pointed to by TCPIP SNMP_EXAMPLES Overview 1 5 Overview 1 4 Writing an eSNMP Subagent Table 1 2 Files for Building a Subagent File Description ESNMP H Header file used to create a subagent Located in TCPIP ESNMP GAWK EXE Interpreter for MIB converter MIB CONVERTER AWK RFC1213 MY RFC1231 MY RFC1285 MY RFC1442 MY SNMP SMI MY SNMP TC MY V2 TC MY TCPIP BUILD_CHESS COM TCPIP CHESS_ SUBAGENT OPT C and H TCPIP CHESS_SUBAGENT EXE TCPIP ESNMP OLB TCPIP ESNMP_SHR EXE UCX ESNMP_SHR EXE TCPIP MIBCOMP E XE TCPIP MOSY EXE TCPIP SNMPI EXE A UNIX based awk shell script that takes a MIB definition in ASN 1 notation and converts it to an MY file MIB II definitions IEEE 802 5 Token Ring MIB definitions FDDI MIB definitions SNMP Version 2 Structure of Management Information SMI definitions SNMP Version 2 SMI definitions from RFC 1902 replaces RFC 1442 SNMP Version 2 SMI definitions from RFC 1903 replaces RFC 1443 SNMP Version 2 SMI definitions from RFC 1903 superset of those in SNMP TC MY Command file that builds the sample chess subagent Options file for use in building the sample chess subagent Source code for chess example Contains detailed documentation that explains how the code functions Functioning chess example image Object libra
67. e value to which to set the contents of the OID This parameter is used for set requests For Set requests you can specify more than one group of the following e variable name e data type e value For other requests you can specify more than one variable name except when you specify the 1 or t flag these flags are valid only with a GetNext or GetBulk request for which only one OID is permitted 4 1 2 MIB Browser Flags Flags are specified in UNIX format Because flags and data types are case sensitive you should always enter them in the case that is specified If a letter or value is specified as uppercase you must enclose it in quotation marks In general if you use uppercase letters where lowercase is specified the results are unpredictable For example the flag v2c functions correctly but the flag V2c does not because the flag character v must be lowercase If you do not specify a flag or if you specify an invalid flag a usage message is displayed You must place the flags after the request type parameter Table 4 2 describes the flags for the snmp_request command 4 2 Using the SNMP Utilities Using the SNMP Utilities 4 1 Using the MIB Browser Table 4 2 Flags for the snmp_request Command Flag Description d i max_ignores Specifies hexadecimal dump mode Before displaying a return value displays a hexadecimal dump of SNMP packets sent and received For example snmp_request ho
68. ed by this process The total amount of real system memory allocated to this process 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 write locked 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 qualified name of executable image The values and the associated status of each are e lindicates that the current process is running CUR e 2 indicates that the process is computable COM e 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 hrSWiInstalled hrSWInstalledTable SNMP set requests are not implemented for the following Host Resources MIB objects MIBs Provided with TCP IP Services 2 3 MIBs Provided with TCP IP Services 2 1 Overview of the Host Resources MIB hrFSLastFullBackupDate hrFSLastPartialBackupDate hrStorageSize hrSWRunStatus hrSystemDate hrSystemInitialLoadDevice hrSystemInitialLoadParameters Note
69. ed to recompile and relink with the following exceptions 1 8 Overview 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 backward compatible version of UCX ESNMP_SHR EXE in the SYS SHARE directory Do not delete this image 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 SYSSSHARE SESNMP_SHR EXE The creation dates of the files with the prefix TCPIP and UCX should be within a few seconds of each other and only one version of each file should exist Make sure b
70. ee with the highest priority over a range of object identifiers 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 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 5 3 eSNMP API Routines esnmp_register A subtree is identified by the base MIB name and the corresponding OID number of the node that is the parent of all MIB variables contained in the subtree For example The MIB II tcp subtree has an OID of 1 3 6 1 2 1 6 All elements subordinate to this have the same first seven digits and are included in the subtree s object table The subtree can also be a single MIB object a leaf node or even a specific instance 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 qualified longest subtree that still contains its instrumented MIB variables The master agent does not permit a
71. efines 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 text based configuration files This chapter provides an overview of the Compaq implementation of eSN MP Topics include e eSNMP master agent and subagent architecture Section 1 1 e The procedure for handling SNMP requests Section 1 2 e The components of the TCP IP Services software kit that implement SNMP Section 1 3 e The files useful in developing your own subagent Section 1 4 e The eSNMP API Section 1 5 e The management information base MIB compiler Section 1 6 e The impact of running SNMP Version 1 subagents against the SNMP Version 2 implementation provided with TCP IP Services Section 1 7 e Sources of additional information about implementing subagents Section 1 8 1 1 SNMP Architecture Figure 1 1 illustrates the SNMP architecture Overview 1 1 Overview 1 1 SNMP Architecture Figure 1 1 SNMP Archite
72. enerating 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 TCPIPSSNMP PREFIX ALL STANDARD VAX CHESS_METHOD C _ CHESS _MIB C CHESS_TBL C Creating a Subagent Using the eSNMP API 3 11 Creating a Subagent Using the eSNMP API 3 4 Including the Routines and Building the Subagent Depending on the version of the Compaq C compiler you are using you might see warnings that you can ignore Portions of these warnings are as follows CC I SIGNEDKNOWN In this declaration DEC C recognizes the ANSI keyword signed This differs from the VAX C behavior SCC I INTRINSICINT In this statement the return type for intrinsic strlen is being changed from size_t to int Link the object modules using a command and options in the following format derived from the chess example LINK SYSSINPUT OPTIONS CHESS_METHOD OBJ CHESS_MIB OBJ CHESS_TBL OBJ SYSSSHARE TCPIPSESNMP_SHR EXE SHARE To link with the eSNMP object library enter the following command LINK SYSSINPUT OPTIONS CHESS_METHOD OBJ CHESS_MIB OBJ CHESS_TBL OBJ TCPIPSSNMP TCPIP ESNMP OLB LIBRARY TCPIPSLIBRARY TCPIPSLIB OLB LIBRARY
73. ented 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 field and once with the ESNMP_REG_OPT_CLUSTER bit clear in the options field 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 field 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 field Requests for ip MIB variables within ipRouteEntry such as ipRoutelfIndex 1 3 6 1 2 1 4 21 1 2 are passed to the gated subagent Requests for other ip variables such as ipNet ToMedial fIndex 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 subtre
74. er MIB subtrees at any time after communication with the master agent is established 3 4 Creating a Subagent Using the eSNMP API Creating a Subagent Using the eSNMP API 3 2 The Structure of Management Information Normally it is the nonleaf nodes that are registered as a subtree with the master agent However leaf nodes or even specific instances can be registered as a subtree The master agent delivers requests to the subagent that has the MIB subtree with the longest prefix and the highest priority 3 3 Creating a MIB Source File Creating the MIB source file requires the following four step process 1 Write the ASN 1 input files as described in Section 3 3 1 2 Process the input files with the MIB compiler as described in Section 3 3 2 3 Compile and link the routines as described in Section 3 4 4 Include the subagent as described in Section 3 5 3 3 1 Writing the ASN 1 Input File After you have assigned names and OIDs to all of the objects in the MIB create an ASN 1 source file using ASCII statements Note Providing information about ASN 1 syntax and programming is beyond the scope of this guide For more information about ASN 1 programming refer to one or more of the documents on this subject provided by the International Organization for Standardization ISO Instead of creating ASN 1 files yourself you can create MY files from existing ASCII files for example from RFCs by using the MIB converter fa
75. er agent started include lt sys time h gt include lt esnmp h gt struct timeval timestamp gettimeofday amp timestamp NULL o_integer vb object esnmp_sysuptime amp timestamp 5 18 eSNMP API Routines 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 e _get respond to Get GetNext and GetBulk requests e _set respond to Set requests eSNMP API Routines 5 19 eSNMP API Routines get Routine get Routine The _get routine is a method routine for the specified MIB item which is typically a MIB group for example system in MIB II or a table entry for example ifEntry in MIB II Format int mib group_get METHOD method Arguments 5 20 method A pointer toa METHOD structure that contains the following fields Field Name Description action One of ESNMP_ACT_GET ESNMP_ACT_ GETNEXT or ESNMP_ACT_GETBULK serial num An integer number that is unique to this SNMP request
76. es 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 first value comes from the MIB II subagent TCPIP OS MIBS and the second comes from the Host Resources MIB subagent TCPIP HR_MIB 4 6 Using the SNMP Utilities 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 Ee Le Sebel 2s e259 Vl ele 1 3 6 1 2 1 2 2 1 2 1 LO IP Interface LOO OpenVMS Adapter lt none gt Loopback Port 1 3 6 1 2 1 25 1 1 0 6024942 0 d 16 44 9 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 Lier 6 lias le 1200 1 3y 61 04e1436 2 15 13 7 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 first three interfaces the values of ifDescr OIDs with the prefix 1 3 6 1 2 1 2 2 1 2 and ifType OIDs with the prefix 1 3 6 1 2 1 2 2 1 3 snmp_request marley dec com public getbulk n 2 m 3 S130 1e2 Td W 3 65152012 Sie 8 Oe Qe Ve Dy Del D
77. escribes 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 Manual Contents DIGITAL TCP IP Services for OpenVMS Concepts and Planning Compaq TCP IP Services for OpenVMS Release Notes Compaq TCP IP Services for OpenVMS Installation and Configuration DIGITAL TCP IP Services for OpenVMS User s Guide Compaq TCP IP Services for OpenVMS M anagament Compaq TCP IP Services for OpenVMS Management Command Reference Compaq TCP IP Services for OpenVMS Management Commands Quick Reference Card Compaq TCP IP Services for OpenVMS UNIX Commands Quick Reference Card DIGITAL TCP IP Services for OpenVMS ONC RPC Programming viii This manual provides conceptual information about networking and the TCP IP protocol including a description of the Compaq implementation of the Berkeley Internet Name Domain BIND service and the Network File System NFS It outlines general planning issues to consider before configuring your system to use the TCP IP Services software This manual also describes the manuals in the documentation set provides a glossary of terms and acronyms for the TCP IP Services software product and documents how to contact the InterNIC Registration Service to register domains and access Request for Comments RF Cs This text file describes new features and chan
78. fied by a combination of parameters e SNMP Version 2 is identified by the value of snmpTrapOID To run the trap sender program do the following 1 Define a foreign command for the program snmp_trapsnd SYSSSYSTEM TCPIPSSNMP_TRAPSND Alternatively you can run the SYS MANAGER TCPIP DEFINE _ COMMANDS COM procedure to define all the foreign commands available with TCP IP Services 2 Enter a command using the following format snmp_trapsnd enterprise agent generic trap specific trap timeticks v version c community d h host p port tcp variable_name data type value 4 2 1 1 Trap Sender Parameters Table 4 4 describes the snmp_trapsnd parameters Each parameter is required but you can specify zero as appropriate Using the SNMP Utilities 4 9 Using the SNMP Utilities 4 2 Using the Trap Sender and Trap Receiver Programs Table 4 4 Parameters for the snmp_trapsnd Command Parameter Description enterprise For SNMP Version 1 specifies the enterprise object identifier OID on whose behalf the trap is being sent For example 1 3 6 1 4 1 1 If you specify O or 0 0 the null OID 0 0 is sent Make sure that any OID you specify conforms to the OID rules For SNMP Version 2 when specified with the v2c flag represents the value of snmpTrapOID 0 agent For SNMP Version 1 traps Specifies the host name or IP address of the entity on generic trap specific trap timeticks variable_name data type v
79. field it then frees the vb gt value data using either the free_oct or the free_oid routine Example include lt esnmp h gt VARBIND vb vb VARBIND malloc sizeof VARBIND clone_oid amp vb gt name oid clone_oct amp vb gt value oct data some processing that uses vb occurs here free_varbind_data vb free vb 5 56 eSNMP API Routines eSNMP API Routines set_debug_level set_debug_level Format Arguments Description Example Sets the logging level which dictates what log messages are generated The program or module calls the routine during program initialization in response to run time options void set_debug_level int stat unsigned integer null stat The logging level The following values can be set individually or in combination Level Meaning ERROR Used when a bad error occurred requires a restart WARNING Used when a packet cannot be handled also implies ERROR This is the default TRACE Used when tracing all packets also implies ERROR and WARNING null This parameter is not used by OpenVMS It is supplied for compatibility with UNIX 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_LO
80. first nonmatching element is larger It is considered smaller if the first nonmatching element is less Return Values 1 The OID is less than the prefix 0 The OID is in prefix 1 The OID is greater than the prefix Example include lt esnmp h gt OID q OBJECT object if cmp_oid_prefix q amp object gt oid 0 printf matches prefix n 5 48 eSNMP API Routines eSNMP API Routines clone_oid clone_oid Format Arguments Description Makes a copy of the OID This routine does not allocate an OID structure oid clone_oid oid new oid oid 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 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 Null An error or the pointer to the OID is returned include lt esnmp h gt OID oidl OID oid2 assume oidl gets assig
81. for OpenVMS Alpha and OpenVMS VAX systems A layered software product TCP IP Services provides a comprehensive suite of functions and applications that support industry standard protocols for heterogeneous network communications and resource sharing This manual describes the features of the Simple Network Managment Protocol SNMP provided with TCP IP Services It also describes the extensible SNMP eSNMP application programming interface API and development environment See the Compaq TCP IP Services for OpenVMS Installation and Configuration manual for information about installing configuring 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 e Chapter 1 describes the implementation of eSNMP provided with Compaq TCP IP Services for OpenVMS e Chapter 2 describes the groups and objects implemented with the Host Resources MIB and MIB II that are provided with the eSNMP software e Chapter 3 describes how to use the eSNMP API to create a MIB subagent to manage entities or applications e Chapter 4 describes the trap sender trap receiver and MIB browser utilities provided with TCP IP Services e Chapter 5 provides reference information about the eSNMP API routines e Chapter 6 d
82. ges to the software including installation upgrade configuration and compatibility information These notes also describe new and existing software problems and restrictions and software and documentation corrections Print this text file at the beginning of the installation procedure and read it before you install TCP IP Services This manual explains how to install and configure the TCP IP Services layered application product This manual describes how to use the applications available with TCP IP Services such as remote file operations email TELNET TN3270 and network printing This manual explains how to use these services to communicate with systems on private internets or on the worldwide Internet This manual describes how to configure and manage the TCP IP Services product Use this manual with the Compaq TCP IP Services for OpenVMS Managenent Command Reference manual 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 This reference card contains inforomation about commonly performed network management tasks and their corresponding TCP IP management and Compaq Tru64 UNIX command formats This manual presents an overview of high level programming using open network computing remote procedure calls ONC RPC Th
83. he snmp_trapsnd flags Table 4 5 Flags for the snmp_trapsnd Command Flag Description c community d Specifies a community string to be used when sending the trap The default is public Displays a hexadecimal dump of the encoded packet continued on next page 4 10 Using the SNMP Utilities Using the SNMP Utilities 4 2 Using the Trap Sender and Trap Receiver Programs Table 4 5 Cont Flags for the snmp_trapsnd Command Flag Description h host Specifies the host name or IP address in ASN 1 dot notation format of the destination host to receive the trap message The default is localhost 127 0 0 1 p port Specifies a port number on the destination host where the message is to be sent The default is UDP 162 tcp Specifies that the TCP transport be used instead of the default U DP transport If a connection cannot be established the program displays the warning connect connection refused v version Specifies the SNMP version to use for sending the PDU The valid versions are 2c or 1 default You can specify the flag and value without including a space for example v2c and v1 4 2 1 3 Trap Sender Examples In the following snmp_trapsnd command examples The first line is the snmp_trapsnd command The remainder is the display received when running the trap receiver program snmp_traprev without flags included The following example generates a trap that originated on the localhost
84. her privileged port number you must run the program from a privileged account To run the trap receiver program do the following 1 Define a foreign command for the program snmp_traprcv S SYSSSYSTEM TCPIPSSNMP_TRAPRCV Alternatively you can run SYS MANAGER TCPIP DEFINE _ COM MANDS COM to define all the foreign commands available with TCP IP Services 2 Enter a command using the following format snmp_traprcv d tcp p port 4 2 2 1 Trap Receiver Flags Table 4 6 describes the snmp_traprcv flags Table 4 6 snmp_traprcv Command Flags Flag Description d Displays a hexadecimal and formatted dump of the received packet p port Specifies the port number on the local host on which to listen for trap messages The default is 162 tcp Listens on the TCP port instead of the UDP default port Reads only a single PDU on an established connection which is similar to the behavior using UDP 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 SNMP TRAP PROTOCOL UDP USER_NAME TCPIPSSNMP PROCESS_NAME TCPIPSSNMP TRAP FILE TCPIPSSYSTEM TCPIPSSNMP TRAP COM 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 qualifier or you use PROTOCOL TCP the service uses the TCP transport In this case
85. ific trap code Set this argument value to 0 zero for SNMP v2 traps enterprise An enterprise OID string in dot notation Set to the object identifier defined by the NOTIFICATION TYPE macro in the defining MIB specification This value is passed as the value of SnmpTrapOl D O in the SNMPv2 Trap PDU vb A VARBIND list of data a null pointer indicates no data 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 configuration 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_LIB OK The routine has completed successfully ESNMP_LIB_ LOST Could not send the trap message to master agent CONNECTION ESNMP_LIB_NOTOK Something failed and the message could not be generated 5 16 eSNMP API Routines eSNMP API Routines esnmp_term esnmp_term Sends a close message to the master agent and shuts down the subagent F
86. ined in the ESNMP H header file All Set requests to the method routine that refer to the same group and that have the same instance number will be presented with the same row structure The method routines can accumulate information in the row structures during Set requests for use during the commit and undo phases The accumulated data can be released by the method routines during the cleanup phase The ROW_CONTEXT structure contains the following fields instance An address of an array containing the instance OID for this conceptual row The libesnmp routine builds this array by subtracting the object OID from the requested variable binding OID instance len The size of the method gt row gt instance field context A pointer to be used privately by the method routine to reference data needed for processing this request save A pointer to be used privately by the method routine to reference data needed for undoing this request state An integer to be used privately by the method routine for holding any state information it requires The libesnmp routines call whatever routine is specified for Set operations in the object table identified 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 5 23 eSNMP API R
87. ip2egp subtree amp ip_subtree esnmp_reg_for_ip2egp priority REGISTRATION_PRIORITY esnmp_reg_for_ip2egp timeout RESPONSE_TIMEOUT esnmp_reg_for_ip2egp range_subid RANGE_SUBID esnmp_reg_for_ip2egp range_upper_bound RANGE_UPPER_BOUND status esnmp_register2 amp esnmp_reg_for_ip2egp if status ESNMP_LIB_OK printf Could not queue the ipRouteEntry n printf subtree for registration n 5 10 eSNMP API Routines 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 ESNMP_LIB OK The routine completed successfully ESNMP_LIB_BAD_REG The MIB subtree was not registered ESNMP_LIB_LOST_ The request to unregister the MIB subtree could CONNECTION not be sent You should restart the protocol Example include lt esnmp h gt int status extern ESNMP_REG esnmp_reg_for_ip2egp status esnm
88. is manual also describes the RPC programming interface and how to use the RPCGEN protocol compiler to create applications continued on next page Table 1 Cont TCP IP Services Documentation Manual Contents 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 Pv6 environment the roles of systems in this environment the types and function of the different IPv6 addresses and how to configure 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 fi
89. ld specifies the OID subidentifier modified by the range_upper_bound field eSNMP API Routines 5 7 eSNMP API Routines esnmp_register2 Field Name Description range_upper_bound An integer value that with a nonzero range _subid field specifies a range instead of one of the MIB subtree s OID subidentifiers The range upper_bound field provides the upper bound of the range and the range _subid field provides the lower bound of the range which is the MIB subtree s OID subidentifier options An integer value that when set to ESNMP_REG_OPT_CLUSTER indicates that the registration is valid clusterwide When the value is set to zero it indicates that the registration is valid for the local node state One of the following integer values that provides the caller with asynchronous updates of the state of registration of this MIB subtree After the return of the esnmp_poll routine the caller can inspect this parameter ESNMP_REG_ STATE _ The registration is PENDING currently held locally while waiting for connection to the master agent ESNMP_REG_STATE_SENT The registration was sent to the master agent ESNMP_REG_STATE_DONE The registration was successfully acknowledged by the master agent ESNMP_REG STATE _ The registration was REGDUP rejected by the master agent because it was a duplicate ESNMP_REG_ STATE _ The master agent does REGNOCLU not support cluster registrations ESNMP_REG_STATE_RE J The master age
90. lection has not been reached You must manually increment the input OID to skip the error and continue with the query continued on next page Using the SNMP Utilities 4 3 Using the SNMP Utilities 4 1 Using the MIB Browser Table 4 2 Cont Flags for the snmp_request Command Flag Description I m max_repetitions n non_repeaters p port r max_retries 4 4 Using the SNMP Utilities Specifies loop mode Note that this flag is the letter I not the number 1 Valid only if request type is GetNext or GetBulk where flag n is set to 0 and flag m is set to a number greater than 0 Causes the master agent to traverse all the MIBs registered with the master agent starting at the first OID after the one specified in the command Note that you can specify only one variable name OID Responses are received one at a time and for each one the OID returned by the master agent is used in a subsequent request Corresponds to the behavior of standard mibwalk programs The MIB browser reads and displays responses and issues requests until the master agent has no more data times out or you press Ctrl Y or Ctrl C If specified with the Get Bulk request the n and m flags and associated values are ignored and the behavior is identical to that of GetNext When the last OID handled by the master agent is reached you receive a response similar to the following for a query on OID 1 3 6 1 6 3 1 1 6 1 using SNMP Ver
91. list of MIB definition files The standard extension is MY but you can specify any valid OpenVMS file name You must specify the full file name The text name for the root of your MIB definitions This parameter must be enclosed in quotation marks This name is used in generating names for template C modules and also for the names of the files themselves subtree tbl c and subtree tbl h The MIB compiler attaches the prefix name string to the beginning of all generated names Displays the entire MIB subtree Specifies the use of SNMP Version 2 parsing rules The following is an example of processing the chess example files using the PRINT_TREE qualifier MIBCOMP RFC1442 MY CHESS_MIB MY chess PRINT_TREE Processing RFC1442 MY Processing CHESS_MIB MY Dump of objects in lexical order This file created by program snmpi ccitt iso internet directory mgmt experimental private enterprises dec ema sysobjectids decosf chess chessProduct ID read only chessMaxGames read only chessNumGames read only Object ID INTEGER INTEGER gameTable gameEntry indexes gameIndex game Index fan H gameDescr p 0 1 1 3 6 1 15 3 0 lal 1 3 6 1 2 1 3 6 1 3 1 3 6 1 4 1 3 6 1 4 1 1 3 6 1 4 1 36 1 3 6 1 4 1 36 2 1 36 184 1 3652 15 1 3 6 1 4 1 36 2 15 2 1 3 6 1 4 1 36 2 15 2 99 1 3 6 1 4 1 36 2 15 2 99 1 35 6 L645 3625 18 2 599 4 VT TEGER read write 1 3 6 1 4 1 36 2 15 2 99 4 1 2 Di
92. n octet string Return Values ESNMP_MTHD_noError The routine completed successfully ESNMP_MTHD_genErr An error has occurred eSNMP API Routines 5 31 eSNMP API Routines o_integer Example include lt esnmp h gt include ip_tbl h lt for ipNetToMediaEntry_type definition VARBIND kvb method gt varbind OBJECT object method gt object ipNetToMediaEntry_type data assume buffer and structure member assignments occur here switch arg case I_atIfIndex return o_integer vb object data gt ipNetToMedialfIndex 5 32 eSNMP API Routines eSNMP API Routines o_octet o_octet Format Arguments Loads an octet value into the VARBIND structure with the appropriate type This function does not allocate the VARBIND structure int o_octet VARBIND vb OBJECT obj unsigned long value vb A pointer to the VARBIND structure that is supposed to receive the data If the original value in the vb field is not null this routine attempts to free it So if you dynamically allocate memory or issue the malloc command to allocate your own VARBIND structure fill the structure with zeros before using it obj A pointer to the OBJ ECT 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 defined in the object structure must be one of the following otherwise an error is returned ESNMP_TYPE
93. nVMS VAX systems you must specify the value of the 1 data type as a 16 digit hexadecimal value For example snmp_trapsnd 0 0 mynode 6 33 100 h mynode v2c _ 1 3 6 1 2 1 1 4 0 I 0x1234567890ABCDEF Note that alphabetic characters are not case sensitive when used with the 1 data type 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 e The valid host name is marley dec com e The public community is type Read address 0 0 0 0 e The address_list community is type Read and Write with write access for the host on which the snmp_request program is running e The location has been specified as shown in the following command TCPIP gt SET CONFIGURATION SNMP _TCPIP gt LOCATION FIRST Falcon Building SECOND Los Angeles CA e 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 Servic
94. nce of the storage described by this entry The size of the data objects allocated from this pool in bytes The size of storage in this entry in hrStorageAllocationU nits The allocated amount of storage in this entry in hrStorageAllocationU nits A unique value for each host or device constant between agent reinitialization An indication of the type of device Some of these devices have corresponding entries in other tables A text description of the device including manufacturer and version number service optional The current operational state of the device The number of errors detected on the device The recommended initial value is zero The product ID of the firmware associated with the processor 2 2 MIBs Provided with TCP IP Services 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 identifier format a numeric repre
95. nclude lt esnmp h gt OCT octetl OCT octet2 assume octetl gets assigned a value memset amp octet2 0 sizeof OCT if clone_oct amp octet2 amp octet1 NULL DPRINTF WARNING It did not work n 5 54 eSNMP API Routines 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 field of the oct structure to zero Example include lt esnmp h gt OCT octet assume octet was assigned a value perhaps with mem2oct and we are now finished with it free_oct amp octet eSNMP API Routines 5 55 eSNMP API Routines free_varbind_data free_varbind_data Frees the dynamically allocated fields in the VARBIND structure However this routine does not deallocate the VARBIND structure itself it deallocates the name and data buffers to which the VARBIND structure points Format void free_varbind_data varbind vb Description This routine performs a free_oid vb gt name operation If indicated by the vb gt type
96. 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 Internet openvmsdoc compaq com Mail Compaq Computer Corporation OSSG Documentation Group ZK 03 4 U 08 110 Spit Brook Rd Nashua NH 03062 2698 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 800 282 6672 Conventions The name TCP IP Services means both e Compaq TCP IP Services for OpenVMS Alpha e Compaq TCP IP Services for OpenVMS VAX The name UNIX refers to the Compaq Tru64 UNIX operating system The following conventions are used in this manual In addition please note that all IP addresses are fictitious Ctrl x PF1x Return bold text italic text UPPERCASE TEXT A sequence such as Ctrl x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button A sequence such as PF 1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button In examples a key name enclosed in a box indicates that you press a key on the keyboa
97. ndude the new symbols Incdude an INSTALL DELETE command for images installed in TCPIP EXTENSION_MIB_ STARTUP COM Remove extra example lines and adjust the GOTO statement Creating a Subagent Using the eSNMP API 3 13 4 Using the SNMP Utilities TCP IP Services includes the following programs which are useful for testing applications and for analyzing SNMP problems e TCPIP SNMP_REQUEST MIB browser Section 4 1 e TCPIP SNMP_TRPSND trap sender Section 4 2 e TCPIP SNMP_TRPRCYV trap receiver Section 4 2 These programs can be invoked by commands that are defined by the SYS STARTUP TCPIP DEFINE_COMMANDS COM command procedure This chapter describes how to use the supplied SNMP utilities 4 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 Define a foreign command for the program snmp_request S SYSSSYSTEM TCPIPSSNMP_REQUEST Alternatively you can run the SYS MANAGER TCPIP DEFINE _ COMMANDS COM procedure to define 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 data type value Section 4 1 1 describes the p
98. ned a value memset amp 0id2 0 sizeof OID if clone_oid amp 0id2 amp oid1 NULL DPRINTF WARNING It did not work n eSNMP API Routines 5 49 eSNMP API Routines free_oid free_oid Frees the OID structure s buffer This routine does not deallocate the OID structure itself it deallocates the elements buffer attached to the structure Format void free_oid oid oid Description This routine frees the buffer pointed to by the OID gt denents field and zeros the field and the NELEM structure Example include lt esnmp h gt OID oid assume oid was assigned a value perhaps with clone_oid and we are now finished with it free_oid amp oid 5 50 eSNMP API Routines eSNMP API Routines clone_buf clone_buf Duplicates a buffer in a dynamically allocated space Format char clone_buf char str int len Arguments str A pointer to the buffer to be duplicated len The number of bytes to be copied Description One extra byte is always allocated at the end and is filled with zeros If the length is less than zero the duplicate buffer length is set to zero A buffer pointer is always returned unless there is a malloc error Return Values Null A malloc error Otherwise the pointer to the allocated buffer that contains a copy of the original buffer is returned Example include lt esnmp h gt char str something nice char copy copy clone_buf str strlen
99. nstance incoming object instance 6 if instLength 6 return ESNMP_MTHD_noSuchInstance The N will be in instance 0 and the IP address will be in instance 2 instance 3 instance 4 and instance 5 eSNMP API Routines 5 43 eSNMP API Routines inst2ip inst2ip Returns an IP address derived from an OID instance Format int inst2ip unsigned int instance int length unsigned int ioadar 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 overflow In this case the value is set to 0 and the next most significant 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 significant element is first exact Can either be TRUE or FAL
100. nt rejected the registration for other reasons reserved This field is reserved for exclusive use by the eSNMP library The caller should not modify it 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 5 8 eSNMP API Routines eSNMP API Routines esnmp_register2 When restarting the eSNMP protocol by calling esnmp_init all MIB subtree registrations are cleared All MIB subtrees must be reregistered A MIB subtree is identified by the base MIB variable name and its corresponding OID This tuple represents the parent of all MIB variables that are contained in the MIB subtree for example the MIB II tcp subtree has an OID of 1 3 6 1 2 1 6 All elements subordinate to this those that have the same first 7 identifiers are included in the subtree s object table A MIB subtree can also be a single MIB object a leaf node or even a specific 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 qualified longest MIB subtree that still contains its instrum
101. ollowing types of application programming interface API routines in the eSNMP developer s kit e Interface routines Section 5 1 e Method routines Section 5 2 e Support routines Section 5 3 5 1 Interface Routines The interface routines are for developers writing the portion of the application programming interface API that handles the connection between the agent and the subagent The interface routines are listed Table 5 1 and described in the following pages Table 5 1 Interface Routines Routine Function esnmp_init Initializes the subagent and initiates communication with the master agent esnmp_register Requests local registration of a MIB subtree esnmp_unregister Cancels local registration of a MIB subtree esnmp_register2 Requests cluster registration of a MIB subtree esnmp_unregister2 Cancels duster registration of a MIB subtree esnmp_capabilities Adds a subagent s capabilities to the master agent s sysORTable esnmp_uncapabilities Removes a subagent s capabilities from the master agent s sysORTable esnmp_poll Processes a pending request from the master agent esnmp_are_you_there Requests a report from the master agent to indicate it is up and running esnmp_trap Sends a trap message to the master agent esnmp_term Sends a close message to the master agent esnmp_sysuptime Converts UNIX system time into a value with the same time base as sysUpTime eSNMP API Routines 5 1
102. ongest prefix and the highest priority The master agent sends a message to the subagent that registered subtree_1 The subagent consults its list of registered subtrees and locates subtree_l It searches the object table of subtree_1 and locates the following e mib_var for Get and Set routines e The first object lexicographically after mib_var for Next or Bulk routines 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 subt ree_1 until either a method routine returns successfully or the table is exhausted In either case a response is returned 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 3 10 Creating a Subagent Using the eSNMP API Creating a Subagent Using the eSNMP API 3 3 Creating a MIB Source File 3 Initialized Subtree Structure Section The third section of the subtree TBL C file is the SUBTREE structure itself A pointer to this structure is passed to the eSNMP library routine esnmp_register to register the subtree It is through this pointer that the library routines find the object
103. ons for each MIB variable in the subtree of the form define I_mib variable nnn These values are unique for each MIB variable in a subtree and are the index into the object table for this MIB variable These values are also generally used to differentiate between variables that are implemented in the same method routine so they can be used in a switch operation 3 Enumeration Definitions Section The third section of the subtree TBL H file contains enumeration definitions for those integer MIB variables that are defined with enumerated values as follows define D_mib variable_enumeration name value These definitions are useful because they describe the value that enumerated integer MIB variables may take on For example enumerations for gameEntry group define D_gameStatus_complete define D_gameStatus_underway define D_gameStatus_delete Wh e 4 MIB Group Data Structure Definitions Section The fourth section of the subtree TBL H file contains data structure definitions of the following form typedef structxxx type mib variable char mib variable_mark mib group_type The MIB compiler generates one of these data structures for each MIB group in the subtree Each structure definition contains a field representing each MIB variable in the group In addition to the MIB variable fields the structure includes a 1 byte mib variable mark field for each variable You can use these for maintaining status of a MIB
104. ormat void esnmp_term void Description Subagents must call this routine when terminating so that the master agent can update its MIB registry quickly and so that resources used by eSNMP on behalf of the subagent can be released Return Values ESNMP_LIB_OK The esnmp_term routine always returns ESNMP_ LIB_OK even if the packet could not be sent eSNMP API Routines 5 17 eSNMP API Routines esnmp_sysuptime esnmp_sysuptime Format Argument Description Converts UNIX system time obtained from gett imeofday into a value with the same time base as sysUpTime unsigned int esnmp_sysuptime struct timeval timestamp timestamp A pointer to struct timeval which contains a value obtained from the gettimeofday system call The structure is defined in include sys time h A null pointer means return the current sysUpTime 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 Example 0 An error occurred because a gettimeofday function failed Otherwise timestamp contains the time in hundredths of a second since the mast
105. oth images include the file 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 files 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 definitions for the routines in
106. ould be construed as constituting an additional warranty ZK6530 This document is available on CD ROM This document was prepared using DECdocument Version 3 3 1b Contents PrefaCe sec oh adage ee Bea he APS Bain ok Saint bs GaP eae ols tient vii 1 Overview 1 1 SNMP Architecture cae ete eee ake es eae eee 1 1 1 2 Request Handling 0 00 cece eee 1 2 1 3 TCP IP Services Components for SNMP 0000 c eee eee ees 1 4 1 4 Writing an eSNMP Subagent 0 0000 ee 1 5 1 5 The eSNMP APL 2 teen eee 1 6 1 5 1 The SNMP Utilities eenen aai aa e a a aaa ee 1 7 1 6 TheM B Compiler irnia ene a a a a wo ee aes we ee 1 7 1 7 SNMP VESINS la a a prre tes a aa aea td dnt d ST E a nee dees a ak 1 8 1 7 1 Using Existing SNMP Version 1 MIB Modules 1 8 1 8 For More Information 0 000 cece ees 1 9 2 MIBs Provided with TCP IP Services 2 1 Overview of the Host Resources MIB 2 2 2 0 00000 eee 2 1 2 1 1 Defining Host Resources MIB Implemented Objects 2 1 2 1 2 Restrictions to Host Resources MIB 0 00 es 2 3 2 2 Overview of MIB I 2 1 ee 2 5 2 2 1 MIB II Implemented Groups 0 000 eee 2 6 2 2 2 Restrictions to MIB II Implementation 005 2 6 3 Creating a Subagent Using the eSNMP API 3 1 Creating a MIB Specification 0 000000 eee 3 1 3 2 The Structure of Management Information 000e ee eee 3 1 3 2 1 Assigning O
107. oup e The VARBIND structures have the same instance OI Ds 2 Each ROW_CONTEXT structure is loaded with the instance information for that conceptual row The ROW_CONTEXT structure context and save fields are set to NULL and the state field 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 method gt action equal to ESNMP_ACT_COMMIT 5 24 eSNMP API Routines eSNMP API Routines set Routine If any row reports failure all rows that were successfully committed are told to undo the phase This is accomplished by calling a single method routine for each row the same one that was called for the commit phase with a method gt action equal to ESNMP_ACT_UNDO Each row is released The same single method routine for each row is called with a method gt action equal to ESNMP_ACT_ CLEANUP This occurs for every row regardless of the results of previous processing 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 method gt row
108. outines set Routine Return Values ESNMP_MTHD_noError ESNMP_MTHD_notWritable ESNMP_MTHD _wrongType ESNMP_MTHD_ wrongLength ESNMP_MTHD_ wrongE ncoding ESNMP_MTHD_wrongValue ESNMP_MTHD_noCreation ESNMP_MTHD_ inconsistentN ame ESNMP_MTHD_ inconsistentValue ESNMP_MTHD_ resourceU navailable ESNMP_MTHD_genErr ESNMP_MTHD_ commitF ailed ESNMP_MTHD_undoF ailed The routine completed successfully The requested object cannot be set or was not implemented The data type for the requested value is the wrong type The requested value is the wrong length The requested value is represented incorrectly The requested value is out of range The requested instance can never be created The requested instance cannot currently be created The requested value is not consistent A failure due to some resource constraint A general processing error The commit phase failed The undo phase failed 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 toa 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 e The referenced objects are in the same MIB gr
109. p_unregister2 amp esnmp_reg_for_ip2egp switch status case ESNMP_LIB_OK rintf The esnmp_unregister2 reak o O case ESNMP_LIB_BAD_REG printf The MIB subtree was no break routine completed successfully n t 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 5 11 eSNMP API Routines esnmp_capabilities esnmp_capabilities Format Arguments Description 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 void esnmp_capabilities OID agent_cap_id char agent_cap_descr agent_cap_id A pointer to an object identifier that represents an authoritative agent capabilities identifier This value is used for the sysORID object in the sysORTable for the managed node agent_cap_descr A pointer to a null terminated character string describing agent_cap_id This value is used for the sysORDescr object in the sysORTable for the managed node This routine is called at any point after initializing eSNMP by a call to the esnmp_init routine 5 12 eSNMP API Routines eSNMP API Routines esnmp_uncapabilities esnmp_uncapabilities Removes a subagent s capabilities from the m
110. pport routine 5 33 o_oid support routine 5 34 o_string support routine 5 35 P __parse_progname support routine 5 64 __print_varbind support routine 5 60 Problems See Troubleshooting features Index 2 set method routine 5 22 set_debug_level support routine 5 57 __set_progname support routine 5 62 set_select_limit support routine 5 61 SMI 3 1 assigning ID codes 3 2 hierarchical tree structure 3 1 registering ID codes 3 2 snmpi utility 3 7 sprintoid support routine 5 39 str2oid support routine 5 38 Structure of management information See SMI Subagent error limit 6 1 Subagents 1 1 including in startup and shutdown 3 12 writing 1 5 3 5 Subtrees 3 2 registering 3 4 subtree TBL C output file 3 9 subtree TBL H output file 3 7 support routines routine reference 5 30 to 5 65 sysObjectID 2 6 sysORTable 2 7 5 12 sysORTable object 2 6 T Timeout default 6 1 Trap messages data types 4 5 receiving 4 13 sending and receiving 4 8 setting up a trap service 4 12 Trap receiver 4 1 command parameters 4 12 examples 4 13 running 4 12 Trap sender 4 1 command examples 4 11 command flags 4 10 Trap sender cont d command parameters 4 9 W running 4 9 Troubleshooting features 6 1 Writing subagents compiling 3 5 U creating source files 3 5 including in startup and shutdown 3 12 UNIX utilities 3 7 linking and building 3 11 object tables 3 7 using ASN
111. r agent Format esnmp_ cleanup Example include esnmp h int rc ESNMP_LIB OK rc esnmp_cleanup Return Values ESNMP_LIB_NOTOK There was no socket ESNMP_LIB_OK Success eSNMP API Routines 5 65 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 e How to modify the subagent error limit Section 6 1 e How to modify the default subagent timeout value Section 6 2 e Log files Section 6 3 For additional information about troubleshooting SNMP problems see the Compaq TCP IP Services for OpenVMS Tuning and Troubleshooting guide 6 1 Modifying the Subagent Error Limit In certain circumstances some subagent programs might enter a loop where a select call repeatedly returns a 1 error value Note that standard SNMP subagents and the Chess example provided in TCPIP EXAMPLES should not exhibit this behavior You can define the logical name TCPIP SNMP_SELECT_ERROR_LIMIT to modify the number of times a 1 error value can be returned from a select call The valid TCPIP SNMP_SELECT_ERROR_LIMIT values range from 1 to less than 232 1 default 100 When defining the error limit remember e Do not use commas when defining the number e f you defined the limit as 0 no limit is set e A defined value greater than or equal to 4000000000 triggers warning
112. rates communication between the master agent and subagents Figure 1 2 eSNMP Data Flow NMS1 Client a Network NMS2 A Client Trap client Legend Flow of trap notification a Flow of get set request Flow of are_you_there message Overview 1 2 Request Handling Host 1 Subagent 1 Subagent 2 Master Agent mi NE Master Agent gt Subagent 1 A VM 0705A Al 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 e MIB browser e Trap sender e Trap receiver These utilities are described in Chapter 4 Overview 1 3 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 e GetNext e GetBulk e set Note TCP IP Services does not support the standard SNMP Inform command The request specifies the object identifer OID of the data to be accessed For information about formatting get and set requests refer to Section 5 2 Request formats are specified in
113. rd In text a key name is not enclosed in a box In the HTML version of this document this convention appears as brackets rather than a box A horizontal ellipsis in examples indicates one of the following possibilities e Additional optional arguments in a statement have been omitted e The preceding item or items can be repeated one or more times e Additional parameters values or other information can be entered A vertical ellipsis indicates the omission of items from a code example or command format the items are omitted because they are not important to the topic being discussed In command format descriptions parentheses indicate that you must enclose choices in parentheses if you specify more than one In command format descriptions brackets indicate optional choices You can choose one or more items or no items Do not type the brackets on the command line However you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement In command format descriptions vertical bars separate choices within brackets or braces Within brackets the choices are optional within braces at least one choice is required Do not type the vertical bars on the command line In command format descriptions braces indicate required choices you must choose at least one of the items listed Do not type the braces on the command line This typeface
114. rom 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 first 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 null An error occurred Otherwise the pointer to the OID structure new is returned 5 40 eSNMP API Routines eSNMP API Routines instance2oid Example include lt esnmp h gt VARBIND vb lt filled in OBJECT object lt filled in unsigned int instance 6 Construct the outgoing OID in a GETNEXT TE Instance is N 1 A A A A where A s are IP address instance 0 data gt ipNetToMediaIfIndex instance 1 1 for i 0 i lt 4 itt instance it2 unsigned char amp data gt ipNetToMediaNetAddress i instance2oid amp vb gt name object instance 6 eSNMP API Routines 5 41 eSNMP API Routines oid2instance oid2instance Extracts the instance values from an OID structure and copies them to the specified array of integers The routine then returns the
115. ry file containing routines used to create a subagent Located in the directory pointed to by TCPIP SNMP Shareable image containing routines used to create a subagent Located in the directory pointed to by SYS SHARE Copy of TCPIP ESNMP_SHR EXE provided for compatibility with existing customer subagents linked under TCP IP Services V4 x Located in the directory pointed to by SYS SHARE Images associated with the MIB compiler Located in SYS SYSTEM 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 1 6 Overview 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 e Subagent initialization and termination e Registration e Polling of the master agent e Trap sending e UNIX system time conversion e 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 e Basic protocol data unit PDU handling e Authentication handling e Octet string handling e Variable binding VARBIND handling e Object identifier OID
116. s Only Dy i Dad MO DB O s be 2a le Aes 3 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 Le SeOrdcee lilies OS 13 Gel dcle AE S S A SOs 2 lee ele lel T 3 6 1 2 1 2 2 1 2 1 LO IP Interface LOO OpenVMS Adapter lt none gt Loopback Port V3 651s 21 252 15 3 S24 1 326 22 14262 1 1 3 3 1 3 6 1 2 1 2 2 1 2 3 WE IP Interface WEO OpenVMS Adapter EWAQ PCI bus Ethernet Adapter 153 26 1222 13630 6 Less Oeli 2d 2 2n lel A 4 1 3 6 1 2 1 2 2 1 2 4 WF IP Interface WFO OpenVMS Adapter FWAO DEFPA PCI bus FDDI Adapter Lev 6 01 Ae 2e2 S e HO15 The following example shows how to use the GetNext request with the 1 loop flag to retrieve all OIDs starting at the first instance after the OID input and finishing at the end of the MIB view Note that if an SNMP Version 2 agent is the server the results using getbulk are identical in general SNMP Version 1 agents do not support getbulk requests snmp_request marley dec com public getnext 1 1 3 6 1 2 1 1 1 0 13601525 112 0 186 1 4e1536 2 15 13 264 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 ar Gsde 2s kile lel 22 1 3 6 1 2 1 1 8 0 0 0d 0 0 0 136001 2nd 25 54 e232 560 L365 2d 255 fio 472 1 3 6 1 6 3 1 1 6 1 0 1296505215
117. sentation 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 identifier 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 2 1 Cont Host Resources MIB Objects Object Name RFC Description OpenVMS Description hrNetworkl fl ndex hrDiskStorageAccess hrDiskStorageM edia hrDiskStorageRemovable hrDiskStorageCapacity hrSWRunIndex hrSWRunPath hrSWRunStatus hrSWRunPerfCPU hrSWRunPerfMem The value of the iflndex that corresponds to this network device Indicates whether the storage device is read write or read only Indicates the storage device media type Indicates whether the disk can be removed from the drive The total size of this long term storage device A unique value for each software product running on the host A description of the location where this software was loaded The status of the software that is running The number in hundredths of a second of the total system s CPU resources consum
118. sion 1 1 3 6 1 6 3 1 1 6 1 0 693056825 no such name returned for variable 1 For a query using SNMP Version 2 the example response is 13 6146 315 T6415 os ior Oe lt prev gel lel ors These examples assume that 693056825 0 0 end of mib view e OID 1 3 6 1 6 3 1 1 6 1 0 is the last OID supported on the target host e The target host is running an SNMP Version 2 agent The statement end of mib view refers to OIDs for all MIBs registered with the master agent Specifies the number of repetitions requested for repeating variables Applies only to the GetBulk and GetNext requests Note that the resulting display can be confusing because the results for the repeater OIDs are interleaved That is the OI Ds are displayed in alternate progression for faster memory throughput If you specify Get Bulk without specifying both the m and n flags the results are unpredictable Specifies the number of variables for which no repetition is requested Applies only to the Get Bulk request If you specify Get Bulk without specifying both the m and n flags the results are unpredictable Specifies the port where the request is to be sent If not specified the request is sent to well known SNMP port 161 Specifies 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
119. splayString read write range gameNumMoves 0 to 255 C3001 41 S 2010 2 99 4 6153 INTEGER gameStatus read write 1 3 6 1 4 1 36 2 15 2 99 4 1 4 INTEGER 3 6 Creating a Subagent Using the eSNMP API read write Creating a Subagent Using the eSNMP API 3 3 Creating a MIB Source File enum complete enum underway 2 enum delete 3 moveTable 3 moveEntry 3 indexes gameIndex moveIndex movelIndex 1356 1 45 EE E E e Led INTEGER read write moveByWhite ES A T 1 3 6 A AS E DisplayString read write range 0 to 255 moveByBlack REA r E P ES L eF PE AA o TEES DisplayString read write range 0 to 255 moveStatus MEESE r VATS 622615 A e 213 4 INTEGER read write enum ok 1 enum delete 2 security 1 snmpV2 1 snmpDomains 1 snmpProxys Ro snmpModules 1 joint_iso_ccitt 2 11 objects written to chess_tbl c 11 objects written to chess_tbl h 3 3 2 1 UNIX Utilities Supplied with TCP IP Services For compatibility with UNIX the mosy and snmpi utilities are provided with TCP IP Services for generating the C language code that defines the object tables These UNIX utilities are supported on OpenVMS for compatibility with UNIX developed procedures For information about using these utilities refer to the Compaq Tru64 UNIX Network Programme s Guide 3 3 2 2 Object Tables The MIBCOMP command is used to generate the C language code that defines the object tables from the MIBs The object tables are defined in the emitted files
120. st2ip 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 e nisa single value integer e TheA A A A portion makes up one IP address e TheB 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 e Convert the least significant 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 e f the conversion of the B B B B portion generates a carry that is returns 1 you pass it to the next most significant part of the key e 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 e The most significant element n is a number therefore add the carry from the A A A A conversion to the number If the result overflows then the search key is not valid include lt esnmp h gt OID incoming OBJECT object int instLength unsigned int instance 9 unsigned int ip_addrA unsigned int ip_addrB int iface int carry amp method gt varbind gt name method gt object The instance is N A A A A B B B B instLength oid2instance incoming object instance 9 iface instLength lt 1 0 int instance 0 carry inst2ip amp ins
121. stl public getnext d v 2c 1 3 6 1 6 3 1 1 6 Sent 30290201 01040670 75626C69 63A11C02 OV ats public 047BE9C1 BDO020100 02010030 0E300C06 P ERSE 0 0 082B0601 06030101 060500 EEEE Received 30820033 02010104 06707562 6C6963A2 0 3 public 1 t 2602047B E9C1BD02 01000201 00308200 amp 0 16308200 12060A2B 06010603 01010601 0 Paare 00020478 D917FC wee Rie ars 1 3 6 1 6 3 1 1 6 1 0 2027493372 Specifies the number of times the MIB browser listens for a reply packet to a request if it receives an invalid packet caused by an invalid packet identifier version or SNMP version and command combination Specify a positive integer for the value max_ignores If you specify a negative value it will be converted to an unsigned positive integer If you specify 0 no retries are attempted 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 i flag when you perform a query with the 1 or t flags to automatically increment the input OID and continue querying a server after a general SNMP error has occurred as may happen with a faulty server In this case the query is terminated even though the end of the MIB se
122. str eSNMP API Routines 5 51 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 Null An error occurred Otherwise the pointer to the oct structure the first argument is returned Example include lt esnmp h gt char buffer int len OCT abc buffer and len are initialized to something memset amp abc 0 sizeof OCT if mem2oct amp abc buffer len NULL DPRINTF WARNING It did not work n 5 52 eSNMP API Routines eSNMP API Routines cmp_oct cmp_oct Compares two octet strings Format int cmp_oct oct octt oct oct2 Arguments oct1 Pointer to the first octet string oct2 Pointer to the second octet string Description The two octet strings are compared byte by byte to determine the length of the shortest octet string If all bytes are equal
123. 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 amp elems 0 objects I_moveStatus The following table describes the elements of the SUBTREE structure the definition of each element in the header file subtree TBL H and the element in the chess example Header File Description Representation Example The name of the subtree s base name chess element The ASCII string representation dots MT 365 R E 6 2 19 2599 of the subtree s OID This is what actually gets registered The OID structure for the base oid 11 amp elems 0 node of the subtree This points back to the array of integers A pointer to the array of objects object_oid objects in the object table It is indexed by the I_xxxx definitions found in the subtree TBL H file The index of the last object in the last I_moveStatus object_TBL file This is used to determine when the end of the table has been reached 4 Routines Section The final section of the subtree TBL C file 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 g
124. 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 ipNetToMedialfIndex 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 ipRoutelfIndex 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 SNMP_LIB_OK The esnmp_register routine has completed successfully ESNMP_LIB_BAD_REG The esnmp_init routine has not been called the timeout parameter is invalid or the subtree has already been queued for registration ESNMP_LIB_ LOST _ The subagent has lost communications with the CONN
125. 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 files if you did not edit them 3 3 2 3 The subtree_TBL H Output File The subtree TBL H file contains the following sections A declaration of the subtree structure Index definitions for each MIB variable in the subtree 1 2 3 Enumeration definitions for MIB variables with enumerated values 4 MIB group data structure definitions 5 Method routine function prototypes The following sections describe each section of the subtree TBL H file Creating a Subagent Using the eSNMP API 3 7 Creating a Subagent Using the eSNMP API 3 3 Creating a MIB Source File 1 Declaration Section The first section of the subtree TBL H file is a declaration of the subtree structure The subtree is automatically initialized by code in the subtree TBL C file A pointer to this structure is passed to the esnmp_register routine to register a subtree with the master agent All access to the object table for this subtree is through this pointer The declaration has the following form extern SUBTREE subtree_subtree 2 Index Definitions Section The second section of the subtree TBL H file contains index definiti
126. t SNMP Component Files File Location Function TCPIP SNMP_TRAPRCV E XE SYS SYSTEM Utility for receiving trap messages TCPIP ESNMP_SHR EXE SYS SHARE Image file containing eSNMP application programming interface API routines TCPIP SNMP_STARTUP COM SYS STARTUP Command procedure that installs master and subagent images and runs TCPIP SNMP_RUN COM TCPIP SNMP_SYSTARTUP COM SYS STARTUP Command procedure TCPIP SNMP_RUN COM TCPIP SNMP_SHUTDOWN COM TCPIP SNMP_SYSHUTDOWN COM TCPIP EXTENSION_MIB_STARTUP COM TCPIP EXTENSION_MIB_ SHUTDOWN COM TCPIP EXTENSION_MIB_RUN COM initiated by TCPIP SNMP_ STARTUP COM Provided for site specific customizations such as parameter settings Command procedure that starts the master agent and subagents TCPIP SYSTEM SYS STARTUP Command procedure that stops the master agent and subagents SYS STARTUP Command procedure initiated by TCPIP SNMP_ SHUTDOWN COM Provided for site specific customization such as parameter settings SY S SYSDEVICE TCPIP SN MP Command procedure invoked by TCPIP SNMP_ SYSTARTUP COM to start custom subagents SY S SYSDEVICE TCPIP SN MP Command procedure invoked by TCPIP SNMP_ SYSHUTDOWN COM to stop custom subagents SY S SYSDEVICE TCPIP SN MP Command procedure invoked by TCPIP SNMP_ SYSTARTUP COM when the service is enabled and starts detached processes to run subagents 1 4 Writing an eSNMP Subagent Table 1 2 lists th
127. t value Use the o_integer function to insert an unsigned longword 64 bits into the VARBIND structure eSNMP API Routines 5 29 eSNMP API Routines 5 3 Support Routines 5 3 Support Routines The support routines are provided as a convenience for developers writing method routines that handle specific MIB elements The following support routines are provided Routine Function o_integer Loads an integer value o_octet Loads an octet value o_oid Loads an OID value o_string Loads a string value o_counter64 Loads a Counter64 variable into the varbind str2oid Converts a string OID to dot notation sprintoid Converts an OID into a string instance2oid Creates a full OID for a value oid2instance inst2ip cmp_oid cmp_oid_prefix clone_oid free_oid clone_buf mem2oct cmp_oct clone_oct free_oct free_varbind_date set_debug_level is_debug_level ESNMP_LOG print_varbind set_select_limit __set_progname __restore_progname __parse_progname esnmp_cleanup Extracts an instance and loads an array Returns an IP address for an OID Compares two OIDs Compares an OID s prefix Makes a copy of an OID Frees a buffer Duplicates a buffer Converts a string to an oct structure Compares two octets Makes a copy of an oct structure Frees a buffer attached to an oct structure Frees the fields in the VARBIND structure Sets the logging level Tests the logging level Directs log messages
128. tance 1 instLength 1 amp ip_addrB FALSE 1 carry inst2ip amp instance 5 instLength 5 amp ip_addrA FALSE carry iface carry if iface gt carry a carry caused an overflow in the most significant element return ESNMP_MTHD_noSuchInstance 5 46 eSNMP API Routines eSNMP API Routines cmp_ oid cmp_oid Compares two OID structures Format int cmp_oid oid g oid p Description This routine does an element by element comparison from the most significant element element 0 to the least significant element If all other elements are equal the OID with the least number of elements is considered less Return Values 1 The OID gis less than OID p 0 The OID qisin OID p 1 The OID gis greater than OID p eSNMP API Routines 5 47 eSNMP API Routines cmp_oid_prefix cmp_oid_prefix Compares an OID against a prefix Format int cmp_oid_prefix oid q oid prefix Description A prefix could be the OID on an object in the object table The elements beyond the prefix are the instance information This routine does an element by element comparison from the most significant element element 0 to the least significant element If all elements of the prefix OID match exactly with corresponding elements of the OID q structure it is considered an even match if the OID g structure contains additional elements The OID g structure is considered greater than the prefix if the
129. the lengths are compared An octet with a null pointer is considered the same as a zero length octet Return Values 1 The string pointed to by the first oct is less than the second 0 The string pointed to by the first oct is equal to the second 1 The string pointed to by the first oct is greater than the second Example include lt esnmp h gt OCT abc efg abe and efg are initialized to something if cmp_oct amp abc amp efg gt 0 DPRINTF WARNING octet abc is larger than efg n eSNMP API Routines 5 53 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 Example Null An error occurred Otherwise the pointer to the oct structure the first argument is returned i
130. this object s unique index within the object table useful when one method routine services many objects The method gt object gt oid field is the OID defined for this object in the MIB The instance requested is derived by comparing this OID with the OID in the request found in the method gt varbind gt name field The oid2instance function is useful for this Description These types of routines call whatever routine is specified for Get operations in the object table identified 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_MTHD_noError ESNMP_MTHD_ noSuchObject ESNMP_MTHD_ noSuchI nstance ESNMP_MTHD_genErr The routine completed successfully The requested object cannot be returned or does not exist The requested instance of an object cannot be returned or does not exist A general processing error eSNMP API Routines 5 21 eSNMP API Routines set Routine set Routine The _set method routine for a specified MIB item which is typically a MIB group for example system in MIB II or a table entry for example ifEntry in MIB II Format int mib group_set METHOD method Arguments method A pointer toa METHOD structure that contains the following fields
131. to the MIB subtree to be handled The subtree structures are externally declared and initialized in the code emitted by the MIBCOMP command subtree TBL C and subtree TBL H where subtree is the name of the MIB subtree This code is taken directly from the MIB document All memory pointed to by this field 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 command The registration priority The entry with the largest number has the highest priority The range is 1 to 255 The subagent that has registered a MIB subtree with the highest priority over a range of object identifiers gets all requests for that range of OIDs MIB subtrees that are registered with the same priority are considered duplicates and the registration is rejected by the master agent The priority field is a mechanism for cooperating subagents to handle different configurations The number of seconds the master agent should wait for responses when requesting data in this MIB subtree This value must be between zero and 300 If the value is zero the default timeout 3 seconds is used You should use the default For information about modifying the default timeout value refer to Section 6 2 An integer value that when nonzero together with the range upper_bound field specifies a range instead of one of the MIB subtree s OID subidentifiers The range _subid fie
132. utine Load the response OID back into the method routine s VARBIND structure Set the method gt varbind field with the OID of the actual MIB variable instance you are returning This is usually accomplished by loading an array of integers with the instance OID you wish to return and calling the instance20ID support routine 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 method gt varbind field with the data to return e o_integer e o_string e o_octet e ooid 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 defined in the object table for the MIB variable and copies the converted data into the method gt varbind field See Section 5 2 3 for information on data value representation Return the correct status value as follows ESNMP_MTHD_noError The routine completed successfully or no errors were found ESNMP_MTHD_noSuchlinstance There is no such instance of the requested object ESNMP_MTHD_noSuchObject No such object exists ESNMP_MTHD_ genErr An error occurred and the routine did not complete successfully 5 2 3 Value Representation The values in a VARBIND structure for each data type are represented as follows Refer to the ESNM
133. when you enter a command to run the trap receiver program you must include the tcp flag 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 qualifier make sure you install the trap receiver program with privileges or run the program from an 4 12 Using the SNMP Utilities Using the SNMP Utilities 4 2 Using the Trap Sender and Trap Receiver Programs account that has SYSPRV privilege Note that the port number must be greater than zero 4 2 2 3 Trap Receiver Examples 1 The following example requests trap information on a system that does not have traps configured and does not have SYSPRV privilege or sufficient privilege snmp_traprcv No snmp trap service entry using default port 162 bind permission denied The example supplied from a nonprivileged account requests trap information in hexadecimal dump format on port 1026 snmp_traprev d p 1026 Message received from 127 0 0 1 3082002A 02010004 06707562 6C6963A4 D060547 81AD4D01 40040000 00000201 00020100 4304032D AED23082 0000 SNMPv1 Trap PDU 7075626C 6963 m community enterprise 0 0 agent address 0 0 0 0 rap type Cold Start 0 timeticks 53325522 ct Using the SNMP Utilities 4 13 9 eSNMP API Routines This chapter provides reference information about the f
134. work n 5 38 eSNMP API Routines eSNMP API Routines sprintoid sprintoid Converts an OID into a null terminated string Format char sprintoid char buffer oid oid Description An OID can have up to 128 elements A full sized OID can require a large buffer Return Values The return value points to its first argument Example include lt esnmp h gt define SOMETHING_BIG 1024 OID abc char buffer SOMETHING_BIG assume abc gets initialized with some value printf dots s n sprintoid buffer amp abc eSNMP API Routines 5 39 eSNMP API Routines instance2oid instance2oid Format Arguments Description 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 oid instance2oid oid new object obj unsigned int instance int len 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 first 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 The instance array may be created by oid2instance or constructed f
135. ws how to display the contents of packets that are sent and received Note that only the SNMP specific portion of the UDP packets is displayed snmp_request marley dec com public get d 1 3 6 1 2 1 1 4 0 Sent 3082002D 02010004 06707562 6C6963A0 Ova TAS public 2002047B E9C1BD02 01000201 00308200 Sasa E EET 0 10308200 0C06082B 06010201 01040005 Okeke re 00 Received 3082003B 02010004 06707562 6C6963A2 Orare tuus public 2E02047B E9C1BD02 01000201 00308200 wea dates are eye ake 0 1E308200 1A06082B 06010201 01040004 08 doe 3 RAA RA AE 0E526963 68617264 20426C61 696E65 Richard Blaine 1 3 6 1 2 1 1 4 0 Richard Blaine 4 2 Using 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 significant state changes that occur on the managed node snmp_traprcv TCPIP SNMP_TRAPRCV EXE Listens for SNMP trap messages and displays any it receives 4 8 Using the SNMP Utilities Using the SNMP Utilities 4 2 Using the Trap Sender and Trap Receiver Programs By default these programs use UDP port 162 However you can specify another port with the p flag or set up an SNMP trap service that specifies the port you want to use Note however that the use of UDP port 162 is coded into stand
136. y an external event such as a system reboot The following counters are affected ifInDiscards ifInErrors ifInNUcastPkts ifInOctets ifInUcastPkts ifInUnknownProtos ifOutErrors ifOutNUcastPkts ifOutOctets ifOutUcastPkts Note that for SNMP Version 2 these counters are data type Counter32 The following ifTable members are always 1 for OpenVMS ifOutDiscards Counter32 ifOutQLen Gauge32 MIBs Provided with TCP IP Services 2 7 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 e Creating a MIB specification Section 3 1 e The structure of management information Section 3 2 e Creating a MIB source file Section 3 3 e Including the routines and building the subagent Section 3 4 e 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 Specification The creation of a management information base MIB begins with data gathering During this phase the developer identifies the information to manage based on the entities that the network manager needs to examine and manipulate Each resource that a MIB manages is represented by an object After gathering the data the developer uses Abstract Syntax Notation 1

Compaq AAR04BCTE Network Card User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents