/ 
Mojo-SNMP-0.13
River stage zero No dependents
/ Mojo::SNMP

NAME

Mojo::SNMP - Run SNMP requests with Mojo::IOLoop

VERSION

0.13

SYNOPSIS

Using methods with callbacks

use Mojo::SNMP;
my $snmp = Mojo::SNMP->new;

$snmp->defaults({timeout => 3, community => "public"});

$snmp->get_next(["10.0.0.1", "10.0.0.2"], ["1.3.6.1.2.1.1.3.0"], sub {
  my ($self, $err, $session) = @_;
});

$snmp->wait unless $snmp->ioloop->is_running;

Using prepare

use Mojo::SNMP;
my $snmp = Mojo::SNMP->new;
my @response;

$snmp->on(response => sub {
  my ($snmp, $session, $args) = @_;
  warn "Got response from $args->{hostname} on $args->{method}(@{$args->{request}})...\n";
  push @response, $session->var_bind_list;
});

$snmp->defaults({
  community => "public", # v1, v2c
  username  => "foo", # v3
  version   => "v2c", # v1, v2c or v3
});

$snmp->prepare("127.0.0.1", get_next => ["1.3.6.1.2.1.1.3.0"]);
$snmp->prepare("localhost", {version => "v3"}, get => ["1.3.6.1.2.1.1.3.0"]);

# start the IOLoop unless it is already running
$snmp->wait unless $snmp->ioloop->is_running;

DESCRIPTION

Mojo::SNMP is an async library for fetching or writing data from/to many SNMP agents. The module does its best to not get in your way, but rather provide a simple API which allow you to extract information from multiple servers at the same time.

This module uses Net::SNMP and Mojo::IOLoop to fetch data from hosts asynchronously. It does this by using a custom dispatcher, Mojo::SNMP::Dispatcher, which attach the sockets created by Net::SNMP directly into the ioloop reactor.

If you want greater speed, you should check out Net::SNMP::XS and make sure Mojo::Reactor::EV and EV is installed.

Mojo::SNMP is supposed to be a replacement for a module I wrote earlier, called SNMP::Effective. Reason for the rewrite is that I'm using the framework Mojolicious which includes an awesome IO loop which allow me to do cool stuff inside my web server.

EVENTS

error

$self->on(error => sub { my ($self, $str, $session, $args) = @_; ... });

Emitted on errors which may occur. $session is a Net::SNMP object and is only available if the error is a result of a Net::SNMP method, such as get_request().

See "response" for $args description.

finish

$self->on(finish => sub { my $self = shift; ... });

Emitted when all requests have completed.

response

$self->on(response => sub { my ($self, $session, $args) = @_; ... });

Called each time a host responds. The $session is the current Net::SNMP object. $args is a hash ref with the arguments given to "prepare", with some additional information:

{
  method => $str, # get, get_next, ...
  request => [$oid, ...],
  ...
}

timeout

$self->on(timeout => sub { my $self = shift; ... })

Emitted if "wait" has been running for more than "master_timeout" seconds.

ATTRIBUTES

concurrent

$self = $self->concurrent(20);
$int = $self->concurrent;

How many hosts to fetch data from at once. Default is 20. (The default may change in later versions)

defaults

$self = $self->defaults({community => "public"});
$hash_ref = $self->community;

This attribute holds a hash ref with default arguments which will be passed on to "session" in Net::SNMP. User-submitted %args will be merged with the defaults before being submitted to "prepare". prepare() will filter out and ignore arguments that don't work for the SNMP version.

NOTE: SNMP version will default to "v2c".

master_timeout

$self = $self->master_timeout(15);
$int = $self->master_timeout;

How long to run in total before timeout. Note: This is NOT per host but for the complete run. Default is 0, which means that it will never time out.

If you want to set a timeout per request request to a host, then this need to be set in "defaults" or in $args passed on to "prepare" or one of the other request methods.

ioloop

$self = $self->ioloop(Mojo::IOLoop->new);
$ioloop = $self->ioloop;

Holds an instance of Mojo::IOLoop.

METHODS

add_custom_request_method

Mojo::SNMP->add_custom_request_method(my_custom_method => sub {
  my ($session, %args) = @_;
  # do custom stuff..
});

Net::SNMP has defined basic methods to write/retrieve data from/to the SNMP agent. "add_custom_request_method" allow you to add support for custom methods, which can be useful if you find yourself doing the same complicated logic over and over again. "bulk_walk" and "walk" are custom methods bundled with this module.

NOTE: This method will define the methods in a global scope, meaning the code below will call the custom callback instead of "get_next_request" in Net::SNMP for all instances of Mojo::SNMP:

$self->add_custom_request_method(get_next => sub { ... });

bulk_walk

$self->bulk_walk($host, $args, \@oids, sub {
  my ($self, $err, $session) = @_;
  return warn $err if $err;
  push @{$res{$host}}, $session->var_bind_list;
});

This is a custom SNMP method added by "add_custom_request_method". See "prepare" for generic information about the variables associated with this method.

This method will run "get_bulk_request" in Net::SNMP until it receives an OID which does not match the base OID. maxrepetitions in $args will default to 10, but could be overrided to potentially increase performance. Example:

$self->bulk_walk("192.168.0.1" => {maxrepetitions => 25}, sub {
  my ($self, $err, $session) = @_;
  return warn $err if $err;
  push @{$res{$host}}, $session->var_bind_list;
});

get

$self->get($host, \%args, \@oids, sub {
  my ($self, $err, $session) = @_;
  return warn $err if $err;
  push @{$res{$host}}, $session->var_bind_list;
});

Will send a SNMP get-request to the remote agent. See "get_request" in Net::SNMP for details on which %args you can pass on. See "prepare" for generic information about the variables associated with this method.

get_bulk

$self->get_bulk($host, \%args, \@oids, sub {
  my ($self, $err, $session) = @_;
  return warn $err if $err;
  push @{$res{$host}}, $session->var_bind_list;
});

Will send a SNMP get-bulk-request to the remote agent. See "get_bulk_request" in Net::SNMP for details on which %args you can pass on. See "prepare" for generic information about the variables associated with this method.

get_next

$self->get_next($host, \%args, \@oids, sub {
  my ($self, $err, $session) = @_;
  return warn $err if $err;
  push @{$res{$host}}, $session->var_bind_list;
});

Will send a SNMP get-next-request to the remote agent. See "get_next_request" in Net::SNMP for details on which $args you can pass on. See "prepare" for generic information about the variables associated with this method.

prepare

$self = $self->prepare($host, \%args, ...);
$self = $self->prepare(\@hosts, \%args, ...);
$self = $self->prepare(\@hosts, ...);
$self = $self->prepare("*" => ...);

  • $host

    This can either be an array ref or a single host. The "host" can be whatever "session" in Net::SNMP can handle; generally a hostname or IP address.

  • \%args

    A hash ref of options which will be passed directly to "session" in Net::SNMP. This argument is optional. See also "defaults".

  • dot-dot-dot

    A list of key-value pairs of SNMP operations and bindlists which will be given to "prepare". The operations are the same as the method names available in Net::SNMP, but without "_request" at end:

    get
get_next
set
get_bulk
inform
walk
bulk_walk
...

    The special hostname "*" will apply the given operation to all previously defined hosts.

Examples:

$self->prepare("192.168.0.1" => {version => "v2c"}, get_next => [$oid, ...]);
$self->prepare("192.168.0.1" => {version => "v3"}, get => [$oid, ...]);
$self->prepare(localhost => set => [$oid => OCTET_STRING, $value, ...]);
$self->prepare("*" => get => [$oid, ...]);

Note: To get the OCTET_STRING constant and friends you need to do:

use Net::SNMP ":asn1";

set

use Net::SNMP ":asn1"; # Export OCTET_STRING

$self->set($host, $args => [$oid, OCTET_STRING, $value, ...], sub {
  my ($self, $err, $session) = @_;
  return warn $err if $err;
  push @{$res{$host}}, $session->var_bind_list;
});

Will send a SNMP set-request to the remote agent. See "set_request" in Net::SNMP for details on which $args you can pass on. See "prepare" for generic information about the variables associated with this method.

walk

$self->walk($host, $args, \@oids, sub {
  my ($self, $err, $session) = @_;
  return warn $err if $err;
  push @{$res{$host}}, $session->var_bind_list;
});

This is a custom SNMP method added by "add_custom_request_method". See "prepare" for generic information about the variables associated with this method.

This method will run "get_next_request" in Net::SNMP until an oid retrieved does not match the base OID, or if the tree is exhausted. You might want to use "bulk_walk" instead for better performance.

wait

$self->wait;

This is useful if you want to block your code: wait() starts the ioloop and runs until "master_timeout" or "finish" is reached.

my $snmp = Mojo::SNMP->new;
$snmp->prepare(...)->wait; # blocks while retrieving data
# ... your program continues after the SNMP operations have finished.

AUTHOR

Jan Henning Thorsen - jhthorsen@cpan.org

CONTRIBUTORS

Espen Tallaksen - espen.tallaksen@telenor.com

Joshua Keroes - joshua.keroes@integratelecom.com

Oliver Gorwits - oliver@cpan.org

Per Carlson - per.carlson@broadnet.no

COPYRIGHT & LICENSE

Copyright (C) 2012-2018, "AUTHOR" and "CONTRIBUTORS".

This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.