POE::Component::SNMP(3User Contributed Perl DocumentatiPOE::Component::SNMP(3)NAMEPOE::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 samples
DESCRIPTIONPOE::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);
"-hostname" is required. This differs from the behavior in
Net::SNMP which is to default to 'localhost'.
"-alias" is 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.
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.
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.
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, 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.
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" 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.
"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.
"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 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.
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
POE
AUTHOR
Adopted and maintained by Rob Bloodgood <rdb@cpan.org>
Originally by Todd Caine <tcaine@eli.net>
COPYRIGHT AND LICENSE
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.
perl v5.14.1 2010-01-11 POE::Component::SNMP(3)
