snmp.pm

开发snmp的开发包有两个开放的SNMP开发库

do SNMP GETNEXT like getnext and format the values according
the handlers specified in $sess->{VarFormats} and
$sess->{TypeFormats}

=item $sess->set(E<lt>varsE<gt> [,E<lt>callbackE<gt>])

do SNMP SET, multiple <vars> formats accepted.
the value field in all <vars> formats must be in a canonical
format (i.e., well known format) to ensure unambiguous
translation to SNMP MIB data value (see discussion of
canonical value format <vars> description section),
returns snmp_errno. If <callback> supplied method
will operate asyncronously

=item $sess->getbulk(E<lt>non-repeatersE<gt>, E<lt>max-repeatersE<gt>, E<lt>varsE<gt>)

do an SNMP GETBULK, from the list of Varbinds, the single
next lexico instance is fetched for the first n Varbinds
as defined by <non-repeaters>. For remaining Varbinds,
the m lexico instances are retrieved each of the remaining
Varbinds, where m is <max-repeaters>.

=item $sess->bulkwalk(E<lt>non-repeatersE<gt>, E<lt>max-repeatersE<gt>, E<lt>varsE<gt> [,E<lt>callbackE<gt>])

Do a "bulkwalk" of the list of Varbinds.  This is done by
sending a GETBULK request (see getbulk() above) for the
Varbinds.  For each requested variable, the response is
examined to see if the next lexico instance has left the
requested sub-tree.  Any further instances returned for
this variable are ignored, and the walk for that sub-tree
is considered complete.

If any sub-trees were not completed when the end of the
responses is reached, another request is composed, consisting
of the remaining variables.  This process is repeated until
all sub-trees have been completed, or too many packets have
been exchanged (to avoid loops).

The bulkwalk() method returns an array containing an array of
Varbinds, one for each requested variable, in the order of the
variable requests.  Upon error, bulkwalk() returns undef and
sets $sess->ErrorStr and $sess->ErrorNum.  If a callback is
supplied, bulkwalk() returns the SNMP request id, and returns
immediately.  The callback will be called with the supplied
argument list and the returned variables list.

Note: Because the client must "discover" that the tree is
complete by comparing the returned variables with those that
were requested, there is a potential "gotcha" when using the
max-repeaters value.  Consider the following code to print a
list of interfaces and byte counts:

    $numInts = $sess->get('ifNumber.0');
    ($desc, $in, $out) = $sess->bulkwalk(0, $numInts,
		  [['ifDescr'], ['ifInOctets'], ['ifOutOctets']]);

    for $i (0..($numInts - 1)) {
        printf "Interface %4s: %s inOctets, %s outOctets\n",
                  $$desc[$i]->val, $$in[$i]->val, $$out[$i]->val;
    }

This code will produce *two* requests to the agent -- the first
to get the interface values, and the second to discover that all
the information was in the first packet.  To get around this,
use '$numInts + 1' for the max_repeaters value.  This asks the
agent to include one additional (unrelated) variable that signals
the end of the sub-tree, allowing bulkwalk() to determine that
the request is complete.

=item $results = $sess->gettable(E<lt>TABLE OIDE<gt>, E<lt>OPTIONS<gt>)

This will retrieve an entire table of data and return a hash reference
to that data.  The returned hash reference will have indexes of the
OID suffixes for the index data as the key.  The value for each entry
will be another hash containing the data for a given row.  The keys to
that hash will be the column names, and the values will be the data.

Example:

  #!/usr/bin/perl

  use SNMP;
  use Data::Dumper;

  my $s = new SNMP::Session(DestHost => 'localhost');

  print Dumper($s->gettable('ifTable'));

On my machine produces:

  $VAR1 = {
            '6' => {
                     'ifMtu' => '1500',
                     'ifPhysAddress' => 'PV',
                     # ...
                     'ifInUnknownProtos' => '0'
                   },
            '4' => {
                     'ifMtu' => '1480',
                     'ifPhysAddress' => '',
                     # ...
                     'ifInUnknownProtos' => '0'
                   },
            # ...
           };

By default, it will try to do as optimized retrieval as possible.
It'll request multiple columns at once, and use GETBULK if possible.
A few options may be specified by passing in an I<OPTIONS> hash
containing various parameters:

=over

=item noindexes => 1

Instructs the code not to parse the indexes and place the results in
the second hash.  If you don't need the index data, this will be
faster.

=item columns => [ colname1, ... ]

This specifies which columns to collect.  By default, it will try to
collect all the columns defined in the MIB table.

=item repeat => I<COUNT>

Specifies a GETBULK repeat I<COUNT>.  IE, it will request this many
varbinds back per column when using the GETBULK operation.  Shortening
this will mean smaller packets which may help going through some
systems.  By default, this value is calculated and attepmts to guess
at what will fit all the results into 1000 bytes.  This calculation is
fairly safe, hopefully, but you can either raise or lower the number
using this option if desired.  In lossy networks, you want to make
sure that the packets don't get fragmented and lowering this value is
one way to help that.

=item nogetbulk => 1

Force the use of GETNEXT rather than GETBULK.  (always true for
SNMPv1, as it doesn't have GETBULK anyway).  Some agents are great
implementers of GETBULK and this allows you to force the use of
GETNEXT oprations instead.

=item callback => \&subroutine

=item callback => [\&subroutine, optarg1, optarg2, ...]

If a callback is specified, gettable will return quickly without
returning results.  When the results are finally retrieved the
callback subroutine will be called (see the other sections defining
callback behaviour and how to make use of SNMP::MainLoop which is
required fro this to work).  An additional argument of the normal hash
result will be added to the callback subroutine arguments.

Note 1: internally, the gettable function uses it's own callbacks
which are passed to getnext/getbulk as appropriate.

Note 2: callback support is only available in the SNMP module version
5.04 and above.  To test for this in code intending to support both
versions prior to 5.04 and and 5.04 and up, the following should work:

  if ($response = $sess->gettable('ifTable', callback => \&my_sub)) {
      # got a response, gettable doesn't support callback
      my_sub($response);
      $no_mainloop = 1;
  }

Deciding on whether to use SNMP::MainLoop is left as an excersize to
the reader since it depends on whether your code uses other callbacks
as well.

=back

=back

=head1 SNMP::TrapSession

$sess = new SNMP::Session(DestHost => 'host', ...)

supports all applicable fields from SNMP::Session
(see above)

=head2 SNMP::TrapSession methods

=over

=item $sess->trap(enterprise, agent, generic, specific, uptime, <vars>)

    $sess->trap(enterprise=>'.1.3.6.1.4.1.2021', # or 'ucdavis' [default]
                agent => '127.0.0.1', # or 'localhost',[dflt 1st intf on host]
                generic => specific,  # can be omitted if 'specific' supplied
                specific => 5,        # can be omitted if 'generic' supplied
                uptime => 1234,       # dflt to localhost uptime (0 on win32)
                [[ifIndex, 1, 1],[sysLocation, 0, "here"]]); # optional vars
                                                             # always last

=item trap(oid, uptime, <vars>) - v2 format

    $sess->trap(oid => 'snmpRisingAlarm',
                uptime => 1234,
                [[ifIndex, 1, 1],[sysLocation, 0, "here"]]); # optional vars
                                                             # always last

=back

=head1 Acceptable variable formats:

<vars> may be one of the following forms:

=over

=item SNMP::VarList

represents an array of MIB objects to get or set,
implemented as a blessed reference to an array of
SNMP::Varbinds, (e.g., [<varbind1>, <varbind2>, ...])

=item SNMP::Varbind

represents a single MIB object to get or set, implemented as
a blessed reference to a 4 element array;
[<obj>, <iid>, <val>, <type>].

=over

=item <obj>

one of the following forms:

=over

=item 1)

leaf identifier (e.g., 'sysDescr') assumed to be
unique for practical purposes

=item 2)

fully qualified identifier (e.g.,
'.iso.org.dod.internet.mgmt.mib-2.system.sysDescr')

=item 3)

fully qualified, dotted-decimal, numeric OID (e.g.,
'.1.3.6.1.2.1.1.1')

=back

=item <iid>

the dotted-decimal, instance identifier. for
scalar MIB objects use '0'

=item <val>

the SNMP data value retrieved from or being set
to the agents MIB. for (f)get(next) operations
<val> may have a variety of formats as determined by
session and package settings. However for set
operations the <val> format must be canonical to
ensure unambiguous translation. The canonical forms
are as follows:

=over

=item OBJECTID

dotted-decimal (e.g., .1.3.6.1.2.1.1.1)

=item OCTETSTR

perl scalar containing octets

=item INTEGER

decimal signed integer (or enum)

=item NETADDR

dotted-decimal

=item IPADDR

dotted-decimal

=item COUNTER

decimal unsigned integer

=item COUNTER64

decimal unsigned integer

=item GAUGE

decimal unsigned integer

=item UINTEGER

decimal unsigned integer

=item TICKS

decimal unsigned integer

=item OPAQUE

perl scalar containing octets

=item NULL

perl scalar containing nothing

=back

=item <type>

SNMP data type (see list above), this field is
populated by 'get' and 'getnext' operations. In
some cases the programmer needs to populate this
field when passing to a 'set' operation. this
field need not be supplied when the attribute
indicated by <tag> is already described by loaded
Mib modules. for 'set's, if a numeric OID is used
and the object is not currently in the loaded Mib,
the <type> field must be supplied

=back

=item simple string

light weight form of <var> used to 'set' or 'get' a
single attribute without constructing an SNMP::Varbind.
stored in a perl scalar, has the form '<tag>.<iid>',
(e.g., 'sysDescr.0'). for 'set' operations the value
is passed as a second arg. Note: This argument form is
not updated in get[next] operations as are the other forms.

=back

=head1 Acceptable callback formats

<callback> may be one of the following forms:

=over

=item without arguments

=over

=item \&subname

=item sub { ... }

=back

=item or with arguments

=over

=item [ \&subname, $arg1, ... ]

=item [ sub { ... }, $arg1, ... ]

=item [ "method", $obj, $arg1, ... ]

=back

=back

callback will be called when response is received or timeout
occurs. the last argument passed to callback will be a
SNMP::VarList reference. In case of timeout the last argument
will be undef.

=over

=item &SNMP::MainLoop([<timeout>, [<callback>]])

to be used with async SNMP::Session
calls. MainLoop must be called after initial async calls
so return packets from the agent will not be processed.
If no args suplied this function enters an infinite loop
so program must be exited in a callback or externally
interupted. If <timeout(sic)

=item &SNMP::finish()

This function, when called from an SNMP::MainLoop() callback
function, will cause the current SNMP::MainLoop() to return
after the callback is completed.  finish() can be used to
terminate an otherwise-infinite MainLoop.  A new MainLoop()
instance can then be started to handle further requests.

=back

=head1 SNMP package variables and functions

=over

=item $SNMP::VERSION

the current version specifier (e.g., 3.1.0)

=item $SNMP::auto_init_mib

default '1', set to 0 to disable automatic reading
of the MIB upon session creation. set to non-zero
to call initMib at session creation which will result
in MIB loading according to Net-SNMP env. variables (see
man mib_api)

=item $SNMP::verbose

default '0', controls warning/info output of
SNMP module, 0 => no output, 1 => enables warning/info
output from SNMP module itself (is also controlled
by SNMP::debugging - see below)

=item $SNMP::use_long_names

default '0', s