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

NAME

POE::Component::SNMP - POE interface to Net::SNMP

SYNOPSIS

    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, $error)             = @$response;

        if ($error) {
            warn "$host snmp error ($cmd => @args): $error\n";
        } else {
	    print "$host SNMP config ($cmd):\n";
	    if (ref $results) {
		print "sysName:     $results->{$system{sysName}}\n";
		print "sysUptime:   $results->{$system{sysUptime}}\n";
		print "sysLocation: $results->{$system{sysLocation}}\n";
	    } else {
		print "server response: $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 Net::SNMP::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 other values, are passed back to callback events, as described in CALLBACKS below, so the callback can determine which host 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). 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 Net::SNMP::get_request().

getnext

See Net::SNMP::get_next_request().

getbulk

See Net::SNMP::get_bulk_request().

walk

See Net::SNMP::get_table().

inform

See Net::SNMP::inform_request().

set

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 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 Net::SNMP::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, and parameters supplied to the request.

The callback's $_[ARG1] parameter is an array reference containing the response information: a scalar *or* a hash reference containing response data, and a string error message (which is only defined if the request failed).

Note: A timeout (no response) or other server-side fault condition is NOT returned in $error, e.g. $_[ARG1][1]. It is returned as a scalar string result, NOT a hash ref, in $_[ARG1][0]. Meaning, if you define ($data, $error) = @$response as in the SYNOPSIS, check that ref $data eq 'HASH' first before trying to dereference it.

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.