HP OpenVMS Systems Documentation

HP TCP/IP Services for OpenVMS
SNMP Programming and Reference

In the following snmp_trapsnd command examples:

• The first line is the snmp_trapsnd command.
• The remainder is the display received when running the trap receiver program ( snmp_traprcv ) without flags included.

1. The following example generates a trap that originated on the localhost (specified by the agent parameter) using the default SNMP version (SNMP Version 1). The -h host parameter is not specified, so the trap will be sent to the local host.

   $ snmp_trapsnd 0.0 local 0 0 0 Message received from 127.0.0.1 SNMPv1-Trap-PDU: community - 7075626C 6963 public enterprise - 0.0 agent address - 0.0.0.0 trap type - Cold Start (0) timeticks - 51938978

2. The following example generates the same trap as in example 1, except that it specifies the use of SNMP Version 2.

   $ snmp_trapsnd 0.0 local 0 0 0 "-v2c" Message received from 127.0.0.1 SNMPv2-Trap-PDU: community - 7075626C 6963 public sysUpTime.0 - 51938968 = 6 d 0:16:29 snmpTrapOID.0 - 0.0

3. The following example sends values to the node mynode with the community name special .

   $ snmp_trapsnd 1.2.3 marley.dec.com 6 33 100 -c special -h mynode Message received from 16.20.208.68 SNMPv1-Trap-PDU: community - 73706563 69616c special enterprise - 1.2.3 agent address - 6.20.208.53 trap type - Enterprise-specific (6) enterprise-specific value - (33) timeticks - 100

The trap receiver program lets you listen for, receive, and display SNMP trap messages. Until interrupted, the program continues to listen on the specified port.

If you enter commands using the default port number or another privileged port number, you must run the program from a privileged account.

To run the trap receiver program, do the following:

1. Define a foreign command for the program:

   $ snmp_traprcv == "$SYS$SYSTEM:TCPIP$SNMP_TRAPRCV"

   
   Alternatively, you can run SYS$MANAGER:TCPIP$DEFINE_COMMANDS.COM to define all the foreign commands available with TCP/IP Services.
2. Enter a command using the following format:

   snmp_traprcv [-d] [-tcp] [-p port]

Table 4-6 describes the snmp_traprcv flags.

To set up an SNMP trap service for use with the trap receiver program, enter a management command in the following format:

SET SERVICE SNMP-TRAP /PROTOCOL=UDP /USER_NAME=TCPIP$SNMP
/PROCESS_NAME=TCPIP$SNMP-TRAP /FILE=TCPIP$SYSTEM:TCPIP$SNMP-TRAP.COM

In this command, port 170 is used as an alternative for port 162, and traps that are received on port 162 are ignored.

If you omit the /PROTOCOL qualifier or you use /PROTOCOL=TCP, the service uses the TCP transport. In this case, when you enter a command to run the trap receiver program, you must include the -tcp flag.

With the SNMP trap service in place, the trap receiver program queries the service for the port number instead of using the default port 162. If you specify a privileged port number (less than 1024) with the /PORT qualifier, make sure you install the trap receiver program with privileges, or run the program from an account that has SYSPRV privilege. Note that the port number must be greater than zero.

4.2.2.3 Trap Receiver Examples

1. The following example requests trap information on a system that does not have traps configured and does not have SYSPRV privilege or sufficient privilege.

   $ snmp_traprcv No snmp-trap service entry, using default port 162. bind - : permission denied

2. The example, supplied from a nonprivileged account, requests trap information in hexadecimal dump format on port 1026.

   $ snmp_traprcv -d -p 1026 Message received from 127.0.0.1 3082002A 02010004 06707562 6C6963A4 0..*.....public. 1D060547 81AD4D01 40040000 00000201 ...G..M.@....... 00020100 4304032D AED23082 0000 ....C..-..0... SNMPv1-Trap-PDU: community - 7075626C 6963 public enterprise - 0.0 agent address - 0.0.0.0 trap type - Cold Start (0) timeticks - 53325522

This chapter provides reference information about the following types of application programming interface (API) routines in the eSNMP developer's kit:

• Interface routines ( Section 5.1)
• Method routines ( Section 5.2)
• Support routines ( Section 5.3)

The interface routines are for developers writing the portion of the application programming interface (API) that handles the connection between the agent and the subagent. The interface routines are listed Table 5-1 and described in the following pages.

Initializes the Extensible SNMP (eSNMP) subagent and initiates communication with the master agent.

Format

int esnmp_init (int *socket,
char *subagent_identifier ) ;

Arguments

socket

The address of the integer that receives the socket descriptor used by eSNMP.

subagent_identifier

The address of a null-terminated string that uniquely identifies this subagent (usually a program name).

Description

Call this routine during program initialization or to restart the eSNMP protocol. If you are restarting, the esnmp_init routine clears all registrations so each subtree must be registered again.

You should attempt to create a unique subagent identifier, perhaps using the program name argv[0] and additional descriptive text. The master agent does not open communications with a subagent whose subagent identifier is already in use.

This routine does not block waiting for a response from the master agent. After calling the esnmp_init routine, call the esnmp_register routine for each subtree that is to be handled by the subagent.

Return Values

ESNMP_LIB_NO_CONNECTION	Could not initialize or communicate with the master agent. Try again after a delay.
ESNMP_LIB_OK	The esnmp_init routine has completed successfully.
ESNMP_LIB_NOTOK	Could not allocate memory for the subagent.

Example

#include <esnmp_h> int socket; status = esnmp_init(&socket, "gated");

Requests local registration of a single MIB subtree. This indicates to the master agent that the subagent instantiates MIB variables within the registered MIB subtree.

Format

int esnmp_register ( subtree *subtree,
int timeout,
int priority ) ;

Arguments

subtree

A pointer to a subtree structure corresponding to the subtree to be handled. The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures. Refer to Chapter 3 for more information about these files.

Note All memory pointed to by the subtree fields must have permanent storage since it is referenced by libesnmp for the duration of the program. You should use the data declarations emitted by the MIBCOMP program.

timeout

The number of seconds the master agent should wait for responses when requesting data in this subtree. This value must be between 0 (zero) and 300. If the value is 0, the default timeout is 3 seconds. HP recommends that you use the default. For information about modifying the default subagent timeout value, refer to Section 6.2.

priority

The registration priority. The priority argument allows you to coordinate cooperating subagents to handle different configurations. The range is 1 to 255.

The entry with the largest number has the highest priority. The subagent that registers a subtree with the highest priority over a range of object identifiers gets all requests for that range of OIDs .

Subtrees registered with the same priority are considered duplicate, and the registration is rejected by the master agent.

Description

Call the initialization routine esnmp_init prior to calling the esnmp_register . Call the esnmp_register function for each subtree structure corresponding to each subtree to be handled. At any time, subtrees can be unregistered by calling esnmp_unregister and then be reregistered by calling the esnmp_register .

When restarting the eSNMP protocol by calling esnmp_init , all registrations are cleared. All subtrees must be reregistered.

A subtree is identified by the base MIB name and the corresponding OID number of the node that is the parent of all MIB variables contained in the subtree. For example: The MIB II tcp subtree has an OID of 1.3.6.1.2.1.6 . All elements subordinate to this have the same first seven digits and are included in the subtree's object table. The subtree can also be a single MIB object (a leaf node) or even a specific instance.

By registering a subtree, the subagent indicates that it will process eSNMP requests for all MIB variables (or OIDs ) within that subtree's range. Therefore, a subagent should register the most fully qualified (longest) subtree that still contains its instrumented MIB variables.

The master agent does not permit a subagent to register the same subtree more than once. However, subagents can register subtrees with ranges that overlap the OID ranges of subtrees previously registered, and subagents can also register subtrees registered by other subagents.

For example, TCP/IP Services supports MIB II. In the eSNMP environment, the os_mibs subagent registers the MIB II subtree ip (OID 1.3.6.1.2.1.4).

TCP/IP Services also provides the gated subagent, which registers the ipRouteEntry MIB subtree (OID 1.3.6.1.2.1.4.21.1).

These MIBs are registered at priority 1. Any subagent that registers at a higher priority (greater than 1) overrides these registrations.

A request for IpRouteIfIndex (OID 1.3.5.1.2.1.4.21.1.2) is passed to the gated subagent. Requests for other ip variables, such as ipNetToMediaIfIndex (OID 1.3.5.1.2.1.4.22.1.1) are passed to the os_mibs subagent. If the gated subagent terminates or unregisters the ipRouteEntry subtree, subsequent requests for ipRouteIfIndex will go to the os_mibs subagent. This occurs because the ip subtree, which includes all ipRouteEntry variables, is now the authoritative region of requests for ipRouteIfIndex .

Return Values

Note that the return value indicates only the initiation of the request. The actual status returned in the master agent's response will be returned in a subsequent call to the esnmp_poll routine in the state field.

SNMP_LIB_OK	The esnmp_register routine has completed successfully.
ESNMP_LIB_BAD_REG	The esnmp_init routine has not been called, the timeout parameter is invalid, or the subtree has already been queued for registration.
ESNMP_LIB_LOST_CONNECTION	The subagent has lost communications with the master agent.

Example

#include <esnmp.h> #define RESPONSE_TIMEOUT 0 /* use the default time set in OPEN message */ #define REGISTRATION_PRIORITY 10 /* priority at which subtrees will register */ int status; extern SUBTREE ipRouteEntry_subtree; status = esnmp_register( &ipRouteEntry_subtree, RESPONSE_TIMEOUT, REGISTRATION_PRIORITY ); if (status != ESNMP_LIB_OK) { printf ("Could not queue the 'ipRouteEntry' \n"); printf ("subtree for registration\n"); }

Cancels registration of a MIB subtree previously registered with the master agent.

Format

int esnmp_unregister ( SUBTREE *subtree ) ;

Arguments

subtree

A pointer to a subtree structure corresponding to the subtree to be handled. The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures. Refer to Chapter 3 for more information about these files.

Description

This routine can be called by the application code to tell the eSNMP subagent not to process requests for variables in this MIB subtree anymore. You can later reregister a MIB subtree, if needed, by calling the esnmp_register routine.

Return Values

SNMP_LIB_OK	The esnmp_unregister routine has completed successfully.
ESNMP_LIB_BAD_REG	The MIB subtree was not registered.
ESNMP_LIB_LOST_CONNECTION	The request to unregister the MIB subtree could not be sent. You should restart the protocol.

Example

#include <esnmp.h> int status extern SUBTREE ipRouteEntry_subtree; status = esnmp_unregister (&ipRouteEntry_subtree); switch (status) { case ESNMP_LIB_OK: printf ("The esnmp_unregister routine completed successfully.\n"); break; case ESNMP_LIB_BAD_REG: printf ("The MIB subtree was not registered.\n"); case ESNMP_LIB_LOST_CONNECTION: printf ("%s%s%s\n", "The request to unregister the ", "MIB subtree could not be sent. ", "You should restart the protocol.\n"); break; }

Requests registration of a single MIB subtree. This indicates to the master agent that the subagent instantiates MIB variables within the registered MIB subtree. The esnmp_register2 routine offers extensions to the esnmp_register routine.

Format

int esnmp_register2 ( ESNMP_REG *reg ) ;

Arguments

reg

A pointer to an ESNMP_REG structure that contains the following fields:

Field Name	Description
subtree	A pointer to a subtree structure corresponding to the MIB subtree to be handled. The subtree structures are externally declared and initialized in the code emitted by the MIBCOMP command ( subtree_TBL.C and subtree_TBL.H, where subtree is the name of the MIB subtree). This code is taken directly from the MIB document. All memory pointed to by this field must have permanent storage since it is referenced by libesnmp for the duration of the program. You should use the data declarations emitted by the MIBCOMP command.
priority	The registration priority. The entry with the largest number has the highest priority. The range is 1 to 255. The subagent that has registered a MIB subtree with the highest priority over a range of object identifiers gets all requests for that range of OIDs. MIB subtrees that are registered with the same priority are considered duplicates, and the registration is rejected by the master agent. The priority field is a mechanism for cooperating subagents to handle different configurations.
timeout	The number of seconds the master agent should wait for responses when requesting data in this MIB subtree. This value must be between zero and 300. If the value is zero, the default timeout (3 seconds) is used. You should use the default. For information about modifying the default timeout value, refer to Section 6.2.
range_subid	An integer value that, when nonzero, together with the range_upper_bound field specifies a range instead of one of the MIB subtree's OID subidentifiers. The range_subid field specifies the OID subidentifier modified by the range_upper_bound field.
range_upper_bound	An integer value that, with a nonzero range_subid field, specifies a range instead of one of the MIB subtree's OID subidentifiers. The range_upper_bound field provides the upper bound of the range and the range_subid field provides the lower bound of the range, which is the MIB subtree's OID subidentifier.
options	An integer value that, when set to ESNMP_REG_OPT_CLUSTER, indicates that the registration is valid clusterwide. When the value is set to zero, it indicates that the registration is valid for the local node.
state	One of the following integer values that provides the caller with asynchronous updates of the state of registration of this MIB subtree. After the return of the esnmp_poll routine, the caller can inspect this parameter. ESNMP_REG_STATE_PENDING The registration is currently held locally while waiting for connection to the master agent. ESNMP_REG_STATE_SENT The registration was sent to the master agent. ESNMP_REG_STATE_DONE The registration was successfully acknowledged by the master agent. ESNMP_REG_STATE_REGDUP The registration was rejected by the master agent because it was a duplicate. ESNMP_REG_STATE_REGNOCLU The master agent does not support cluster registrations. ESNMP_REG_STATE_REJ The master agent rejected the registration for other reasons.
reserved	This field is reserved for exclusive use by the eSNMP library. The caller should not modify it.

Description

The initialization routine ( esnmp_init ) must be called prior to calling the esnmp_register2 routine. The esnmp_register2 function must be called for each subtree structure corresponding to each MIB subtree that it will be handling. At any time, MIB subtrees can be unregistered by calling esnmp_unregister2 and then can be reregistered by calling esnmp_register2 .

When restarting the eSNMP protocol by calling esnmp_init , all MIB subtree registrations are cleared. All MIB subtrees must be reregistered.

A MIB subtree is identified by the base MIB variable name and its corresponding OID. This tuple represents the parent of all MIB variables that are contained in the MIB subtree; for example, the MIB II tcp subtree has an OID of 1.3.6.1.2.1.6. All elements subordinate to this (those that have the same first 7 identifiers) are included in the subtree's object table. A MIB subtree can also be a single MIB object (a leaf node) or even a specific instance.

By registering a MIB subtree, the subagent indicates that it will process SNMP requests for all MIB variables (or OIDs) within that MIB subtree's region. Therefore, a subagent should register the most fully qualified (longest) MIB subtree that still contains its instrumented MIB variables.

A subagent using the esnmp_register2 routine can register the same MIB subtree for the local node and for a cluster. To register the MIB subtree for both, you must call the esnmp_register2 routine twice: once with the ESNMP_REG_OPT_CLUSTER bit set in the options field and once with the ESNMP_REG_OPT_CLUSTER bit clear in the options field. Alternatively, you can register a MIB subtree for the cluster only or for the local node only, by setting or clearing the ESNMP_REG_OPT_CLUSTER bit, respectively, in the options field.

---

Previous

Next

Contents

Index