Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

SNMP::Effective
An effective SNMP-information-gathering module

SNMP::Effective - An effective SNMP-information-gathering module


NAME

SNMP::Effective - An effective SNMP-information-gathering module


VERSION

This document refers to version 1.05 of SNMP::Effective.


SYNOPSIS


 use SNMP::Effective;

 

 my $snmp = SNMP::Effective->new(

     max_sessions   => $NUM_POLLERS,

     master_timeout => $TIMEOUT_SECONDS,

 );

 

 $snmp->add(

     dest_host => $ip,

     callback  => sub { store_data() },

     get       => [ '1.3.6.1.2.1.1.3.0', 'sysDescr' ],

 );

 # lather, rinse, repeat

 

 # retrieve data from all hosts

 $snmp->execute;


DESCRIPTION

This module collects information, over SNMP, from many hosts and many OIDs, really fast.

It is a wrapper around the facilities of SNMP.pm, which is the Perl interface to the C libraries in the SNMP package. Advantages of using this module include:

Simple configuration
The data structures required by SNMP are complex to set up before polling, and parse for results afterwards. This module provides a simpler interface to that configuration by accepting just a list of SNMP OIDs or leaf names.

Parallel execution
Many users are not aware that SNMP can poll devices asynchronously using a callback system. By specifying your callback routine as in the SYNOPSIS section above, many network devices can be polled in parallel, making operations far quicker. Note that this does not use threads.

It's fast
To give one example, SNMP::Effective can walk, say, eight indexed OIDs (port status, errors, traffic, etc) for around 300 devices (that's 8500 ports) in under 30 seconds. Storage of that data might take an additional 10 seconds (depending on whether it's to RAM or disk). This makes polling/monitoring your network every five minutes (or less) no problem at all.

The interface to this module is simple, with few options. The sections below detail everything you need to know.


METHODS ARGUMENTS

The method arguments are very flexible. Any of the below acts as the same:


 $obj->method(MyKey   => $value);

 $obj->method(my_key  => $value);

 $obj->method(My_Key  => $value);

 $obj->method(mYK__EY => $value);


METHODS

new

This is the object constructor, and returns an SNMP::Effective object.

Arguments

max_sessions
Maximum number of simultaneous SNMP sessions.

mastertimeout
Maximum number of seconds before killing execute.

All other arguments are passed on to $snmp_effective->add( ... ).

add

Adding information about what SNMP data to get and where to get it.

Arguments

dest_host
Either a single host, or an array-ref that holds a list of hosts. The format is whatever SNMP can handle.

arg
A hash-ref of options, passed on to SNMP::Session.

callback
A reference to a sub which is called after each time a request is finished.

heap
This can hold anything you want. By default it's an empty hash-ref.

get / getnext / walk
Either ``oid object'', ``numeric oid'', SNMP::Varbind SNMP::VarList or an array-ref containing any combination of the above.

set
Either a single SNMP::Varbind or a SNMP::VarList or an array-ref of any of the above.

This can be called with many different combinations, such as:

dest_host / any other argument
This will make changes per dest_host specified. You can use this to change arg, callback or add OIDs on a per-host basis.

get / getnext / walk / set
The OID list submitted to add() will be added to all dest_host, if no dest_host is specified.

arg / callback
This can be used to alter all hosts' SNMP arguments or callback method.

execute

This method starts setting and/or getting data. It will run as long as necessary, or until master_timeout seconds has passed. Every time some data is set and/or retrieved, it will call the callback-method, as defined globally or per host.

master_timeout


 Get/Set the master timeout

max_sessions


 Get/Set the number of max session

log

This returns the Log4perl object that is used for logging:


 $self->log->warn("log this message!");

hostlist




 Returns a list containing all the hosts.

arg


 Returns a hash with the default args

callback


 Returns a ref to the default callback sub-routine.


FUNCTIONS

make_name_oid

Takes a list of numeric OIDs and turns them into an mib-object string.


 make_name_oid("1.3.6.1.2.1.1.1"); # return sysDescr

make_numeric_oid

Inverse of make_numeric_oid: Takes a list of mib-object strings, and turns them into numeric format.


 make_numeric_oid("sysDescr"); # return .1.3.6.1.2.1.1.1

match_oid

Takes two arguments: One OID to match against, and the OID to match.


 match_oid("1.3.6.10",   "1.3.6");    # return 10

 match_oid("1.3.6.10.1", "1.3.6");    # return 10.1

 match_oid("1.3.6.10",   "1.3.6.11"); # return undef


The callback method

When SNMP is done collecting data from a host, it calls a callback method, provided by the Callback => sub{} argument. Here is an example of a callback method:


 sub my_callback {

     my($host, $error) = @_

  

     if($error) {

         warn "$host failed with this error: $error"

         return;

     }

 

     my $data = $host->data;

 

     for my $oid (keys %$data) {

         print "$host returned oid $oid with this data:\n";

 

         print join "\n\t",

               map { "$_ => $data->{$oid}{$_}" }

                   keys %{ $data->{$oid}{$_} };

         print "\n";

     }

 }


DEBUGGING

Debugging is enabled through Log::Log4perl. If nothing else is spesified, it will default to ``error'' level, and print to STDERR. The component-name you want to change is ``SNMP::Effective'', inless this module ins inherited.


NOTES

walk
SNMP::Effective doesn't really do a SNMP native ``walk''. It makes a series of ``getnext'', which is almost the same as SNMP's walk.

set
If you want to use SNMP SET, you have to build your own varbind:

 $varbind = SNMP::VarBind($oid, $iid, $value, $type);

 $effective->add( set => $varbind );


TODO

Improve debugging support


DEPENDENCIES

In addition to the contents of the standard Perl distribution, this module requires the following:

Log::Log4perl
By default the level of reporting is set to error and will be directed to STDERR.

SNMP
Note that this is not the same as Net::SNMP on the CPAN. You want the SNMP CPAN distribution or the SNMP distribution.

Time::HiRes
Perl versions greater than 5.7.3 are supplied with this module.

Tie::Array
Perl versions greater than 5.5.0 are supplied with this module.

constant and overload
Perl versions greater than 5.4.0 will have these modules.


AUTHOR

Jan Henning Thorsen, <pm at flodhest.net>


BUGS

Please report any bugs or feature requests to bug-snmp-effective at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


SUPPORT

You can find documentation for this module with the perldoc command.


    perldoc SNMP::Effective

You can also look for information at:


ACKNOWLEDGEMENTS

Various contributions by Oliver Gorwits.


COPYRIGHT & LICENSE

Copyright 2007 Jan Henning Thorsen, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy