NSNMP(3)

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.