| Previous | Contents | Index |
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:
$ snmp_traprcv == "$SYS$SYSTEM:TCPIP$SNMP_TRAPRCV" |
snmp_traprcv [-d] [-tcp] [-p port] |
Table 4-6 describes the snmp_traprcv flags.
| Flag | Description |
|---|---|
| -d | Displays a hexadecimal and formatted dump of the received packet. |
| -p port | Specifies the port number on the local host on which to listen for trap messages. The default is 162. |
| -tcp | Listens on the TCP port instead of the UDP (default) port. Reads only a single PDU on an established connection, which is similar to the behavior using UDP. |
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
$ snmp_traprcv No snmp-trap service entry, using default port 162. bind - : permission denied |
$ 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:
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.
| Routine | Function |
|---|---|
| esnmp_init | Initializes the subagent and initiates communication with the master agent. |
| esnmp_register | Requests local registration of a MIB subtree. |
| esnmp_unregister | Cancels local registration of a MIB subtree. |
| esnmp_register2 | Requests cluster registration of a MIB subtree. |
| esnmp_unregister2 | Cancels cluster registration of a MIB subtree. |
| esnmp_capabilities | Adds a subagent's capabilities to the master agent's sysORTable . |
| esnmp_uncapabilities | Removes a subagent's capabilities from the master agent's sysORTable . |
| esnmp_poll | Processes a pending request from the master agent. |
| esnmp_are_you_there | Requests a report from the master agent to indicate it is up and running. |
| esnmp_trap | Sends a trap message to the master agent. |
| esnmp_term | Sends a close message to the master agent. |
| esnmp_sysuptime | Converts UNIX system time into a value with the same time base as sysUpTime . |
Initializes the Extensible SNMP (eSNMP) subagent and initiates communication with the master agent.
int esnmp_init (int *socket,
char *subagent_identifier ) ;
socket
The address of the integer that receives the socket descriptor used by eSNMP.subagent_identifier
The address of a null-terminated string that uniquely identifies this subagent (usually a program name).
Call this routine during program initialization or to restart the eSNMP protocol. If you are restarting, the esnmp_init routine clears all registrations so each subtree must be registered again.You should attempt to create a unique subagent identifier, perhaps using the program name argv[0] and additional descriptive text. The master agent does not open communications with a subagent whose subagent identifier is already in use.
This routine does not block waiting for a response from the master agent. After calling the esnmp_init routine, call the esnmp_register routine for each subtree that is to be handled by the subagent.
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.
#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.
int esnmp_register ( subtree *subtree,
int timeout,
int priority ) ;
subtree
A pointer to a subtree structure corresponding to the subtree to be handled. The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures. Refer to Chapter 3 for more information about these files.
Note
All memory pointed to by the subtree fields must have permanent storage since it is referenced by libesnmp for the duration of the program. You should use the data declarations emitted by the MIBCOMP program.timeout
The number of seconds the master agent should wait for responses when requesting data in this subtree. This value must be between 0 (zero) and 300. If the value is 0, the default timeout is 3 seconds. Compaq recommends that you use the default. For information about modifying the default subagent timeout value, refer to Section 6.2.priority
The registration priority. The priority argument allows you to coordinate cooperating subagents to handle different configurations. The range is 1 to 255.The entry with the largest number has the highest priority. The subagent that registers a 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.
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 .
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.
#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.
int esnmp_unregister ( SUBTREE *subtree ) ;
subtree
A pointer to a subtree structure corresponding to the subtree to be handled. The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures. Refer to Chapter 3 for more information about these files.
This routine can be called by the application code to tell the eSNMP subagent not to process requests for variables in this MIB subtree anymore. You can later reregister a MIB subtree, if needed, by calling the esnmp_register routine.
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.
#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.
int esnmp_register2 ( ESNMP_REG *reg ) ;
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.
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.
A subagent can also register MIB subtrees that overlap the OID range of MIB subtrees that it previously registered or the OID ranges of MIB subtrees registered by other subagents.
For example, consider the two subagents os_mibs and gated . The os_mibs subagent registers the ip MIB subtree (1.3.6.1.2.1.4), and the gated subagent registers the ipRouteEntry MIB subtree (1.3.6.1.2.1.4.21.1). Both of these registrations are made with the ESNMP_REG_OPT_CLUSTER bit set in the options field. Requests for ip MIB variables within ipRouteEntry , such as ipRouteIfIndex (1.3.6.1.2.1.4.21.1.2), are passed to the gated subagent. Requests for other ip variables, such as ipNetToMediaIfIndex (1.3.6.1.2.1.4.22.1.1), are passed to the os_mibs subagent. If the gated subagent terminates or unregisters the ipRouteEntry MIB subtree, subsequent requests for ipRouteIfIndex go to the os_mibs subagent. This occurs because the ip MIB subtree, which includes all ipRouteEntry MIB variables, is now the authoritative region of requests for ipRouteIfIndex .
SNMP_LIB_OK The esnmp_register2 routine has completed successfully. ESNMP_LIB_BAD_REG The esnmp_init routine has not been called, the timeout parameter is invalid, a registration slot is not available, or this MIB subtree has already been queued for registration. A message is also in the log file. ESNMP_LIB_LOST_CONNECTION The subagent lost communication with the master agent.
| Previous | Next | Contents | Index |