Data Types

snmp.types

class Asn1Encodable

This is the base class for all other classes documented here. It defines the API for encoding and decoding SNMP objects to and from the byte strings that are sent across the network. It also defines the == equality operator, as well as the less-strict equals() method.

classmethod decode(data, leftovers=False, copy=True)

Create a new object by decoding it from the byte string data. In the default case, this method expects to consume the entire string. If data encodes multiple objects, then leftovers should be set to True, in which case the leftover portion of the data will be returned as well (i.e. it will return a tuple containing both the decoded object and the leftover data).

The copy argument determines whether the decoded object will contain a reference to the original data, or a copy. This has nothing to do with performance, and everything to do with computing message signatures when message authentication is required.

If the data cannot be decoded as requested, a snmp.ber.ParseError will be raised.

encode()

Encode an object into a byte-string. This method may throw an exception if the object contains an invalid value, but should succeed otherwise.

__eq__(other)

The == operator performs a strict equality check, which returns True if and only if the two objects are of the exact same type, and also have the same value, as determined by the equals() method.

equals(other)

This method checks whether two objects represent equal values, regardless of the exact type. The two types, however, must at least derive from the same base class, one of Integer, OctetString, Null, OID, or they may be two sequence types.

class Integer(value)

This is the base class for all other integral types. On its own, it represents the built-in ASN.1 INTEGER type, which is restricted to a 32-bit signed integer by the SMIv2 (see RFC 2578#section-2).

property value

The object’s value as a native int.

class OctetString(data)

This class represents the built-in ASN.1 OCTET STRING type. It may be subclassed to implement other types such as IpAddress.

property data

The object’s raw data as a bytes-like object.

class Null

This class represents the built-in ASN.1 NULL type. It is also the base class for types like EndOfMibView.

class OID(*nums)

This class represents an ASN.1 Object Identifier. An object identifier is a sequence of up to 255 integers (called sub-identifiers) that describe a path to a node in the MIB tree. For an explanation of the MIB tree, consult RFC 2578. Object identifiers are normally expressed in string by placing a dot between each sub-identifier, like this: "1.3.6.1.2.1.1.1".

Sub-identifiers are limited to the range 0 to (2^32)-1, with the exception of the first two; the first must be between 0 and 2, and the second must be between 0 and 39. Because of the encoding rules, it is not possible to send an OID with less than two sub-identifiers. This class can be instantiated with zero or one sub-identifiers, but, when encoded, will be treated as if there were implicit zeros at the end.

Lastly, every instance of this class is treated as a value type, meaning that its contents are immutable. Methods such as extend(), which modify the the value, always return a new object, and leave the original unchanged.

classmethod parse(oid)

This method serves as an alternate way to call the constructor. It parses an OID string (e.g. "1.3.6.1.2.1.1.1") and returns an OID object. OID strings may also contain a leading dot before the first sub-identifier.

__str__()

Return the standard dot-separated representation of the OID.

__lt__(other)

Compare two OIDs lexicographically (that’s the word the RFCs use).

__len__()

Return the number of sub-identifiers in the OID.

__getitem__(n)

The square bracket operator returns sub-identifier n, where n is an integer between 0 and the length of the OID minus one. n may also be a slice, in which case the result is a tuple.

__iter__()

Return an object to iterate over the sub-identifiers.

extend(*nums)

Append the given sub-identifiers to the OID and return it as a new object.

appendIndex(*index)

Every SNMP object is identified by an OID with a format of <prefix>.<index>, where the prefix refers to an object type definied in the MIB, and the index encodes one or more primitive objects. This is explained in RFC 1157#section-3.2.6.3.

This method encodes the given object(s), as outlined in RFC 2578#section-7.7, and appends the encoding(s) to the end of the OID, returning a new object.

extractIndex(prefix, *types)

This method is the reverse of appendIndex(). The prefix argument is an OID referring to an object definition in the MIB, and the types argument gives the expected type of each object in the index. Most indices contain a single object, in which case the getIndex() wrapper function may be more convenient.

If the OID does not begin with the given prefix, this method will raise a snmp.types.OID.BadPrefix exception. If the prefix does match, but the index cannot be decoded, it will raise an snmp.types.OID.IndexDecodeError. The index is returned as a tuple whose length matches the length of types.

getIndex(prefix, cls=Integer)

This method wraps a call to extractIndex() for an index consisting of only a single object. Where that method returns a tuple of length 1, this method returns the object directly.

snmp.smi

class Unsigned(value)

This class represents a 32-bit unsigned integer.

property value
class Integer32(value)

This class is indistinguishable from snmp.types.Integer.

property value
class Unsigned32(value)

This class is indistinguishable from snmp.types.Unsigned.

property value
class IpAddress(addr)

An IPv4 address.

property addr

The address in human-readable “X.X.X.X” format.

property data

A byte string encoding the address in network format.

class Counter32(value)

A 32-bit unsigned integer used to represent monotonically increasing values that wrap to zero upon overflowing.

property value
class Gauge32(value)

A 32-bit unsigned integer used to represent values within a specific range that do not wrap.

property value
class TimeTicks(value)

A 32-bit unsigned integer used to represent time measurements in hundredths of a second.

property value
class Opaque(data)

This data type is deprecated since SNMPv2c.

property data
class Counter64(value)

A 64-bit unsigned integer with similar semantics to Counter32.

property value

snmp.pdu

class NoSuchObject

A special value sent in a response to indicate that the requested OID is unknown to the remote engine.

class NoSuchInstance

A special value sent in a response to indicate that there is no object associated with the requested OID.

class EndOfMibView

A special value sent in response to a Get-Next or Get-Bulk request to indicate that there are no more objects to return.

class VarBind(name, value=None)

An SNMP variable binding pairs an OID with a value. In actual usage, the OID (i.e. the “name”) consists of a prefix, which refers to an object definition in the MIB, and an index, identifying a unique instance of that object for a specific engine. The value is an instance of the type specified in the object definition. For requests, the “name” may be any OID, and the value should be Null.

The name argument to the constructor may either be an OID object, or it may be an OID string. The value may be any SNMP object, or None, for a Null value.

property name

The “name” of the variable, which is an OID.

property value

The variable’s value, which is some instance of Asn1Encodable.

class VarBindList(*args)

A VarBindList is a container for VarBind objects. The constructor accepts any number of VarBinds, OIDs, or OID strings.

__len__()

Return the number of variable bindings in this list.

__getitem__(n)

Retrieve a variable binding, or a tuple of variable bindings, from the list.

__iter__()

Return an object to iterate over the variable bindings in this list.

class PDU(*varbinds, requestID=0, errorStatus=0, errorIndex=0)

SNMP defines several different Protocol Data Units (PDUs), each representing a specific operation, or message type. All PDUs follow the same structure, with three Integer fields containing metadata, and a list of variable bindings (VarBindList). Each variable binding consists of a name and a value, as described in the VarBind class documentation. This is the base class for all PDU types, except for GetBulkRequestPDU, which uses its metadata fields differently than the others.

When constructing a PDU object, the variable bindings are provided as positional arguments. These may be instances of VarBind, but they can also be OIDs, either as an OID object, or in string format. If OIDs are used, then the VarBinds will be populated with Null values.

property requestID

The request ID is an arbitrary number used to match up responses to requests.

property errorStatus

A non-zero error status in a response indicates that an error occured in the processing of the request. Allowable error status values, as well as their names, are enumerated in the PDU.ErrorStatus class. If the error relates to a specific variable binding, then the errorIndex field will also contain a non-zero value.

property errorIndex

When a response contains a non-zero error status, this field indicates the source of the error. A value of 0 indicates that the error relates to the message as a whole. A value greater than 0 gives the index of the variable binding that caused the error. Note that this means that index 1 refers to the first variable binding in the list.

property variableBindings

This property gives access to the VarBindList containing the message’s variable bindings.

class ErrorStatus(errorStatus)

This IntEnum class enumerates the possible values of the errorStatus field. Note that some values are only valid in newer versions of SNMP.

class GetRequestPDU(*varbinds, requestID=0, errorStatus=0, errorIndex=0)
class GetNextRequestPDU(*varbinds, requestID=0, errorStatus=0, errorIndex=0)
class ResponsePDU(*varbinds, requestID=0, errorStatus=0, errorIndex=0)
class SetRequestPDU(*varbinds, requestID=0, errorStatus=0, errorIndex=0)
class TrapPDU(*varbinds, requestID=0, errorStatus=0, errorIndex=0)
class GetBulkRequestPDU(*varbinds, requestID=0, nonRepeaters=0, maxRepetitions=0)
property requestID

Same as PDU.requestID.

property nonRepeaters

This field is explained briefly on the Management Operations page.

property maxRepetitions

This field is explained briefly on the Management Operations page.

property variableBindings

Same as PDU.variableBindings.

class InformRequestPDU(*varbinds, requestID=0, errorStatus=0, errorIndex=0)
class SNMPv2TrapPDU(*varbinds, requestID=0, errorStatus=0, errorIndex=0)
class ReportPDU(*varbinds, requestID=0, errorStatus=0, errorIndex=0)