NAME
POE::Component::SNMP - POE interface to Net::SNMP
SYNOPSIS
# 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 samplesDESCRIPTION
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.
CREATING SNMP COMPONENTS
- create - create an SNMP session
-
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:$object->method(-parameter => $value); $object->method( parameter => $value);-hostnameis required. This differs from the behavior in Net::SNMP which is to default to'localhost'.-aliasis not required unless you want to query more than one host. See "Concurrency", below.
Concurrency
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.
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 with POE's ASSERT_DEFAULT, but it won't work regardless.
Sockets
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 thus is able to reuse the same socket for each request, but is not asynchronous. 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 host. 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.
REQUESTS
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 for specific examples.
getgetnextgetbulkwalkinformsettrap-
$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. 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 Net::SNMP::snmpv2_trap(). A false value indicates an error, and the error message can be retrieved using callingerrmsg, below. errmsg-
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 SNMP component. Cancels all current and pending requests immediately and closes the session. If the component is currently dispatching a request (waiting for a reply) when this request is received, the response NOT be delivered.
-callback_args-
# $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. See "CALLBACKS" for details.
CALLBACKS
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.
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.
The callback's $_[ARG1] parameter is an array reference containing the response information: The first element 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, they will be returned as additional elements in $_[ARG1].
NOTE: This is a change from previous versions of the module! Previously, errors were returned in $_[ARG1][1].
SEE ALSO
Net::SNMP
POEAUTHOR
Adopted and maintained by Rob Bloodgood <rdb@cpan.org>
Originally by Todd Caine <tcaine@eli.net>
COPYRIGHT AND LICENSE
Copyright 2004-2006 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.