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.