SNMP Manager Programmer’s Guide Abstract This manual explains how to use the Manager Services product. The Manager Services product helps C and C++ programmers generate SNMP (Simple Network Management Protocol) managers that run as NonStop Kernel processes in Guardian or Open System Services (OSS) environments.
Document History Part Number Product Version Published 124334 Manager Services D21 August 1996 134249 Manager Services D21 May 1997 New editions incorporate any updates issued since the previous edition. A plus sign (+) after a release ID indicates that this manual describes function added to the base release, either by an interim product modification (IPM) or by a new product version on a .99 site update tape (SUT). Ordering Information For manual ordering information: domestic U.S.
New and Changed Information The SNMP Manager Programmer’s Guide has been revised to reflect the updated contents of the following source code files for the sample manager examples documented in Section 2, Programming Examples.
New and Changed Information SNMP Manager Programmer’s Guide– 134249 iv
Contents New and Changed Information iii About This Manual xi Notation Conventions xv 1.
2. Programming Examples (continued) Contents 2. Programming Examples (continued) Overview of Source Code Structure 2-5 Managers Supporting UDP Only 2-5 Managers Supporting UDP and IPC 2-6 Common Utility Functions 2-34 Guardian and OSS Differences 2-40 SNMPGT 2-42 SNMPGET 2-55 SNMPNEXT 2-65 SNMPSET 2-68 SNMPWALK 2-82 SNMPTRAP 2-94 SNMPMON 2-108 SNMPHOST 2-114 SNMPHOST Header File 2-119 SNMPHOST Source Code 2-122 3. Using the MIB Compiler 4.
5. Constructing and Interpreting Packets (continued) Contents 5. Constructing and Interpreting Packets (continued) Functions for Initializing Packets 5-12 SNMP_Create_Request() 5-12 SNMP_Create_Trap() 5-14 Functions for Binding MIB Objects 5-17 SNMP_Bind_Integer() 5-18 SNMP_Bind_IP_Address() 5-20 SNMP_Bind_Null() 5-23 SNMP_Bind_Object_ID() 5-25 SNMP_Bind_String() 5-28 SNMP_Bind_Unsigned_Integer() 5-31 Function for Releasing Packet Memory 5-33 6.
7. Sending and Receiving Packets Contents 7. Sending and Receiving Packets Communicating With NonStop Agents 7-1 Establishing Communication 7-2 Sending Packets 7-3 Receiving Packets 7-5 Communicating With Agents and Other Managers 7-5 Establishing Communication 7-5 Sending Packets 7-6 Receiving Packets 7-7 8. Building Executable Managers Building Guardian Managers 8-1 Building OSS Managers 8-4 9.
Examples Contents Examples Example 2-1. Example 2-2. Example 2-3. Example 2-4. Example 2-5. Example 2-6. Example 2-7. Example 2-8. Example 2-9. Example 2-10. Example 2-11. Example 2-12. Example 2-13. Example 2-14. Example 2-15. Example 2-16. Example 2-17. Example 2-18. Example 8-1. Example 8-2.
Figures (continued) Contents Figures (continued) Figure 5-1. Figure 5-2. Figure 5-3. Figure 5-4. Figure 5-5. Figure 7-1. Figure 7-2. The SNMP Packet 5-1 The Request and Response Packet 5-2 The Trap Packet 5-4 Variable Bindings 5-5 Retrieving MIB Objects in Lexicographic Order 5-8 Calls for Sending and Receiving IPC-Encoded Packets 7-1 Calls for Sending and Receiving UDP-Encoded Packets 7-6 Tables Table 2-1. Table 2-2. Table 2-3. Table 2-4. Table 2-5. Table 4-1. Table 4-2. Table 4-3. Table 5-1.
About This Manual Simple Network Management Protocol (SNMP) managers are SNMP-compliant applications used to manage resources on systems supplied by various vendors. Managers interact with SNMP agents in order to access Management Information Base (MIB) objects under the control of the agents or subagents that interact with the agents. Values of MIB objects, which describe the attributes of system resources, are retrieved and changed by managers.
Purpose About This Manual See “Related Reading,” later in this section, for information on obtaining these RFCs.
Related Reading About This Manual • Section 9, Reference Summary, consolidates reference information for Manager Services, such as the syntax for all the library functions and MIB compiler and sample manager invocation. Related Reading Documentation useful while creating managers using Manager Services can be found in both manuals provided by Tandem and other information resources.
Your Comments Invited About This Manual RFCs are public-domain documents that you can obtain from InfoWay or from one of the following sources: • DDN Network Information Center 14200 Park Meadow Drive, Suite 200 Chantilly, VA 22021 USA phone: 1-800-365-3642 e-mail: nic@nic.ddn.mil • The Internet. If your site has IP-connectivity to the Internet community, you can use “anonymous” FTP to the host nic.ddn.mil (residing at 192.112.36.5) and retrieve files from the directory rfc/. • Electronic mail.
Notation Conventions General Syntax Notation The following list summarizes the notation conventions for syntax presentation in this manual. Nonitalic Letters. Nonitalic letters indicate keywords and reserved words. For example: mibcomp [-numbers] Some constructs, such as Manager Services library function names and predefined types, must be encoded in mixed case. For example: case VT_OPAQUE: if (vbp->value_u.v_string.start_bp != (OCTET_T *)0) EBufferClean(vbp->value_u.v_string)); lowercase italic letters.
General Syntax Notation Notation Conventions <--n. In a source code example, an arrow accompanied by a number identifies code that is discussed in text, immediately preceding the example, that is accompanied by the same number. For example, the following identifier, 2, indicates that an explanation for the code it accompanies appears earlier, as shown: #define MAXNAMEBUF <--2 #define MAXHOSTNAME 80 8 2. These defines are used by check_host_name() when validating host names.
1 Introduction to Manager Services Simple Network Management Protocol (SNMP) is an Internet standard that facilitates managing resources on networks interconnecting devices manufactured by different vendors. The application used to manage network resources is known as a manager. A manager monitors and controls resources on the network by sending messages to applications known as agents, which have access to resources manageable using SNMP.
MIB Object Identification Introduction to Manager Services Request messages are sent by managers to monitor and control resources. Requests retrieve specific information about resources or change the attributes of specific resources. Agents and subagents occasionally send traps to managers. Traps are messages containing important but unsolicited information about resources of concern to specific managers.
Introduction to Manager Services MIB Object Attributes The numbers in MIB definitions describe an object hierarchy for all vendors’ SNMP objects. For objects in the previous example, the hierarchy looks like this for the collection of objects describing the subagent process: iso (1) org (3) dod (6) internet (1) private (4) enterprises (1) tandem (169) nonstopsystems (3) zhrm (180) zhrmSaProcess (4) zhrmSaProcCurrTime (1) zhrmSaProcVersion (2) zhrmSaProcName (3) . . .
SNMP Packets Introduction to Manager Services As the SYNTAX clause indicates, any value assigned to this object must be an integer, specifically 0 or 1 in this case. The ACCESS clause assigns an access attribute of read-write to this object, indicating that managers can both retrieve and change the value of the object. A manager can send a request packet to retrieve information when the access attribute is read-only or read-write.
The SNMP Manager Introduction to Manager Services sending the trap and the contents of the notification, and may contain one or more variable bindings. SNMP managers must be able to construct and interpret packets of various types and describe and interpret the numeric identifiers and values of MIB objects. The SNMP Manager The main job of the SNMP manager is to facilitate the monitoring and control of network resources.
Extended Roles Introduction to Manager Services • • • MIB object handling logic resolves user input regarding specific resources into MIB object representations that describe the resources, in preparation for formatting objects as variable bindings. This logic also converts SNMP object representations into formats useful for analysis or output. SNMP packet construction logic converts user requests into Get, GetNext, or Set packets and, when required, creates Trap packets.
Manager Services Components Introduction to Manager Services manager notifies the upper manager by means of a trap. The upper manager can then take whatever action is appropriate, such as issuing SNMP requests of its own. Each manager is actually a resource that can be managed using SNMP. For example, the priority at which a manager process executes or the rate at which it issues requests may be desirable to monitor and control.
Using Request/Response Packets Introduction to Manager Services These components, available for both the Guardian and OSS environments of the NonStop Kernel, help you create request packets, interpret response packets, and create and interpret trap packets. Using Request/Response Packets Your managers can send requests and receive responses over several communication protocols.
Introduction to Manager Services Request Authentication Request Authentication Before an SNMP request is processed, the receiving entity (agent or subagent) authenticates the request to determine whether the sending entity (manager) is qualified to perform the operation in the request. Request authentication rules vary from vendor to vendor. Many SNMP agents use a two-step process to determine whether to process manager requests: 1. The community name contained in the request packet is examined.
Using Trap Packets Introduction to Manager Services • Requests for MIB objects under the control of subagents are passed to subagents for processing. Some subagents perform authentication based on the community name, IP address, and a password appended to the community name: agent-community-string::subagent-password • All MIB objects under the control of the NonStop agent are accessible.
Guardian and OSS Interoperability Introduction to Manager Services network protocol to the Trap Multiplexer for conversion into EMS events. The Trap Multiplexer converts all the traps it receives into EMS events, which can be accessed by a manager that resides on a NonStop Kernel system. Figure 1-8.
Manager Development Cycle Introduction to Manager Services Figure 1-9.
Designing Your Manager Introduction to Manager Services Figure 1-10.
Introduction to Manager Services Defining Manager Logic binding specification contains a numeric identifier for a MIB object known as an instance identifier. The instance identifier consists of the object’s OID and a suffix, used primarily to unambiguously identify objects that have multiple instances, such as objects that are part of table entries. Consider, for example, the interfaces group of MIB-II.
Defining Manager Logic Introduction to Manager Services Figure 1-11 highlights, in bold type, where in your manager logic you use Manager Services components. Figure 1-11. Components of Manager Logic ... #include library-header-files ... packet-structure-declarations ... user-interface-management-logic ... MIB-object-handling-logic ... packet-initialization-function-call ... bind-variable-bindings-function-call(s) ... encoded-packet-buffer-setup-function-call(s) ... packet-encoding-function-call ...
Introduction to Manager Services Defining Manager Logic Here is some additional information about the logic components highlighted in Figure 1-11: Library header files You always include seven library header files. They contain the definitions of structures and prototypes of functions the library uses to process packets. Section 3 describes the header files.
Introduction to Manager Services Building the Executable Manager Decoding packet When your manager receives a response or trap packet, you decode it using the library function SNMP_Decode_Packet_WER(), described in Section 6. Deallocating space When memory allocated for holding packets is no longer needed, you use several library functions to deallocate it. To deallocate a packet structure, use SNMP_Free(), described in Section 5.
Installing Managers Introduction to Manager Services Figure 1-12.
Epilogue Manager Portability Introduction to Manager Services • For IPC communication, the PAID of the manager process must be compatible with that of the NonStop agent process to access MIB objects in the zagInProfile group of the NonStop agent’s private MIB. Epilogue Manager Portability The developers of Manager Services implemented it by porting components of Envoy, Epilogue Technology Corporation’s SNMP toolkit.
Introduction to Manager Services SNMP Manager Programmer’s Guide– 134249 1- 20 OSS Environment
2 Programming Examples This section describes the sample managers that are provided with Manager Services. Table 2-1 provides a summary of sample manager functions; some of the managers use the UDP application program interface (API) to communicate over TCP/IP, while others support both UDP and IPC. Table 2-1. Summary of Sample Manager Functions Sample Manager Protocol Supported Functions SNMPGT UDP Handles a Get packet for MIB objects specified at invocation.
Manager Logic Programming Examples Table 2-2. Sample Manager Source Code Files Sample Manager C File Names System File Names File Descriptions SNMPGT snmpgt.c snmpgtc C source code for main control block SNMPGET snmpfs.c snmpfsc snmpget.c snmpgetc C source code for packet encoding and decoding C source code for main control block snmpfs.c snmpfsc snmpnxt.c snmpnxtc snmpfs.c snmpfsc snmpset.c snmpsetc snmpfs.c snmpfsc readmib.c rtutils.c readmibc rtutilsc mibrt snmpwlk.
Header Files Programming Examples Header Files The Manager Services header files needed by the sample managers are summarized in Table 2-3. Table 2-3. Sample Manager Header Files File Description C File Names System File Names Prototypes of Manager Services library packethandling functions asn1.h buffer.h buildpkt.h localio.h objectid.h snmp.h snmpdefs.h snmpstat.
Overview of Source Code Structure Programming Examples 1. Log onto the NonStop Kernel system on which the sample files are installed: logon snmp.user1 2. Edit the build script in grdbuild to reflect the location of the sample files on your system. Edit snmpwlkc to qualify the file name of mibrt (in the read_mib() call) to reflect the location of mibrt on your system. 3. Build the sample managers: obey grdbuild 4. Ensure that any agents and subagents you want the managers to interact with are running.
Managers Supporting UDP Only Programming Examples decoding as well as packet transmission and receipt by using functions defined in snmpfsc and declared in the header file named snmpfsh. • • All the sample managers use common utilities for some of their MIB handling activities. Common utilities are a collection of functions that are part of the Manager Services library, but intended to be used only as examples for some of the MIB object handling operations your managers need to provide.
Managers Supporting UDP and IPC Programming Examples includes snmpfsh, a header file that declares the structure and prototypes of functions used in snmpfsc. Figure 2-2.
Managers Supporting UDP and IPC Programming Examples Example 2-1. Contents of snmpfsh #ifndef _SNMPFS_H_ #define _SNMPFS_H_ #ifndef _sockaddr_in_DEFINED #include nolist #endif /* _sockaddr_in_DEFINED */ typedef struct SNMP_HOST_INT_S /* Host interface structure */ { unsigned short version; /* Used for version control */ /* Set by SNMP_Init_ to 1.
Managers Supporting UDP and IPC Programming Examples agent_name The name of a NonStop agent process; used for IPC communication. host_addr The IP address of a NonStop Kernel or other system; used for UDP communication. dest A structure (defined in in.h) describing a socket to use for sending requests and traps when using UDP communication. from The socket from which a response or trap is received when using UDP communication.
Managers Supporting UDP and IPC Programming Examples 1. The header files support various operations performed by the functions: SNMP operations buffer.h snmpdefs.h print.h snmpfs.h Encoded-packet handling Unencoded-packet handling Packet printing Operations performed by snmpfsc C operations stdio.h ctype.h stddef.h stdlib.h string.h C library utilities for such activities as memory and string management UDP operation systype.h socket.h netdb.h in.h UDP packet handling System operations tal.
Managers Supporting UDP and IPC Programming Examples 6. These defines describe flags passed to SNMP_Open_() and SNMP_WriteRead_() to specify the kind and amount of information to print: 0 suppresses all output messages. 1 (PRINT_DEBUG_MSG) prints debug messages. 2 (PRINT_SEND_MSG) prints outgoing packets. 4 (PRINT_RECV_MSG) prints incoming packets. 7.
Managers Supporting UDP and IPC Programming Examples 22. The SNMP_FS_ErrMsg_() function accepts error numbers returned by the other functions in snmpfsc and returns a character pointer to a buffer containing an explanation of the failure. The value of defines associated with err_num is used to determine which message to return. The value of det_err_num, if any, is embedded in the returned message where appropriate. 23. The SNMP_Init_() function determines whether to use UDP or IPC communication.
Managers Supporting UDP and IPC Programming Examples 32. The SNMP_WriteRead_() function encodes and transmits request packets and receives and decodes response packets. This function accepts a pointer to SNMP_HOST_INT_T, a pointer to an unencoded request packet structure, a double pointer to the response packet structure, a pointer to a structure containing descriptors for the encoded-packet buffer (ebuffp), and an integer describing the kind of output messages desired.
Managers Supporting UDP and IPC Programming Examples 37. If the PRINT_SEND_MSG flag is set, the contents of spkt are displayed using the common utility function print_pkt(). 38. The Manager Services library function EBufferUsed() returns the number of bytes between start_bp and next_bp to send_cnt. 39. For UDP communication, the destination socket address is written to the beginning of the buffer described by ebuffp, as required by the D20 socket library.
Managers Supporting UDP and IPC Programming Examples 48. The Manager Services function SNMP_Decode_Packet_WER() decodes the response packet using myEBuff descriptors, returning a pointer to the decodedpacket structure. 49. If decoding fails, the Manager Services SNMP_Free() library function releases memory allocated for the packet structure and, if the PRINT_DEBUG_MSG flag is set, a message is printed. 50.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 2 of 19) #define MAXNAMEBUF 80 #define MAXHOSTNAME 8 <--2 #define INVALID_HOST_ADDR 0XFFFFFFFFl /* Defines for the return values for the check_host_name procedure.
Managers Supporting UDP and IPC Programming Examples Example 2-2.
Managers Supporting UDP and IPC Programming Examples Example 2-2.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 5 of 19) while ((ptr = strchr(name, '.')) != NULL) { dots++; /* keep track of no. of dots */ memset(id, NULL, 20); strncpy(id, name, ptr - name); byte = atoi(id); if ( byte < 0 || byte > 255) { fprintf(stdout, "Invalid IP address %s\n", hname); return HOSTNAME_ERROR; } name = ptr + 1; } /* of while */ /* if IP address contains invalid no.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 6 of 19) if (err3) { fprintf(stdout, "Hostname is not defined on EXPAND Network.\n"); fprintf(stdout, "Using TCP/IP.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 7 of 19) { /* Local Access using a file */ FILE_CLOSE_(host_int->file_num); <--21 host_int->file_num = -1; } } /* End SNMP_Close_ */ #pragma page /*************************************************************************** NAME: SNMP_FS_ErrMsg_ PURPOSE: Decodes a numeric error number returned from the SNMP_* procedures into displayable text. PARAMETERS: short Error number, short Detailed error number.
Managers Supporting UDP and IPC Programming Examples Example 2-2.
Managers Supporting UDP and IPC Programming Examples Example 2-2.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 10 of 19) return_remote: <--26 host_int->dest.sin_family = AF_INET; host_int->dest.sin_port = htons(SNMP_REQUEST_PORT); host_int->dest.sin_addr.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 11 of 19) #pragma page /*************************************************************************** NAME: SNMP_Open_ PURPOSE: Create a path to get to the SNMP agent based upon the info in the SNMP_HOST_INT_T structure. This will either get a SOCKET or open a file. PARAMETERS: SNMP_HOST_INT_T * Location of host interface struct. UNSIGNED SHORT Debug flag. Controls the displaying of debug information.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 12 of 19) if (PRINT_DEBUG_MSG) { fprintf(stdout, "\n------ RUNNING REMOTE ------\n"); } return 0; } else { /* Local Access using a file */ memset(temp_file_name, NULL, sizeof(temp_file_name)); /* Check for an empty host_name */ if (strlen(host_int->host_name) != 0) { strcpy(temp_file_name, host_int->host_name); strcat(temp_file_name, "."); } strcat(temp_file_name, host_int->agent_name); strcat(temp_file_name, ".
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 13 of 19) #pragma page /*************************************************************************** NAME: SNMP_WriteRead_ PURPOSE: Send and receive an SNMP buffer to the destination based upon the info in the SNMP_HOST_INT_T structure. PARAMETERS: SNMP_HOST_INT_T * Location of host interface struct. SNMP_PKT_T * Send packet pointer. Points to the data to send. SNMP_PKT_T ** Received packet pointer pointer.
Managers Supporting UDP and IPC Programming Examples Example 2-2.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 15 of 19) if (err != 0) { host_int->err_num = err; /* Save the error number */ if (PRINT_DEBUG_MSG) { fprintf(stdout, "Encoding packet failed with error %i.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 16 of 19) } else <--40 { /* Using local access (file) */ status = WRITEX(host_int->file_num, myEBuff.start_bp, send_cnt, &written_cnt); if (status != CCE) { FILE_GETINFO_ (host_int->file_num, &err); host_int->err_num = err; /* Save the error number */ if (PRINT_DEBUG_MSG) { fprintf(stdout, "WRITEX initialization failed with error %i.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 17 of 19) } else { /* Using local access (file) */ fprintf(stdout, "AWAITIOX for WRITEX returned error %i.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 18 of 19) if (PRINT_DEBUG_MSG) { fprintf(stdout, "READX initialization failed with error %i.
Managers Supporting UDP and IPC Programming Examples Example 2-2. Contents of snmpfsc (page 19 of 19) memcpy ((char*) &host_int->from, (void *) ebuffp->start_bp, sizeof(host_int->from)); /* Adjust the "read count" to skip the socket address. */ read_cnt -= sizeof(struct sockaddr_in); } *rpkt = SNMP_Decode_Packet_WER(myEBuff.
Common Utility Functions Programming Examples Common Utility Functions Several utility functions used by the sample managers are provided with Manager Services. Summarized in Table 2-4, these functions are intended to be used only as examples for some of the MIB object handling operations managers need to perform. In your own managers, you would replace the common utility calls with calls to your own functions tailored to support your application.
Common Utility Functions Programming Examples hexcheck() The hexcheck() function accepts a pointer to an ASCII or hexadecimal string value and returns the number of bytes in the string. #include "printh" count = hexcheck(string-value); int hexcheck(char *string-value); count is the number of bytes in the string. In the case of ASCII strings, for which you use a double colon (::) to encode a colon, only one of the colons is counted.
Common Utility Functions Programming Examples struc namerec { OBJ_ID_T oid; char *nmstr; int type; Type contains one of the values described under str_to_type(). If the OID in the oid structure is not for a MIB-II object, p is set to 0. oid is a pointer to a structure of type OBJ_ID_T, defined in asn1.
Common Utility Functions Programming Examples typedef struct OBJ_ID_S {int num_components; OIDC_T *component_list; } OBJ_ID_T; Refer to Section 4, Using Header Files, Data Structures, and Defines, for more information on OBJ_ID_T. print_pkt() The print_pkt() function prints the contents of an unencoded-packet buffer of type SNMP_PKT_T. #include "printh" print_pkt(packet); void print_pkt(SNMP_PKT_T *); packet is a pointer to an unencoded-packet buffer of type SNMP_PKT_T, defined in snmpdefs.
Common Utility Functions Programming Examples Err_stat An indication of whether an exception occurred. Values are prescribed by RFC 1157: noError, tooBig, noSuchName, badValue, readOnly, and genErr. Err_ndx An indication of which variable binding is involved in the exception. VBLlen The number of bytes used by all variable bindings in the packet. VBcount The number of variable bindings in the packet. VarBind # The sequential number of the variable binding, starting at 0.
Common Utility Functions Programming Examples Section 3, Using the MIB Compiler, describes the format of the -readtree and nametree output. string2oid() The string2oid() function parses the in-memory structure created by a previous call to read_mib() and returns information about the OID of a MIB object name in a structure of type OBJ_ID_T.
Guardian and OSS Differences Programming Examples 3 (linkUp) 4 (authenticationFailure) 5 (egpNeighborLoss) 6 (enterpriseSpecific) generic-trap-string is a pointer to one of the generic trap strings described above. str_to_type() The str_to_type() function converts a string depicting an SNMP type into its corresponding Manager Services representation. include "printh" rcode = str_to_type(type-string); int str_to_type(char *type-string); rcode is an integer indicating the outcome of the call.
Guardian and OSS Differences Programming Examples • The following lines appear in snmpfsc to support the use of Guardian printf statements from OSS processes: #ifndef _INTEROPERABLE #define _INTEROPERABLE #endif The only difference in sample manager invocation is the format of the NonStop agent name passed in the -a parameter.
SNMPGT Programming Examples SNMPGT This manager handles a Get packet for one or more MIB objects specified at invocation. It encodes the packet using BER encoding, prints the request packet, sends a request and receives a response using the UDP protocol, and prints the response packet.
SNMPGT Programming Examples target-host-identifier identifies the device on which the target agent resides. You can specify either a name or an IP address; omit the backslash when specifying a NonStop Kernel node: somenode somesys.tandem.com 130.252.12.3 MIB-object identifies a MIB object instance. If the object is a MIB-II object, you can refer to it by name or using the dotted OID format; use the dotted OID format for objects that are not MIB-II objects: sysContact.0 1.3.6.1.2.1.25.2.2.
SNMPGT Programming Examples 1. The header files support various activities the manager performs: SNMP operations asn1.h localio.h print.h Defines various ASN.1 structures Defines structures for holding unencoded ASN.1 information Defines encoded-packet buffer structures and function prototypes Defines entry points into the OID structure Includes snmpdefs.
SNMPGT Programming Examples 10. A while loop parses all the arguments in the invocation line that are preceded by a minus sign (-). Any values stored override the default values assigned earlier. 11. The target host identifier is stored in hostname. 12. A for loop extracts OIDs from the invocation line. 13. The number of OIDs is stored in oidcnt to use later when binding variables to the request packet. 14. Two of the three fields in the socket structure are initialized.
SNMPGT Programming Examples following the socket structure. The Manager Services function EBufferUsed() computes the number of used bytes in the buffer. 25. The encoded packet in sndbuff is transmitted after computing the number of bytes to transmit. 26. The AWAITIOX() system call determines when an I/O operation has been completed. This particular call causes the manager to wait indefinitely for completion of transmission. 27.
SNMPGT Programming Examples Example 2-4. Contents of snmpgtc (page 1 of 8) #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include
SNMPGT Programming Examples Example 2-4.
SNMPGT Programming Examples Example 2-4. Contents of snmpgtc (page 3 of 8) { opt = *( *argv + 1 ); argv++, argc--; if (argc == 0) /* 12Mar97 DVVP : reject incomplete command */ break; switch ( opt ) { case 'c': community = *argv; argv++, argc--; break; case 'i': requestid = strtol( *argv, (char **)NULL, 0 ); /* check if invalid request ID */ if ((requestid == 0) && (*argv[0] != '0')) { fprintf(stdout, "\nInvalid Requestid %s.
SNMPGT Programming Examples Example 2-4.
SNMPGT Programming Examples Example 2-4. Contents of snmpgtc (page 5 of 8) { fprintf(stderr, "Invalid IP address %s\n", hostname); exit(0); } name = ptr + 1; } /* of while */ /* if IP address contains invalid no.
SNMPGT Programming Examples Example 2-4. Contents of snmpgtc (page 6 of 8) { if (oidstr_to_oid( oidstr[i], &base_oid) < 0 ) { fprintf(stderr, "Bad object identifier: %s\n", oidstr[i]); exit(0); } if (SNMP_Bind_Null(send_pkt, i, base_oid.num_components, base_oid.
SNMPGT Programming Examples Example 2-4.
SNMPGT Programming Examples Example 2-4.
SNMPGET Programming Examples SNMPGET Like SNMPGT, SNMPGET handles a Get packet for one or more MIB objects. However, SNMPGET encodes the Get packet for UDP or IPC communication, depending on the target host identifier you specify at invocation: • • UDP communication is used if the host is not the same host as the manager’s host or if it cannot be reached over Expand. IPC communication is used if the host is the same host as the manager’s host or if it can be reached over Expand.
SNMPGET Programming Examples retry-count specifies the number of times to resend the packet if an error occurs. The default is 0. timeout-seconds is the number of seconds the manager should wait for request or response transmission completion before resending the request or terminating. The default is 5. NonStop-agent-process is the name of a NonStop agent process with which you want the manager to interact. The default is $ZSNMP.
SNMPGET Programming Examples MIB-object identifies a MIB object instance. If the object is a MIB-II object, you can refer to it by name or using the dotted OID format; use the dotted OID format for objects that are not MIB-II objects: sysContact.0 1.3.6.1.2.1.25.2.2.0 You can specify as many as 16 MIB objects. Example 2-5 illustrates the output SNMPGET generates. Example 2-5. Sample SNMPGET Output TACL> SNMPGET -a $zsnmp1 \mynode sysDescr.
SNMPGET Programming Examples 4. If values for a NonStop agent process name, destination port, or timeout were specified at invocation, the values are assigned to the appropriate fields in the host interface structure, SNMP_HOST_INT_T. 5. SNMP_Open_(), defined in snmpfsc, obtains a socket for UDP communication or opens a file for NonStop agent IPC communication. 6. The logic for constructing a request packet is the same as that in SNMPGT. 7.
SNMPGET Programming Examples Example 2-6. Contents of snmpgetc (page 1 of 6) #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include
SNMPGET Programming Examples Example 2-6.
SNMPGET Programming Examples Example 2-6. Contents of snmpgetc (page 3 of 6) /* check if invalid request ID */ if ((requestid == 0) && (*argv[0] != '0')) { fprintf(stdout, "\nInvalid Requestid %s. \n\n", *argv); exit(0); } /* check if requestid value is out of range */ if (errno == ERANGE) { fprintf(stdout, "\nInvalid Requestid %s.
SNMPGET Programming Examples Example 2-6. Contents of snmpgetc (page 4 of 6) if (argc < 2) { fprintf(stdout, usage, whoami); exit(0); } hostname = *argv++; argc--; for (i = 0; argc > 0; i++) { if (i == MAXOIDS) { fprintf(stdout, "Exceeded %d object identifiers\n", MAXOIDS); exit(0); } oidstr[i] = *argv++; argc--; } oidcnt = i; opt2 = SNMP_Init_(&host_int, sizeof(host_int), hostname); <--3 switch (opt2) { case 0: case 1: break; default: exit(0); } /* switch */ /* Now I can override any default.
SNMPGET Programming Examples Example 2-6. Contents of snmpgetc (page 5 of 6) err2 = SNMP_Open_(&host_int, debug_level); <--5 if (err2 != 0) { fprintf(stdout, "SNMP_OPEN_ returned error %i.
SNMPGET Programming Examples Example 2-6. Contents of snmpgetc (page 6 of 6) /* * PDU request ID is reset to 1 by setting * requestid to 0 and then incrementing it */ if (requestid == MAX_REQID_VALUE) requestid = 0; send_pkt->pdu.std_pdu.request_id = ++requestid; } err2 = SNMP_WriteRead_ (&host_int, send_pkt, &rcvd_pkt, &ebuff, <--8 debug_level); if (err2 != 0) { fprintf(stdout, "SNMP_WRITEREAD_ returned error %i (", err2); fprintf(stdout, SNMP_FS_ErrMsg_ (err2, host_int.
SNMPNEXT Programming Examples SNMPNEXT SNMPNEXT handles a GetNext packet for one or more MIB objects, encoding the packet for UDP or IPC communication in the same fashion as SNMPGET. Invoke SNMPNEXT the same way you invoke SNMPGET: SNMPNEXT [-c agent-community string] [-i request-id] [-p agent-request-port} [-r retry-count] [-t timeout-seconds] [-a NonStop-agent-process] [-x output-information-level] target-host-identifier MIB-object [MIB-object...
SNMPNEXT Programming Examples NonStop-agent-process is the name of a NonStop agent process with which you want the manager to interact. The default is $ZSNMP. When specifying the agent name for a manager that will run as an OSS process, delimit it with single quotation marks: '$ZSNMP1' This value is only used when the target-host-identifier is the local host or an Expand host. output-information-level describes the kind and amount of output information you want generated.
SNMPNEXT Programming Examples subagent so that it communicates with $ZSNMP1, the object retrieved is the expected object. Example 2-7. Sample SNMPNEXT Output TACL> SNMPNEXT -a $zsnmp1 \mynode 1.3.6.1.2.1.25.2.0 ------ RUNNING LOCAL -----SENDING PACKET: Packet Length=65, Version=0, Community: Length=6, Value=public PDU Type=get-next-request Length=65, RQ_ID=1, Err_stat=noError, Err_ndx=0 VBLlen=39, VBcount=1 VarBind #0, content size=39, Flags & type=0x05, encoded length=5 OBJECT IDENTIFIER: mib-2.25.2.
SNMPSET Programming Examples SNMPSET SNMPSET handles a Set packet for one or more MIB objects, encoding the packet for UDP or IPC communication in the same fashion as SNMPGET. Invoke SNMPSET as follows. If you want to change the value of a MIB-II object, you can simply identify it by name.
SNMPSET Programming Examples timeout-seconds is the number of seconds the manager should wait for request or response transmission completion before resending the request or terminating. The default is 5. NonStop-agent-process is the name of a NonStop agent process with which you want the manager to interact. The default is $ZSNMP.
SNMPSET Programming Examples data-type describes the SNMP data type of the target MIB object when it is not a MIB-II object. It must be one of these values: OCTET_STRING DisplayString OBJECT_IDENTIFIER NULL INTEGER IpAddress Counter Gauge TimeTicks Opaque value is the value to assign to the target MIB object. Enclose strings in double quotation marks (""), use a colon (:) to specify binary data, and use the dotted notation (1.2.3.4) or NonStop Kernel node name for IP addresses.
SNMPSET Programming Examples Example 2-9 illustrates the contents of snmpsetc, the source code file for the main block of SNMPSET. Numbers in the example correspond to numbers in the observations made between here and the example. 1. Variables for handling the value of MIB objects of type OBJECT_IDENTIFIER are declared. 2.
SNMPSET Programming Examples 11. The value of peertype, which holds the Manager Services representation of the SNMP data type for the target MIB object, is used to determine how to create a variable binding for the object. Variable bindings are bound using Manager Services functions tailored to support MIB objects of specific SNMP data types.
SNMPSET Programming Examples Example 2-9. Contents of snmpsetc (page 1 of 9) #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include
SNMPSET Programming Examples Example 2-9.
SNMPSET Programming Examples Example 2-9. Contents of snmpsetc (page 3 of 9) { case 'a': /* For local access */ snmpagt = *argv; argv++, argc--; break; case 'c': community = *argv; argv++,argc--; break; case 'i': requestid = strtol(*argv, (char **)NULL, 0); /* check if invalid request ID */ if ((requestid == 0) && (*argv[0] != '0')) { fprintf(stdout, "\nInvalid Requestid %s.
SNMPSET Programming Examples Example 2-9.
SNMPSET Programming Examples Example 2-9. Contents of snmpsetc (page 5 of 9) { case 0: case 1: break; default: exit(0); } /* switch */ /* Now I can override any default. This must be done before the */ /* call to SNMP_Open_. */ if (snmpagt != 0) { strcpy(host_int.agent_name, snmpagt); } if (dest_port != SNMP_REQUEST_PORT) { host_int.dest.sin_port = htons(dest_port); } if (timeout != 5) { host_int.
SNMPSET Programming Examples Example 2-9.
SNMPSET Programming Examples Example 2-9. Contents of snmpsetc (page 7 of 9) name = valstr[i]; while ((ptr = strchr(name, '.')) != NULL) { dots++; /* keep track of no. of dots */ memset(id, NULL, 20); strncpy(id, name, ptr - name); byte = atoi(id); if ( byte < 0 || byte > 255) { fprintf(stdout, "Invalid IP address %s\n", valstr[i]); fprintf(stdout, "while binding the VT_IPADDRESS\n"); exit(0); } name = ptr + 1; } /* of while */ /* if IP address contains invalid no.
SNMPSET Programming Examples Example 2-9. Contents of snmpsetc (page 8 of 9) rcode = SNMP_Bind_IP_Address(send_pkt, i, base_oid.num_components, base_oid.component_list, (OCTET_T *)&ipaddr); break; case VT_OBJECT: <-- 15 if (oidstr_to_oid(valstr[i], &val_oid) < 0) { fprintf(stdout, "Bad object identifier: %s\n", valstr[i]); fprintf(stdout, "while binding the VT_OBJECT\n"); exit(0); } rcode = SNMP_Bind_Object_ID(send_pkt, i, base_oid.num_components, base_oid.component_list, val_oid.
SNMPSET Programming Examples Example 2-9.
SNMPWALK Programming Examples SNMPWALK SNMPWALK lets you browse through MIBs in lexicographical order. It issues GetNext packets starting at a point in the SNMP object hierarchy you specify at invocation. SNMPWALK, like SNMPGET, encodes the packets for UDP or IPC communication.
SNMPWALK Programming Examples agent-request-port is the UDP destination port to use to address the agent. The default is 161. retry-count specifies the number of times to resend the packet if an error occurs. The default is 0. timeout-seconds is the number of seconds the manager should wait for request or response transmission completion before resending the request or terminating. The default is 5.
SNMPWALK Programming Examples first-MIB-object identifies the instance of the MIB object preceding the first MIB object you want to retrieve. If the object is represented in mibrt, you can refer to it by name or using the dotted OID format; use the dotted OID format for objects that are not represented in mibrt: sysContact.0 1.3.6.1.2.1.25.2.2.0 The default is 0.0. Example 2-10 illustrates the output SNMPWALK generates when requested to retrieve three objects represented in mibrt.
SNMPWALK Programming Examples Example 2-10. Sample SNMPWALK Output TACL> SNMPWALK -d 3 -a $zsnmp1 \mynode sysDescr.0 ------ RUNNING LOCAL -----SENDING PACKET: Packet Length=69, Version=0, Community: Length=6, Value=public PDU Type=get-next-request Length=69, RQ_ID=1, Err_stat=noError, Err_ndx=0 VBLlen=43, VBcount=1 VarBind #0, content size=43, Flags & type=0x05, encoded length=5 OBJECT IDENTIFIER: sysDescr.
SNMPWALK Programming Examples Example 2-11 illustrates the contents of snmpwlkc, the source code file for the main block of SNMPWALK. Numbers in the example correspond to numbers in the observations made between here and the example: 1. The readmib.h and rtutils.h header files contain prototypes for the common utility functions SNMPWALK uses in conjunction with mibrt: read_mib() and string2oid(). 2. Any value specified at invocation with the -d parameter is stored in distance. 3.
SNMPWALK Programming Examples Example 2-11. Contents of snmpwlkc (page 1 of 7) #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include
SNMPWALK Programming Examples Example 2-11. Contents of snmpwlkc (page 2 of 7) int distance = 0x7fffffff; EBUFFER_T ebuff; short err = 0; short err2; int firstid; short fn = -1; u_long host_addr; SNMP_HOST_INT_T host_int; char /* host interface*/ *hostname; int i; int j; int need; char *oidstr = "0.
SNMPWALK Programming Examples Example 2-11. Contents of snmpwlkc (page 3 of 7) case 'c': community = *argv; argv++,argc--; break; case 'd': <--2 distance = strtol(*argv, (char **)NULL, 0); argv++,argc--; break; case 'i': requestid = strtol(*argv, (char **)NULL, 0); /* check if invalid request ID */ if ((requestid == 0) && (*argv[0] != '0')) { fprintf(stdout, "\nInvalid Requestid %s.
SNMPWALK Programming Examples Example 2-11. Contents of snmpwlkc (page 4 of 7) default: fprintf(stdout, usage, whoami); exit(0); } /* switch */ } /* while */ if (argc > 2 || argc == 0) { fprintf(stdout, usage, whoami); exit(0); } if (argc >= 1) { hostname = *argv; argv++,argc--; } if (argc == 1) oidstr = *argv; /* Init the output file */ outfile = stdout; /* Read the MIB tree file (and init the mibt global) */ read_mib ("mibrt"); <--3 /* convert string to OID using the just loaded MIB tree */ base_oid.
SNMPWALK Programming Examples Example 2-11. Contents of snmpwlkc (page 5 of 7) if (snmpagt != 0) { strcpy(host_int.agent_name, snmpagt); } if (dest_port != SNMP_REQUEST_PORT) { host_int.dest.sin_port = htons(dest_port); } if (timeout != 5) { host_int.timeout = timeout * 100; } err2 = SNMP_Open_(&host_int, debug_level); <--6 if (err2 != 0) { fprintf(stdout, "SNMP_OPEN_ returned error %i.
SNMPWALK Programming Examples Example 2-11. Contents of snmpwlkc (page 6 of 7) if (requestid == MAX_REQID_VALUE) requestid = 0; send_pkt->pdu.std_pdu.request_id = ++requestid; } err2 = SNMP_WriteRead_ (&host_int, send_pkt, &rcvd_pkt, &ebuff, <--10 debug_level); if (err2 != 0) { fprintf(stdout, "SNMP_WRITEREAD_ returned error %i (", err2); fprintf(stdout, SNMP_FS_ErrMsg_ (err2, host_int.
SNMPWALK Programming Examples Example 2-11. Contents of snmpwlkc (page 7 of 7) case VT_STRING: case VT_OPAQUE: if (vbp->value_u.v_string.start_bp != (OCTET_T *)0) EBufferClean(&(vbp->value_u.v_string)); break; case VT_OBJECT: Clean_Obj_ID(&(vbp->value_u.
SNMPTRAP Programming Examples SNMPTRAP SNMPTRAP sends a trap packet using the UDP protocol.
SNMPTRAP Programming Examples The default value of the manager host identifier is the IP address of the manager’s node. generic-trap-identifier is one of the standard generic trap integers or string values: 0 (coldStart) 1 (warmStart) 2 (linkDown) 3 (linkUp) 4 (authenticationFailure) 5 (egpNeighborLoss) 6 (enterpriseSpecific) The default is 0. specific-trap-number is an enterprise-defined integer that characterizes the trap in greater detail. The default is 0.
SNMPTRAP Programming Examples data-type describes the SNMP data type of a MIB object when it is not a MIB-II object. It must be one of these values: OCTET_STRING DisplayString OBJECT_IDENTIFIER NULL INTEGER IpAddress Counter Gauge TimeTicks Opaque value is the value of a MIB object. Enclose strings in double quotation marks (""), use a colon (:) to specify binary data, and use the dotted notation (1.2.3.4) or NonStop Kernel node name for IP addresses.
SNMPTRAP Programming Examples Example 2-13 illustrates the contents of snmptrpc, the source code file for SNMPTRAP. Numbers in the example correspond to numbers in the observations made between here and the example. 1. The default components of the enterprise OID are initialized. 2. The Manager Services define SNMP_TRAP_PORT is used to initialize the destination port value to 162. 3. The default value of the manager’s host is initialized. 4. Invocation line arguments are obtained. 5.
SNMPTRAP Programming Examples Example 2-13. Contents of snmptrpc (page 1 of 10) #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include #ifdef __TANDEM #include nolist #else #include #endif #include nolist #include
SNMPTRAP Programming Examples Example 2-13. Contents of snmptrpc (page 2 of 10) char usage[] = "Usage: %s [-l] [-n] [-c community] [-e enterprise] " "[-a managerhost] [-g generictrap] [-s specifictrap] [-t timestamp]" " [-p port] host [name [type] value] ...
SNMPTRAP Programming Examples Example 2-13.
SNMPTRAP Programming Examples Example 2-13. Contents of snmptrpc (page 4 of 10) hostname = *argv++; argc--; for (i = 0; argc > 0; i++) <--5 { if (i == MAXOIDS) { fprintf(stderr, "Exceeded %d object identifiers\n", MAXOIDS); exit(0); } if ((longform && argc < 3) || argc < 2) { fprintf(stderr, usage, whoami); exit(0); } oidstr[i] = *argv++; argc--; if (longform) { typestr[i] = *argv++; argc--; } valstr[i] = *argv++; argc--; } /* for loop */ oidcnt = i; dest.sin_family = AF_INET; dest.
SNMPTRAP Programming Examples Example 2-13. Contents of snmptrpc (page 5 of 10) name = ptr + 1; } /* of while */ /* if IP address contains invalid no.
SNMPTRAP Programming Examples Example 2-13. Contents of snmptrpc (page 6 of 10) if (isdigit(*agentstr)) <--8 { /* * error checking of IP address value * and error checking on inet_addr() */ name = agentstr; dots = 0; while ((ptr = strchr(name, '.')) != NULL) { dots++; /* keep track of no.
SNMPTRAP Programming Examples Example 2-13. Contents of snmptrpc (page 7 of 10) if (isdigit(*genstr)) <--9 { generic = strtol(genstr, (char **)NULL, 0); if (generic < 0 || generic > 6) { fprintf(stderr, "Invalid generic trap: %s\n", genstr); exit(0); } } else { if ((generic = str_to_trap(genstr)) < 0) { fprintf(stderr, "Invalid generic trap: %s\n", genstr); exit(0); } } send_pkt = SNMP_Create_Trap(VERSION_RFC1067, <--10 strlen(community), community, base_oid.num_components, base_oid.
SNMPTRAP Programming Examples Example 2-13. Contents of snmptrpc (page 8 of 10) if (asn1type && mibtype && mibtype != asn1type) fprintf(stderr,"WARNING: ASN.1 type supplied disagrees with MIB\n"); asn1type = asn1type ? asn1type : mibtype; switch (asn1type) <--12 { case VT_NUMBER: rcode = SNMP_Bind_Integer(send_pkt, i, base_oid.num_components, base_oid.
SNMPTRAP Programming Examples Example 2-13. Contents of snmptrpc (page 9 of 10) name = ptr + 1; } /* of while */ /* if IP address contains invalid no.
SNMPTRAP Programming Examples Example 2-13. Contents of snmptrpc (page 10 of 10) case VT_STRING: case VT_OPAQUE: rcode = SNMP_Bind_String( send_pkt, i, base_oid.num_components, base_oid.component_list, (OCTET_T) asn1type, hexcheck(valstr[i]), (unsigned char*)valstr[i], /* buffer is static */ 1); break; case VT_EMPTY: rcode = SNMP_Bind_Null(send_pkt, i, base_oid.num_components, base_oid.
SNMPMON Programming Examples SNMPMON SNMPMON monitors a UDP port for SNMP packets and prints any packets it receives. When you invoke this manager, you can optionally specify a port number and TCP/IP process name: SNMPMON [-p port-to-monitor] [-t tcp/ip-process-name] port-to-monitor identifies the UDP port to use for packet receipt. To use a port numbered less than 1024, the SNMPMON process must be started by a member of the super user group (255, n). The default value is 162.
SNMPMON Programming Examples Example 2-15. Contents of snmpmonc (page 1 of 5) #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #ifdef __TANDEM #include nolist #else #include #endif #include nolist #include
SNMPMON Programming Examples Example 2-15.
SNMPMON Programming Examples Example 2-15.
SNMPMON Programming Examples Example 2-15.
SNMPMON Programming Examples Example 2-15.
SNMPHOST Programming Examples SNMPHOST SNMPHOST retrieves and displays information from the hrDevice group of the Host Resources MIB defined by RFC 1514 using Get and GetNext packets encoded for UDP or IPC communication.
SNMPHOST Programming Examples Starting with the first entry in the hrDevice Table, SNMPHOST retrieves information from as many hrDeviceTable entries as you request at invocation. When the entry is for a processor, printer, or disk storage device, SNMPHOST also retrieves an additional value from the tables indicated in Figure 2-3. Table 2-5 provides some information about the MIB objects retrieved. Table 2-5. MIB Objects Retrieved by SNMPHOST MIB Object OID Description hrDeviceIndex 1.3.6.1.2.1.25.3.2.
SNMPHOST Programming Examples Invoke SNMPHOST as follows; invocation is similar to SNMPWALK invocation, except SNMPHOST accepts a -b parameter that lets you specify how you want information displayed.
SNMPHOST Programming Examples agent-request-port is the UDP destination port to use to address the agent. The default is 161. retry-count specifies the number of times to resend the packet if an error occurs. The default is 0. timeout-seconds is the number of seconds the manager should wait for request or response transmission completion before resending the request or terminating. The default is 5.
SNMPHOST Programming Examples Example 2-16 illustrates the output SNMPHOST generates when requested to retrieve information for 25 devices. Example 2-16. Sample SNMPHOST Output TACL> SNMPHOST -d 25 -a $zsnmp1 mynode ------ RUNNING LOCAL -----1 CPU00(NSR-P) running D30.02 running CPU load(19 %) 2 CPU01(NSR-P) running D30.02 running CPU load(12 %) 3 CPU02(NSR-P) running D30.02 running CPU load(28 %) 4 CPU03(NSR-P) running D30.02 running CPU load(75 %) 5 CPU04(NSR-P) running D30.
SNMPHOST Header File Programming Examples SNMPHOST Header File Example 2-17 shows the contents of snmphosh. Numbers in the example correspond to numbers in the observations made between here and the example. 1.
SNMPHOST Header File Programming Examples GetPrinterStatus() Retrieves the value of hrPrinterStatus from a structure of type DEV_ENTRY_T GetDiskCapacity() Retrieves the value of hrDiskStorageCapacity from a structure of type DEV_ENTRY_T oidstring2oid() Converts an OID formatted like a string ("1.3.
SNMPHOST Header File Programming Examples Example 2-17.
SNMPHOST Source Code Programming Examples SNMPHOST Source Code The source code of SNMPHOST defines and calls the functions declared in snmphosh to construct and parse packets and calls functions defined in snmpfsc to perform activities related to packet encoding, decoding, and transport. Figure 2-4 summarizes the calling sequence. Figure 2-4.
SNMPHOST Source Code Programming Examples Example 2-18 shows the contents of snmphosc. Numbers in the example correspond to numbers in the observations made between here and the figure: 1. Header files for packet-transmission and request/response-handling structures and functions are included. 2. Strings corresponding to hrDeviceStatus integers are defined. 3. Two encoded-packet buffers are declared, one for hrDeviceTable packets and one for auxiliary-table packets. 4.
SNMPHOST Source Code Programming Examples 11. The function SetCpuLoad() saves the value of hrProcessorLoad in the auxInfo.nCpuLoad field of a DEV_ENTRY_T structure for subsequent printing. The next function, GetCpuLoad() returns the value saved previously. 12. The function SetPrinterStatus() saves the value of hrPrinterStatus in the auxInfo.nPrinterStatus field of a DEV_ENTRY_T structure for subsequent printing. The next function, GetPrinterStatus() returns the value saved previously. 13.
SNMPHOST Source Code Programming Examples 19. The OID for hrDeviceType is prepared and bound to the request packet. 20. The OID for hrDeviceDescr is prepared and bound. 21. The OID for hrDeviceStatus is prepared and bound. 22. A while loop continues to send GetNext packets and process response packets as long as the value of bMoreEntries is 1. 23.
SNMPHOST Source Code Programming Examples 37. The OIDs for the three MIB objects this function can retrieve are initialized, and a request packet structure (pkt1) and response packet structure (recv_pkt1) are declared. 38. A packet for a Get request for a single MIB object is initialized. 39.
SNMPHOST Source Code Programming Examples 56. InitDevTable() allocates memory for retrieved device information. 57. Memory is allocated and descriptors initialized for the GetNext and Get encodedpacket buffers. 58. GetHostDevices() retrieves device information. 59. DisplayHostDevices() prints it. 60. Buffer memory is deallocated, and SNMP_Close_() terminates communication with the agent. Example 2-18.
SNMPHOST Source Code Programming Examples Example 2-18.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 3 of 23) static numprnstatus = sizeof(prn_status)/sizeof(char *); /* Return the printer status string */ static char* prn_status_to_str (long status) <--6 { static char default_str[40]; if (status >= numprnstatus) { sprintf(default_str, "%ld (%lX)", status, status); return (default_str); } return (prn_status[status]); } /* prn_status_to_str */ /* Provide name to OID translation.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 4 of 23) /* Compare two object identifiers with different lengths.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 5 of 23) } /* AllocateDevEntry */ void SetCpuLoad (DEV_ENTRY_T* pEntry, long nLoad) <--11 { pEntry->auxInfo.nCpuLoad = nLoad; } /* SetCpuLoad */ long GetCpuLoad (DEV_ENTRY_T* pEntry) { return pEntry->auxInfo.nCpuLoad; } /* GetCpuLoad */ void SetPrinterStatus (DEV_ENTRY_T* pEntry, long nStatus) <--12 { pEntry->auxInfo.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 6 of 23) GetDiskCapacity (DEV_ENTRY_T* pEntry) { return pEntry->auxInfo.nDiskCapacity; } /* GetDiskCapacity */ short GetHostDevices (SNMP_HOST_INT_T* host_int, <--14 DEV_ENTRY_T** ppDevTable, short devcnt, char* community, short retrycnt, int requestid) { short bMoreEntries; <--15 static OBJ_ID_T devIndexObj; short err1; char hrDeviceDescr[] = "1.3.6.1.2.1.25.3.2.1.3"; char hrDeviceIndex[] = "1.3.6.1.2.1.25.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 7 of 23) /* Save the hrIndex OID for later use */ devIndexObj.num_components = base_oid.num_components; <--18 devIndexObj.component_list = (OIDC_T*) malloc (sizeof(OIDC_T)* MAX_OID_COUNT); memcpy (devIndexObj.component_list, base_oid.component_list, sizeof(OIDC_T) * devIndexObj.num_components); SNMP_Bind_Null(pkt, vbIndex++, base_oid.num_components, base_oid.component_list); /* Set up the hrDeviceType */ base_oid.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 8 of 23) if (base_oid.num_components == 0) { fprintf(stdout, "Bad object identifier: %s\n", hrDeviceStatus); exit(0); } SNMP_Bind_Null(pkt, vbIndex++, base_oid.num_components, base_oid.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 9 of 23) { fprintf(stdout, "SNMP_WRITEREAD_ returned error %i (", err1); fprintf(stdout, SNMP_FS_ErrMsg_ (err1, host_int->err_num)); fprintf(stdout, ")\n"); SNMP_Free(recv_pkt); } else break; } /* for (i = 0; i <= retrycnt; i++) */ if (i > retrycnt) exit(0); SNMP_Free(pkt); <--24 EBufferReset(&ebuff); pkt = recv_pkt; <--25 if (pkt == 0) { printf ("No response from host.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 10 of 23) /* resetting request ID */ /* * PDU request ID is reset to 1 by setting * requestid to 0 and then incrementing it */ if (requestid == MAX_REQID_VALUE) requestid = 0; requestid++; <--26 pkt->pdu_type = GET_NEXT_REQUEST_PDU; pkt->pdu.std_pdu.request_id = requestid; pkt->pdu.std_pdu.error_status = 0; pkt->pdu.std_pdu.error_index = 0; vbp = pkt->pdu.std_pdu.std_vbl.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 11 of 23) /* pick up the last digit of the hrDeviceType field */ pCurrOutputEntry->nDeviceType = objp->component_list[objp->num_components-1]; vbp = &pkt->pdu.std_pdu.std_vbl.vblist[2]; <--30 if (vbp->vb_data_flags_n_type != VT_STRING) { printf ("Unexpected error (varbind[2] not OCTET STRING)\n"); exit(0); } pCurrOutputEntry->nDevDescrLen = EBufferUsed(&(vbp->value_u.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 12 of 23) } /* while (bMoreEntries) */ if (nCurrDevIndex == 0) { printf ("No Host MIB data found.\n"); printf ("Check to see if this host supports the host MIB.\n"); } SNMP_Free(pkt); <--35 return nCurrDevIndex; } /* GetHostDevices */ short GetAuxDeviceTbl (SNMP_HOST_INT_T* host_int, <--36 DEV_ENTRY_T* pDevTableEntry, char* community, short retrycnt, int requestid) { short err1; char hrDiskStorageCapacity[] = "1.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 13 of 23) case 5: /* printers */ SetPrinterStatus (pDevTableEntry, 0); base_oid.num_components = oidstring2oid (hrPrinterStatus, base_oid.component_list, MAX_OID_COUNT); if (base_oid.num_components == 0) { fprintf(stdout, "Bad object identifier: %s\n", hrPrinterStatus); exit(0); } break; case 6: /* disks */ SetDiskCapacity (pDevTableEntry, 0); base_oid.num_components = oidstring2oid (hrDiskStorageCapacity, base_oid.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 14 of 23) /* Send packet and receive response */ for (i = 0; i <= retrycnt; i++) <--43 { if (i == 0) { firstid = requestid; } else { fprintf(stdout, "\n---RESENDING PACKET---\n"); /* resetting request ID */ /* * PDU request ID is reset to 1 by setting * requestid to 0 and then incrementing it */ if (requestid == MAX_REQID_VALUE) requestid = 0; pkt1->pdu.std_pdu.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 15 of 23) switch (pkt1->pdu.std_pdu.error_status) { case NO_ERROR: break; default: printf ("Unexpected error (%d)\n", pkt1->pdu.std_pdu.error_status); exit(0); } /* switch error_status */ vbp1 = pkt1->pdu.std_pdu.std_vbl.vblist; switch (pDevTableEntry->nDeviceType) { <--45 case 3: /* processors */ SetCpuLoad (pDevTableEntry, vbp1->value_u.
SNMPHOST Source Code Programming Examples Example 2-18.
SNMPHOST Source Code Programming Examples Example 2-18.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 18 of 23) case 19: /* clock */ printf (" (clock device)"); break; case 20: /* volatile memory */ printf (" (volatile memory device)"); break; case 21: /* non-volatile memory */ printf (" (non-volatile memory device)"); break; default: break; } /* switch */ printf ("\n"); lineCnt++; if (!bBatchMode) { <--51 if ((lineCnt % nPageSize) == 0) { printf (".....ENTER to continue."); printf (" SPACE to stop.
SNMPHOST Source Code Programming Examples Example 2-18.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 20 of 23) host_int.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 21 of 23) /* check if the requestid value is within range */ if (errno == ERANGE) { fprintf(stdout, "\nInvalid Requestid %s.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 22 of 23) err2 = SNMP_Init_ (&host_int, sizeof(host_int), hostname); <--54 switch (err2) { case 0: case 1: break; default: exit(0); } /* end switch */ /*************************************************************************/ /* Now I can override any default. This must be done before the */ /* call to SNMP_Open_. */ if (snmpagt != 0) { strcpy(host_int.
SNMPHOST Source Code Programming Examples Example 2-18. Contents of snmphosc (page 23 of 23) { fprintf(stdout, "Not enough memory for the main SNMP buffer.\n"); exit(0); } EBufferSetup(BFL_IS_DYNAMIC, &ebuff, buffp, need); /* Obtain buffer space for the AUX packets */ if ((buffp = (char *)SNMP_memory_alloc(need)) == 0) { fprintf(stdout, "Not enough memory for the AUX SNMP buffer.
SNMPHOST Source Code Programming Examples SNMP Manager Programmer’s Guide– 134249 2 -149
SNMPHOST Source Code Programming Examples SNMP Manager Programmer’s Guide– 134249 2 -150
3 Using the MIB Compiler The MIB compiler parses ASN.1 MIB definitions and creates output useful when writing MIB object handling logic: • • Output useful for reference while programming can be generated using the -numbers and -statistics options. Output that is program-readable can be generated using the -nametree and -readtree options. When you invoke the MIB compiler, you identify all the files you want it to parse. The MIB compiler performs ASN.
Using the MIB Compiler 1 1.3 1.3.6 1.3.6.1 1.3.6.1.1 1.3.6.1.2 1.3.6.1.2.1 1.3.6.1.2.1.25 1.3.6.1.2.1.25.3 1.3.6.1.2.1.25.3.1 1.3.6.1.2.1.25.3.1.1 1.3.6.1.2.1.25.3.1.2 1.3.6.1.2.1.25.3.1.3 1.3.6.1.2.1.25.3.1.4 1.3.6.1.2.1.25.3.1.5 1.3.6.1.2.1.25.3.1.6 1.3.6.1.2.1.25.3.1.10 1.3.6.1.2.1.25.3.1.11 1.3.6.1.2.1.25.3.1.12 1.3.6.1.2.1.25.3.1.13 1.3.6.1.2.1.25.3.1.14 1.3.6.1.2.1.25.3.1.15 1.3.6.1.2.1.25.3.1.16 1.3.6.1.2.1.25.3.1.17 1.3.6.1.2.1.25.3.1.18 1.3.6.1.2.1.25.3.1.19 1.3.6.1.2.1.25.3.1.20 1.3.6.1.2.1.25.3.
Using the MIB Compiler -nametree generates an output file containing C code defining an array of structures that your manager can use for OID-to-name conversion and vice versa. The file is compiled into the manager, so the manager must be re-compiled whenever you want it to handle additional MIB objects using the -nametree output.
Using the MIB Compiler -readtree generates an output file containing ASCII text describing MIB objects. The file can be loaded at run time by a manager that can interpret the text format to perform OID-to-name conversion and vice versa. Because the -readtree file is dynamically read, changing its contents does not require manager recompilation.
Using the MIB Compiler -exclude MIB-module-name.MIB-object-name eliminates output for selected MIB objects. For example, to avoid generating -numbers output for the snmp group in MIB-II and the hrSystem group in the Host Resources MIB, invoke the MIB compiler like this: mibcomp -numbers -exclude RFC1213-MIB.snmp -exclude HOSTRESOURCES-MIB.
Using the MIB Compiler @ automated-response-file-name identifies an input file containing MIB compiler invocation specifications. Specifications in an automated response file can be written one to a line, or can be separated by spaces on a line. Precede comment lines with a semicolon (;), two hyphens (--), or a pound sign (#). Here is an example of an automated response file: ; This is an example automated response file.
4 Using Header Files, Data Structures, and Defines This section describes Manager Services data definitions used in conjunction with the library functions. Header Files Table 4-1 summarizes the Manager Services header files you need to include in your manager source code. Although Manager Services provides additional header files, these are the only ones you need to explicitly include. The other header files are included as needed by those listed in Table 4-1. Table 4-1.
Using Header Files, Data Structures, and Defines Packet-Handling Structures Table 4-2. Manager Services Typedefs Typedef Description ALENGTH_T The fully decoded value of an ASN.1 length field ATVALUE_T The fully decoded value of an ASN.
Encoded-Packet Structure (EBUFFER_T) Using Header Files, Data Structures, and Defines num_components holds the number of integers in the sequence of integers making up an OID. For example, an OID of 1.2.3.4 has four components. component_list points to an array of elements of type OIDC_T. OIDC_T is a Manager Services typedef for a 32-bit unsigned integer. Each element in the array holds one of the OID integers.
Unencoded-Packet Structure (SNMP_PKT_T) Using Header Files, Data Structures, and Defines Unencoded-Packet Structure (SNMP_PKT_T) This structure holds a request, response, or trap packet. The following fields in this structure are of interest to Manager Services programmers; most of the field types are typedefs listed earlier in Typedefs on page 4-1. typedef struct SNMP_PKT_S { ... UINT_16_T lcl_ident ... INT_32_T snmp_version; ... EBUFFER_T community; ...
Unencoded-Packet Structure (SNMP_PKT_T) Using Header Files, Data Structures, and Defines pdu_type characterizes the kind of PDU in the packet. The following Manager Services defines describe values for pdu_type: #define #define #define #define #define #define GET_REQUEST_PDU GET_NEXT_REQUEST_PDU GET_RESPONSE_PDU SET_REQUEST_PDU TRAP_PDU NO_PDU 0 1 2 3 4 0xFF pdu_length is the number of bytes in the PDU.
Using Header Files, Data Structures, and Defines Unencoded-Packet Structure (SNMP_PKT_T) std_vbl is a structure of type VBL_T that describes the variable bindings associated with the packet. The structure contains several fields of interest to Manager Services programmers: typedef struct VBL_S { ALENGTH_T vbl_length; int vbl_count; VB_T *vblist; ... } VBL_T; vbl_length is the number of bytes in vblist. vbl_count is the number of variable bindings in vblist.
Unencoded-Packet Structure (SNMP_PKT_T) Using Header Files, Data Structures, and Defines vb_obj_id is the OID of the variable binding. vb_data_flags_n_type describes the class form and data type of the variable binding.
Decoding Statistics Structure (SNMP_STATS_T) Using Header Files, Data Structures, and Defines generic_trap is the generic trap type. The following Manager Services defines describe values for this field: #define #define #define #define #define #define #define COLD_START WARM_START LINK_DOWN LINK_UP AUTH_FAILURE EGP_NEIGHBOR_LOSS ENTERPRISE_SPECIFIC 0 1 2 3 4 5 6 specific_trap is the specific trap code. trap_time_ticks is the timestamp associated with the trap.
Using Header Files, Data Structures, and Defines Decoding Statistics Structure (SNMP_STATS_T) Here is a description of the fields in this structure that are of interest to Manager Services programmers: typedef struct SNMP_STATS_S { unsigned long snmpInPkts; unsigned long snmpInBadCommunityNames; unsigned long snmpInBadCommunityUses; unsigned long snmpInASNParseErrs; unsigned long snmpOutPkts; unsigned long snmpInBadVersions; unsigned long snmpInBadTypes; unsigned long snmpInTooBigs; unsigned long snmpInNo
Defines Using Header Files, Data Structures, and Defines Defines Table 4-3 summarizes some Manager Services defines you may find useful. Table 4-3. Useful Manager Services Defines Define Name Value MAX_OID_COUNT 32 SNMP_MAX_PACKET_SIZE 1400 SNMP_MIN_PACKET_SIZE 484 SNMP_REQUEST_PORT 161 SNMP_TRAP_PORT 162 SNMP_VERSION_1 0 IPC encoding results in packets that are much less compact than those created using BER encoding.
5 Constructing and Interpreting Packets Packets are the messages exchanged between SNMP entities to retrieve, change, or report on the values of MIB objects. This section briefly explores the nature of the three kinds of packets (request, response, and trap) and how you use Manager Services functions and structures to construct request and trap packets and interpret response and trap packets.
Request and Response Packets Constructing and Interpreting Packets Table 5-1. Assigning Version and Community Values Packet Field Assigned Value By Value Description version SNMP_Create_Request() SNMP_Create_Trap() You use one of the following defines to set this value to 0: VERSION_RFC1067 VERSION_RFC1098 VERSION_RFC1157 SNMP_VERSION_1 Agents, subagents, or other managers For trap packets assembled elsewhere, this value is assigned by the originating entity.
Request and Response Packets Constructing and Interpreting Packets Table 5-2. Assigning Request and Response Packet Values Packet Field Assigned Value By PDU type SNMP_Create _Request() You use one of the following defines to set the PDU type to the indicated integer when you construct a request packet: GET_REQUEST_PDU (0) GET_NEXT_REQUEST_PDU (1) SET_REQUEST_PDU (3) Manager Services Response PDUs contain a PDU type of GET_RESPONSE_PDU (2).
Trap Packets Constructing and Interpreting Packets Trap Packets Figure 5-3 illustrates the fields in a trap packet. The PDU type identifies the PDU as a Trap PDU. The enterprise field is an OID identifying the trap originator. The address is the IP address of the trap originator. The generic-trap and specific-trap fields are integers that characterize the trap. Figure 5-3.
Variable Bindings Constructing and Interpreting Packets Variable Bindings A variable binding is a pair of values describing a MIB object: the object’s instance identifier and its value. The value is null in Get and GetNext requests, has a managerassigned value in Set requests, and has an agent- or subagent-assigned value in response packets. Trap packets may or may not have variable bindings associated with them.
Constructing and Interpreting Packets Instance Identifiers The MIB description for a table identifies the table’s index object, which is one or more of the objects in each table entry. For example, the zhrmDevUnTable in the Host Resources Subagent’s MIB is defined as a sequence of entries consisting of six MIB objects, one of which (zhrmDevUnIndex) is the index object: zhrmDevUnTable OBJECT-TYPE SYNTAX SEQUENCE OF ZhrmDevUnEntry ... zhrmDevUnEntry OBJECT-TYPE SYNTAX ZhrmDevUnEntry ...
Lexicographic Ordering Constructing and Interpreting Packets Some entries have index values derived from multiple entry objects. The TCP group of MIB-II contains a table, tcpConnTable, whose entries are indexed using the values of four objects: tcpConnLocalAddress, tcpConnLocalPort, tcpConRemAddress, and tcpConnRemPort. So an instance identifier for any of the objects in an entry contains the object’s OID plus a suffix consisting of the values of each of the four index objects.
Associating Variable Bindings With Packets Constructing and Interpreting Packets Figure 5-5.
Associating Variable Bindings With Packets Constructing and Interpreting Packets Table 5-4. Assigning Variable Bindings (page 2 of 3) Data Item Assigned Value By instance identifiers values Value Description SNMP_PKT_T Field SNMP_Bind_ functions For request or trap packets you assemble, you assign an instance identifier for each variable binding.
Interpreting Received Packets Constructing and Interpreting Packets Table 5-4. Assigning Variable Bindings (page 3 of 3) Data Item Assigned Value By syntax Manager Services Value Description SNMP_PKT_T Field For request and trap packets, Manager Services determines the data type of the variable binding from the SNMP_Bind_ call you use. For requests and responses: pdu.std_pdu.std_vbl. vblist.vb_data_flags_ n_type For traps: pdu.trap_pdu.trap_vbl. vblist.
Interpreting Received Packets Constructing and Interpreting Packets Table 5-5. Using SNMP_PKT_T to Interpret Received Packets (page 2 of 2) Retrieve This Packet Information PDU type 2 (Response PDU) 4 (Trap PDU) From This Field in SNMP_PKT_T pdu_type For responses: request-id error-status error-index pdu.std_pdu.request_id pdu.std_pdu.error_status pdu.std_pdu.error_index For traps: enterprise address generic-trap specific-trap time-stamp pdu.trap_pdu.enterprise_objid.component-list pdu.trap_pdu.
Constructing and Interpreting Packets Functions for Initializing Packets Functions for Initializing Packets There are two Manager Services functions for initializing a packet. You use SNMP_Create_Request() when creating a request packet and SNMP_Create_Trap() when creating a trap packet. This subsection describes and provides examples for these two functions. SNMP_Create_Request() This function initializes a request packet for a Get, GetNext, or Set PDU.
Constructing and Interpreting Packets SNMP_Create_Request() VERSION_RFC1067 VERSION_RFC1098 VERSION_RFC1157 SNMP_VERSION_1 community-length is the number of bytes in the community identifier to which communityidentifier points. community-identifier is a pointer to a character buffer containing the community identifier. request-id is an integer you use to correlate the request packet with a subsequent response packet.
Constructing and Interpreting Packets SNMP_Create_Trap() SNMP_Create_Trap() This function initializes a trap packet. It dynamically allocates memory for a packet structure of type SNMP_PKT_T, assigns to it all trap packet variables except variable bindings, and returns a pointer to the structure. To associate variable bindings with the packet, use the functions defined in Functions for Binding MIB Objects on page 5-17.
Constructing and Interpreting Packets SNMP_Create_Trap() community-identifier is a pointer to a character buffer containing the community identifier. enterprise-count is the number of components in the OID identifying the enterprise whose value you supply in enterprise-components. For example, a Tandem enterprise identifier of 1.1.3.6.1.4.1.169 has a component count of 8.
Constructing and Interpreting Packets SNMP_Create_Trap() number of elements in the OID component array and the component count variable to 32: OIDC_T snmp_product_id[] = { /* ISO */ 1, /* ORG */ 3, /* DOD */ 6, /* INTERNET */ 1, /* PRIVATE */ 4, /* ENTERPRISES */ 1, /* Tandem */ 169, /* nonstopsystems */ 3 }; int snmp_product_id_count=sizeof(snmp_product_id)/sizeof(OIDC_T); ...
Functions for Binding MIB Objects Constructing and Interpreting Packets Then the trap packet is initialized: send-pkt = SNMP_Create_Trap(VERSION_RFC1067, strlen(community), community, base_oid.num_components, base_oid.component_list, (OCTET_T *)&host_addr, generic, specific, timestamp, oidcnt); Functions for Binding MIB Objects After initializing a request or trap packet, you bind variable bindings to it using one SNMP_Bind_ function per variable binding.
SNMP_Bind_Integer() Constructing and Interpreting Packets SNMP_Bind_Integer() This function associates a variable binding of type INTEGER with a packet previously initialized with SNMP_Create_Request() or SNMP_Create_Trap(). rcode = SNMP_Bind_Integer(packet, index, instance-count, instance-components, value); int SNMP_Bind_Integer(SNMP_PKT_T int int OIDC_T INT_32_T *packet, index, instance-count, *instance-components, value); rcode is a return integer indicating whether the call succeeded.
Constructing and Interpreting Packets SNMP_Bind_Integer() several variables in the main block; the Manager Services define MAX_OID_COUNT is used to set the number of elements in the OID component array and the component count variable to 32.
SNMP_Bind_IP_Address() Constructing and Interpreting Packets The value of peertype, which holds the Manager Services representation for the SNMP data type for the target MIB object, is used to determine which SNMP_Bind_ function to call. The function SNMP_Bind_Integer() is called when the value of peertype is VT_NUMBER: switch (peertype) { case VT_NUMBER: rcode = SNMP_Bind_Integer(send_pkt, i, base_oid.num_components, base_oid.
Constructing and Interpreting Packets SNMP_Bind_IP_Address() instance-count is the number of components in the instance identifier whose value you supply in instance-components. For example, an instance identifier of 1.2.3.4 has a component count of 4. instance-components is a pointer to a structure of type OIDC_T that contains the instance identifier of the variable binding. value is a pointer to a 4-byte area containing the value of the variable binding.
Constructing and Interpreting Packets SNMP_Bind_IP_Address() function str_to_type() is used to validate whether the type specified at invocation is a valid SNMP data type and converts it to the Manager Services representation for it.
SNMP_Bind_Null() Constructing and Interpreting Packets SNMP_Bind_Null() This function associates a variable binding of type NULL with a packet previously initialized with SNMP_Create_Request() or SNMP_Create_Trap(). Use this function to bind all MIB variables in Get and GetNext PDUs or to bind a NULL MIB variable in Set or Trap PDUs.
Constructing and Interpreting Packets SNMP_Bind_Null() invocation line specifies MIB objects that are not defined in MIB-II. Manager Services has an internal table it can use to find the data type of MIB-II objects: #define MAXOIDS 16 OIDC_T base_component_list[MAX_OID_COUNT]; OBJ_ID_T base_oid = { MAX_OID_COUNT, base_component_list }; ...
SNMP_Bind_Object_ID() Constructing and Interpreting Packets The value of peertype, which holds the Manager Services representation for the SNMP data type for the target MIB object, is used to determine which SNMP_Bind_ function to call. The function SNMP_Bind_Null() is called when the value of peertype is VT_EMPTY: switch (peertype) { case VT_EMPTY: rcode = SNMP_Bind_Null(send_pkt, i, base_oid.num_components, base_oid.
Constructing and Interpreting Packets SNMP_Bind_Object_ID() instance-count is the number of components in the instance identifier whose value you supply in instance-components. For example, an instance identifier of 1.2.3.4 has a component count of 4. instance-components is a pointer to a structure of type OIDC_T that contains the instance identifier of the variable binding. value-count is the number of components in the OID whose value you supply in valuecomponents.
Constructing and Interpreting Packets SNMP_Bind_Object_ID() A for loop extracts instance identifiers from the invocation line arguments, stores any data type entered in typestr, and stores the value entered in valstr: for (i = 0; argc > 0; i++) { ... oidstr[i] = *argv++; argc--; if (longform) { typestr[i] = *argv++; argc--; } valstr[i] = *argv++; argc--; } oidcnt = i; After the request packet is initialized into send_pkt, a for loop is used to assign variable bindings to it.
SNMP_Bind_String() Constructing and Interpreting Packets SNMP_Bind_String() This function associates a variable binding of type OCTET_STRING, DisplayString, Opaque, or NSAPADDRESS with a packet previously initialized with SNMP_Create_Request() or SNMP_Create_Trap().
Constructing and Interpreting Packets SNMP_Bind_String() data-type indicates the SNMP data type of the object being bound. Assign one of these values: VT_STRING VT_OPAQUE VT_NSAPADDRESS value-length is the number of bytes in the value. value is a pointer to a buffer containing the string value. buffer-flag is an indication of whether you want Manager Services to allocate dynamic memory for holding a copy of your string value or to use a the buffer you have already allocated for it.
Constructing and Interpreting Packets SNMP_Bind_String() A for loop extracts instance identifiers from the invocation line arguments, stores any data type entered in typestr, and stores the value entered in valstr: for (i = 0; argc > 0; i++) { ... oidstr[i] = *argv++; argc--; if (longform) { typestr[i] = *argv++; argc--; } valstr[i] = *argv++; argc--; } oidcnt = i; After the request packet is initialized into send_pkt, a for loop is used to assign variable bindings to it.
Constructing and Interpreting Packets SNMP_Bind_Unsigned_Integer() SNMP_Bind_Unsigned_Integer() This function associates a variable binding of type Counter, Gauge, Timeticks, or UINTEGER32 with a packet previously initialized with SNMP_Create_Request() or SNMP_Create_Trap().
Constructing and Interpreting Packets SNMP_Bind_Unsigned_Integer() data-type indicates the SNMP data type of the object being bound. Assign one of these values: VT_COUNTER VT_GAUGE VT_TIMETICKS VT_UINTEGER32 value is an unsigned integer value to be assigned to the variable binding. The following example, taken from SNMPSET, binds an unsigned integer value to a request packet. Related declarations include a global define and OID structure declaration.
Constructing and Interpreting Packets Function for Releasing Packet Memory valid SNMP data type and converts it to the Manager Services representation for it.
Constructing and Interpreting Packets Function for Releasing Packet Memory SNMP Manager Programmer’s Guide– 134249 5- 34
6 Encoding and Decoding Packets Before you transmit an SNMP request or trap packet, it needs to be encoded into a format that can be interpreted by the receiving entity. Manager Services supports two encoding formats: • • BER (Basic Encoding Rules) encoding. BER encoding is a standard way to encode ASN.1 information as octet strings. BER-encoded packets can be transmitted over any transport protocol that the receiving entity supports.
EBUFFER_T Attributes Encoding and Decoding Packets EBUFFER_T Attributes Buffers that hold encoded packets must be described by the EBUFFER_T structure, defined in Section 4, Using Header Files, Data Structures, and Defines,, although you can use EBUFFER_T buffers for any buffer in your manager: EBUFFER_T ebuff; The EBUFFER_T type provides a set of descriptors for a buffer. It does not itself allocate the storage to hold information.
Encoding and Decoding Packets Initializing the Encoded-Packet Buffer Descriptors Manager Services Memory Allocation If your manager has not allocated memory when you call SNMP_Encode_Packet() or tdm_SNMP_Encode_Packet(), Manager Services dynamically allocates enough memory to hold the encoded packet.
Encoding Packets Encoding and Decoding Packets After the call to EBufferSetup(), the start_bp and next_bp indicators point to the start of the buffer, and the value of remaining is the number of bytes you allocated. ebuff remaining start_bp next_bp 604 Encoding Packets After you have initialized an encoded-packet buffer, you use SNMP_Encode_Packet() or tdm_SNMP_Encode_Packet() to encode into it the contents of a request or trap packet.
Releasing Encoded-Packet Buffer Memory Encoding and Decoding Packets Releasing Encoded-Packet Buffer Memory When you no longer need a buffer for which space has been dynamically allocated by you or by Manager Services, you use the EBufferClean() function to release allocated memory: EBufferClean(&ebuff); This function releases memory allocated for the buffer and calls EBufferInitialize(), setting the buffer descriptors as described for that function.
Using a Buffer for General Purposes Encoding and Decoding Packets • EBufferPreLoad() sets up buffer descriptors for a buffer to which you have already written information but have not initialized using the buffer functions: EBufferPreLoad(BFL_IS_DYNAMIC, &ebuff, buffp, length); ebuff length buffp EBufferPreLoad() ebuff start_bp next_bp remaining = 0 • 605 EBufferClone() copies a buffer into a second buffer it dynamically allocates, duplicating the contents of the source buffer and its buffer des
Functions for Managing an EBUFFER_T Buffer Encoding and Decoding Packets Functions for Managing an EBUFFER_T Buffer This subsection describes and provides examples for the functions listed in Table 6-1, which are used for initializing and managing EBUFFER_T buffers. Table 6-1. Functions for Managing EBUFFER_T Buffers Function Description EBufferClean() Releases dynamically obtained memory for a buffer and calls EBufferInitialize().
Encoding and Decoding Packets EBufferClone() The sample managers call this function after packet processing is finished and before terminating: EBUFFER_T ebuff; EBufferClean(&ebuff); SNMPWALK uses EBufferClean() to release memory associated with an octet string in a response packet when rebuilding the response packet to become the next request packet.
EBufferInitialize() Encoding and Decoding Packets This function is useful when you need to save buffers, as when your manager handles multiple request or trap packets and you want to use previously encoded buffers in the event a retry operation is indicated. An example of this function is: EBUFFER_T EBUFFER_T buffsrc; buffdup1; rcode = EBufferClone(&buffsrc, &buffdup1); EBufferInitialize() This function initializes the buffer descriptors of an EBUFFER_T buffer to zero.
EBufferPreLoad() Encoding and Decoding Packets next-ptr identifies where to return the value of next_bp. buffer a pointer to the descriptor structure for the buffer for which you want to retrieve next_bp.
Encoding and Decoding Packets EBufferRemaining() flags is one of the following integers corresponding to the define you specify in your first argument: 0 (BFL_IS_DYNAMIC) 1 (BFL_IS_STATIC) The following call initializes ebuff pointers so that the value “Save me” is preserved: EBUFFER_T char ebuff; buff[20] = "xxSave me zzzz"; EBufferPreLoad(BFL_IS_STATIC, &ebuff, &buff[2], 7); EBufferRemaining() This function returns the value of the EBUFFER_T buffer descriptor named remaining, which indicates the num
EBufferSetup() Encoding and Decoding Packets buffer a pointer to the descriptor structure for the buffer whose buffer descriptors you want reset. The following call resets buffer descriptors in ebuff: EBUFFER_T ebuff; EBufferReset(&ebuff); EBufferSetup() This function initializes buffer descriptors for a buffer you have obtained static or dynamic memory for, setting start_bp and next_bp to point to the first byte in the buffer and the value of remaining to the number of bytes you allocated.
Encoding and Decoding Packets EBufferStart() The sample manager SNMPGET dynamically allocates a 2000-byte buffer for the encoded-packet buffer, then calls EBufferSetup() to prepare the buffer for receiving the encoded packet: EBUFFER_T ebuff; int need; char *buffp; need = 2000; if ((buffp = (char *)SNMP_memory_alloc(need)) ==0 return (-1); EBufferSetup(BFL_IS_DYNAMIC, &ebuff, buffp, need); EBufferStart() This function returns the value of start_bp, the EBUFFER_T descriptor that points to the first byte o
SNMP_memory_alloc() Encoding and Decoding Packets buffer is a pointer to the descriptor structure of the buffer for which you want to know the number of used bytes. The sample manager SNMPGT calls EBufferUsed() to determine how many bytes to write to the buffer used to transmit a request. The variable sndbuff is the encodedpacket buffer used for requests.
Encoding and Decoding Packets Functions for Encoding Packets Functions for Encoding Packets After you have initialized an encoded-packet buffer, you use one of these functions to encode into it the contents of a request or trap packet: • • SNMP_Encode_Packet() BER-encodes the packet. BER encoding can be interpreted by any SNMP agent or manager. tdm_SNMP_Encode_Packet() can either BER- or IPC-encode a packet. IPC encoding can be interpreted by a NonStop agent process.
Encoding and Decoding Packets tdm_SNMP_Encode_Packet() memory allocated is sufficient, then proceeds only if it is. If you have not allocated memory for the buffer, this function dynamically allocates enough memory to hold the encoded packet. rcode = tdm_SNMP_Encode_Packet(packet, buffer, mode); int SNMP_Encode_Packet(SNMP_PKT_T* packet, EBUFFER_T* buffer short mode); rcode is an integer describing the outcome of the call. If the call is successful, 0 is returned; if not, -1 is returned.
Encoding and Decoding Packets Function for Decoding Packets Function for Decoding Packets When you receive a response or trap packet, regardless of whether the packet is BER- or IPC-encoded, you use SNMP_Decode_Packet_WER() to decode it into a structure of type SNMP_PKT_T, which this function allocates dynamically. Dynamically allocated memory should be released by using SNMP_Free() when you no longer need the decoded-packet structure.
Encoding and Decoding Packets Function for Decoding Packets The sample managers that support both UDP and IPC obtain the number of bytes read when the packet was received by calling AWAITIOX(). Before decoding BER-encoded packets, the start_bp pointer is set to the byte after the socket address: short SNMP_PKT_T EBUFFER_T long read_cnt; **rpkt; myEBuff; err2 = 0; AWAITIOX (&temp_file_num, (long*) &IOC_buffp, &read_cnt, &IO_tag, (long)(host_int->timeout)); host_int->count_read = read_cnt; ...
7 Sending and Receiving Packets After encoding a request or trap packet, you transmit it. Request packets are sent to SNMP agents, and trap packets to other managers. After a request packet has been processed, you receive and interpret its corresponding response packet. The logic you use for sending and receiving encoded packets depends on the way the packets are encoded: • • To transmit and receive IPC-encoded packets, you use NonStop Kernel interprocess communication calls.
Establishing Communication Sending and Receiving Packets Establishing Communication The FILE_OPEN_() system call, made from the SNMP_Open_() function defined in snmpfsc, establishes a communication path between the manager and NonStop agent processes. In preparation for this call, the NonStop agent process name is assigned to the variable named temp_file_name.
Sending Packets Sending and Receiving Packets Sending Packets The function SNMP_Write_Read_(), defined in snmpfsc, performs packet encoding, sending, receipt, and decoding. This function uses several local variables for these purposes: err The return code from the call to the tdm_SNMP_Encode_Packet() encoding function. IO_tag A tag returned by AWAITIOX() calls following read and write operations. IOC_buffp The buffer pointer returned by AWAITIOX() calls following read and write operations.
Sending Packets Sending and Receiving Packets After EBufferReset() reinitializes the ebuffp descriptors, a second descriptor structure, myEBuff, is initialized. Two sets of descriptors are needed because the buffers transmitted using the IPC protocol vary slightly from those using the UDP protocol.
Receiving Packets Sending and Receiving Packets If the NonStop agent detects an error, it generates an EMS event and returns a file system error number of 306. Receiving Packets The descriptors of the encoded-packet buffer are reinitialized in preparation for handling the response packet: EBufferReset(ebuffp); EBufferReset(&myEBuff); Response packets are received into the buffer pointed to by ebuffp, starting at the byte to which start_bp points.
Sending Packets Sending and Receiving Packets value of the target IP address. The destination port value is replaced if a port number is specified at invocation: host_int->dest.sin_family = AF_INET; host_int->dest.sin_port = htons(SNMP_REQUEST_PORT); host_int->dest.sin_addr.s_addr = host_int->host_addr; Figure 7-2.
Receiving Packets Sending and Receiving Packets bytes to send is the sum of the socket information and the number of used bytes indicated by myEBuff: send_cnt = EBufferUsed(&myEBuff); memcpy (ebuffp->start_bp, (void*) &host_int->dest, sizeof(struct sockaddr_in); send_cnt += sizeof(struct sockaddr_in); A t_sendto_nw() call sends the encoded-packet buffer on the nowait socket.
Receiving Packets Sending and Receiving Packets SNMP Manager Programmer’s Guide– 134249 7 -8
8 Building Executable Managers Among the sample manager files provided with Manager Services are two scripts for building executable managers from the source code files: • • To build managers that run as Guardian processes, you use grdbuild. To build managers that run as OSS processes, you use ossbuild. This section describes grdbuild and ossbuild. Building Guardian Managers The TACL OBEY command file that builds managers that run as Guardian processes, grdbuild, is shown in Example 8-1.
Building Guardian Managers Building Executable Managers Example 8-1. Script for Building Guardian Managers (page 1 of 3) #push myParms <--1 #push bindOptions #set myParms wide, symbols, columns 110, nowarn (84,143),& <--2 ssv0 "[#defaults]",& ssv1 "$DSV.ZSNMPMGR",& ssv2 "$system.ztcpip",& ssv3 "$system.system" [#set :bindOptions & <--3 + set inspect on, symbols on + mode noUpShift + set heap 64 pages + set runnamed OFF, highpin ON, highrequesters ON + select search $SYSTEM.ZTCPIP.
Building Guardian Managers Building Executable Managers Example 8-1. Script for Building Guardian Managers (page 2 of 3) INLPREFIX + bind /inline,OUT $S.#GET2/ [:bindOptions] + add * from SNMPGTO + build SNMPGT! + exit bind /inline, OUT $S.#HOST1/ [:bindOptions] + add * from SNMPHOSO + add * from SNMPFSO + build SNMPHOST! + exit bind /inline, OUT $S.#MON1/ [:bindOptions] + add * from SNMPMONO + build SNMPMON! + exit bind /inline, OUT $S.
Building OSS Managers Building Executable Managers Example 8-1. Script for Building Guardian Managers (page 3 of 3) bind /inline,OUT $S.#WALK1/ [:bindOptions] + add * from SNMPFSO + add * from SNMPWLKO + add * from READMIBO + add * from RTUTILSO + build SNMPWALK! + exit #pop bindOptions #pop myParms Building OSS Managers The make file that builds managers that run as OSS processes, ossmake, is shown in Example 8-2.
Building OSS Managers Building Executable Managers Example 8-2. Script for Building OSS Managers (page 1 of 3) ############################################################# # The following defines need to be changed to match your # # system's configuration.
Building OSS Managers Building Executable Managers Example 8-2. Script for Building OSS Managers (page 2 of 3) ############################################################# # SNMPGT # ############################################################# $(myossdir)/snmpgt: snmpgt.o $(CC) -o $(myossdir)/snmpgt $(CFLAGS) $(myossdir)/snmpgt.o $(LIBS) $(OBJS) snmpgt.o: $(myossdir)/snmpgt.c $(CC) -o $(myossdir)/snmpgt.o -c $(myossdir)/snmpgt.
Building OSS Managers Building Executable Managers Example 8-2. Script for Building OSS Managers (page 3 of 3) ############################################################# # SNMPMON # ############################################################# $(myossdir)/snmpmon: snmpmon.o $(CC) -o $(myossdir)/snmpmon $(CFLAGS) $(myossdir)/snmpmon.o $(LIBS) $(OBJS) snmpmon.o: $(myossdir)/snmpmon.c $(CC) -o $(myossdir)/snmpmon.o -c $(myossdir)/snmpmon.
Building OSS Managers Building Executable Managers SNMP Manager Programmer’s Guide– 134249 8 -8
9 Reference Summary This section provides quick-reference information on the following topics: The sample managers Sample manager features Sample manager files Common utility functions Sample manager invocation MIB compiler invocation Library header files Typedefs Packet-handling structures OID structure (OBJ_ID_T) Encoded-packet structure (EBUFFER_T) Unencoded-packet structure (SNMP_PKT_T) Decoding statistics structure (SNMP_STATS_T) Defines Packet-construction functions Initializing packets Binding MIB
The Sample Managers Reference Summary The Sample Managers Sample Manager Features Sample Manger Protocol Supported Functions SNMPGT UDP Handles a Get packet for MIB objects specified at invocation. SNMPGET UDP and IPC Same as SNMPGT, except makes IPC communication available for requests for NonStop agents. SNMPNEXT UDP and IPC Handles a GetNext packet for MIB objects specified at invocation. SNMPSET UDP and IPC Handles a Set packet for MIB objects specified at invocation.
Sample Manager Files Reference Summary Sample Manager Files Sample Manager C File Names System File Names File Descriptions SNMPGT snmpgt.c snmpgtc C source code for main control block SNMPGET snmpfs.c snmpfsc snmpfs.h snmpfsh snmpget.c snmpgetc C source code for packet encoding and decoding Declarations and prototypes supporting code in snmpfsc C source code for main control block snmpfs.c snmpfsc snmpfs.h snmpfsh snmpnxt.c snmpnxtc snmpfs.c snmpfsc snmpfs.h snmpfsh snmpset.
Common Utility Functions Reference Summary Sample Manager All C File Names System File Names asn1.h buffer.h buildpkt.h localio.h objectid.h snmp.h snmpdefs.h snmpstat.h asn1h bufferh buildpkh localioh objectih snmph snmpdefh snmpstah Declarations and prototypes for Manager Services library packet-handling functions systype.h systypeh Type definitions for Guardian and OSS environments print.
Common Utility Functions Reference Summary Sample Managers Using Function Function Header File string2oid() rtutils.h Converts the OID of a MIB object described in the read_mib() input file to its corresponding name. SNMPWALK str_to_trap() print.h Converts the string value of the generic trap field in a trap PDU to the corresponding integer value. SNMPTRAP str_to_type() print.h Converts a string depicting an SNMP type into its corresponding Manager Services representation.
Common Utility Functions Reference Summary A pointer to the namerec structure, defined in print.h: p struc namerec { OBJ_ID_T oid; char *nmstr; int type; Type contains one of the values described under str_to_type(). oid A pointer to a structure of type OBJ_ID_T. oidstr_to_oid() The oidstr_to_oid() function accepts an OID string and describes it using the OBJ_ID_T type. If the OID string is a MIB-II object name, an internal mapping table is used to find its OID.
Common Utility Functions Reference Summary read_mib() The read_mib() function loads the contents of a MIB compiler -readtree output file at run time and converts it into an in-memory structure that string2oid() can parse. The inmemory structure has the same format as the MIB compiler -nametree output. #include "readmibh" read_mib(readtree-filename); int read_mib(char* readtree-filename); readtreefilename A pointer to the file containing the MIB compiler -readtree output.
Common Utility Functions Reference Summary str_to_trap() The str_to_trap() function converts the string value of a generic trap to its corresponding integer value.
Sample Manager Invocation Reference Summary Sample Manager Invocation SNMPGT This manager handles a Get packet for one or more MIB objects specified at invocation. It encodes the packet using BER encoding, prints the request packet, sends a request and receives a response using the UDP protocol, and prints the response packet. SNMPGT [-c agent-community string] [-i request-id] [-p agent-request-port} [-r retry-count] [-t timeout-seconds] target-host-identifier MIB-object [MIB-object...
Sample Manager Invocation Reference Summary is used if the host is the same host as the manager’s host or if it can be reached over Expand. If IPC communication fails, UDP communication is used. SNMPGET [-c agent-community string] [-i request-id] [-p agent-request-port} [-r retry-count] [-t timeout-seconds] [-a NonStop-agent-process] [-x output-information-level] target-host-identifier MIB-object [MIB-object...
Sample Manager Invocation Reference Summary target-hostidentifier The device on which the target agent resides. You can specify either a name or an IP address; you can supply or omit the backslash when specifying a NonStop Kernel node. MIB-object A MIB object instance. If the object is a MIB-II object, you can refer to it by name or using the dotted OID format; use the dotted OID format for objects that are not MIB-II objects.
Sample Manager Invocation Reference Summary -l Stands for long form. Use this parameter when changing the value of MIB objects that are not MIB-II objects. data-type Describes the SNMP data type of the target MIB object when it is not a MIB-II object. It must be one of these values: OCTET_STRING DisplayString OBJECT_IDENTIFIER NULL INTEGER IpAddress Counter Gauge TimeTicks Opaque value The value to assign to the target MIB object.
Sample Manager Invocation Reference Summary number-ofobjects An integer indicating the number of MIB objects you want to retrieve. The default is 2147483647. first-MIBobject Identifies the instance of the MIB object preceding the first MIB object you want to retrieve. If the object is represented in mibrt, you can refer to it by name or using the dotted OID format; use the dotted OID format for objects that are not represented in mibrt. The default is 0.0.
Sample Manager Invocation Reference Summary generic-trapidentifier One of the standard generic trap integers or string values: 0 (coldStart) 1 (warmStart) 2 (linkDown) 3 (linkUp) 4 (authenticationFailure) 5 (egpNeighborLoss) 6 (enterpriseSpecific) The default is 0. specifictrap-number An enterprise-defined integer that characterizes the trap in greater detail. The default is 0. timestamp An unsigned integer to assign to the timestamp field in the trap PDU. The default is 0.
Sample Manager Invocation Reference Summary SNMPMON SNMPMON monitors a UDP port for SNMP packets and prints any packets it receives. SNMPMON [-p port-to-monitor] [-t tcp/ip-process-name] port-tomonitor The UDP port to use for packet receipt. To use a port numbered less than 1024, the SNMPMON process must be started by a member of the super user group (255, n). The default value is 162. tcp/ipprocess-name The TCP/IP process to bind to for packet receipt. The default is $ZTC0.
MIB Compiler Invocation Reference Summary MIB Compiler Invocation mibcomp [-numbers | -statistics | -nametree | -readtree] [-exclude MIB-module-name.MIB-object-name]... [-l file-search-path]... [-o output-file-name] [-nowarn] [-quiet] {@ automated-response-file-name | MIB-file-name}... -numbers Creates an output file containing a line describing each subtree and leaf in a MIB file. For subtrees, the OID and name appear. For leaves, the OID, name, and syntax appear.
Library Header Files Reference Summary -quiet Suppresses progress messages generated by the MIB compiler as it checks the syntax of each MIB object. To suppress progress messages for the last in a series of input files, specify the -quiet option before the last input file name. To suppress progress messages for multiple input files, specify the -quiet option before the input file names. @ automatedresponsefile-name Identifies an input file containing MIB compiler invocation specifications.
Typedefs Reference Summary Typedefs Typedef Description ALENGTH_T The fully decoded value of an ASN.1 length field ATVALUE_T The fully decoded value of an ASN.
Encoded-Packet Structure (EBUFFER_T) Reference Summary num_components The number of integers in the sequence of integers making up an OID. For example, an OID of 1.2.3.4 has four components. component_list Pointer to an array of elements of type OIDC_T. OIDC_T is a Manager Services typedef for a 32-bit unsigned integer. Each element in the array holds one of the OID integers. Encoded-Packet Structure (EBUFFER_T) This structure describes a variable-length string buffer for holding encoded packets.
Unencoded-Packet Structure (SNMP_PKT_T) Reference Summary Unencoded-Packet Structure (SNMP_PKT_T) This structure holds a request, response, or trap packet. The following fields in this structure are of interest to Manager Services programmers; most of the field types are typedefs listed earlier in this section, under “Typedefs.” typedef struct SNMP_PKT_S { ... UINT_16_T lcl_ident ... INT_32_T snmp_version; ... EBUFFER_T community; ...
Unencoded-Packet Structure (SNMP_PKT_T) Reference Summary pdu_type The kind of PDU in the packet. The following Manager Services defines describe values for pdu_type: #define #define #define #define #define #define GET_REQUEST_PDU GET_NEXT_REQUEST_PDU GET_RESPONSE_PDU SET_REQUEST_PDU TRAP_PDU NO_PDU 0 1 2 3 4 0xFF pdu_length The number of bytes in the PDU. pdu A tagged union with two principal variations, std_pdu and trap_pdu, the former for request and response PDUs and the latter for trap PDUs.
Unencoded-Packet Structure (SNMP_PKT_T) Reference Summary vbl_length The number of bytes in vblist. vbl_count The number of variable bindings in vblist. vblist An array of structures of type VB_T. Each structure in the array describes one variable binding; these are the fields of interest to Manager Services programmers. typedef struct VB_S { ... ALENGTH_T vb_seq_size; OBJ_ID_T vb_obj_id; OCTET_T vb_data_flags_n_type; ... ALENGTH_T vb_data_length; ...
Unencoded-Packet Structure (SNMP_PKT_T) Reference Summary value_u A tagged union capable of holding values for all the data types described in RFC 1155. The variable binding’s value is assigned to one of the fields depending on its type: v_number holds signed integer values. v_counter holds unsigned integer values. v_string holds octet string values. v_object holds OIDs. v_network_address[4] holds network addresses. A structure for holding a trap PDU. This structure contains six fields.
Reference Summary Decoding Statistics Structure (SNMP_STATS_T) Decoding Statistics Structure (SNMP_STATS_T) This structure holds statistical counters of packet decoding activities. A global structure of this type with the name snmp_stats must be defined in every manager.
Defines Reference Summary Defines Define Name Value MAX_OID_COUNT 32 SNMP_MAX_PACKET_SIZE 1400 SNMP_MIN_PACKET_SIZE 484 SNMP_REQUEST_PORT 161 SNMP_TRAP_PORT 162 SNMP_VERSION_1 0 /* IPC maximum: 4096 */ Packet-Construction Functions Initializing Packets SNMP_Create_Request() This function initializes a request packet for a Get, GetNext, or Set PDU.
Initializing Packets Reference Summary packet A pointer to a structure of type SNMP_PKT_T if the function succeeds or 0 if it fails. pdu-type The kind of PDU to be placed in the packet. Use one of the following defines: For Get requests, use GET_REQUEST_PDU (0). For GetNext requests, use GET_NEXT_REQUEST_PDU (1). For Set requests, use SET_REQUEST_PDU (3).
Initializing Packets Reference Summary SNMP_Free(), described later in this section under “Function for Releasing Packet Memory.
Binding MIB Objects Reference Summary generic-trap The generic trap code. Assign one of the following values, which correspond to the values indicated: 0 (coldStart) 1 (warmStart) 2 (linkDown) 3 (linkUp) 4 (authenticationFailure) 5 (egpNeighborLoss) 6 (enterpriseSpecific) specific-trap An integer describing a specific trap code, which is an enterprisedefined code providing additional information about the nature of the trap.
Binding MIB Objects Reference Summary index A zero-based index value indicating the position into which to bind the MIB variable in a list of variable bindings. A value of 0 binds the variable at the front of the list, 1 binds the variable into the second position, and so forth. The order in which you assign variable bindings to a list is irrelevant.
Binding MIB Objects Reference Summary instancecount The number of components in the instance identifier whose value you supply in instance-components. For example, an instance identifier of 1.2.3.4 has a component count of 4. instancecomponents A pointer to a structure of type OIDC_T that contains the instance identifier of the variable binding. value A pointer to a 4-byte area containing the value of the variable binding.
Binding MIB Objects Reference Summary SNMP_Bind_Object_ID() This function associates a variable binding of type OBJECT_IDENTIFIER with a packet previously initialized with SNMP_Create_Request() or SNMP_Create_Trap().
Binding MIB Objects Reference Summary SNMP_Bind_String() This function associates a variable binding of type OCTET_STRING, DisplayString, Opaque, or NSAPADDRESS with a packet previously initialized with SNMP_Create_Request() or SNMP_Create_Trap().
Binding MIB Objects Reference Summary value-length The number of bytes in the value. value A pointer to a buffer containing the string value. buffer-flag An indication of whether you want Manager Services to allocate dynamic memory for holding a copy of your string value or to use a buffer you have already allocated for it.
Releasing Packet Memory Reference Summary instancecomponents A pointer to a structure of type OIDC_T that contains the instance identifier of the variable binding. data-type Indicates the SNMP data type of the object being bound. Assign one of these values: VT_COUNTER VT_GAUGE VT_TIMETICKS VT_UINTEGER32 value An unsigned integer value to assign to the variable binding.
Interpreting Received Packets Reference Summary Retrieve This Packet Information From This Field in SNMP_PKT_T Instance identifiers of variable bindings For responses: pdu.std_pdu.std_vbl.vblist.vb_obj_id For traps: pdu.trap_pdu.trap_vbl.vblist.vb_obj_id Values of variable bindings For responses: pdu.std_pdu.std_vbl.vblist.value_u.field For traps: pdu.trap_pdu.trap_vbl.vblist.value_u.
Packet Encoding and Decoding Functions Reference Summary Packet Encoding and Decoding Functions Managing the Encoded-Packet Buffer Summary of Buffer Management Functions Function Description EBufferClean() Releases dynamically obtained memory for a buffer and calls EBufferInitialize(). EBufferClone() Copies a buffer into a second buffer after dynamically allocating memory for it, duplicating the source buffer’s contents and descriptors.
Managing the Encoded-Packet Buffer Reference Summary EBufferClean() This function releases dynamic memory previously allocated for an EBUFFER_T buffer and calls EBufferInitialize() to set all the buffer descriptors to zero: ebuff start_bp next_bp remaining = 0 603 EBufferClean(buffer); void EBufferClean(EBUFFER_T *buffer); A pointer to the descriptor structure for the buffer for which memory is to be released.
Managing the Encoded-Packet Buffer Reference Summary rcode An integer describing the outcome of the call. A value of 0 indicates success; a value of -1 indicates failure. source-buffer A pointer to the descriptor structure for the buffer you want to duplicate. dest-buffer A pointer to the descriptor structure for the buffer you want created. EBufferInitialize() This function initializes the buffer descriptors of an EBUFFER_T buffer to zero.
Reference Summary Managing the Encoded-Packet Buffer next-ptr Where to return the value of next_bp. buffer A pointer to the descriptor structure from which you want to retrieve next_bp.
Managing the Encoded-Packet Buffer Reference Summary EBufferPreLoad() This function sets up buffer descriptors for an allocated buffer to which you have already written information but for which you have not initialized EBUFFER_T descriptors.
Managing the Encoded-Packet Buffer Reference Summary EBufferRemaining() This function returns the value of the EBUFFER_T buffer descriptor named remaining, which indicates the number of unused bytes in the buffer: remaining EBufferRemaining() start_bp next_bp 902 bytes-left = EBufferRemaining(buffer); ALENGTH_T EBufferRemaining(EBUFFER_T *buffer); bytes-left An integer indicating the number of unused bytes in the buffer.
Managing the Encoded-Packet Buffer Reference Summary EBufferSetup() This function initializes buffer descriptors for a buffer you have obtained static or dynamic memory for, setting start_bp and next_bp to point to the first byte in the buffer and the value of remaining to the number of bytes you allocated: ebuff remaining start_bp next_bp 604 EBufferSetup( {BFL_IS_DYNAMIC | BFL_IS_STATIC}, buffer, start-byte, num-bytes); void EBufferSetup (unsigned int EBUFFER_T OCTET_T ALENGTH_T flags, *buffer, *sta
Managing the Encoded-Packet Buffer Reference Summary start-ptr = EBufferStart(buffer); OCTET_T* EBufferStart(*buffer); start-ptr Where to return the value of start_bp. buffer A pointer to the descriptor structure from which you want to retrieve the value of start_bp. EBufferUsed() This function returns the number of used bytes in an EBUFFER_T buffer.
Encoding Packets Reference Summary Encoding Packets SNMP_Encode_Packet() This function BER-encodes a request or trap packet into an initialized encoded-packet buffer. If you previously allocated memory for the buffer, SNMP_Encode_Packet() determines whether the memory allocated is sufficient, then proceeds only if it is. If you have not allocated memory for the buffer, this function dynamically allocates enough memory to hold the encoded packet.
Decoding Packets Reference Summary Decoding Packets When you receive a response or trap packet, regardless of whether the packet is BER- or IPC-encoded, you use SNMP_Decode_Packet_WER() to decode it into a structure of type SNMP_PKT_T, which this function allocates dynamically. Dynamically allocated memory should be released by using SNMP_Free() when you no longer need the decoded-packet structure.
Index A address field 5-4 Agents 1-1 ALENGTH_T 4-2 AllocateDevEntry() 2-123 asn1.h 4-1 ATVALUE 4-2 ATVALUE_T 4-2 Authentication 1-9 Automated response file 3-6 AWAITIOX() 7-4, 7-7 B BER encoding 1-6 protocol 7-1 BER encoding 6-1 BFL_IS_DYNAMIC 4-3 BFL_IS_STATIC 4-3 Binding MIB objects 5-17 buffer.h 4-1 Building Guardian managers 8-1 OSS managers 8-4 buildpkt.
F Index Encoded-packet buffer (continued) EBufferClone() 6-8 EBufferInitialize() 6-9 EBufferNext() 6-9 EBufferPreLoad() 6-10 EBufferRemaining() 6-11 EBufferReset() 6-11 EBufferSetup() 6-12 EBufferStart() 6-13 EBufferUsed() 6-13 memory allocation 6-3 releasing memory 6-5 SNMP_memory_alloc() 6-14 Encoding BER 1-6 IPC 1-6 Encoding packets 6-4, 6-15 enterprise field 5-4 enterprise_objid 4-7 Epilogue managers 1-19 error-index 5-2 error-status 5-2 error_index 4-5 error_status 4-5 F GetNext PDUs 1-4 GetPrinter
N Index Manager Services (continued) packet decoding function 6-17 packet encoding functions 6-15 packet initialization functions 5-12 packet memory release function 5-33 purpose 1-1 typedefs 4-1 Managers building 1-17, 8-1 defining logic 1-13 definition 1-1 designing 1-13 development cycle 1-12 extended roles 1-6 installing 1-18 primary role 1-5 MAX_OID_COUNT 4-10 MIB 1-7 definition 1-2 entry 1-4 index 1-4 object attributes 1-3 object description 1-2 MIB browsers 1-5 MIB compiler automated response file
R Index Packets (continued) decoding 1-6, 6-4, 6-17 definition 1-2 encoding 1-6, 6-4, 6-15 encoding and decoding 6-1 initializing 5-12 interpreting contents 1-6, 5-10 PDU field 1-4 receipt 1-6 releasing memory 5-33 request 5-2 response 5-2 sending and receiving 7-1 transmission 1-6 transmission protocols 1-8 trap 5-4 version field 1-4 pdu field 4-5 PDU type 5-2, 5-4 PDU types 1-4 pdu.std_pdu.error_index 5-11 pdu.std_pdu.error_status 5-11 pdu.std_pdu.request_id 5-11 pdu.std_pdu.std_vbl.vblist.
S Index S Sample managers building 2-4 common utility functions 2-34 files 2-1 Guardian and OSS differences 2-40 SNMPGET 2-55 SNMPGT 2-42 SNMPHOST 2-114 SNMPMON 2-108 SNMPNEXT 2-65 SNMPSET 2-68 SNMPTRAP 2-94 SNMPWALK 2-82 source code overview 2-5 summary of functions 2-1 supporting IPC and UDP 2-6 supporting UDP only 2-5 using 2-4 Scalar objects 1-4 Set PDUs 1-4 SetCpuLoad() 2-124, 2-126 SetDiskCapacity() 2-124, 2-126 SetPrinterStatus() 2-124, 2-126 SET_REQUEST_PDU 4-5 SNMP 2-10, 2-11, 2-12, 4-10 snmpdefs
T Index specific-trap 5-4 specific_trap 4-8 start_bp 6-2 std_pdu 4-5 std_vbl 4-6 string2oid() 2-39 str_to_trap() 2-39 str_to_type() 2-40 Subagents 1-7 Syntax summary 9-1 T Tabular objects 1-4 tdm_SNMP_Encode_Packet() 6-15 Traps packets 5-4 PDUs 1-4 transmission 1-10 TRAP_PDU 4-5 trap_pdu 4-7 trap_time_ticks 4-8 trap_vbl 4-8 typedefs 4-1 t_recvfrom_nw() 7-7 t_sendto_nw() 7-6 U UINT_16_T 4-2 UINT_32_T 4-2 UINT_8_T 4-2 Unencoded-packet structure 4-4 V value_u 4-7 Variable bindings definition 1-3 fields 5-
Special Character Index Special Character # 2-12 #MGR 2-12 -exclude option 3-5 -nametree option 3-3 -nowarn option 3-5 -numbers option 3-1 -quiet option 3-5 -readtree option 3-4 -statistics option 3-2 SNMP Manager Programmer’s Guide– 134249 Index- 7
Special Character Index SNMP Manager Programmer’s Guide– 134249 Index- 8
