Net_SNMP_util(3) User Contributed Perl Documentation Net_SNMP_util(3)
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.
o 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.
o 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.
o 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:
o sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', 'timeticks', $timeticks)
o 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.
o 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.
o 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.
o 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 texual 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
o The Net_SNMP_util module uses syntax that is not supported in
versions of Perl earlier than v5.6.0.
o The Net_SNMP_util module uses the Net::SNMP module, and as such may
depend on other modules. Please see the documentaion 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.
perl v5.28.1 2008-11-21 Net_SNMP_util(3)
snmp_session 1.130.0 - Generated Mon May 13 10:08:46 CDT 2019