SNMP Operations (Essential SNMP)

E.2. SNMP Operations

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

[81]Simon Leinen's package supports both SNMP v1 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.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-2, and because the MIB-2 objects are pre-loaded, 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.2.2. snmpgetnext( )

The snmpgetnext() routine performs a get-next 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 get-next 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 get-next operation you don't necessarily know what the next object in the MIB tree is.

E.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.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.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 10, "Traps". 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 10, "Traps" for a more detailed discussion of SNMP traps.