Mojo::SNMP - Run SNMP requests with Mojo::IOLoop
0.13
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;
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;
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.
$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().
$session
See "response" for $args description.
$args
$self->on(finish => sub { my $self = shift; ... });
Emitted when all requests have completed.
$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, ...], ... }
$self->on(timeout => sub { my $self = shift; ... })
Emitted if "wait" has been running for more than "master_timeout" seconds.
$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)
$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.
%args
prepare()
version
NOTE: SNMP version will default to "v2c".
$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.
$self = $self->ioloop(Mojo::IOLoop->new); $ioloop = $self->ioloop;
Holds an instance of Mojo::IOLoop.
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 { ... });
$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:
maxrepetitions
$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; });
$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.
$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.
$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.
$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:
OCTET_STRING
use Net::SNMP ":asn1";
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.
$self->walk($host, $args, \@oids, sub { my ($self, $err, $session) = @_; return warn $err if $err; push @{$res{$host}}, $session->var_bind_list; });
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.
$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.
wait()
my $snmp = Mojo::SNMP->new; $snmp->prepare(...)->wait; # blocks while retrieving data # ... your program continues after the SNMP operations have finished.
Jan Henning Thorsen - jhthorsen@cpan.org
jhthorsen@cpan.org
Espen Tallaksen - espen.tallaksen@telenor.com
espen.tallaksen@telenor.com
Joshua Keroes - joshua.keroes@integratelecom.com
joshua.keroes@integratelecom.com
Oliver Gorwits - oliver@cpan.org
oliver@cpan.org
Per Carlson - per.carlson@broadnet.no
per.carlson@broadnet.no
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.
To install Mojo::SNMP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojo::SNMP
CPAN shell
perl -MCPAN -e shell install Mojo::SNMP
For more information on module installation, please visit the detailed CPAN module installation guide.