NAME
NSNMP::Simple - simple interface to get and set synchronously
SYNOPSIS
my $sysnameoid = '1.3.6.1.2.1.1.5.0';
my $hostname = NSNMP::Simple->get('127.0.0.1', $sysnameoid);
die $NSNMP::Simple::error unless defined $hostname;
NSNMP::Simple->set('127.0.0.1', $sysnameoid, NSNMP::OCTET_STRING,
'thor.cs.cmu.edu', community => 'CMUprivate')
or die $NSNMP::Simple::error;
my %sysoids = NSNMP::Simple->get_table('127.0.0.1', '1.3.6.1.2.1');
DESCRIPTION
NSNMP::Simple lets you get or set a single OID via SNMP with a single line of code. It's easier to use, and roughly an order of magnitude faster, than Net::SNMP 4.1.2, but Net::SNMP is still much more mature and complete. I don't presently recommend using NSNMP::Simple in production code.
MODULE CONTENTS
NSNMP::Simple->get($agent, $oid, %args)
Returns the value of $oid
on the SNMP agent at $agent
, which can be a hostname or an IP address, optionally followed by a colon and a numeric port number, which defaults to 161, the default SNMP port.
%args
can contain any or all of the following:
version => $ver
-
$ver is an SNMP version number (1 or 2 --- 3 isn't yet supported --- see "BUGS"). Default is 1.
community => $comm
-
Specifies the community string. Default is
public
. retries => $retries
-
Specifies retries. Default is 1 --- that is, two tries. Retries are evenly spaced.
timeout => $timeout
-
Specifies a timeout in (possibly fractional) seconds. Default is 5.0.
Translates the value of $oid
into a Perlish value, so, for example, an INTEGER OID whose value is 1 will be returned as "1", not "\001". IpAddresses are translated to dotted-quad notation, integer-like types are translated to integers, and OCTET STRINGS, OPAQUES, and NsapAddresses are left alone.
It doesn't return the type of the value at all.
In case of failure, it returns undef
and sets $NSNMP::Simple::error
to a string describing the error in English, in the same format as Net::SNMP's error messages.
NSNMP::Simple->set($agent, $oid, $type, $value, %args)
Sets the value of $oid
on the SNMP agent at $agent
to the value $value
, as BER-encoded type $type
. Returns true on success, false on failure, and also sets $NSNMP::Simple::error
on failure. Accepts the same %args
as ->get
.
NSNMP::Simple->get_table($agent, $oid, %args)
Gets the values of all OIDs under $oid
on the SNMP agent at $agent
. Returns a list of alternating OIDs and values, in OID lexical order; you can stuff it into a hash if you don't care about the order. If there are no OIDs under $oid
, returns an empty list and clears $NSNMP::Simple::error
. Note that this can be caused either by misspelling the OID or by actually having an empty table, and there's no way to tell which. (See the note in "BUGS" in SNMP about the SNMP protocol design.)
If any of the component SNMP requests returns an unexpected error, get_table
returns an empty list and sets $NSNMP::Simple::error
.
Note for Net::SNMP users: get_table
does not set $NSNMP::Simple::error
on an empty table, but Net::SNMP's get_table
does.
Accepts the same %args
as ->get
.
The OIDs in the returned list are spelled in ASCII with or without a leading dot, depending on whether or not $oid
has a leading dot.
$error
$NSNMP::Simple::error
is undef after any successful subroutine call on this module, and an English string describing the error after any unsuccessful subroutine call.
$NSNMP::Simple::error_status
is undef when $error
is undef, and when $error
is defined, $error_status
contains an integer describing the type of error. This may be a raw SNMP error-status
code, such as NSNMP::noSuchName, or it may be one of the following values:
- NSNMP::Simple::noResponse
-
This code means that the remote host sent no response, or at least, no response we could decode, so we timed out. (The timeout value is configurable, as described earlier.)
- NSNMP::Simple::badHostName
-
This code means that
NSNMP::Simple
couldn't resolve the hostname given. It might be malformed or a nonexistent DNS name, or it might be an existing DNS name, but DNS might be broken for some other reason.
FILES
None.
AUTHOR
Kragen Sitaker <kragen@pobox.com>
BUGS
This module uses the SNMP module, so it inherits most of the bugs of that module.
It's still too slow. On my 500MHz laptop, it can SNMP-walk 5675 OIDs in about 7.2 CPU seconds, for less than 800 OIDs per second. ucd-snmp (now confusingly called net-snmp, not to be confused with Net::SNMP) takes 1.8 CPU seconds to perform the same task. That's four times as fast. On the other hand, Net::SNMP manages about 110 OIDs per second, seven times slower still.