Section E.1. SNMP_Util


E.1. SNMP_Util

Perl scripts need two use statements to take advantage of the SNMP Perl module:

     use BER;     use SNMP_Session; 

The BER and SNMP_Session modules make up the core of Simon's package. The SNMP_util module discussed in this appendix makes using this package a little easier. It requires only one use statement:

     use SNMP_util; 

Mike's package uses the other two modules, so it's not necessary to include all three in your scripts.

E.1.1. MIB Management Routines

The following sections describe a set of routines for working with MIBs.

E.1.1.1. snmpmapOID( )

The MIB objects in RFC 1213 (MIB-II) and RFC 2955 (Frame Relay) are preloaded by the routines in this package. This means that you can refer to a symbolic name like sysLocation.0 rather than to its numeric OID (.1.3.6.1.2.1.1.6 ). The snmpmapOID( ) routine allows you to add name-OID pairs to this map. The routine is used as follows:

     snmpmapOID(text, OID, [text, OID...]) 

All the parameters are strings. text is the textual (or symbolic) name that you want to use and OID is the numeric object ID of the object to which the name refers. A single call to this routine may specify any number of name-OID pairs.

If snmpmapOID( ) fails, it returns undef, so you can test for errors like this:

     @return = snmpmapOID(..);     if(!@return) {        # error     } 

E.1.1.2. snmpMIB_to_OID( )

This routine takes the filename of a MIB as an argument. It reads and parses the MIB file and associates the object IDs defined by the MIB with their textual names. It returns the number of mappings it created. A return value of 0 means that no mappings were created; -1 means an error occurred (i.e., it was unable to open the file). The routine is used as follows:

     snmpMIB_to_OID(filename) 

E.1.1.3. snmpLoad_OID_Cache( )

This routine allows you to map textual names to object IDs using a file. The file should consist of a number of lines in the form:

     textual_name OID 

This is much faster than calling snmpMIB_to_OID( ) because it doesn't require parsing a MIB file. The only argument to this routine is the name of the file that contains the preparsed data:

     snmpLoad_OID_Cache(filename) 

snmpLoad_OID_Cache( ) returns -1 if it can't open the file; a return value of 0 indicates success.

E.1.1.4. snmpQueue_MIB_File( )

This routine specifies a list of MIB files that will be used for mapping textual names to object IDs. If a name or OID can't be found in the internal map, each MIB file is parsed in turn until a match is found. The routine is used as follows:

     snmpQueue_MIB_File(filename, [filename]) 

E.1.2. SNMP Operations

The routines for performing SNMP operations correspond to the standard SNMP Version 1 operations[*] and have the following parameters in common:

[*] Simon Leinen's package supports both SNMPv1 and v2; Mike Mitchell's SNMP_util module supports only v1.


community (optional)

The community string. If no community string is specified, public is used.


host (required)

The hostname or IP address of the device you want to query.


port (optional)

The port number to which to send the query or trap. The default for all routines except snmptrap( ) is 161. The default for snmptrap( ) is 162.


timeout (optional)

The timeout in seconds; if no response is received within this period, the operation is considered to have failed and is retried. The default is 2 seconds.


retries (optional)

The number of retries before the routine returns failure. The default is 5.


backoff (optional)

The backoff value; for each successive retry, the new timeout period is obtained by multiplying the current timeout with the backoff. The default is 1.


OID (required)

The object ID or textual name of the object you are querying.

E.1.2.1. snmpget( )

The syntax of the snmpget( ) routine is:

     snmpget(community@host:port:timeout:retries:backoff, OID, [OID...]) 

If snmpget( ) fails, it returns undef.

Recall that all the MIB-II objects are preloaded into this Perl module, so the following code is legal:

     @sysDescr = snmpget("public\@cisco.ora.com", "sysDescr"); 

We did not specify any of the optional parameters (timeout, backoff, etc.); the default values will be used. This routine lets us request "sysDescr" as shorthand for sysDescr.0. When the Perl module builds its mappings of names to object IDs, it automatically appends the trailing .0 to any scalar objects it finds. Because sysDescr is a scalar object defined by MIB-II, and because the MIB-II objects are preloaded, sysDescr is mapped to .1.3.6.1.2.1.1.1.0. If you request a scalar object from a private MIB, you must append .0 to the OID.

Since one call to snmpget( ) can retrieve many objects, the return values are stored in an array. For example:

     @oids = snmpget("public\@cisco.ora.com", "sysDescr", "sysName"); 

When this function call executes, the value for sysDescr will be stored in $oids[0]; the value for sysName will be stored in $oids[1]. All the routines in this package share this behavior.

E.1.2.2. snmpgetnext( )

The snmpgetnext( ) routine performs a getnext operation to retrieve the value of the MIB object that follows the object you pass to it. Its syntax is:

     snmpgetnext(community@host:port:timeout:retries:backoff, OID, [OID...]) 

If snmpgetnext( ) fails, it returns undef.

As with snmpget( ), you can request many OIDs; the return value from snmpgetnext( ) is an array, with the result of each getnext operation in each successive position in the array. The array you get back from snmpgetnext( ) differs from the array returned by snmpget( ) in that the value of each object is preceded by the object's ID, in the form:

     OID:value 

This routine returns both the OID and the value because with the getnext operation, you don't necessarily know what the next object in the MIB tree is.

E.1.2.3. snmpwalk( )

The snmpwalk( ) routine could easily be implemented with repeated calls to snmpgetnext( ); it traverses the entire object tree, starting with the object passed to it. Its syntax is:

     snmpwalk(community@host:port:timeout:retries:backoff, OID) 

If snmpwalk( ) fails, it returns undef.

Unlike many of the routines in this module, snmpwalk( ) allows only one OID as an argument. Like the other routines, it returns an array of values; each element of the array consists of an object's ID followed by its value, separated by a colon. For example, after executing the following code:

     @system = snmpwalk("public\@cisco.ora.com","system"); 

the contents of the array @system would be something like:

     1.0:cisco.ora.com Cisco     2.0:1.3.6.1.4.1.0     3.0:23 days, 11:01:57     4.0:Ora Network Admin Staff     5.0:cisco.ora.com     6.0:Atlanta, GA     7.0:4 

Note that the array doesn't include the entire object ID. We've told snmpwalk( ) to walk the tree starting at the system object, which has the OID .1.3.6.1.2.1.1. The first child object, and the first item in the array, is sysName, which is .1.3.6.1.2.1.1.1.0. snmpwalk( ) returns 1.0:cisco.ora.com because it omits the generic part of the OID (in this case, system) and prints only the instance-specific part (1.0). Similarly, the next item in the array is system.2.0, or system.sysObjectID.0; its value is Cisco's enterprise ID.

E.1.2.4. snmpset( )

The snmpset( ) routine allows you to set the value of an object on an SNMP-managed device. In addition to the standard arguments (hostname, community, etc.), this routine expects three arguments for each object you want it to set: the object's ID, datatype, and value. The syntax for this routine is:

     snmpset(community@host:port:timeout:retries:backoff,             OID, type, value, [OID, type, value...]) 

The type argument must be one of the following strings:


string

Represents the string type


int

Represents the 32-bit integer type


ipaddr

Represents the IP address type


oid

Represents the object identifier (OID) type

If snmpset( ) fails, it returns undef.

Performing a set from a script is straightforward. The following code sets the value of sysContact to "Joe@Ora". If the operation succeeds, snmpset( ) returns the new value for sysContact. If the operation fails, the fs variable is not set and snmpset( ) prints an error message:

     $setResponse =         snmpset("private\@cisco.ora.com", sysContact,"string","Joe\@Ora");     if ($setResponse) {         print "SET: sysContact: $setResponse\n";     } else {         print "No response from cisco.ora.com\n";     } 

The most common reasons for an snmpset( ) to fail are that the host isn't up, the host isn't running an SNMP agent, or the community string is wrong.

E.1.2.5. snmptrap( )

The snmptrap( ) routine generates an SNMPv1 trap. Most of the arguments are familiar:

     snmptrap(community@host:port:timeout:retries:backoff,              enterpriseOID, agent, generalID, specificID,              OID, type, value, [OID, type, value...]) 

The enterpriseOID, agent, generalID, and specificID arguments are discussed in Chapter 9. Each OID/type/value triplet defines a data binding to be included in the trap. OID is the object ID of the variable you want to send, value is the value you want to send for this object, and type is the object's datatype. type must be one of the following three strings:


string

Represents the string type


int

Represents the 32-bit integer type


oid

Represents the object identifier (OID) type

If snmptrap( ) fails, it returns undef. See Chapter 9 for a more detailed discussion of SNMP traps.




Essential SNMP
Essential SNMP, Second Edition
ISBN: 0596008406
EAN: 2147483647
Year: 2003
Pages: 165

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net