Provided by: libsnmp-session-perl_1.14~git20130523.186a005-2_all bug

NAME

       Net_SNMP_util - SNMP utilities based on Net::SNMP

SYNOPSIS

       The Net_SNMP_util module implements SNMP utilities using the Net::SNMP module.  It
       implements snmpget, snmpgetnext, snmpwalk, snmpset, snmptrap, and snmpgetbulk.  The
       Net_SNMP_util module assumes that the user has a basic understanding of the Simple Network
       Management Protocol and related network management concepts.

DESCRIPTION

       The Net_SNMP_util module simplifies SNMP queries even more than Net::SNMP alone.  Easy-to-
       use "get", "getnext", "walk", "set", "trap", and "getbulk" routines are provided, hiding
       all the details of a SNMP query.

Option Notes

       host Parameter
           SNMP parameters can be specified as part of the hostname/ip address passed as the
           first argument.  The syntax is

               community@host:port:timeout:retries:backoff:version

           If the community is left off, it defaults to "public".  If the port is left off, it
           defaults to 161 for everything but snmptrap().  The snmptrap() routine uses a default
           port of 162.  Timeout and retries defaults to whatever Net::SNMP uses, currently 5.0
           seconds and 1 retry (2 tries total).  The backoff parameter is currently
           unimplemented.  The version parameter defaults to SNMP version 1.  Some SNMP values
           such as 64-bit counters have to be queried using SNMP version 2.  Specifying "2" or
           "2c" as the version parameter will accomplish this.  The snmpgetbulk routine is only
           supported in SNMP version 2 and higher.  Additional security features are available
           under SNMP version 3.

           Some machines have additional security features that only allow SNMP queries to come
           from certain IP addresses.  If the host doing the query has multiple interfaces, it
           may be necessary to specify the interface the query should come from.  The port
           parameter is further broken down into

               remote_port!local_address!local_port

           Here are some examples:

               somehost
               somehost:161
               somehost:161!192.168.2.4!4000  use 192.168.2.4 and port 4000 as source
               somehost:!192.168.2.4          use 192.168.2.4 as source
               somehost:!!4000                use port 4000 as source

           Most people will only need to use the first form ("somehost").

       OBJECT IDENTIFIERs
           To further simplify SNMP queries, the query routines use a small table that maps the
           textual representation of OBJECT IDENTIFIERs to their dotted notation.  The OBJECT
           IDENTIFIERs from RFC1213 (MIB-II) and RFC1315 (Frame Relay) are preloaded.  This
           allows OBJECT IDENTIFIERs like "ifInOctets.4" to be used instead of the more
           cumbersome "1.3.6.1.2.1.2.2.1.10.4".

           Several functions are provided to manage the mapping table.  Mapping entries can be
           added directly, SNMP MIB files can be read, and a cache file with the text-to-OBJECT-
           IDENTIFIER mappings are maintained.  By default, the file "OID_cache.txt" is loaded,
           but it can by changed by setting the variable $Net_SNMP_util::CacheFile to the desired
           file name.  The functions to manipulate the mappings are:

               snmpmapOID                  Add a textual OID mapping directly
               snmpMIB_to_OID              Read a SNMP MIB file
               snmpLoad_OID_Cache          Load an OID-mapping cache file
               snmpQueue_MIB_File          Queue a SNMP MIB file for loading on demand

       Net::SNMP extensions
           This module is built on top of Net::SNMP.  Net::SNMP has a different method of
           specifying SNMP parameters.  To support this different method, this module will accept
           an optional hash reference containing the SNMP parameters. The hash may contain the
           following:

                   [-port          => $port,]
                   [-localaddr     => $localaddr,]
                   [-localport     => $localport,]
                   [-version       => $version,]
                   [-domain        => $domain,]
                   [-timeout       => $seconds,]
                   [-retries       => $count,]
                   [-maxmsgsize    => $octets,]
                   [-debug         => $bitmask,]
                   [-community     => $community,]   # v1/v2c
                   [-username      => $username,]    # v3
                   [-authkey       => $authkey,]     # v3
                   [-authpassword  => $authpasswd,]  # v3
                   [-authprotocol  => $authproto,]   # v3
                   [-privkey       => $privkey,]     # v3
                   [-privpassword  => $privpasswd,]  # v3
                   [-privprotocol  => $privproto,]   # v3
                   [-contextengineid => $engine_id,] # v3
                   [-contextname     => $name,]      # v3

           Please see the documentation for Net::SNMP for a description of these parameters.

       SNMPv3 Arguments
           A SNMP context is a collection of management information accessible by a SNMP entity.
           An item of management information may exist in more than one context and a SNMP entity
           potentially has access to many contexts.  The combination of a contextEngineID and a
           contextName unambiguously identifies a context within an administrative domain.  In a
           SNMPv3 message, the contextEngineID and contextName are included as part of the
           scopedPDU.  All methods that generate a SNMP message optionally take a
           -contextengineid and -contextname argument to configure these fields.

           Context Engine ID
               The -contextengineid argument expects a hexadecimal string representing the
               desired contextEngineID.  The string must be 10 to 64 characters (5 to 32 octets)
               long and can be prefixed with an optional "0x".  Once the -contextengineid is
               specified it stays with the object until it is changed again or reset to default
               by passing in the undefined value.  By default, the contextEngineID is set to
               match the authoritativeEngineID of the authoritative SNMP engine.

           Context Name
               The contextName is passed as a string which must be 0 to 32 octets in length using
               the -contextname argument.  The contextName stays with the object until it is
               changed.  The contextName defaults to an empty string which represents the
               "default" context.

Functions

   snmpget() - send a SNMP get-request to the remote agent
           @result = snmpget(
                       [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                       [\%param_hash],
                       @oids
                   );

       This function performs a SNMP get-request query to gather data from the remote agent on
       the host specified.  The message is built using the list of OBJECT IDENTIFIERs passed as
       an array.  Each OBJECT IDENTIFIER is placed into a single SNMP GetRequest-PDU in the same
       order that it held in the original list.

       The requested values are returned in an array in the same order as they were requested.
       In scalar context the first requested value is returned.

   snmpgetnext() - send a SNMP get-next-request to the remote agent
           @result = snmpgetnext(
                       [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                       [\%param_hash],
                       @oids
                   );

       This function performs a SNMP get-next-request query to gather data from the remote agent
       on the host specified.  The message is built using the list of OBJECT IDENTIFIERs passed
       as an array.  Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in
       the same order that it held in the original list.

       The requested values are returned in an array in the same order as they were requested.
       The OBJECT IDENTIFIER number is added as a prefix to each value using a colon as a
       separator, like '1.3.6.1.2.1.2.2.1.2.1:ethernet'.  In scalar context the first requested
       value is returned.

   snmpgetbulk() - send a SNMP get-bulk-request to the remote agent
           @result = snmpgetbulk(
                       [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                       $nonrepeaters,
                       $maxrepetitions,
                       [\%param_hash],
                       @oids
                   );

       This function performs a SNMP get-bulk-request query to gather data from the remote agent
       on the host specified.

       •   The $nonrepeaters value specifies the number of variables in the @oids list for which
           a single successor is to be returned.  If it is null or undefined, a value of 0 is
           used.

       •   The $maxrepetitions value specifies the number of successors to be returned for the
           remaining variables in the @oids list.  If it is null or undefined, the default value
           of 12 is used.

       •   The message is built using the list of OBJECT IDENTIFIERs passed as an array.  Each
           OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same order
           that it held in the original list.

       The requested values are returned in an array in the same order as they were requested.

       NOTE: This function can only be used when the SNMP version is set to SNMPv2c or SNMPv3.

   snmpwalk() - walk OBJECT IDENTIFIER tree(s) on the remote agent
           @result = snmpwalk(
                       [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                       [\%param_hash],
                       @oids
                   );

       This function performs a sequence of SNMP get-next-request or get-bulk-request (if the
       SNMP version is 2 or higher) queries to gather data from the remote agent on the host
       specified.  The initial message is built using the list of OBJECT IDENTIFIERs passed as an
       array.  Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same
       order that it held in the original list.  Queries continue until all the returned OBJECT
       IDENTIFIERs are no longer a child of the base OBJECT IDENTIFIERs.

       The requested values are returned in an array in the same order as they were requested.
       The OBJECT IDENTIFIER number is added as a prefix to each value using a colon as a
       separator, like '1.3.6.1.2.1.2.2.1.2.1:ethernet'.  If only one OBJECT IDENTIFIER is
       requested, just the "instance" part of the OBJECT IDENTIFIER is added as a prefix, like
       '1:ethernet', '2:ethernet', '3:fddi'.

   snmpset() - send a SNMP set-request to the remote agent
           @result = snmpset(
                       [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                       [\%param_hash],
                       $oid1, $type1, $value1,
                       [$oid2, $type2, $value2 ...]
                   );

       This function is used to modify data on the remote agent using a SNMP set-request.  The
       message is built using the list of values consisting of groups of an OBJECT IDENTIFIER, an
       object type, and the actual value to be set.  The object type can be one of the following
       strings:

           integer | int
           string | octetstring | octet string
           oid | object id | object identifier
           ipaddr | ip addr4ess
           timeticks
           uint | uinteger | uinteger32 | unsigned int | unsigned integer | unsigned integer32
           counter | counter 32
           counter64
           gauge | gauge32

       The object type may also be an octet corresponding to the ASN.1 type.  See the Net::SNMP
       documentation for more information.

       The requested values are returned in an array in the same order as they were requested.
       In scalar context the first requested value is returned.

   snmptrap() - send a SNMP trap to the remote manager
           @result = snmptrap(
                       [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                       $enterprise,
                       $agentaddr,
                       $generictrap,
                       $specifictrap,
                       [\%param_hash],
                       $oid1, $type1, $value1,
                       [$oid2, $type2, $value2 ...]
                   );

       This function sends a SNMP trap to the remote manager on the host specified.  The message
       is built using the list of values consisting of groups of an OBJECT IDENTIFIER, an object
       type, and the actual value to be set.  The object type can be one of the following
       strings:

           integer | int
           string | octetstring | octet string
           oid | object id | object identifier
           ipaddr | ip addr4ess
           timeticks
           uint | uinteger | uinteger32 | unsigned int | unsigned integer | unsigned integer32
           counter | counter 32
           counter64
           gauge | gauge32

       The object type may also be an octet corresponding to the ASN.1 type.  See the Net::SNMP
       documentation for more information.

       A true value is returned if sending the trap is successful.  The undefined value is
       returned when a failure has occurred.

       When the trap is sent as SNMPv2c, the $enterprise, $agentaddr, $generictrap, and
       $specifictrap arguments are ignored.  Furthermore, the first two (oid, type, value) tuples
       should be:

       •   sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', 'timeticks', $timeticks)

       •   snmpTrapOID.0 - ('1.3.6.1.6.3.1.1.4.1.0', 'oid', $oid)

       NOTE: This function can only be used when the SNMP version is set to SNMPv1 or SNMPv2c.

   snmpmaptable() - walk OBJECT IDENTIFIER tree(s) on the remote agent
           $result = snmpmaptable(
                       [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                       \&function,
                       [\%param_hash],
                       @oids
                   );

       This function performs a sequence of SNMP get-next-request or get-bulk-request (if the
       SNMP version is 2 or higher) queries to gather data from the remote agent on the host
       specified.  The initial message is built using the list of OBJECT IDENTIFIERs passed as an
       array.  Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same
       order that it held in the original list.  Queries continue until all the returned OBJECT
       IDENTIFIERs are no longer a child of the base OBJECT IDENTIFIERs.  The OBJECT IDENTIFIERs
       must correspond to column entries for a conceptual row in a table.  They may however be
       columns in different tables as long as each table is indexed the same way.

       •   The \&function argument will be called once per row of the table.  It will be passed
           the row index as a partial OBJECT IDENTIFIER in dotted notation, e.g. "1.3" or
           "10.0.1.34", and the values of the requested table columns in that row.

       The number of rows in the table is returned on success.  The undefined value is returned
       when a failure has occurred.

   snmpmaptable4() - walk OBJECT IDENTIFIER tree(s) on the remote agent
           $result = snmpmaptable4(
                       [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                       \&function,
                       $maxrepetitions,
                       [\%param_hash],
                       @oids
                   );

       This function performs a sequence of SNMP get-next-request or get-bulk-request (if the
       SNMP version is 2 or higher) queries to gather data from the remote agent on the host
       specified.  The initial message is built using the list of OBJECT IDENTIFIERs passed as an
       array.  Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same
       order that it held in the original list.  Queries continue until all the returned OBJECT
       IDENTIFIERs are no longer a child of the base OBJECT IDENTIFIERs.  The OBJECT IDENTIFIERs
       must correspond to column entries for a conceptual row in a table.  They may however be
       columns in different tables as long as each table is indexed the same way.

       •   The \&function argument will be called once per row of the table.  It will be passed
           the row index as a partial OBJECT IDENTIFIER in dotted notation, e.g. "1.3" or
           "10.0.1.34", and the values of the requested table columns in that row.

       •   The $maxrepetitions argument specifies the number of rows to be returned by a single
           get-bulk-request.  If it is null or undefined, the default value of 12 is used.

       The number of rows in the table is returned on success.  The undefined value is returned
       when a failure has occurred.

   snmpwalkhash() - send a SNMP get-next-request to the remote agent
           @result = snmpwalkhash(
                       [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                       \&function(),
                       [\%param_hash],
                       @oids,
                       [\%hash]
                   );

       This function performs a sequence of SNMP get-next-request or get-bulk-request (if the
       SNMP version is 2 or higher) queries to gather data from the remote agent on the host
       specified.  The message is built using the list of OBJECT IDENTIFIERs passed as an array.
       Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same order
       that it held in the original list.  Queries continue until all the returned OBJECT
       IDENTIFIERs are outside of the tree specified by the initial OBJECT IDENTIFIERs.

       The \&function is called once for every returned value.  It is passed a reference to a
       hash, the hostname, the textual OBJECT IDENTIFIER, the dotted-numberic OBJECT IDENTIFIER,
       the instance, the value and the requested textual OBJECT IDENTIFIER.  That function can
       customize the result so the values can be extracted later by hosts, by oid_names, by
       oid_numbers, by instances... like these:

           $hash{$host}{$name}{$inst} = $value;
           $hash{$host}{$oid}{$inst} = $value;
           $hash{$name}{$inst} = $value;
           $hash{$oid}{$inst} = $value;
           $hash{$oid . '.' . $ints} = $value;
           $hash{$inst} = $value;
           ...

       If the last argument to snmpwalkhash is a reference to a hash, that hash reference is
       passed to the passed-in function instead of a local hash reference.  That way the function
       can look up other objects unrelated to the current invocation of snmpwalkhash.

       The snmpwalkhash routine returns the hash.

   snmpmapOID() - add textual OBJECT INDENTIFIER mapping
           snmpmapOID(
               $text1, $oid1,
               [ $text2, $oid2 ...]
           );

       This routine adds entries to the table that maps textual representation of OBJECT
       IDENTIFIERs to their dotted notation.  For example,

           snmpmapOID('ciscoCPU', '1.3.6.1.4.1.9.9.109.1.1.1.1.5.1');

       allows the string 'ciscoCPU' to be used as an OBJECT IDENTIFIER in any SNMP query routine.

       This routine doesn't return anything.

   snmpLoad_OID_Cache() - Read a file of cached OID mappings
           $result = snmpLoad_OID_Cache(
                       $file
           );

       This routine opens the file named by the $file argument and reads it.  The file should
       contain text, OBJECT IDENTIFIER pairs, one pair per line.  It adds the pairs as entries to
       the table that maps textual representation of OBJECT IDENTIFIERs to their dotted notation.
       Blank lines and anything after a '#' or between '--' is ignored.

       This routine returns 0 on success and -1 if the $file could not be opened.

   snmpMIB_to_OID() - Read a MIB file for textual OID mappings
           $result = snmpMIB_to_OID(
                       $file
           );

       This routine opens the file named by the $file argument and reads it.  The file should be
       an SNMP Management Information Base (MIB) file that describes OBJECT IDENTIFIERs supported
       by an SNMP agent.  per line.  It adds the textual representation of the OBJECT IDENTIFIERs
       to the text-to-OID mapping table.

       This routine returns the number of entries added to the table or -1 if the $file could not
       be opened.

   snmpQueue_MIB_File() - queue a MIB file for reading "on demand"
           snmpQueue_MIB_File(
               $file1,
               [$file2, ...]
           );

       This routine queues the list of SNMP MIB files for later processing.  Whenever a text-to-
       OBJECT IDENTIFIER lookup fails, the list of queued MIB files is consulted.  If it isn't
       empty, the first MIB file in the list is removed and passed to snmpMIB_to_OID().  The
       lookup is attempted again, and if that still fails the next MIB file in the list is
       removed and passed to snmpMIB_to_OID(). This process continues until the lookup succeeds
       or the list is exhausted.

       This routine doesn't return anything.

EXPORTS

       The Net_SNMP_util module uses the Exporter module to export useful constants and
       subroutines.  These exportable symbols are defined below and follow the rules and
       conventions of the Exporter module (see Exporter).

       Exportable
           &snmpget, &snmpgetnext, &snmpgetbulk, &snmpwalk, &snmpset, &snmptrap, &snmpmaptable,
           &snmpmaptable4, &snmpwalkhash, &snmpmapOID, &snmpMIB_to_OID, &snmpLoad_OID_Cache,
           &snmpQueue_MIB_File, ErrorMessage

EXAMPLES

   1. SNMPv1 get-request for sysUpTime
       This example gets the sysUpTime from a remote host.

           #! /usr/local/bin/perl
           use strict;
           use Net_SNMP_util;
           my ($host, $ret)
           $host = shift || 'localhost';
           $ret = snmpget($host, 'sysUpTime');

           print("sysUpTime for $host is $ret\n");

           exit 0;

   2. SNMPv3 set-request of sysContact
       This example sets the sysContact information on the remote host to "Help Desk x911".  The
       parameters passed to the snmpset function are for the demonstration of syntax only.  These
       parameters will need to be set according to the SNMPv3 parameters of the remote host used
       by the script.

           #! /usr/local/bin/perl
           use strict;
           use Net_SNMP_util;
           my($host, %v3hash, $ret);
           $host = shift || 'localhost';
           $v3hash{'-version'}         = 'snmpv3';
           $v3hash{'-username'}        = 'myv3Username';
           $v3hash{'-authkey'}         = '0x05c7fbde31916f64da4d5b77156bdfa7';
           $v3hash{'-authprotocol'}    = 'md5';
           $v3hash{'-privkey'}         = '0x93725fd3a02a48ce02df4e065a1c1746';

           $ret = snmpset($host, \%v3hash, 'sysContact', 'string', 'Help Desk x911');

           print "sysContact on $host is now $ret\n";
           exit 0;

   3. SNMPv2c walk for ifTable
       This example gets the contents of the ifTable by sending get-bulk-requests until the
       responses are no longer part of the ifTable.  The ifTable can also be retrieved using
       "snmpmaptable".

           #! /usr/local/bin/perl
           use strict;
           use Net_SNMP_util;
           my($host, @ret, $oid, $val);
           $host = shift || 'localhost';

           @ret = snmpwalk($host . ':::::2', 'ifTable');
           foreach $val (@ret) {
               ($oid, $val) = split(':', $val, 2);
               print "$oid => $val\n";
           }
           exit 0;

   4. SNMPv2c maptable collecting ifDescr, ifInOctets, and ifOutOctets.
       This example collects a table containing the columns ifDescr, ifInOctets, and ifOutOctets.
       A printing function is called once per row.

           #! /usr/local/bin/perl
           use strict;
           use Net_SNMP_util;

           sub printfun($$$$) {
               my($inst, $desc, $in, $out) = @_;
               printf "%3d %-52.52s %10d %10d\n", $inst, $desc, $in, $out;
           }

           my($host, @ret);
           $host = shift || 'localhost';

           printf "%-3s %-52s %10s %10s\n", "Int", "Description", "In", "Out";
           @ret = snmpmaptable($host . ':::::2', \&printfun,
                               'ifDescr', 'ifInOctets', 'ifOutOctets');

           exit 0;

REQUIREMENTS

       •   The Net_SNMP_util module uses syntax that is not supported in versions of Perl earlier
           than v5.6.0.

       •   The Net_SNMP_util module uses the Net::SNMP module, and as such may depend on other
           modules.  Please see the documentation on Net::SNMP for more information.

AUTHOR

       Mike Mitchell <Mike.Mitchell@sas.com>

ACKNOWLEGEMENTS

       The original concept for this module was based on SNMP_Session.pm written by Simon Leinen
       <simon@switch.ch>

COPYRIGHT

       Copyright (c) 2007 Mike Mitchell.  All rights reserved.  This program is free software;
       you may redistribute it and/or modify it under the same terms as Perl itself.