NSNMP - fast, flexible, low-level, pure-Perl SNMP library
$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');
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.
This module defines a number of constants for BER and SNMP type tags and error names.
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.
These are small integers: noError, tooBig, noSuchName, badValue, readOnly, genErr.
Returns one of the strings 'noError', 'noSuchName', etc.
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.
encode
decode
NSNMP::Message
If it can't parse the message, it returns undef.
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.
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.)
Returns the community string.
Returns the type tag of the PDU, such as NSNMP::GET_REQUEST, NSNMP::GET_RESPONSE, NSNMP::SET_REQUEST, etc. (See "Constants".)
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.)
Return the numeric error-status and error-index from the SNMP packet. In non-error cases, these will be 0.
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.
[$oid, $type, $value]
->decode_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.
$oid
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.
$bytestring
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 as a string (not an integer). Mandatory.
[[$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.
->varbindlist
varbindlist => [$msg->varbindlist]
PDU type --- normally NSNMP::GET_REQUEST, NSNMP::GET_RESPONSE, etc. (See "Constants".) Mandatory.
Community string. Default is public.
public
Error-status and error-index, as integers. Only meaningful on response messages. Default 0.
Human-readable version of SNMP: 1, 2, or 3, default 1. Presently 2 and 3 have features this library doesn't support.
Example usage of the main entry points, encode, decode, encode_oid, and decode_oid, follows:
encode_oid
decode_oid
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", );
None.
Kragen Sitaker <kragen@pobox.com>
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.
die
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.
To install NSNMP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm NSNMP
CPAN shell
perl -MCPAN -e shell install NSNMP
For more information on module installation, please visit the detailed CPAN module installation guide.