GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  NSNMP (3)

.ds Aq ’

NAME

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

CONTENTS

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 NSNMP (3) 2004-01-25

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.