POE::Component::SNMP - POE interface to Net::SNMP
# this script is included in the distribution as eg/snmp_sample.pl use POE qw/Component::SNMP/; my %system = ( sysUptime => '.1.3.6.1.2.1.1.3.0', sysName => '.1.3.6.1.2.1.1.5.0', sysLocation => '.1.3.6.1.2.1.1.6.0', ); my @oids = values %system; my $base_oid = '.1.3.6.1.2.1.1'; # system.* POE::Session->create( inline_states => { _start => \&_start, snmp_handler => \&snmp_handler, } ); sub _start { my ($kernel, $heap) = @_[KERNEL, HEAP]; POE::Component::SNMP->create( alias => 'snmp', # same as default hostname => 'localhost', community => 'public', version => 'snmpv2c', # debug => 0x0A, ); $kernel->post( snmp => get => snmp_handler => -varbindlist => \@oids ); # ... or maybe ... $kernel->post( snmp => walk => snmp_handler => -baseoid => $base_oid ); # ... or possibly even ... my @callback_args = (1, 2, 3); $kernel->post( snmp => getbulk => snmp_handler => -varbindlist => [ $base_oid ], -maxrepetitions => 6, -callback_args => \@callback_args ); $heap->{pending} = 3; } sub snmp_handler { my ($kernel, $heap, $request, $response) = @_[KERNEL, HEAP, ARG0, ARG1]; my ($alias, $host, $cmd, @args) = @$request; my ($results, @callback_args) = @$response; if (ref $results) { print "$host SNMP config ($cmd):\n"; print "sysName: $results->{$system{sysName}}\n"; print "sysUptime: $results->{$system{sysUptime}}\n"; print "sysLocation: $results->{$system{sysLocation}}\n"; } else { print "$host SNMP error ($cmd => @args):\n$results\n"; } print "Additional args: @callback_args\n"; if (--$heap->{pending} == 0) { $kernel->post( $alias => 'finish' ); } } $poe_kernel->run(); # see the eg/ folder in the distribution archive for more samples
POE::Component::SNMP is a POE-ized wrapper around the Net::SNMP module written by David M. Town. Most of its arguments aren't even evaluated by POE, except for -alias and -callback_args, as described below.
-alias
-callback_args
POE::Component::SNMP->create( hostname => $hostname, # required [alias => $alias, ] # default 'snmp' [community => $community,] # default 'public' [version => $version, ] # default '1', SNMPv1 [timeout => $timeout, ] # default 5.0 (seconds) [retries => $retries, ] # default 1 [debug => $debug, ] # default 0 [ ... any other arguments Net::SNMP recognizes ... ] );
create() passes all of its arguments to the constructor for a Net::SNMP object untouched with the exception of -alias. See Net::SNMP::session(). The constructor supports either of the following two parameter naming styles:
create()
$object->method(-parameter => $value); $object->method( parameter => $value);
-hostname is required. This differs from the behavior in Net::SNMP which is to default to 'localhost'.
-hostname
'localhost'
-alias is not required unless you want to query more than one host. See "Concurrency", below.
In order to access multiple SNMP hosts simultaneously, you must create a separate instance of the component for each host, by giving each component a different -alias parameter in the constructor.
Multiple requests to a particular instance are processed in FIFO order, including retries (-retries defaults to 1). This means that if you have multiple pending requests to a single host, and one automatically attempts retry for whatever reason, the retry request will "go to the end of the line" behind any other queued requests.
-retries
There is no limit to how many simultaneous instances can be processing requests. It is possible to create multiple instances for the same host.
The -alias and -hostname parameters, as well as additional request-specific data, are passed back to callback events, as described in "CALLBACKS" below, so the callback can determine what context the current response (or timeout) is related to.
NOTE: It is an error to attempt to create more than one SNMP session with the same -alias. It's not fatal unless you run POE with ASSERT_USAGE, but it won't work regardless.
By default, Net::SNMP creates a single socket per network interface. This is possible because the Net::SNMP event loop processes all SNMP requests in FIFO order and is thus able to reuse the same socket for each request, regardless of its destination; however, it is not multiplexed. Since we can only watch one connection per socket at a time, this creates a conflict if you want to contact more than one remote host simultaneously. The workaround used by the module is to create each socket using a different randomly generated value for the -localport parameter, specifying a unique local UDP port for each instance of the component. This could potentially interfere with remote communications if your local firewall policy requires a specific source port for outgoing SNMP requests (as noted by David Town, the author of Net::SNMP). In this situation, you can supply an explicit -localport argument to the constructor, but remember that every active session requires its own unique local port per session/host, per interface.
-localport
Most of the events accept a list of arguments which are passed directly to a Net::SNMP session. See "METHODS" in Net::SNMP for more information on these arguments.
Requests take the form:
$poe_kernel->post( $session_alias => $request => $callback_state => @snmp_args );
See the "SYNOPSIS" and the following per-request specifics for examples.
get
$poe_kernel->post( snmp => get => parse_get_results => # system.sysUptime varbindlist => [ '.1.3.6.1.2.1.1.3.0' ] );
See Net::SNMP::get_request().
getnext
$poe_kernel->post( snmp => get => parse_getnext_results => # system.* varbindlist => [ '.1.3.6.1.2.1.1.1.0', '.1.3.6.1.2.1.1.2.0', '.1.3.6.1.2.1.1.3.0', '.1.3.6.1.2.1.1.4.0', '.1.3.6.1.2.1.1.5.0', '.1.3.6.1.2.1.1.6.0', '.1.3.6.1.2.1.1.7.0', '.1.3.6.1.2.1.1.8.0', ] );
See Net::SNMP::get_next_request().
getbulk
$poe_kernel->post( snmp => getbulk => parse_getbulk_results => maxrepetitions => 8, # system.* varbindlist => [ '.1.3.6.1.2.1.1' ] );
See Net::SNMP::get_bulk_request().
walk
$poe_kernel->post( snmp => walk => parse_walk_results => # system.* baseoid => [ '.1.3.6.1.2.1.1' ] );
See Net::SNMP::get_table().
getentries
See Net::SNMP::get_entries().
inform
See Net::SNMP::inform_request().
set
$poe_kernel->post( snmp => set => snmp_set_callback => # system.sysContact varbindlist => [ '.1.3.6.1.2.1.1.4.0', 'OCTET_STRING', 'test@test.com'] );
See Net::SNMP::set_request().
trap
$kernel->post( snmp => trap => @snmp_args ); # or, even better: my $status = $kernel->call( snmp => trap => @snmp_args );
Send a SNMPv1 trap message. See Net::SNMP::trap(). This method differs from the requests in that it does not take a state name as a callback parameter. If the method is invoked with POE::Kernel::call(), the return value is that of Net::SNMP::trap(). A false value indicates an error, and the error message can be retrieved using errmsg, below.
errmsg
trap2c
$kernel->post( snmp => trap2c => @snmp_args ); # or, even better: my $status = $kernel->call( snmp => trap2c => @snmp_args );
Send a SNMPv2c trap message. See Net::SNMP::snmpv2_trap(). This method differs from the others in that it does not take a state name as a callback parameter. If the method is invoked with POE::Kernel::call(), the return value is that of snmpv2_trap(). A false value indicates an error, and the error message can be retrieved via errmsg, below.
POE::Kernel::call()
snmpv2_trap()
my $last_snmp_error_message = $kernel->call( snmp => 'errmsg' );
Retrieves the last error message, if any, from the specified SNMP session.
finish
$kernel->post( snmp => 'finish' );
Shut down the specified SNMP component. All current and pending requests are cancelled immediately and the session is closed. If the component is currently dispatching a request (waiting for a reply) when this request is received, the response NOT be delivered to the designated callback.
NOTE: Things break if you use POE::Kernel's call() method to issue a request to a component and then call() a finish to the same component within the same event/subroutine. So don't do that. Stick with post() and you'll be fine.
call()
post()
When a request receives a response (or times out), the supplied callback event (a POE event name defined in the session that called the SNMP component) is invoked. (See POE::Session for more information about $_[_ARG0] and $_[_ARG1])
$_[_ARG0]
$_[_ARG1]
The callback's $_[ARG0] parameter is an array reference containing the request information: the component alias, hostname, the method called (e.g. 'get'), and parameters supplied to the request.
$_[ARG0]
The callback's $_[ARG1] parameter is an array reference containing the response information. The first element ($_[ARG1][0]) is either a hash reference containing response data or a scalar error message string. If any arguments have been passed to the request via -callback_args (below), they will be returned as additional elements in $_[ARG1].
$_[ARG1]
$_[ARG1][0]
NOTE: This is a change from older versions of the module! Previously, errors were returned in $_[ARG1][1].
$_[ARG1][1]
# $callback_state receives @args in $_[_ARG1] $kernel->post( $alias => get => $callback_state => -callback_args => \@args, -varbindlist => \@oids );
This optional parameter to all component requests returning a response sets a list of additional values to be passed to the POE state as parameters. The argument must be an array reference, which will be dereferenced as a list of additional response parameters after the SNMP response data.
Net::SNMP POE
Adopted and maintained by Rob Bloodgood <rdb@cpan.org>
Originally by Todd Caine <tcaine@eli.net>
Copyright 2004-2008 by Rob Bloodgood
Copyright 2003 by Todd Caine
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install POE::Component::SNMP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::SNMP
CPAN shell
perl -MCPAN -e shell install POE::Component::SNMP
For more information on module installation, please visit the detailed CPAN module installation guide.