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

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',
				      timeout   => 3,
                                    );

        $kernel->post( snmp => get  => snmp_handler => -varbindlist => \@oids );
        # ... or maybe even ...
        $kernel->post( snmp => walk => snmp_handler => -baseoid => $base_oid );

        $heap->{pending} = 2;
    }

    sub snmp_handler {
        my ($kernel, $heap, $request, $response) = @_[KERNEL, HEAP, ARG0, ARG1];
        my ($alias,   $host, $cmd, @args) = @$request;
        my ($results)                     = @$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";
        }

        if (--$heap->{pending} == 0) {
            $kernel->post( $alias => 'finish' );
        }
    }

    $poe_kernel->run();

DESCRIPTION

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, 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', with a warning
   [version   => $version,  ] # default '1', SNMPv1
   [timeout   => $timeout,  ] # default 5.0
   [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 "METHODS" in Net::SNMP on session() for details. The constructor supports either of the following two parameter naming styles:

$object->method(-parameter => $value);
$object->method( parameter => $value);

-hostname is required.

-community defaults to 'public', but the module will emit a runtime warning if the community is not explicitly specified.

-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.

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 a fatal runtime error to attempt to create more than one SNMP session with the same -alias.

Sockets

By default, Net::SNMP creates a single socket per network interface. Since POE 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.

get

See "METHODS" in Net::SNMP on get_request().

getnext

See "METHODS" in Net::SNMP on get_next_request().

getbulk

See "METHODS" in Net::SNMP on get_bulk_request().

walk

See "METHODS" in Net::SNMP on get_table().

inform

See "METHODS" in Net::SNMP on inform_request().

set

See "METHODS" in Net::SNMP on 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 "METHODS" in Net::SNMP on 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 $kernel->call(), the return value is that of trap(). A false value indicates an error, and the error message can be retrieved using errmsg, below.

errmsg
my $last_snmp_error_message = $kernel->call( snmp => 'errmsg' );

Retrieves the last SNMP error message, if any, from the specified SNMP session.

finish
$kernel->post( snmp => 'finish' );

Shut down the SNMP component. Cancels any pending requests and closes the session.

CALLBACKS

When a request either 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: either a hash reference containing response data or a scalar error message string.

Note: This is a change from previous versions of the module! For compatibility, any errors are still returned in $_[ARG1][1], but this will go away.

SEE ALSO

Net::SNMP
POE

AUTHOR

Adopted and maintained by Rob Bloodgood <rob@exitexchange.com>

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.