1NAME 2 SNMP::Util - Snmp modules to perform snmp set,get,walk,next,walk_hash etc. 3 4SYNOPSIS 5 `use SNMP::Util;' 6 7 ## Documentation (POD) =head1 NAME 8 9 Perl SNMP utilities - SNMP::Util - Version 1.8 10 11DESCRIPTION 12 This Perl library is a set of utilities for configuring and monitoring SNMP based devices. This library requires 13 the UCD port of SNMP and the SNMP.pm module writted by Joe Marzot. 14 15Version 16 17 1.0 Initial Release 18 1.1 Fixed Manifest File 19 1.2 Added get_hash / walk_hash now calls walk / Modified output in poll_value 20 1.3 Added use strict to library and fixed some bugs with my vars 21 1.4 Fixed code to elminate perl warning 22 1.5 Changed all mapInt functions to mapEnum - (support for mapInt not in 23 Joe Marzot's version 1.8). 24 1.6 Updated docs html and text 25 1.7 Includes patches from Charles Anderson 26 1.8 Includes patches from tyoshida 27Software requirements 28 The following applications need to be built and installed before running the SNMP::Util application. 29 30 ucd-snmp-3.5 - ftp:://ftp.ece.ucdavis.edu:/pub/snmp/ucd-snmp.tar.gz 31 SNMP-1.8 - www.perl.com/CPAN 32 33Summary of functions 34 get - snmpget and return formatted array 35 get_hash - snmpget and return hash 36 get_set_restore - get value, set new range of values and restore value 37 next - snmpnext and return formatted array 38 ping_check - get uptime and return 1 if reachable 39 ping_check_exit - get uptime and exit if not reachable 40 poll_device - poll a device until it becomes reachable 41 poll_devices - poll several devices until they becomes reachable 42 poll_value - snmpget in a loop until variable reaches desired state 43 set - snmpset and return 44 set_get - snmpset followed by get and check 45 walk - snmpwalk and return formatted array 46 walk_hash - snmpwalk and return hash ($hash->{mibname}{index} = value) 47 48Creation on the SNMP::Util object 49 You must first do a use statement to pull in the library. Then the snmp object can be created. 50 51 #!/usr/local/lib/perl 52 use lib "put lib path here" 53 use SNMP::Util; 54 55 The SNMP::Util object is created as follows: 56 57 $snmp = new SNMP::Util(-device => $IP, 58 -community => $community, 59 -timeout => 5, 60 -retry => 0, 61 -poll => 'on', 62 -poll_timeout => 5, 63 -verbose => 'off', 64 -errmode => 'return', 65 -delimiter => ' ', 66 ) 67 68 community = snmp community string 69 timeout = snmp timeout in seconds (You may also use sub second values ie 0.5) 70 retry = number of snmp retries on timeouts 71 poll = poll the unreachable device after number of retries reached and then retry again 72 poll timeout = poll timeout in minutes default = 5 minutes 73 verbose = controls the output of the snmp low level library 74 errmode = error mode ('return' on error or 'die' on error) default = return 75 delimeter = specifies the character to use between octets when getting octet-strings 76 77 78 Note: Delimiter can also be set by using the setting the Global variable as follows: 79 $SNMP::Util::Delimiter = '-' 80 81 Creating and using multiple objects 82 83 First populate an array of IP addresses: 84 85 @IP_array = ('1.1.1.1','1.1.1.2','1.1.1.3','1.1.1.4') 86 87 foreach $IP (@IP_array){ 88 89 $snmp->{$IP} = new SNMP::Util(-device => $IP, 90 -community => $community, 91 -timeout => 5, 92 -retry => 0, 93 -poll => 'on', 94 -delimiter => ' ', 95 ) 96 } 97 98 #Now get the uptime for each switch 99 foreach $IP (@IP_array){ 100 $uptime = $snmp->{$IP}->get('v','sysUpTime.0') 101 print "Uptime for $IP = $uptime\n" 102 } 103 104How to use the object for a simple snmpget 105 $uptime = $snmp->get('v','sysUpTime.0') 106 where 'v', is the format of the output (v = value) 107 and $uptime contains the system uptime in 10ths of seconds 108 109MIB Loading 110 The SNMP::Util module loads the mib using the SNMP::Util_env.pm module by using the following statements. 111 112 use SNMP::Util_env 113 # Initialize mib 114 &SNMP::initMib() 115 116 You must update the SNMP::Util_env.pm file or simply set up these environment 117 variables and the SNMP::Util_env.pm file will not override them. 118 119 The environment variables are as follows: 120 121 $ENV{'MIBDIRS'} = '/usr/local/lib/snmp/mibs' 122 $ENV{'MIBFILES'} = '/ats/data/mibs/rfc1850.mib: 123 /ats/data/mibs/rfc1406.mib:/ats/data/mibs/rfc1407.mib: 124 /ats/data/mibs/rfc1595.mib:/ats/data/mibs/rfc1724.mib' 125 126 You can specify whatever MIBS you would like to load. 127 128Error Handling method 129 All error handling is done through the error handling method (error). The error message can be obtained by using 130 the method (errmsg) The detailed error message can be obtained by using the method (errmsg_detail) This error 131 method returns a boolean result to indicate if an error ocurred 132 133 example: 134 135 if ($snmp->error){ 136 $error = $snmp->errmsg; 137 $error_detail = $snmp->errmsg_detail; 138 print "snmp error = $error\n"; 139 print "snmp error detail = $error_detail\n"; 140 } 141 142Print Output Logging 143 The printing of output is controlled by the logging routine. the amount of output is configured by setting the 144 MAX_LOG_LEVEL environment variable. There are four levels of output logging: (none,status,fail,debug). You may 145 also set the logging using the global variable Max_log_level. 146 147 none = print no output (use errmsg only for errors) 148 status = print general status information 149 fail = print general status and failures 150 debug = print general status, failures, and debug information 151 152 You can set the environment variable in your environment or inside the 153 program using the following format: 154 155 $env{'MAX_LOG_LEVEL'} = 'debug' 156 157 or using the global 158 $SNMP::Util::Max_log_level = 'debug' 159 160 Example Output from Logging: 161 162 get (noSuchName) There is no such variable name in this MIB. 163 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 164 snmpget 100.100.100.1 public ifIndex.1 ifAdminStatus.1 165 snmp error index = 1 166 167 Note: error index = the index of the var bind that failed 168 169Formatting SNMP output (get, next, walk) 170 The SNMP utilities have a formatting function which will format the return values which are most cases an array. 171 172 The format options are specified as strings as follows: 173 174 print " format string = oOnNtvei\n" 175 print " o = oid with index\n" 176 print " O = oid without index\n" 177 print " n = name with index\n" 178 print " N = name without index\n" 179 print " t = type\n" 180 print " v = value\n" 181 print " e = enumeration\n" 182 print " i = instance of the mib variable\n\n" 183 184 Note: enumerations apply to integers and timeticks. It will convert integer values 185 to enumerations and it will convert timeticks to days,hours,minutes,seconds. 186 187 example usage: 188 189 @result = $snmp->get('nve','sysUptime.0') 190 $result[0] = sysUptime.0 191 $result[1] = 13392330 192 $result[2] = 1 days, 13:12:03 193 194 Note: Any format can be used for the (get,walk,next routines) 195 Only 'e' or 'v' is needed in the walk_hash routine. 196 197 This formatting was designed to allow the user to format the output in whatever format they need for there 198 application. You may want to use the 'v' option when comparing timetick values, but you may want to use the 'e' 199 option for the human readable display. 200 201 The snmpget routine may be equated to an array if the formatting has more than one value or it may be equated to a 202 scalar value if the formatting has only one value. It must be equated to an array if the snmpget is a multi var 203 bind. 204 205Input Formatting 206 The input supplied to the SNMP functions is designed to be very flexible and allows the user to use shortcuts to 207 apply instances to variables. 208 209 Input formatting options for the get,next,walk 210 211 Simple format name.instance or oid.instance 212 213 $snmp->get('e','ifIndex.1','ifAdminStatus.1','ifOperStatus.1') 214 $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') 215 216 Shortcut format instance up front (no instance in mib name or oid 217 218 $snmp->get('e',1,'ifIndex','ifAdminStatus','ifOperStatus') 219 $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') 220 221 Long format name,instance,name,instance etc of oid,instance,oid,instance etc 222 223 $snmp->get('e','ifIndex',1,'ifAdminStatus',1,'ifOperStatus',1) 224 $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) 225 226 You may also set up an array for any of the above formats and pass the array into the get function as follows: 227 228 @oids = ('ifIndex.1','ifAdminStatus.1','ifOperStatus.1') 229 $snmp->get('e',@oids) 230 231 Hash like format name => instance or oid => instance 232 233 $interface = 1 234 $snmp->get( 235 'e', 236 ifIndex => $interface, 237 ifAdminStatus => $interface, 238 ifOperStatus => $interface, 239 ifSpeed => $interface, 240 ) 241 or 242 243 $snmp->get( 244 index => $interface, 245 ifIndex, 246 ifAdminStatus, 247 ifOperStatus, 248 ifSpeed, 249 ) 250 251 Calling get with dashed options 252 253 @result = $snmp->get( 254 -format => 'ne', 255 -oids => [ 256 ifIndex => $interface, 257 ifAdminStatus => $interface, 258 ifOperStatus => $interface, 259 ifSpeed => $interface, 260 ], 261 ) 262 or 263 @oids = ('ifIndex.1','ifAdminStatus.1','ifOperStatus.1') 264 @result = $snmp->get( 265 -format => 'ne', 266 -oids => \@oids, 267 ) 268 269 Note: When using the dashed option format, you must pass the array by reference as shown 270 above. 271 272 273 =head2 Input formats for the set routine 274 275 Simple format name.instance,value or oid.instance,value 276 277 $snmp->set('ifAdminStatus.1','up') 278 $snmp->set('1.3.6.1.2.1.2.2.1.7.1','up') 279 280 Shortcut format instance up front (no instance in mib name or oid 281 282 $snmp->set(1,'ifAdminStatus','up') 283 $snmp->set(1,'1.3.6.1.2.1.2.2.1.7','up') 284 285 Long format name,instance,value or oid,instance,value 286 287 $snmp->set('ifAdminStatus',1,'up') 288 $snmp->set('1.3.6.1.2.1.2.2.1.7',1,'up') 289 290 You may also set up an array for any of the above formats and pass the array into the 291 get method as follows: 292 293 @oids = ('ifAdminStatus.1','up') 294 $snmp->set(@oids) 295 296 Hash like format 297 298 $snmp->set( 299 "ifAdminStatus.$interface" => 'up', 300 ) 301 or 302 303 $snmp->set( 304 index => $interface, 305 "ifAdminStatus" => 'up', 306 ) 307 308 309 310 =head1 SNMP Method summary 311 312 get 313 314 The get will do a snmpget and return an array specified by the format statement. 315 316 Usage: @result = $snmp->get('ne','ifAdminStatus.1') 317 $result[0] = ifAdminStatus.1 318 $result[1] = 'up' 319 320 $result = $snmp->get('e','ifAdminStatus.1') 321 Note: As shown above, the result is a scalar if only one value is returned 322 323 get_hash 324 325 This method will do an snmpget and return a hash. The format for the hash is (value = $hash->{mibname}{index}). 326 327 328 example: $hash = $snmp->get_hash('ne','ifIndex.1','ifIndex.2', 329 'ifOperStatus.1','ifOperStatus.2'); 330 331 $hash->{ifIndex}{1} = 1 332 $hash->{ifIndex}{2} = 2 333 $hash->{ifOperStatus}{1} = up 334 $hash->{ifOperStatus}{2} = up 335 336 Note: Valid format statements for get_hash are 'ne' or 'nv' 337 338 =head2 get_set_restore 339 340 The get_set_restore will get the variable, set it to a range and restore the value 341 342 Usage: @result = $snmp->get_set_restore('1..10','ifAdminStatus.1'); 343 where the value '1..10' is the range of values 344 345 Note: The range is specified using .. for ranges and , for individual values. 346 347 next 348 349 The next will do a snmpnext and return an array specified by the format statement. 350 351 Usage: @result = $snmp->next('ne','ifAdminStatus.1') 352 $result[0] = ifAdminStatus.2 353 $result[1] = 'up' 354 355 $result = $snmp->next('e','ifAdminStatus.1') 356 Note: As shown above, the result is a scalar if only one value is returned 357 358 =head2 ping_check 359 360 The ping_check will do a snmpget of uptime and return 1 if device is alive 361 362 ping_check_exit 363 364 The ping_check will do a snmpget of uptime and exit if not alive 365 366 poll_device 367 368 The poll_device will loop on the snmpget of uptime command until the device is reachable. The loop will exit once 369 the poll_timeout time is reached (default = 5 minutes). 370 371 poll_devices 372 373 The poll_devices will do a snmpget of uptime on several devices until the device are reachable. The loop will exit 374 once the poll_timeout time is reached (default = 5 minutes). 375 376 $snmp->poll_devices(@IP_array); 377 where @IP_array = array of IP addresses 378 379 poll_value 380 381 The poll value method will poll a mib variable until it reaches that state and returns the amount of time it took 382 to reach that state 383 384 Usage: $snmp->poll_value(-oid => "ifAdminStatus.$interface", 385 -state => 'up', 386 -timeout => 120, 387 -montime => 5, 388 -delay => 1) 389 390 or 391 392 $snmp->poll_value(-oid => "1.3.6.1.2.1.2.2.1.8", 393 -instance => $interface, 394 -state => 'up', 395 -timeout => 120, 396 -montime => 5, 397 -delay => 1) 398 399 or 400 401 use a array ref if you want the polling to stop when the result 402 matches more than one value 403 404 $snmp->poll_value(-oid => "1.3.6.1.2.1.2.2.1.8", 405 -instance => $interface, 406 -state => ['up','down'] 407 -timeout => 120, 408 -montime => 5, 409 -delay => 1) 410 411 412 Note: You must use the instance when using oids. 413 414 set 415 416 The set will set a group of variables and return 1 if passed 417 418 Usage: @result = $snmp->set( 419 index => 1, 420 ifAdminStatus => 'up', 421 ) 422 423 set_get 424 425 The set_get will set a group of variables,get,check and return 1 if passed 426 427 Usage: @result = $snmp->set( 428 index => 1, 429 ifAdminStatus => 'up', 430 ) 431 432 walk 433 434 The walk will do a snmpwalk and return an array specified by the format statement. It also has a special print 435 option to print out each loop in the walk. This method is capable of doing multivarbind walks. 436 437 Usage: @result = $snmp->walk(-format => 'ne', 438 -oids =>['ifAdminStatus'], 439 -print => 'on'); 440 441 where print = 'on' or 'off' 442 443 or use the shortcut format (Note: print will be disabled by default 444 445 @result = $snmp->walk('ne','ifAdminStatus'); 446 447 $result[0] = ifAdminStatus.1 448 $result[1] = 'up' 449 $result[2] = ifAdminStatus.2 450 $result[3] = 'up' 451 ... 452 453 walk_hash 454 455 The walk_hash will do a snmpwalk and return a hash with the value specified by the format. This method is capable 456 of doing multivarbind walks. 457 458 Usage: $result = $snmp->walk_hash('e','ifIndex','ifAdminStatus','ifOperStatus') 459 $result->{ifIndex}{1} = 1 460 $result->{ifAdminStatus}{1} = 'up' 461 $result->{ifOperStatus}{1} = 'up' 462 $result->{ifIndex}{2} = 2 463 $result->{ifAdminStatus}{2} = 'up' 464 $result->{ifOperStatus}{2} = 'up' 465 466 or 467 Usage: $result = $snmp->walk_hash('v','ifIndex','ifAdminStatus','ifOperStatus') 468 $result->{ifIndex}{1} = 1 469 $result->{ifAdminStatus}{1} = 1 470 $result->{ifOperStatus}{1} = 1 471 $result->{ifIndex}{2} = 2 472 $result->{ifAdminStatus}{2} = 1 473 $result->{ifOperStatus}{2} = 1 474 475 476