.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net_SNMP_util 3pm"
.TH Net_SNMP_util 3pm "2023-06-16" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net_SNMP_util \- SNMP utilities based on Net::SNMP
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
The Net_SNMP_util module implements \s-1SNMP\s0 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.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Net_SNMP_util module simplifies \s-1SNMP\s0 queries even more than Net::SNMP  
alone.  Easy-to-use \*(L"get\*(R", \*(L"getnext\*(R", \*(L"walk\*(R", \*(L"set\*(R", \*(L"trap\*(R", and \*(L"getbulk\*(R"
routines are provided, hiding all the details of a \s-1SNMP\s0 query.
.SH "Option Notes"
.IX Header "Option Notes"
.IP "host Parameter" 4
.IX Item "host Parameter"
\&\s-1SNMP\s0 parameters can be specified as part of the hostname/ip address passed
as the first argument.  The syntax is
.Sp
.Vb 1
\&    community@host:port:timeout:retries:backoff:version
.Ve
.Sp
If the community is left off, it defaults to \*(L"public\*(R".
If the port is left off, it defaults to 161 for everything but \fBsnmptrap()\fR.
The \fBsnmptrap()\fR 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 \s-1SNMP\s0 version 1.  Some \s-1SNMP\s0 values such as
64\-bit counters have to be queried using \s-1SNMP\s0 version 2.  Specifying \*(L"2\*(R" or
\&\*(L"2c\*(R" as the version parameter will accomplish this.  The snmpgetbulk routine
is only supported in \s-1SNMP\s0 version 2 and higher.  Additional security features
are available under \s-1SNMP\s0 version 3.
.Sp
Some machines have additional security features that only allow \s-1SNMP\s0
queries to come from certain \s-1IP\s0 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
.Sp
.Vb 1
\&    remote_port!local_address!local_port
.Ve
.Sp
Here are some examples:
.Sp
.Vb 5
\&    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
.Ve
.Sp
Most people will only need to use the first form (\*(L"somehost\*(R").
.IP "\s-1OBJECT\s0 IDENTIFIERs" 4
.IX Item "OBJECT IDENTIFIERs"
To further simplify \s-1SNMP\s0 queries, the query routines use a small table that
maps the textual representation of \s-1OBJECT\s0 IDENTIFIERs to their dotted notation.
The \s-1OBJECT\s0 IDENTIFIERs from \s-1RFC1213\s0 (MIB-II) and \s-1RFC1315\s0 (Frame Relay) are
preloaded.  This allows \s-1OBJECT\s0 IDENTIFIERs like \*(L"ifInOctets.4\*(R" to be used
instead of the more cumbersome \*(L"1.3.6.1.2.1.2.2.1.10.4\*(R".
.Sp
Several functions are provided to manage the mapping table.  Mapping entries
can be added directly, \s-1SNMP MIB\s0 files can be read, and a cache file with the
text-to-OBJECT-IDENTIFIER mappings are maintained.  By default, the file
\&\*(L"OID_cache.txt\*(R" is loaded, but it can by changed by setting the variable
\&\f(CW$Net_SNMP_util::CacheFile\fR to the desired file name.  The functions to
manipulate the mappings are:
.Sp
.Vb 4
\&    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
.Ve
.IP "Net::SNMP extensions" 4
.IX Item "Net::SNMP extensions"
This module is built on top of Net::SNMP.  Net::SNMP has a different method
of specifying \s-1SNMP\s0 parameters.  To support this different method, this module
will accept an optional hash reference containing the \s-1SNMP\s0 parameters. The
hash may contain the following:
.Sp
.Vb 10
\&        [\-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
.Ve
.Sp
Please see the documentation for Net::SNMP for a description of these
parameters.
.IP "SNMPv3 Arguments" 4
.IX Item "SNMPv3 Arguments"
A \s-1SNMP\s0 context is a collection of management information accessible by a \s-1SNMP\s0 
entity.  An item of management information may exist in more than one context 
and a \s-1SNMP\s0 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 \s-1SNMP\s0 message optionally take a \fB\-contextengineid\fR and \fB\-contextname\fR 
argument to configure these fields.
.RS 4
.IP "Context Engine \s-1ID\s0" 4
.IX Item "Context Engine ID"
The \fB\-contextengineid\fR 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 \*(L"0x\*(R".  Once the 
\&\fB\-contextengineid\fR 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
\&\s-1SNMP\s0 engine.
.IP "Context Name" 4
.IX Item "Context Name"
The contextName is passed as a string which must be 0 to 32 octets in length 
using the \fB\-contextname\fR argument.  The contextName stays with the object 
until it is changed.  The contextName defaults to an empty string which 
represents the \*(L"default\*(R" context.
.RE
.RS 4
.RE
.SH "Functions"
.IX Header "Functions"
.SS "\fBsnmpget()\fP \- send a \s-1SNMP\s0 get-request to the remote agent"
.IX Subsection "snmpget() - send a SNMP get-request to the remote agent"
.Vb 5
\&    @result = snmpget(
\&                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
\&                [\e%param_hash],
\&                @oids
\&            );
.Ve
.PP
This function performs a \s-1SNMP\s0 get-request query to gather data from the remote
agent on the host specified.  The message is built using the list of \s-1OBJECT\s0
IDENTIFIERs passed as an array.  Each \s-1OBJECT IDENTIFIER\s0 is placed into a single
\&\s-1SNMP\s0 GetRequest-PDU in the same order that it held in the original list.
.PP
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.
.SS "\fBsnmpgetnext()\fP \- send a \s-1SNMP\s0 get-next-request to the remote agent"
.IX Subsection "snmpgetnext() - send a SNMP get-next-request to the remote agent"
.Vb 5
\&    @result = snmpgetnext(
\&                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
\&                [\e%param_hash],
\&                @oids
\&            );
.Ve
.PP
This function performs a \s-1SNMP\s0 get-next-request query to gather data from the
remote agent on the host specified.  The message is built using the list of
\&\s-1OBJECT\s0 IDENTIFIERs passed as an array.  Each \s-1OBJECT IDENTIFIER\s0 is placed into a
single \s-1SNMP\s0 GetNextRequest-PDU in the same order that it held in the original
list.
.PP
The requested values are returned in an array in the same order as they were
requested.  The \s-1OBJECT IDENTIFIER\s0 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.
.SS "\fBsnmpgetbulk()\fP \- send a \s-1SNMP\s0 get-bulk-request to the remote agent"
.IX Subsection "snmpgetbulk() - send a SNMP get-bulk-request to the remote agent"
.Vb 7
\&    @result = snmpgetbulk(
\&                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
\&                $nonrepeaters,
\&                $maxrepetitions,
\&                [\e%param_hash],
\&                @oids
\&            );
.Ve
.PP
This function performs a \s-1SNMP\s0 get-bulk-request query to gather data from the
remote agent on the host specified.
.IP "\(bu" 4
The \fB\f(CB$nonrepeaters\fB\fR value specifies the number of variables in the \f(CW@oids\fR list
for which a single successor is to be returned.  If it is null or undefined,
a value of 0 is used.
.IP "\(bu" 4
The \fB\f(CB$maxrepetitions\fB\fR value specifies the number of successors to be returned
for the remaining variables in the \f(CW@oids\fR list.  If it is null or undefined,
the default value of 12 is used.
.IP "\(bu" 4
The message is built using the list of
\&\s-1OBJECT\s0 IDENTIFIERs passed as an array.  Each \s-1OBJECT IDENTIFIER\s0 is placed into a
single \s-1SNMP\s0 GetNextRequest-PDU in the same order that it held in the original
list.
.PP
The requested values are returned in an array in the same order as they were
requested.
.PP
\&\fB\s-1NOTE:\s0\fR This function can only be used when the \s-1SNMP\s0 version is set to
SNMPv2c or SNMPv3.
.SS "\fBsnmpwalk()\fP \- walk \s-1OBJECT IDENTIFIER\s0 tree(s) on the remote agent"
.IX Subsection "snmpwalk() - walk OBJECT IDENTIFIER tree(s) on the remote agent"
.Vb 5
\&    @result = snmpwalk(
\&                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
\&                [\e%param_hash],
\&                @oids
\&            );
.Ve
.PP
This function performs a sequence of \s-1SNMP\s0 get-next-request or get-bulk-request
(if the \s-1SNMP\s0 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
\&\s-1OBJECT\s0 IDENTIFIERs passed as an array.  Each \s-1OBJECT IDENTIFIER\s0 is placed into a
single \s-1SNMP\s0 GetNextRequest-PDU in the same order that it held in the original
list.  Queries continue until all the returned \s-1OBJECT\s0 IDENTIFIERs are no longer
a child of the base \s-1OBJECT\s0 IDENTIFIERs.
.PP
The requested values are returned in an array in the same order as they were
requested.  The \s-1OBJECT IDENTIFIER\s0 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 \s-1OBJECT IDENTIFIER\s0 is requested, just the \*(L"instance\*(R" part of the \s-1OBJECT
IDENTIFIER\s0 is added as a prefix, like '1:ethernet', '2:ethernet', '3:fddi'.
.SS "\fBsnmpset()\fP \- send a \s-1SNMP\s0 set-request to the remote agent"
.IX Subsection "snmpset() - send a SNMP set-request to the remote agent"
.Vb 6
\&    @result = snmpset(
\&                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
\&                [\e%param_hash],
\&                $oid1, $type1, $value1,
\&                [$oid2, $type2, $value2 ...]
\&            );
.Ve
.PP
This function is used to modify data on the remote agent using a \s-1SNMP\s0
set-request.  The message is built using the list of values consisting of groups
of an \s-1OBJECT IDENTIFIER,\s0 an object type, and the actual value to be set.
The object type can be one of the following strings:
.PP
.Vb 9
\&    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
.Ve
.PP
The object type may also be an octet corresponding to the \s-1ASN.1\s0 type.  See
the Net::SNMP documentation for more information.
.PP
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.
.SS "\fBsnmptrap()\fP \- send a \s-1SNMP\s0 trap to the remote manager"
.IX Subsection "snmptrap() - send a SNMP trap to the remote manager"
.Vb 10
\&    @result = snmptrap(
\&                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
\&                $enterprise,
\&                $agentaddr,
\&                $generictrap,
\&                $specifictrap,
\&                [\e%param_hash],
\&                $oid1, $type1, $value1, 
\&                [$oid2, $type2, $value2 ...]
\&            );
.Ve
.PP
This function sends a \s-1SNMP\s0 trap to the remote manager on the host specified.
The message is built using the list of values consisting of groups of an
\&\s-1OBJECT IDENTIFIER,\s0 an object type, and the actual value to be set.
The object type can be one of the following strings:
.PP
.Vb 9
\&    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
.Ve
.PP
The object type may also be an octet corresponding to the \s-1ASN.1\s0 type.  See
the Net::SNMP documentation for more information.
.PP
A true value is returned if sending the trap is successful.  The undefined value
is returned when a failure has occurred.
.PP
When the trap is sent as SNMPv2c, the \fB\f(CB$enterprise\fB\fR, \fB\f(CB$agentaddr\fB\fR,
\&\fB\f(CB$generictrap\fB\fR, and \fB\f(CB$specifictrap\fB\fR arguments are ignored.  Furthermore,
the first two (oid, type, value) tuples should be:
.IP "\(bu" 4
sysUpTime.0 \- ('1.3.6.1.2.1.1.3.0', 'timeticks', \f(CW$timeticks\fR)
.IP "\(bu" 4
snmpTrapOID.0 \- ('1.3.6.1.6.3.1.1.4.1.0', 'oid', \f(CW$oid\fR)
.PP
\&\fB\s-1NOTE:\s0\fR This function can only be used when the \s-1SNMP\s0 version is set to
SNMPv1 or SNMPv2c.
.SS "\fBsnmpmaptable()\fP \- walk \s-1OBJECT IDENTIFIER\s0 tree(s) on the remote agent"
.IX Subsection "snmpmaptable() - walk OBJECT IDENTIFIER tree(s) on the remote agent"
.Vb 6
\&    $result = snmpmaptable(
\&                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
\&                \e&function,
\&                [\e%param_hash],
\&                @oids
\&            );
.Ve
.PP
This function performs a sequence of \s-1SNMP\s0 get-next-request or get-bulk-request
(if the \s-1SNMP\s0 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
\&\s-1OBJECT\s0 IDENTIFIERs passed as an array.  Each \s-1OBJECT IDENTIFIER\s0 is placed into a
single \s-1SNMP\s0 GetNextRequest-PDU in the same order that it held in the original
list.  Queries continue until all the returned \s-1OBJECT\s0 IDENTIFIERs are no longer
a child of the base \s-1OBJECT\s0 IDENTIFIERs.  The \s-1OBJECT\s0 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.
.IP "\(bu" 4
The \fB\e&function\fR argument will be called once per row of the table.  It
will be passed the row index as a partial \s-1OBJECT IDENTIFIER\s0 in dotted notation,
e.g. \*(L"1.3\*(R" or \*(L"10.0.1.34\*(R", and the values of the requested table columns in
that row.
.PP
The number of rows in the table is returned on success.  The undefined value
is returned when a failure has occurred.
.SS "\fBsnmpmaptable4()\fP \- walk \s-1OBJECT IDENTIFIER\s0 tree(s) on the remote agent"
.IX Subsection "snmpmaptable4() - walk OBJECT IDENTIFIER tree(s) on the remote agent"
.Vb 7
\&    $result = snmpmaptable4(
\&                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
\&                \e&function,
\&                $maxrepetitions,
\&                [\e%param_hash],
\&                @oids
\&            );
.Ve
.PP
This function performs a sequence of \s-1SNMP\s0 get-next-request or get-bulk-request
(if the \s-1SNMP\s0 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
\&\s-1OBJECT\s0 IDENTIFIERs passed as an array.  Each \s-1OBJECT IDENTIFIER\s0 is placed into a
single \s-1SNMP\s0 GetNextRequest-PDU in the same order that it held in the original
list.  Queries continue until all the returned \s-1OBJECT\s0 IDENTIFIERs are no longer
a child of the base \s-1OBJECT\s0 IDENTIFIERs.  The \s-1OBJECT\s0 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.
.IP "\(bu" 4
The \fB\e&function\fR argument will be called once per row of the table.  It
will be passed the row index as a partial \s-1OBJECT IDENTIFIER\s0 in dotted notation,
e.g. \*(L"1.3\*(R" or \*(L"10.0.1.34\*(R", and the values of the requested table columns in
that row.
.IP "\(bu" 4
The \fB\f(CB$maxrepetitions\fB\fR 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.
.PP
The number of rows in the table is returned on success.  The undefined value
is returned when a failure has occurred.
.SS "\fBsnmpwalkhash()\fP \- send a \s-1SNMP\s0 get-next-request to the remote agent"
.IX Subsection "snmpwalkhash() - send a SNMP get-next-request to the remote agent"
.Vb 7
\&    @result = snmpwalkhash(
\&                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
\&                \e&function(),
\&                [\e%param_hash],
\&                @oids,
\&                [\e%hash]
\&            );
.Ve
.PP
This function performs a sequence of \s-1SNMP\s0 get-next-request or get-bulk-request
(if the \s-1SNMP\s0 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
\&\s-1OBJECT\s0 IDENTIFIERs passed as an array.  Each \s-1OBJECT IDENTIFIER\s0 is placed into a
single \s-1SNMP\s0 GetNextRequest-PDU in the same order that it held in the original
list.  Queries continue until all the returned \s-1OBJECT\s0 IDENTIFIERs are outside
of the tree specified by the initial \s-1OBJECT\s0 IDENTIFIERs.
.PP
The \fB\e&function\fR is called once for every returned value.  It is passed a
reference to a hash, the hostname, the textual \s-1OBJECT IDENTIFIER,\s0 the
dotted-numberic \s-1OBJECT IDENTIFIER,\s0 the instance, the value and the requested
textual \s-1OBJECT IDENTIFIER.\s0  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:
.PP
.Vb 7
\&    $hash{$host}{$name}{$inst} = $value;
\&    $hash{$host}{$oid}{$inst} = $value;
\&    $hash{$name}{$inst} = $value;
\&    $hash{$oid}{$inst} = $value;
\&    $hash{$oid . \*(Aq.\*(Aq . $ints} = $value;
\&    $hash{$inst} = $value;
\&    ...
.Ve
.PP
If the last argument to \fBsnmpwalkhash\fR 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 \fBsnmpwalkhash\fR.
.PP
The snmpwalkhash routine returns the hash.
.SS "\fBsnmpmapOID()\fP \- add textual \s-1OBJECT INDENTIFIER\s0 mapping"
.IX Subsection "snmpmapOID() - add textual OBJECT INDENTIFIER mapping"
.Vb 4
\&    snmpmapOID(
\&        $text1, $oid1,
\&        [ $text2, $oid2 ...]
\&    );
.Ve
.PP
This routine adds entries to the table that maps textual representation of
\&\s-1OBJECT\s0 IDENTIFIERs to their dotted notation.  For example,
.PP
.Vb 1
\&    snmpmapOID(\*(AqciscoCPU\*(Aq, \*(Aq1.3.6.1.4.1.9.9.109.1.1.1.1.5.1\*(Aq);
.Ve
.PP
allows the string 'ciscoCPU' to be used as an \s-1OBJECT IDENTIFIER\s0 in any \s-1SNMP\s0
query routine.
.PP
This routine doesn't return anything.
.SS "\fBsnmpLoad_OID_Cache()\fP \- Read a file of cached \s-1OID\s0 mappings"
.IX Subsection "snmpLoad_OID_Cache() - Read a file of cached OID mappings"
.Vb 3
\&    $result = snmpLoad_OID_Cache(
\&                $file
\&    );
.Ve
.PP
This routine opens the file named by the \fB\f(CB$file\fB\fR argument and reads it.
The file should contain text, \s-1OBJECT IDENTIFIER\s0 pairs, one pair
per line.  It adds the pairs as entries to the table that maps textual
representation of \s-1OBJECT\s0 IDENTIFIERs to their dotted notation.
Blank lines and anything after a '#' or between '\-\-' is ignored.
.PP
This routine returns 0 on success and \-1 if the \fB\f(CB$file\fB\fR could not be opened.
.SS "\fBsnmpMIB_to_OID()\fP \- Read a \s-1MIB\s0 file for textual \s-1OID\s0 mappings"
.IX Subsection "snmpMIB_to_OID() - Read a MIB file for textual OID mappings"
.Vb 3
\&    $result = snmpMIB_to_OID(
\&                $file
\&    );
.Ve
.PP
This routine opens the file named by the \fB\f(CB$file\fB\fR argument and reads it.
The file should be an \s-1SNMP\s0 Management Information Base (\s-1MIB\s0) file
that describes \s-1OBJECT\s0 IDENTIFIERs supported by an \s-1SNMP\s0 agent.
per line.  It adds the textual representation of the \s-1OBJECT\s0 IDENTIFIERs
to the text-to-OID mapping table.
.PP
This routine returns the number of entries added to the table or \-1 if
the \fB\f(CB$file\fB\fR could not be opened.
.ie n .SS "\fBsnmpQueue_MIB_File()\fP \- queue a \s-1MIB\s0 file for reading ""on demand"""
.el .SS "\fBsnmpQueue_MIB_File()\fP \- queue a \s-1MIB\s0 file for reading ``on demand''"
.IX Subsection "snmpQueue_MIB_File() - queue a MIB file for reading on demand"
.Vb 4
\&    snmpQueue_MIB_File(
\&        $file1,
\&        [$file2, ...]
\&    );
.Ve
.PP
This routine queues the list of \s-1SNMP MIB\s0 files for later processing.
Whenever a text-to-OBJECT \s-1IDENTIFIER\s0 lookup fails, the list of queued \s-1MIB\s0
files is consulted.  If it isn't empty, the first \s-1MIB\s0 file in the list is
removed and passed to \fB\fBsnmpMIB_to_OID()\fB\fR.  The lookup is attempted again,
and if that still fails the next \s-1MIB\s0 file in the list is removed and passed
to \fB\fBsnmpMIB_to_OID()\fB\fR. This process continues until the lookup succeeds
or the list is exhausted.
.PP
This routine doesn't return anything.
.SH "EXPORTS"
.IX Header "EXPORTS"
The Net_SNMP_util module uses the \fIExporter\fR module to export useful
constants and subroutines.  These exportable symbols are defined below and
follow the rules and conventions of the \fIExporter\fR module (see Exporter).
.IP "Exportable" 4
.IX Item "Exportable"
&snmpget, &snmpgetnext, &snmpgetbulk, &snmpwalk, &snmpset, &snmptrap,
&snmpmaptable, &snmpmaptable4, &snmpwalkhash, &snmpmapOID, &snmpMIB_to_OID,
&snmpLoad_OID_Cache, &snmpQueue_MIB_File, ErrorMessage
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "1. SNMPv1 get-request for sysUpTime"
.IX Subsection "1. SNMPv1 get-request for sysUpTime"
This example gets the sysUpTime from a remote host.
.PP
.Vb 6
\&    #! /usr/local/bin/perl
\&    use strict;
\&    use Net_SNMP_util;
\&    my ($host, $ret)
\&    $host = shift || \*(Aqlocalhost\*(Aq;
\&    $ret = snmpget($host, \*(AqsysUpTime\*(Aq);
\&
\&    print("sysUpTime for $host is $ret\en");
\&
\&    exit 0;
.Ve
.SS "2. SNMPv3 set-request of sysContact"
.IX Subsection "2. SNMPv3 set-request of sysContact"
This example sets the sysContact information on the remote host to 
\&\*(L"Help Desk x911\*(R".  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.
.PP
.Vb 10
\&    #! /usr/local/bin/perl
\&    use strict;
\&    use Net_SNMP_util;
\&    my($host, %v3hash, $ret);
\&    $host = shift || \*(Aqlocalhost\*(Aq;
\&    $v3hash{\*(Aq\-version\*(Aq}         = \*(Aqsnmpv3\*(Aq;
\&    $v3hash{\*(Aq\-username\*(Aq}        = \*(Aqmyv3Username\*(Aq;
\&    $v3hash{\*(Aq\-authkey\*(Aq}         = \*(Aq0x05c7fbde31916f64da4d5b77156bdfa7\*(Aq;
\&    $v3hash{\*(Aq\-authprotocol\*(Aq}    = \*(Aqmd5\*(Aq;
\&    $v3hash{\*(Aq\-privkey\*(Aq}         = \*(Aq0x93725fd3a02a48ce02df4e065a1c1746\*(Aq;
\&
\&    $ret = snmpset($host, \e%v3hash, \*(AqsysContact\*(Aq, \*(Aqstring\*(Aq, \*(AqHelp Desk x911\*(Aq);
\&
\&    print "sysContact on $host is now $ret\en";
\&    exit 0;
.Ve
.SS "3. SNMPv2c walk for ifTable"
.IX Subsection "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 \f(CW\*(C`snmpmaptable\*(C'\fR.
.PP
.Vb 5
\&    #! /usr/local/bin/perl
\&    use strict;
\&    use Net_SNMP_util;
\&    my($host, @ret, $oid, $val);
\&    $host = shift || \*(Aqlocalhost\*(Aq;
\&
\&    @ret = snmpwalk($host . \*(Aq:::::2\*(Aq, \*(AqifTable\*(Aq);
\&    foreach $val (@ret) {
\&        ($oid, $val) = split(\*(Aq:\*(Aq, $val, 2);
\&        print "$oid => $val\en";
\&    }
\&    exit 0;
.Ve
.SS "4. SNMPv2c maptable collecting ifDescr, ifInOctets, and ifOutOctets."
.IX Subsection "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.
.PP
.Vb 3
\&    #! /usr/local/bin/perl
\&    use strict;
\&    use Net_SNMP_util;
\&
\&    sub printfun($$$$) {
\&        my($inst, $desc, $in, $out) = @_;
\&        printf "%3d %\-52.52s %10d %10d\en", $inst, $desc, $in, $out;
\&    }
\&
\&    my($host, @ret);
\&    $host = shift || \*(Aqlocalhost\*(Aq;
\&
\&    printf "%\-3s %\-52s %10s %10s\en", "Int", "Description", "In", "Out";
\&    @ret = snmpmaptable($host . \*(Aq:::::2\*(Aq, \e&printfun,
\&                        \*(AqifDescr\*(Aq, \*(AqifInOctets\*(Aq, \*(AqifOutOctets\*(Aq);
\&
\&    exit 0;
.Ve
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
.IP "\(bu" 4
The Net_SNMP_util module uses syntax that is not supported in versions of Perl 
earlier than v5.6.0.
.IP "\(bu" 4
The Net_SNMP_util module uses the \fINet::SNMP\fR module, and as such may depend
on other modules.  Please see the documentation on \fINet::SNMP\fR for more
information.
.SH "AUTHOR"
.IX Header "AUTHOR"
Mike Mitchell <Mike.Mitchell@sas.com>
.SH "ACKNOWLEGEMENTS"
.IX Header "ACKNOWLEGEMENTS"
The original concept for this module was based on \fISNMP_Session.pm\fR written
by Simon Leinen <simon@switch.ch>
.SH "COPYRIGHT"
.IX Header "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.