API reference¶
While Snimpy is targeted at being used interactively or through simple scripts, you can also use it from your Python program.
It provides a high-level interface as well as lower-level
ones. However, the effort is only put in th manager
module and
other modules are considered as internal details.
manager
module¶
This module is the high-level interface to Snimpy. It exposes
Manager
class to instantiate a new manager (which is an SNMP
client). This is the preferred interface for Snimpy.
Here is a simple example of use of this module:
>>> load("IF-MIB")
>>> m = Manager("localhost")
>>> m.ifDescr[1]
<String: lo>
-
class
snimpy.manager.
Manager
(host='localhost', community='public', version=2, cache=False, none=False, timeout=None, retries=None, loose=False, bulk=40, secname=None, authprotocol=None, authpassword=None, privprotocol=None, privpassword=None, contextname=None)[source]¶ SNMP manager. An instance of this class will represent an SNMP manager (client).
When a MIB is loaded with
load()
, scalars and row names from it will be made available as an instance attribute. For a scalar, reading the corresponding attribute will get its value while setting it will allow to modify it:>>> load("SNMPv2-MIB") >>> m = Manager("localhost", "private") >>> m.sysContact <String: root> >>> m.sysContact = "Brian Jones" >>> m.sysContact <String: Brian Jones>
For a row name, the provided interface is like a Python dictionary. Requesting an item using its index will retrieve the value from the agent (the server):
>>> load("IF-MIB") >>> m = Manager("localhost", "private") >>> m.ifDescr[1] <String: lo> >>> m.ifName[1] = "Loopback interface"
Also, it is possible to iterate on a row name to get all available values for index:
>>> load("IF-MIB") >>> m = Manager("localhost", "private") >>> for idx in m.ifDescr: ... print(m.ifDescr[idx])
You can get a slice of index values from a table by iterating on a row name subscripted by a partial index:
>>> load("IF-MIB") >>> m = Manager("localhost", "private") >>> for idx in m.ipNetToMediaPhysAddress[1]: ... print(idx) (<Integer: 1>, <IpAddress: 127.0.0.1>)
You can use multivalue indexes in two ways: using Pythonic multi-dimensional dict syntax, or by providing a tuple containing index values:
>>> load("IF-MIB") >>> m = Manager("localhost", "private") >>> m.ipNetToMediaPhysAddress[1]['127.0.0.1'] <String: aa:bb:cc:dd:ee:ff> >>> m.ipNetToMediaPhysAddress[1, '127.0.0.1'] <String: aa:bb:cc:dd:ee:ff>
A context manager is also provided. Any modification issued inside the context will be delayed until the end of the context and then grouped into a single SNMP PDU to be executed atomically:
>>> load("IF-MIB") >>> m = Manager("localhost", "private") >>> with m: ... m.ifName[1] = "Loopback interface" ... m.ifName[2] = "First interface"
Any error will be turned into an exception:
>>> load("IF-MIB") >>> m = Manager("localhost", "private") >>> m.ifDescr[999] Traceback (most recent call last): ... SNMPNoSuchName: There is no such variable name in this MIB.
Internal modules¶
Those modules shouldn’t be used directly.
mib
module¶
This module is a low-level interface to manipulate and extract information from MIB files. It is a CFFI wrapper around libsmi. You may find convenient to use it in other projects but the wrapper is merely here to serve Snimpy use and is therefore incomplete.
-
class
snimpy.mib.
Node
(node)[source]¶ MIB node. An instance of this class represents a MIB node. It can be specialized by other classes, like
Scalar
,Table
,Column
,Node
.-
property
enum
¶ Get possible enum values. When the node can only take a discrete number of values, those values are defined in the MIB and can be retrieved through this property.
- Returns
The dictionary of possible values keyed by the integer value.
-
property
fmt
¶ Get node format. The node format is a string to use to display a user-friendly version of the node. This is can be used for both octet strings or integers (to make them appear as decimal numbers).
- Returns
The node format as a string or None if there is no format available.
-
property
oid
¶ Get OID for the current node. The OID can then be used to request the node from an SNMP agent.
- Returns
OID as a tuple
-
property
ranges
¶ Get node ranges. An node can be restricted by a set of ranges. For example, an integer can only be provided between two values. For strings, the restriction is on the length of the string.
The returned value can be None if no restriction on range exists for the current node, a single value if the range is fixed or a list of tuples or fixed values otherwise.
- Returns
The valid range for this node.
-
property
type
¶ Get the basic type associated with this node.
- Returns
The class from
basictypes
module which can represent the node. When retrieving a valid value for this node, the returned class can be instanciated to get an appropriate representation.
-
property
typeName
¶ Retrieves the name of the the node’s current declared type (not basic type).
- Returns
A string representing the current declared type, suitable for assignment to type.setter.
-
property
-
class
snimpy.mib.
Notification
(node)[source]¶ MIB notification node. This class represent a notification.
-
exception
snimpy.mib.
SMIException
[source]¶ SMI related exception. Any exception thrown in this module is inherited from this one.
-
class
snimpy.mib.
Scalar
(node)[source]¶ MIB scalar node. This class represents a scalar value in the MIB. A scalar value is a value not contained in a table.
-
class
snimpy.mib.
Table
(node)[source]¶ MIB table node. This class represents a table. A table is an ordered collection of objects consisting of zero or more rows. Each object in the table is identified using an index. An index can be a single value or a list of values.
-
property
columns
¶ Get table columns. The columns are the different kind of objects that can be retrieved in a table.
- Returns
list of table columns (
Column
instances)
-
property
implied
¶ Is the last index implied? An implied index is an index whose size is not fixed but who is not prefixed by its size because this is the last index of a table.
- Returns
True if and only if the last index is implied.
-
property
-
snimpy.mib.
get
(mib, name)[source]¶ Get a node by its name.
- Parameters
mib – The MIB name to query
name – The object name to get from the MIB
- Returns
the requested MIB node (
Node
)
-
snimpy.mib.
getByOid
(oid)[source]¶ Get a node by its OID.
- Parameters
oid – The OID as a tuple
- Returns
The requested MIB node (
Node
)
-
snimpy.mib.
getColumns
(mib)[source]¶ Return all columns from a givem MIB.
- Parameters
mib – The MIB name
- Returns
The list of all columns for the MIB
- Return type
list of
Column
instances
-
snimpy.mib.
getNodes
(mib)[source]¶ Return all nodes from a given MIB.
- Parameters
mib – The MIB name
- Returns
The list of all MIB nodes for the MIB
- Return type
list of
Node
instances
-
snimpy.mib.
getNotifications
(mib)[source]¶ Return all notifications from a givem MIB.
- Parameters
mib – The MIB name
- Returns
The list of all notifications for the MIB
- Return type
list of
Notification
instances
-
snimpy.mib.
getScalars
(mib)[source]¶ Return all scalars from a given MIB.
- Parameters
mib – The MIB name
- Returns
The list of all scalars for the MIB
- Return type
list of
Scalar
instances
-
snimpy.mib.
getTables
(mib)[source]¶ Return all tables from a given MIB.
- Parameters
mib – The MIB name
- Returns
The list of all tables for the MIB
- Return type
list of
Table
instances
-
snimpy.mib.
load
(mib)[source]¶ Load a MIB into the library.
- Parameters
mib – The MIB to load, either a filename or a MIB name.
- Returns
The MIB name that has been loaded.
- Raises
SMIException – The requested MIB cannot be loaded.
-
snimpy.mib.
loadedMibNames
()[source]¶ Generates the list of loaded MIB names.
- Yield
The names of all currently loaded MIBs.
snmp
module¶
This module is a low-level interface to build SNMP requests, send
them and receive answers. It is built on top of pysnmp but the
exposed interface is far simpler. It is also far less complete and
there is an important dependency to the basictypes
module for
type coercing.
-
exception
snimpy.snmp.
SNMPAuthorization
¶
-
exception
snimpy.snmp.
SNMPCommitFailed
¶
-
exception
snimpy.snmp.
SNMPEndOfMibView
¶
-
exception
snimpy.snmp.
SNMPException
[source]¶ SNMP related base exception. All SNMP exceptions are inherited from this one. The inherited exceptions are named after the name of the corresponding SNMP error.
-
exception
snimpy.snmp.
SNMPGen
¶
-
exception
snimpy.snmp.
SNMPInconsistentName
¶
-
exception
snimpy.snmp.
SNMPInconsistentValue
¶
-
exception
snimpy.snmp.
SNMPNoAccess
¶
-
exception
snimpy.snmp.
SNMPNoCreation
¶
-
exception
snimpy.snmp.
SNMPNoSuchInstance
¶
-
exception
snimpy.snmp.
SNMPNoSuchObject
¶
-
exception
snimpy.snmp.
SNMPNotWritable
¶
-
exception
snimpy.snmp.
SNMPUndoFailed
¶
-
exception
snimpy.snmp.
SNMPWrongEncoding
¶
-
exception
snimpy.snmp.
SNMPWrongLength
¶
-
exception
snimpy.snmp.
SNMPWrongType
¶
-
exception
snimpy.snmp.
SNMPWrongValue
¶
-
class
snimpy.snmp.
Session
(host, community='public', version=2, secname=None, authprotocol=None, authpassword=None, privprotocol=None, privpassword=None, contextname=None, bulk=40, none=False)[source]¶ SNMP session. An instance of this object will represent an SNMP session. From such an instance, one can get information from the associated agent.
-
property
bulk
¶ Get bulk settings.
- Returns
False if bulk is disabled or a non-negative integer for the number of repetitions.
-
get
(*oids)[source]¶ Retrieve an OID value using GET.
- Parameters
oids – a list of OID to retrieve. An OID is a tuple.
- Returns
a list of tuples with the retrieved OID and the raw value.
-
property
retries
¶ Get number of times a request is retried.
- Returns
Number of retries for each request.
-
set
(*args)[source]¶ Set an OID value using SET. This function takes an odd number of arguments. They are working by pair. The first member is an OID and the second one is
basictypes.Type
instace whose pack() method will be used to transform into the appropriate form.- Returns
a list of tuples with the retrieved OID and the raw value.
-
property
timeout
¶ Get timeout value for the current session.
- Returns
Timeout value in microseconds.
-
walk
(*oids)[source]¶ Walk from given OIDs but don’t return any “extra” results. Only results in the subtree will be returned.
- Parameters
oid – OIDs used as a start point
- Returns
a list of tuples with the retrieved OID and the raw value.
-
walkmore
(*oids)[source]¶ Retrieve OIDs values using GETBULK or GETNEXT. The method is called “walk” but this is either a GETBULK or a GETNEXT. The later is only used for SNMPv1 or if bulk has been disabled using
bulk()
property.- Parameters
oids – a list of OID to retrieve. An OID is a tuple.
- Returns
a list of tuples with the retrieved OID and the raw value.
-
property
basictypes
module¶
This module is aimed at providing Pythonic representation of various SNMP types. Each SMIv2 type is mapped to a corresponding class which tries to mimic a basic type from Python. For example, display strings are like Python string while SMIv2 integers are just like Python integers. This module is some kind of a hack and its use outside of Snimpy seems convoluted.
-
class
snimpy.basictypes.
Enum
(entity, value, raw=True)[source]¶ Class for an enumeration. An enumaration is an integer but labels are attached to some values for a more user-friendly display.
-
classmethod
fromOid
(entity, oid, implied=False)[source]¶ Create instance from an OID.
This is the sister function of
toOid()
.- Parameters
oid – The OID to use to create an instance
entity – The MIB entity we want to instantiate
- Returns
A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID
-
classmethod
-
class
snimpy.basictypes.
Integer
(entity, value, raw=True)[source]¶ Class for any integer.
-
classmethod
fromOid
(entity, oid, implied=False)[source]¶ Create instance from an OID.
This is the sister function of
toOid()
.- Parameters
oid – The OID to use to create an instance
entity – The MIB entity we want to instantiate
- Returns
A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID
-
toOid
(implied=False)[source]¶ Convert to an OID.
If this function is implemented, then class function
fromOid()
should also be implemented as the “invert” function of this one.This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.
- Returns
An OID that can be used as index
-
classmethod
-
class
snimpy.basictypes.
IpAddress
(entity, value, raw=True)[source]¶ Class representing an IP address/
-
classmethod
fromOid
(entity, oid, implied=False)[source]¶ Create instance from an OID.
This is the sister function of
toOid()
.- Parameters
oid – The OID to use to create an instance
entity – The MIB entity we want to instantiate
- Returns
A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID
-
toOid
(implied=False)[source]¶ Convert to an OID.
If this function is implemented, then class function
fromOid()
should also be implemented as the “invert” function of this one.This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.
- Returns
An OID that can be used as index
-
classmethod
-
class
snimpy.basictypes.
OctetString
(entity, value, raw=True)[source]¶ Class for a generic octet string. This class should be compared to
String
which is used to represent a display string. This class is usually used to store raw bytes, like a bitmask of VLANs.
-
class
snimpy.basictypes.
Oid
(entity, value, raw=True)[source]¶ Class to represent and OID.
-
classmethod
fromOid
(entity, oid, implied=False)[source]¶ Create instance from an OID.
This is the sister function of
toOid()
.- Parameters
oid – The OID to use to create an instance
entity – The MIB entity we want to instantiate
- Returns
A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID
-
toOid
(implied=False)[source]¶ Convert to an OID.
If this function is implemented, then class function
fromOid()
should also be implemented as the “invert” function of this one.This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.
- Returns
An OID that can be used as index
-
classmethod
-
class
snimpy.basictypes.
String
(entity, value, raw=True)[source]¶ Class for a display string. Such a string is an unicode string and it is therefore expected that only printable characters are used. This is usually the case if the corresponding MIB node comes with a format string.
With such an instance, the user is expected to be able to provide a formatted. For example, a MAC address could be written 00:11:22:33:44:55.
-
class
snimpy.basictypes.
StringOrOctetString
(entity, value, raw=True)[source]¶ -
classmethod
fromOid
(entity, oid, implied=False)[source]¶ Create instance from an OID.
This is the sister function of
toOid()
.- Parameters
oid – The OID to use to create an instance
entity – The MIB entity we want to instantiate
- Returns
A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID
-
toOid
(implied=False)[source]¶ Convert to an OID.
If this function is implemented, then class function
fromOid()
should also be implemented as the “invert” function of this one.This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.
- Returns
An OID that can be used as index
-
classmethod
-
class
snimpy.basictypes.
Timeticks
(entity, value, raw=True)[source]¶ Class for timeticks.
-
classmethod
fromOid
(entity, oid, implied=False)[source]¶ Create instance from an OID.
This is the sister function of
toOid()
.- Parameters
oid – The OID to use to create an instance
entity – The MIB entity we want to instantiate
- Returns
A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID
-
toOid
(implied=False)[source]¶ Convert to an OID.
If this function is implemented, then class function
fromOid()
should also be implemented as the “invert” function of this one.This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.
- Returns
An OID that can be used as index
-
classmethod
-
class
snimpy.basictypes.
Type
(entity, value, raw=True)[source]¶ Base class for all types.
-
classmethod
fromOid
(entity, oid, implied=False)[source]¶ Create instance from an OID.
This is the sister function of
toOid()
.- Parameters
oid – The OID to use to create an instance
entity – The MIB entity we want to instantiate
- Returns
A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID
-
toOid
(implied=False)[source]¶ Convert to an OID.
If this function is implemented, then class function
fromOid()
should also be implemented as the “invert” function of this one.This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.
- Returns
An OID that can be used as index
-
classmethod
-
class
snimpy.basictypes.
Unsigned32
(entity, value, raw=True)[source]¶ Class to represent an unsigned 32bits integer.