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

VERSION
    0.0301

SYNOPSIS
      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
    You should use this module if you need to fetch data from many SNMP
    servers really fast. 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 use Net::SNMP and Mojo::IOLoop to fetch data from hosts
    asynchronous. 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 is able to load.

    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 set 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 hosts 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
    How many hosts to fetch data from at once. Default is 20. (The default
    may change in later versions)

  defaults
    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
    How long to run in total before timeout. Note: This is NOT per host but
    for the complete run. Default is 0, meaning run for as long as you have
    to.

  ioloop
    Holds an instance of Mojo::IOLoop.

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

        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';

        Note: "walk" is a custom method provided by this module. It will run
        "get_next_request" until the next oid retrieved does not match the
        base OID or if the tree is exhausted.

  wait
    This is useful if you want to block your code: "wait()" starts the
    ioloop and runs until "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.

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

AUTHOR
    Jan Henning Thorsen - "jhthorsen@cpan.org"

    Joshua Keroes - "joshua@cpan.org"

