SNMP::Util - Snmp modules to perform snmp set,get,walk,next,walk_hash etc.
use SNMP::Util;
## Documentation (POD)
<![CDATA[
Perl SNMP utilities - SNMP::Util - Version 1.8
]]>
This Perl library is a set of utilities for configuring and monitoring SNMP
based devices. This library requires the UCD port of SNMP and the SNMP.pm
module writted by Joe Marzot.
<![CDATA[
1.0 Initial Release
1.1 Fixed Manifest File
1.2 Added get_hash / walk_hash now calls walk / Modified output in poll_value
1.3 Added use strict to library and fixed some bugs with my vars
1.4 Fixed code to elminate perl warning
1.5 Changed all mapInt functions to mapEnum - (support for mapInt not in
Joe Marzot's version 1.8).
1.6 Updated docs html and text
1.7 Includes patches from Charles Anderson
1.8 Includes patches from tyoshida
]]>
The following applications need to be built and installed before running the
SNMP::Util application.
<![CDATA[
ucd-snmp-3.5 - ftp:://ftp.ece.ucdavis.edu:/pub/snmp/ucd-snmp.tar.gz
SNMP-1.8 - www.perl.com/CPAN
]]>
<![CDATA[
get - snmpget and return formatted array
get_hash - snmpget and return hash
get_set_restore - get value, set new range of values and restore value
next - snmpnext and return formatted array
ping_check - get uptime and return 1 if reachable
ping_check_exit - get uptime and exit if not reachable
poll_device - poll a device until it becomes reachable
poll_devices - poll several devices until they becomes reachable
poll_value - snmpget in a loop until variable reaches desired state
set - snmpset and return
set_get - snmpset followed by get and check
walk - snmpwalk and return formatted array
walk_hash - snmpwalk and return hash ($hash->{mibname}{index} = value)
]]>
You must first do a use statement to pull in the library. Then the snmp object can
be created.
<![CDATA[
#!/usr/local/lib/perl
use lib "put lib path here"
use SNMP::Util;
The SNMP::Util object is created as follows:
$snmp = new SNMP::Util(-device => $IP,
-community => $community,
-timeout => 5,
-retry => 0,
-poll => 'on',
-poll_timeout => 5,
-verbose => 'off',
-errmode => 'return',
-delimiter => ' ',
)
community = snmp community string
timeout = snmp timeout in seconds (You may also use sub second values ie 0.5)
retry = number of snmp retries on timeouts
poll = poll the unreachable device after number of retries reached and then retry again
poll timeout = poll timeout in minutes default = 5 minutes
verbose = controls the output of the snmp low level library
errmode = error mode ('return' on error or 'die' on error) default = return
delimeter = specifies the character to use between octets when getting octet-strings
Note: Delimiter can also be set by using the setting the Global variable as follows:
$SNMP::Util::Delimiter = '-'
]]>
First populate an array of IP addresses:
<![CDATA[
@IP_array = ('1.1.1.1','1.1.1.2','1.1.1.3','1.1.1.4')
foreach $IP (@IP_array){
$snmp->{$IP} = new SNMP::Util(-device => $IP,
-community => $community,
-timeout => 5,
-retry => 0,
-poll => 'on',
-delimiter => ' ',
)
}
#Now get the uptime for each switch
foreach $IP (@IP_array){
$uptime = $snmp->{$IP}->get('v','sysUpTime.0')
print "Uptime for $IP = $uptime\n"
}
]]>
<![CDATA[
$uptime = $snmp->get('v','sysUpTime.0')
where 'v', is the format of the output (v = value)
and $uptime contains the system uptime in 10ths of seconds
]]>
The SNMP::Util module loads the mib using the SNMP::Util_env.pm module by using the following statements.
<![CDATA[
use SNMP::Util_env
# Initialize mib
&SNMP::initMib()
You must update the SNMP::Util_env.pm file or simply set up these environment
variables and the SNMP::Util_env.pm file will not override them.
The environment variables are as follows:
$ENV{'MIBDIRS'} = '/usr/local/lib/snmp/mibs'
$ENV{'MIBFILES'} = '/ats/data/mibs/rfc1850.mib:
/ats/data/mibs/rfc1406.mib:/ats/data/mibs/rfc1407.mib:
/ats/data/mibs/rfc1595.mib:/ats/data/mibs/rfc1724.mib'
You can specify whatever MIBS you would like to load.
]]>
All error handling is done through the error handling method (error).
The error message can be obtained by using the method (errmsg)
The detailed error message can be obtained by using the method (errmsg_detail)
This error method returns a boolean result to indicate if an error ocurred
<![CDATA[
example:
if ($snmp->error){
$error = $snmp->errmsg;
$error_detail = $snmp->errmsg_detail;
print "snmp error = $error\n";
print "snmp error detail = $error_detail\n";
}
]]>
The printing of output is controlled by the logging routine. the amount of output is
configured by setting the MAX_LOG_LEVEL environment variable. There are four levels of output logging: (none,status,fail,debug). You may also set the logging using the global variable Max_log_level.
<![CDATA[
none = print no output (use errmsg only for errors)
status = print general status information
fail = print general status and failures
debug = print general status, failures, and debug information
You can set the environment variable in your environment or inside the
program using the following format:
$env{'MAX_LOG_LEVEL'} = 'debug'
or using the global
$SNMP::Util::Max_log_level = 'debug'
Example Output from Logging:
get (noSuchName) There is no such variable name in this MIB.
snmpget 100.100.100.1 public 1.3.6.1.2.1.2.2.1.1.1 1.3.6.1.2.1.2.2.1.7.1
snmpget 100.100.100.1 public ifIndex.1 ifAdminStatus.1
snmp error index = 1
Note: error index = the index of the var bind that failed
]]>
The SNMP utilities have a formatting function which will format the return values
which are most cases an array.
<![CDATA[
The format options are specified as strings as follows:
print " format string = oOnNtvei\n"
print " o = oid with index\n"
print " O = oid without index\n"
print " n = name with index\n"
print " N = name without index\n"
print " t = type\n"
print " v = value\n"
print " e = enumeration\n"
print " i = instance of the mib variable\n\n"
Note: enumerations apply to integers and timeticks. It will convert integer values
to enumerations and it will convert timeticks to days,hours,minutes,seconds.
example usage:
@result = $snmp->get('nve','sysUptime.0')
$result[0] = sysUptime.0
$result[1] = 13392330
$result[2] = 1 days, 13:12:03
Note: Any format can be used for the (get,walk,next routines)
Only 'e' or 'v' is needed in the walk_hash routine.
]]>
This formatting was designed to allow the user to format the output in
whatever format they need for there application. You may want to use
the 'v' option when comparing timetick values, but you may want to use
the 'e' option for the human readable display.
The snmpget routine may be equated to an array if the formatting has more than
one value or it may be equated to a scalar value if the formatting has only one
value. It must be equated to an array if the snmpget is a multi var bind.
The input supplied to the SNMP functions is designed to be very flexible and
allows the user to use shortcuts to apply instances to variables.
Simple format name.instance or oid.instance
<![CDATA[
$snmp->get('e','ifIndex.1','ifAdminStatus.1','ifOperStatus.1')
$snmp->get('e','1.3.6.1.2.1.2.2.1.1.1','1.3.6.1.2.1.2.2.1.7.1','1.3.6.1.2.1.2.2.1.8.1')
]]>
Shortcut format instance up front (no instance in mib name or oid
<![CDATA[
$snmp->get('e',1,'ifIndex','ifAdminStatus','ifOperStatus')
$snmp->get('e',1,'1.3.6.1.2.1.2.2.1.1','1.3.6.1.2.1.2.2.1.7','1.3.6.1.2.1.2.2.1.8')
]]>
Long format name,instance,name,instance etc of oid,instance,oid,instance etc
<![CDATA[
$snmp->get('e','ifIndex',1,'ifAdminStatus',1,'ifOperStatus',1)
$snmp->get('e','1.3.6.1.2.1.2.2.1.1',1,'1.3.6.1.2.1.2.2.1.7',1,'1.3.6.1.2.1.2.2.1.8',1)
]]>
You may also set up an array for any of the above formats and pass the array into the
get function as follows:
<![CDATA[
@oids = ('ifIndex.1','ifAdminStatus.1','ifOperStatus.1')
$snmp->get('e',@oids)
]]>
Hash like format name => instance or oid => instance
<![CDATA[
$interface = 1
$snmp->get(
'e',
ifIndex => $interface,
ifAdminStatus => $interface,
ifOperStatus => $interface,
ifSpeed => $interface,
)
or
$snmp->get(
index => $interface,
ifIndex,
ifAdminStatus,
ifOperStatus,
ifSpeed,
)
]]>
Calling get with dashed options
<![CDATA[
@result = $snmp->get(
-format => 'ne',
-oids => [
ifIndex => $interface,
ifAdminStatus => $interface,
ifOperStatus => $interface,
ifSpeed => $interface,
],
)
or
@oids = ('ifIndex.1','ifAdminStatus.1','ifOperStatus.1')
@result = $snmp->get(
-format => 'ne',
-oids => \@oids,
)
Note: When using the dashed option format, you must pass the array by reference as shown
above.
]]>
Simple format name.instance,value or oid.instance,value
<![CDATA[
$snmp->set('ifAdminStatus.1','up')
$snmp->set('1.3.6.1.2.1.2.2.1.7.1','up')
]]>
Shortcut format instance up front (no instance in mib name or oid
<![CDATA[
$snmp->set(1,'ifAdminStatus','up')
$snmp->set(1,'1.3.6.1.2.1.2.2.1.7','up')
]]>
Long format name,instance,value or oid,instance,value
<![CDATA[
$snmp->set('ifAdminStatus',1,'up')
$snmp->set('1.3.6.1.2.1.2.2.1.7',1,'up')
You may also set up an array for any of the above formats and pass the array into the
get method as follows:
@oids = ('ifAdminStatus.1','up')
$snmp->set(@oids)
]]>
Hash like format
<![CDATA[
$snmp->set(
"ifAdminStatus.$interface" => 'up',
)
or
$snmp->set(
index => $interface,
"ifAdminStatus" => 'up',
)
]]>
The get will do a snmpget and return an array specified by the format
statement.
<![CDATA[
Usage: @result = $snmp->get('ne','ifAdminStatus.1')
$result[0] = ifAdminStatus.1
$result[1] = 'up'
$result = $snmp->get('e','ifAdminStatus.1')
Note: As shown above, the result is a scalar if only one value is returned
]]>
This method will do an snmpget and return a hash. The format for the hash is
(value = $hash->{mibname}{index}).
<![CDATA[
example: $hash = $snmp->get_hash('ne','ifIndex.1','ifIndex.2',
'ifOperStatus.1','ifOperStatus.2');
$hash->{ifIndex}{1} = 1
$hash->{ifIndex}{2} = 2
$hash->{ifOperStatus}{1} = up
$hash->{ifOperStatus}{2} = up
Note: Valid format statements for get_hash are 'ne' or 'nv'
]]>
The get_set_restore will get the variable, set it to a range and restore the value
<![CDATA[
Usage: @result = $snmp->get_set_restore('1..10','ifAdminStatus.1');
where the value '1..10' is the range of values
Note: The range is specified using .. for ranges and , for individual values.
]]>
The next will do a snmpnext and return an array specified by the format
statement.
<![CDATA[
Usage: @result = $snmp->next('ne','ifAdminStatus.1')
$result[0] = ifAdminStatus.2
$result[1] = 'up'
$result = $snmp->next('e','ifAdminStatus.1')
Note: As shown above, the result is a scalar if only one value is returned
]]>
The ping_check will do a snmpget of uptime and return 1 if device is alive
The ping_check will do a snmpget of uptime and exit if not alive
The poll_device will loop on the snmpget of uptime command until the device is reachable.
The loop will exit once the poll_timeout time is reached (default = 5 minutes).
The poll_devices will do a snmpget of uptime on several devices until the device are reachable.
The loop will exit once the poll_timeout time is reached (default = 5 minutes).
<![CDATA[
$snmp->poll_devices(@IP_array);
where @IP_array = array of IP addresses
]]>
The poll value method will poll a mib variable until it reaches that state and returns the amount of time it took to reach that state
<![CDATA[
Usage: $snmp->poll_value(-oid => "ifAdminStatus.$interface",
-state => 'up',
-timeout => 120,
-montime => 5,
-delay => 1)
or
$snmp->poll_value(-oid => "1.3.6.1.2.1.2.2.1.8",
-instance => $interface,
-state => 'up',
-timeout => 120,
-montime => 5,
-delay => 1)
]]>
or
<![CDATA[
use a array ref if you want the polling to stop when the result
matches more than one value
$snmp->poll_value(-oid => "1.3.6.1.2.1.2.2.1.8",
-instance => $interface,
-state => ['up','down']
-timeout => 120,
-montime => 5,
-delay => 1)
Note: You must use the instance when using oids.
]]>
The set will set a group of variables and return 1 if passed
<![CDATA[
Usage: @result = $snmp->set(
index => 1,
ifAdminStatus => 'up',
)
]]>
The set_get will set a group of variables,get,check and return 1 if passed
<![CDATA[
Usage: @result = $snmp->set(
index => 1,
ifAdminStatus => 'up',
)
]]>
The walk will do a snmpwalk and return an array specified by the format
statement. It also has a special print option to print out each loop in the
walk. This method is capable of doing multivarbind walks.
<![CDATA[
Usage: @result = $snmp->walk(-format => 'ne',
-oids =>['ifAdminStatus'],
-print => 'on');
where print = 'on' or 'off'
or use the shortcut format (Note: print will be disabled by default
@result = $snmp->walk('ne','ifAdminStatus');
$result[0] = ifAdminStatus.1
$result[1] = 'up'
$result[2] = ifAdminStatus.2
$result[3] = 'up'
...
]]>
The walk_hash will do a snmpwalk and return a hash with the value specified by the format.
This method is capable of doing multivarbind walks.
<![CDATA[
Usage: $result = $snmp->walk_hash('e','ifIndex','ifAdminStatus','ifOperStatus')
$result->{ifIndex}{1} = 1
$result->{ifAdminStatus}{1} = 'up'
$result->{ifOperStatus}{1} = 'up'
$result->{ifIndex}{2} = 2
$result->{ifAdminStatus}{2} = 'up'
$result->{ifOperStatus}{2} = 'up'
or
Usage: $result = $snmp->walk_hash('v','ifIndex','ifAdminStatus','ifOperStatus')
$result->{ifIndex}{1} = 1
$result->{ifAdminStatus}{1} = 1
$result->{ifOperStatus}{1} = 1
$result->{ifIndex}{2} = 2
$result->{ifAdminStatus}{2} = 1
$result->{ifOperStatus}{2} = 1
]]>