NAME

NSNMP - fast, flexible, low-level, pure-Perl SNMP library

SYNOPSIS

    $bytes = NSNMP->encode(type => $type, request_id => $request_id,
                          varbindlist => [
                            [$ber_encoded_oid, $vtype, $value],
                            ...
                          ],
                          # and optionally:
                          community => $com, error_status => $status,
                          error_index => $index);
    $decoded = NSNMP->decode($bytes);
    ($decoded->snmp_version, $decoded->community, $decoded->type,
     $decoded->request_id, $decoded->error_status,
     $decoded->error_index, $decoded->varbindlist);
    $errname = NSNMP->error_description($decoded->error_status);
    $comprehensible_oid =
        NSNMP->decode_oid(($decoded->varbindlist)[0]->[0]);
    $ber_encoded_oid = NSNMP->encode_oid('1.3.6.1.2.1.1.5.0');

DESCRIPTION

If you want something well-tested and production-quality, you probably want Net::SNMP; if you just want to get and set some values with SNMP, you probably want NSNMP::Simple. This module is for you if you want something fast, something suitable for dumping packet contents, or something suitable for writing an SNMP agent.

This is an SNMP message encoding and decoding library, providing very low-level facilities; you pretty much need to read the SNMP RFCs to use it. It is, however, very fast (it's more than an order of magnitude faster than Net::SNMP 4.1.2, and it can send a request and parse a response in only slightly more time than the snmpd from net-snmp-5.0.6 takes to parse the request and send a response), and it's relatively complete --- the interface is flexible enough that you can use it to write SNMP management applications, SNMP agents, and test suites for SNMP implementations.

It doesn't export anything.

MODULE CONTENTS

Constants

This module defines a number of constants for BER and SNMP type tags and error names.

BER and SNMP types

These are one-byte strings: INTEGER, OCTET_STRING, NULL, OBJECT_IDENTIFIER, SEQUENCE, IpAddress, Counter32, Gauge32, TimeTicks, GET_REQUEST, GET_NEXT_REQUEST, GET_RESPONSE, SET_REQUEST.

SNMP error names

These are small integers: noError, tooBig, noSuchName, badValue, readOnly, genErr.

NSNMP->error_description($error_status)

Returns one of the strings 'noError', 'noSuchName', etc.

NSNMP->decode($message)

Given the bytes of a message (for example, received on a socket, or returned from "encode"), "decode" returns an "NSNMP::Message" object on which you can call methods to retrieve various fields of the SNMP message.

If it can't parse the message, it returns "undef".

See RFC 1157 (or a later SNMP RFC) for the meanings of each of these fields.

My 500MHz laptop can run about 1-1.5 million iterations of a Perl loop per second, and it can decode almost 8000 small messages per second with this method. It can decode a little over half as many if you also need varbindlists.

The available methods for retrieving message fields follow.

->version: Returns the numeric SNMP version: 1, 2, or 3. (Note that 1 is encoded as 0 in the packet, and 2 is encoded as 1, etc., but this method returns the human-readable number, not the weird encoding in the packet.)
->community: Returns the community string.
->type: Returns the type tag of the PDU, such as NSNMP::GET_REQUEST, NSNMP::GET_RESPONSE, NSNMP::SET_REQUEST, etc. (See "Constants".)
->request_id: Returns the bytes representing the request ID in the SNMP message. (This may seem perverse, but often, you don't have to decode them --- you can simply reuse them in a reply packet, or look them up in a hash of outstanding requests. Of course, in the latter case, you might have to decode them anyway, if the agent was perverse and re-encoded them in a different way than you sent them out.)
->error_status, ->error_index: Return the numeric error-status and error-index from the SNMP packet. In non-error cases, these will be 0.
->varbindlist: Returns a list of "[$oid, $type, $value]" triples. The type is a BER type, normally equal to NSNMP::OCTET_STRING or one of the other constants for BER types. (See "Constants".) The OIDs are still encoded in BER; you can use "->decode_oid" to get human-readable versions, as documented below.

NSNMP->encode_oid($oid)

This method produces the BER-encoded version of the ASCII-represented OID $oid, which must be a sequence of decimal numbers separated by periods. Leading periods are allowed.

NSNMP->decode_oid($bytestring)

Given the BER encoding of an OID in $bytestring, this method produces the OID's ASCII representation, as a sequence of decimal numbers separated by periods, without a leading period.

NSNMP->encode(%args)

Returns a string containing an encoded SNMP message, according to the args specified. Available args correspond one for one to the "NSNMP::Message" methods defined above under "decode"; they include the following:

request_id => $req_id_str: Request ID as a string (not an integer). Mandatory.
varbindlist => "[[$oid, $type, $value], [$oid, $type, $value]...]": Varbindlist as an ARRAY ref containing (oid, type, value) tuples, represented also as ARRAY refs. OIDs, types, and values are assumed to already be BER-encoded. You can sensibly pass the results of the "->varbindlist" method from a decoded message in here, just wrap it in an ARRAY ref: "varbindlist => [$msg->varbindlist]". Mandatory.
type => $type: PDU type --- normally NSNMP::GET_REQUEST, NSNMP::GET_RESPONSE, etc. (See "Constants".) Mandatory.
community => $community: Community string. Default is "public".
error_status => $error
error_index => $index: Error-status and error-index, as integers. Only meaningful on response messages. Default 0.
version => $ver: Human-readable version of SNMP: 1, 2, or 3, default 1. Presently 2 and 3 have features this library doesn't support.

EXAMPLES

Example usage of the main entry points, "encode", "decode", "encode_oid", and "decode_oid", follows:

    my $bytes = NSNMP->encode(
      type => NSNMP::GET_REQUEST, 
      request_id => (pack "N", 38202),
      varbindlist => [
        [NSNMP->encode_oid('.1.3.6.1.2.1.1.5.0'), NSNMP::NULL, ''],
      ],
    );
    $socket->send($bytes);
    my $decoded = NSNMP->decode($bytes);
    # prints "111111\n"
    print(
      ($decoded->version==1),
      ($decoded->community eq 'public'),
      ($decoded->type eq NSNMP::GET_REQUEST),
      ($decoded->request_id eq pack "N", 38202),
      ($decoded->error_status == 0),
      ($decoded->error_index == 0), "\n"
    );
    my @varbinds = $decoded->varbindlist;
    # prints "111\n"
    print(
      (NSNMP->decode_oid($varbinds[0][0]) eq '1.3.6.1.2.1.1.5.0'),
      ($varbinds[0][1] eq NSNMP::NULL),
      ($varbinds[0][2] eq ''),
      "\n",
    );

FILES

None.

AUTHOR

Kragen Sitaker <kragen@pobox.com>

BUGS

This documentation does not adequately express the stupidity and rottenness of the SNMP protocol design.

The ASN.1 BER, in which SNMP packets are encoded, allow the sender lots of latitude in deciding how to encode things. This module doesn't have to deal with that very often, but it does have to deal with the version, error-status, and error-index fields of SNMP messages, which are generally encoded in a single byte each. If the sender of an SNMP packet encodes them in multiple bytes instead, this module will fail to decode them, or worse, produce nonsense output. It should instead handle these packets correctly.

Malformed VarBindLists can cause the "->varbindlist" method to "die" with an unhelpful error message. It should instead return a helpful error indication of some kind.

It doesn't do much yet; in particular, it doesn't do SNMPv1 traps or anything from SNMPv2 or v3.

It doesn't even consider doing any of the following: decoding BER values found in varbind values, understanding MIBs, or anything that involves sending or receiving packets. These jobs belong to other modules, most of which haven't been written yet.