Jan Henning Thorsen

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.