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 POE with ASSERT_USAGE, 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 is thus able to reuse the same socket for each request; however, it 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 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.
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.
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. (See POE::Session for more information about $_[_ARG0] and $_[_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.
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].
NOTE: This is a change from older versions of the module! Previously, errors were returned in $_[ARG1][1].
-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, which will be dereferenced as a list of additional response parameters after the SNMP response data.
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.