/ 
POE-Component-SNMP-Session-0.1202
River stage one • 1 direct dependent • 1 total dependent
/ POE::Component::SNMP::Session

NAME

POE::Component::SNMP::Session - Wrap Net-SNMP's SNMP::Session in POE

VERSION

Version 0.1202

SYNOPSIS

This module wraps the SNMP module from the net-snmp project within POE's non-blocking event loop, to perform asynchronous SNMP requests.

use POE qw/Component::SNMP::Session/;

POE::Component::SNMP::Session->create();
...

NOTE: the Perl support for net-snmp is NOT installable via CPAN. On most linux distros, it is usually available as a companion package to net-snmp. The Windows port comes with an PPD package for ActiveState Perl that must be installed manually.

NOTE: this module is NOT based on the (mostly) pure-perl Net::SNMP module by David M. Town. See POE::Component::SNMP for an async interface to Net::SNMP.

CREATING SNMP COMPONENTS

create - create an SNMP session

The constructor takes the same arguments as the "SNMP::Session" in SNMP module, with one addition.

Alias

the Alias parameter specifies the POE session alias the component will receive. If this parameter is not supplied, the default value is 'snmp'. Be careful of creating duplicate sessions! Depending on your environment, POE might throw an error, or it might not. So don't do that.

The DestHost parameter is technically optional, and defaults to 'localhost', but you really should set it. Also, this parameter name is Case Sensitive, so it must be supplied in mixed case as shown here.

All other parameters are passed through to SNMP::Session untouched.

NOTE: SNMPv3 session creation blocks until authorization completes. This means that if your DestHost doesn't respond, your program will block for Timeout microseconds (default 1s). Also, if authentication fails, the constructor will fail, so it is important to check the return value of create() in this case.

NOTE: Timeout values are in microseconds, not seconds. Setting a value like 60 and thinking it's seconds will cause your requests to timeout before they've finished transmitting, and confusion will ensue.

REQUESTS

The requests accept a list of arguments which are passed directly to a SNMP::Session object. See "SNMP::Session" in SNMP for more information on these arguments.

Requests take the form:

$poe_kernel->post( $component_alias => $request =>
                   $callback_state => @snmp_args );

The arguments are the component alias, the request type, a callback state in the requesting session, and then any arguments you would pass to the SNMP::Session method of the same name.

get
$poe_kernel->post( snmp => get => $state =>
                   [ '.1.3.6.1.2.1.1.3.0' ],
                   # or
                   [ 'sysUptime.0' ],
                   # or
                   [ sysUptime => 0 ],
                   # or
                   [ 'sysUptime' ],
                 );
getnext
$poe_kernel->post( snmp => getnext => $state => ['sysUpTime'] );
getbulk
$poe_kernel->post( snmp => getbulk => $state =>
                   # nonrepeaters
                   1,
                   # maxrepetitions
                   8,
                   # vars
                   new SNMP::VarList (['ifNumber'], ['ifSpeed'], ['ifDescr'])
                 );
bulkwalk
$poe_kernel->post( snmp => bulkwalk => $state =>
                   1, 8,
                   new SNMP::VarList (['ifNumber'], ['ifSpeed'], ['ifDescr'])
                 );
set
	    $poe_kernel->post( snmp => set => $state =>
                               [ 'sysContact' ] => 'sample@test.com',
	                     );

These are the request types the component knows about. Details on the correct parameters for each request type are available at "SNMP::Session" in SNMP.

There are several valid ways to specify query parameters, listed at "Acceptable variable formats:" in SNMP.

For sending traps, you should instantiate an SNMP::TrapSession object directly.

finish

Shuts down the component instance (other SNMP sessions are unaffected). Any requests that are still pending will have their respective responses/timeouts delivered, but new requests will be discarded.

CALLBACK STATES

sub snmp_response {
    my($kernel, $heap, $request, $response) = @_[KERNEL, HEAP, ARG0, ARG1];

    my ($alias,   $host, $session, $cmd, @args)  = @$request;
    my ($results) = @$response;

    my $value = $results->[0][2];

    # ... stuff ...
}

A callback state (a POE event) is invoked when the component either receives a response or timeout. The event receives data in its $_[ARG0] and $_[ARG1] parameters.

$_[ARG0] is an array reference containing: the SNMP::Session object that the component is using, the alias of the component, and the hostname (DestHost) the component is communicating with.

$_[ARG1] is an array reference containing: the response value.

If the response value is defined, it will be a SNMP::VarList object containing the SNMP results. The SNMP::VarList object is a blessed reference to an array of SNMP::Varbind objects. See "Acceptable variable formats:" in SNMP for more details.

If the response value is undef, then any error message can be accessed via the SNMP::Session object as $session->{ErrorStr}.

See "SNMP::Session" in SNMP for details.

AUTHOR

Rob Bloodgood, <rdb at cpan.org>

CAVEATS

SNMPv3 connections automatically send a synchronous (blocking) request to establish authorization (technically, it probes for the engineID). If the request times out (for example if the agent is not responding), the entire program will block for Timeout microseconds. YMMV, but for unreliable or slow connections, you may want to try a smaller timeout value, so you receive a failure more quickly.

BUGS

Please report any bugs or feature requests to bug-snmp-session-poe at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-SNMP-Session. 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 POE::Component::SNMP::Session

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2007-2009 Rob Bloodgood, all rights reserved.

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