NAME¶

SNMP::Multi - Perform SNMP operations on multiple hosts simultaneously

SYNOPSIS¶

    use SNMP::Multi;
    my $req = SNMP::Multi::VarReq->new (
        nonrepeaters => 1,
        hosts => [ qw/ router1.my.com router2.my.com / ],
        vars  => [ [ 'sysUpTime' ], [ 'ifInOctets' ], [ 'ifOutOctets' ] ],
    );
    die "VarReq: $SNMP::Multi::VarReq::error\n" unless $req;
    my $sm = SNMP::Multi->new (
        Method      => 'bulkwalk',
        MaxSessions => 32,
        PduPacking  => 16,
        Community   => 'public',
        Version     => '2c',
        Timeout     => 5,
        Retries     => 3,
        UseNumeric  => 1,
        # Any additional options for SNMP::Session::new() ...
    )
    or die "$SNMP::Multi::error\n";
    $sm->request($req) or die $sm->error;
    my $resp = $sm->execute() or die "Execute: $SNMP::Multi::error\n";
    print "Got response for ", (join ' ', $resp->hostnames()), "\n";
    for my $host ($resp->hosts()) {
        print "Results for $host: \n";
        for my $result ($host->results()) {
            if ($result->error()) {
                print "Error with $host: ", $result->error(), "\n";
                next;
            }
            print "Values for $host: ", (join ' ', $result->values());
            for my $varlist ($result->varlists()) {
                print map { "\t" . $_->fmt() . "\n" } @$varlist;
            }
            print "\n";
        }
    }

DESCRIPTION¶

The SNMP::Multi package provides a mechanism to perform SNMP operations on several hosts simultaneously. SNMP::Multi builds on G. Marzot's SNMP Perl interface to the UC-Davis SNMP libraries, using asynchronous SNMP operations to send queries/sets to multiple hosts simultaneously.

Results from all hosts are compiled into a single object, which offers methods to access the data in aggregate, or broken down by host or the individual request.

SNMP::Multi supports SNMP GET, SET, GETNEXT, GETBULK and BULKWALK requests. It also performs PDU packing in order to improve network efficiency, when packing is possible.

OPTIONS¶

The SNMP::Multi constructor takes the following options to control its behavior. Any other options are stored and handed to the SNMP::Session constructor when a new SNMP session is created. As the behavior of SNMP::Multi depends upon certain SNMP::Session parameters (i.e. Timeout), these will be listed below as SNMP::Multi options. These "overlapped" options will be passed un-changed to SNMP::Session's constructor.

``Method''

``Requests''

``PduPacking''

``MaxSessions''

``Concurrent''

``GetbulkMax''

``ExternalSelect''

``Retries'' (shared with SNMP::Session)

``Timeout'' (shared with SNMP::Session)

        (retries + 1) * timeout

``Community'' (shared with SNMP::Session)

``Version'' (shared with SNMP::Session)

METHODS¶

The SNMP::Multi object provides several methods for the caller. In most cases, only the new(), request(), and execute() methods need to be used. The various methods are documented in approximately the order in which they are normally called.

SNMP::Multi::new(...)

SNMP::Multi::request( <ref to SNMP::Multi::VarReq> )

    my $req = SNMP::Multi::VarReq->new( ... );
    my $sm  = SNMP::Multi->new( ... );
    while ($req) {
        $sm->request($req);
        my $resp = $sm->execute();
        handle_response($resp);
        print "Timeout - retrying" if ($req = $sm->remaining());
    }

Building SNMP::Multi::VarReq Requests¶

SNMP variable requests are composed and passed to the SNMP::Multi object through an auxiliary class called an SNMP::Multi::VarReq. This class simply collects SNMP requests for variables and hosts (and optionally validates them).

The interface to SNMP::Multi::VarReq is very simple, providing only new() and add() methods. They take the following arguments:

    'vars'           => [ list of Varbinds to be requested (REQUIRED) ]
    'hosts'          => [ list of hosts for this variable list ]
    'nonrepeaters'   => [ GETBULK/BULKWALK "nonrepeaters" parameter ]
    'maxrepetitions' => [ GETBULK/BULKWALK "maxrepetitions" parameter ]

Every call to new() or add() must contain a list of SNMP variables. If the hosts parameter is not specified, the variable list will be requested from all hosts currently known by the SNMP::Multi::VarReq object. If a host list is given, the variables will be requested only from the named hosts.

Some simple sanity checks can be performed on the VarReq by calling its validate() method, or by setting $SNMP::Multi::VarReq::autovalidate to 1 before calling the new() method.

An example of building up a complicated request using new() and add():

    Start with:
        $r = SNMP::Multi::VarReq->new(
            hosts => [ qw/ A B C / ],
            vars  => [ qw/ 1 2 3 / ]
        );
    to get:
        A: 1 2 3
        B: 1 2 3
        C: 1 2 3
    Now add a var to each host:
        $r->add( vars => [ qw/ 4 / ] );
    to get:
        A: 1 2 3 4
        B: 1 2 3 4
        C: 1 2 3 4
    Add a var to a specific set of hosts:
        $r->add( hosts => [ qw/ A C / ],
                 vars  => [ qw/ 5   / ] );
    to get:
        A: 1 2 3 4 5
        B: 1 2 3 4
        C: 1 2 3 4 5
    Finally, create two new hosts and add a pair of vars to them:
        $r->add( hosts => [ qw/ D E / ],
                 vars =>  [ qw/ 6 7 / ] );
    to get:
        A: 1 2 3 4 5
        B: 1 2 3 4
        C: 1 2 3 4 5
        D: 6 7
        E: 6 7

The SNMP::Multi::VarReq object also provides a dump() method which generates a simple dump of the current host/var requests.

SNMP PDU Packing Features¶

SNMP::Multi packs SNMP::Varbind requests into larger request "hunks" to reduce the number of request/response pairs required to complete the SNMP::Multi request. This packing is controlled by the SNMP::Multi 'PduPacking' parameter.

For instance, assume your application creates an SNMP::Multi object with a 'PduPacking' value of 3. SNMP::Multi will pack 5 single SNMP variable requests into two distinct requests. The first request will contain the first 3 variables, the second will get the remaining two variables.

PDU packing is not done for SNMP GETBULK and BULKWALK requests. The feature may be disabled by setting the 'PduPacking' parameter to '0'.

Accessing SNMP Data From Agent Responses¶

The SNMP::Multi::execute() method returns the responses from the SNMP agents in an SNMP::Multi::Response object. This object, indexed by hostname, consists of per-host response objects (SNMP::Multi::Response::Host's), each of which contains a list of SNMP::Multi::Result objects. The Result objects connect an SNMP::VarList with the error status (if any) from the SNMP request. An entry is only made in the Response object if the SNMP agent returned some response to SNMP::Multi.

This is fairly complicated, but the various objects provide accessor methods to make access to the SNMP responses simple. Assume your application is structured something like this example source code:

    my $req = SNMP::Multi::VarReq->new( hosts => [...],
                                        vars  => [...] );
    my $sm  = SNMP::Multi->new( ... requests => $req, ... );
    my $response = $sm->execute( $overall_timeout );
    die $sm->error() if $sm->error();

Now the data can be accessed through methods on the objects that make up the SNMP::Multi::Response returned by execute(). An SNMP::VarList object is returned for each variable requested. This normalizes the return format across all SNMP operations (including bulkwalks).

See the SYNOPSIS section above for an example of how to access the SNMP data values after calling the execute() method.

SNMP::Multi::Response methods

SNMP::Multi::Response::Host methods

        print "This is the list of results for $host: \n";

SNMP::Multi::Result methods

The SNMP::Multi::Result object correlates SNMP error information with the response to an SNMP request.

EXAMPLES¶

A complete example is given in the "SYNOPSIS" section above.

CAVEATS¶

The VarList returned for GETBULK requests is "decoded" by SNMP::Multi into an array of single VarLists, one for each requested variable. This behavior differs from the return from the getbulk() method in the SNMP.pm module, but is consistent with the return value of SNMP.pm's bulkwalk() method.

Note that the V1 SNMP protocol has very limited error reporting (the agent returns no values, and the 'errind' is set to the index of the offending SNMP variable request). The SNMP::Multi module adjusts the 'errind' index to indicate which of the variables request requested for a host have failed, regardless of the number of actual packets exchanged. This is necessary to support SNMP::Multi's transparent pdu-packing feature.

SNMP::Multi relies on features added to the SNMP module by Electric Lightwave, Inc. These features have been incorporated into UCD-SNMP releases 4.2 and later. You must have SNMP 4.2 or later installed to use this package.

Using SNMP::Multi with large numbers of hosts or large requests may cause network congestion. All targets may send PDU's to the originating host simultaneously, which could cause heavy traffic and/or dropped packets at the host. Adjusting the Concurrent and PduPacking variables can mitigate this problem.

Network congestion may be a serious problem for bulkwalks, due to multiple packets being exchanged per session. However, network latency and variable target response times cause packets in multiple bulkwalk exchanges to become spread out as the walk progresses. The initial exchange, however, will always cause congestion.

BUGS¶

There is no interface to specify a different SNMP community string for a specific host, although the community is stored on a per-host basis.

SEE ALSO¶

SNMP, the NetSNMP homepage at http://www.net-snmp.org/.

AUTHOR¶

Karl ("Terminator rAT") Schilke <rat@eli.net>

CONTRIBUTORS¶

Joshua Keroes, Todd Caine, Toni Prug <tony@irational.org>

COPYRIGHT¶

Developed by Karl "Terminator rAT" Schilke for Electric Lightwave, Inc. Copyright (c) 2000-2002 Electric Lightwave, Inc. All rights reserved.

Co-maintained by Toni Prug.

This software is provided ``as is'' and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and/or fitness for a particular purpose.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

POD ERRORS¶

Hey! The above document had some coding errors, which are explained below:

Around line 93:

'=item' outside of any '=over'

Around line 250:

You forgot a '=back' before '=head1'

Around line 257:

'=item' outside of any '=over'

Around line 268:

You can't have =items (as at line 277) unless the first thing after the =over is an =item

Around line 326:

You forgot a '=back' before '=head1'

You forgot a '=back' before '=head1'

Around line 444:

'=item' outside of any '=over'

Around line 480:

'=item' outside of any '=over'

Around line 551:

You forgot a '=back' before '=head1'