Simple Network Management Protocol (SNMP)

SOCS supports monitoring of networked devices via the Simple Network Management Protocol (SNMP). SNMP is a standard protocol for collecting and organizing information about devices on the network.

SNMP support is provided through the python module pysnmp (Note that the old snmplabs.com version of this documentation is hacked! Don’t go to it, but use the lextudio.com version linked here). pysnmp supports twisted as an I/O framework, which integrates nicely with OCS/SOCS/PCS. PCS makes this twisted interface for SNMP available via the SNMPTwister class, which is borrowed from SOCS and amended to use the PCS MIB files. The full SOCS SNMP documentation can be found here.

MIB to Python Conversion

For developers adding a new SNMP monitoring PCS Agent, you may need to convert a MIB file to python. This can be done with mibdump, a utility provided by pysmi. This used to be a conversion script called mibdump.py that had to be downloaded and used, but now it should come installed with pysmi. Other useful (linux) packages for debugging include smitools and snmp.

An example for converting the Raritan PDU MIB that was run from the same directory that contained the raw MIB text file (hence the --mib-source=.):

$ mibdump –mib-source=. –mib-source=/usr/share/snmp/mibs/ –mib-source=https://mibs.pysnmp.com/asn1/@mib@ PDU2-MIB

Examples

A standalone example of using SNMPTwister to interact with a device:

 from twisted.internet import reactor
 from twisted.internet.defer import inlineCallbacks
 from pcs.snmp import SNMPTwister

 # Setup communication with Raritan PDU
 snmp = SNMPTwister('10.10.10.50', 161)

 # Define OIDs to query
 num_outlets=24
 get_list = []
 for i in range(1, num_outlets+1):
     get_list.append(('PDU2-MIB', 'outletSwitchingState', 1, i))

 set_list = [('PDU2-MIB', 'switchingOperation', 1, 4)]

 @inlineCallbacks
 def query_snmp():
     x = yield snmp.get(get_list, 2)
     for i in range(len(x)):
         print(x[i][0].prettyPrint())
         print(x[i][1]._value)
     reactor.stop()

 @inlineCallbacks
 def cycle_outlet():
     # Would power cycle outlet 2 in this example
     x = yield snmp.set(set_list, 2, 2)
     print(x)
     reactor.stop()

 # Call query_snmp within the reactor
 reactor.callWhenRunning(query_snmp)
 # Call cycle_outlet
# reactor.callWhenRunning(cycle_outlet)
 reactor.run()

Running this code would return a list of the names of the commands and the states for all 24 outlets. The first outlet’s output looks like:

PDU2-MIB::outletSwitchingState.1.1
7

where the 7 means that it is on - see the MIB file for all of the possibilities.

API

If you are developing an SNMP monitoring agent, the SNMP + twisted interface is available for use and detailed here:

class pcs.snmp.SNMPTwister(address, port=161)[source]

Helper class for handling SNMP communication with twisted.: Same as the socs version but importing pcs MIB files.

More information can be found in the pySNMP documentation: PySNMP Examples

Parameters:

address (str) – Address of the SNMP Agent to send GET/SET requests to
port (int) – Associated port for SNMP communication. Default is 161

snmp_engine

PySNMP engine

Type:: pysnmp.entity.engine.SnmpEngine

address

Address of the SNMP Agent to send GET/SET requests to

Type:: str

udp_transport

UDP transport for UDP over IPv4

Type:: pysnmp.hlapi.twisted.transport.UdpTransportTarget

log

txaio logger object

Type:: txaio.tx.Logger

get(oid_list, version)[source]

Issue a getCmd to get SNMP OID states.

Example

>>> snmp = SNMPTwister('localhost', 161)
>>> snmp.get([ObjectType(ObjectIdentity('MBG-SNMP-LTNG-MIB',
                                        'mbgLtNgRefclockState',
                                        1)),
              ObjectType(ObjectIdentity('MBG-SNMP-LTNG-MIB',
                                        'mbgLtNgRefclockLeapSecondDate',
                                        1))])

>>> snmp = SNMPTwister('localhost', 161)
>>> result = snmp.get([('MBG-SNMP-LTNG-MIB', 'mbgLtNgRefclockState', 1),
                       ('MBG-SNMP-LTNG-MIB', 'mbgLtNgRefclockLeapSecondDate', 1)])
>>> # Simply printing the returned object shows a nice string
>>> print(result[0])
MBG-SNMP-LTNG-MIB::mbgLtNgRefclockState.1 = notSynchronized
>>> # The corresponding integer value is hidden within the returned object
>>> print(result[0][1]._value)
2

Parameters:

oid_list (list) –
List of high-level MIB Object OIDs. The list elements should either be ObjectType, or tuples which define the OIDs, as shown in the example above. See Specifying MIB object for more info.
version (int) –
SNMP version for communicaton (1, 2, or 3). All versions supported here without auth or privacy. If using v3 the configured username on the SNMP device should be ‘ocs’. For details on version implementation in pysnmp see SNMP Versions.

Returns:

A Deferred which will callback with the var_binds list from self._success. If successful, this will contain a list of ObjectType class instances representing MIB variables returned in SNMP response.

Return type:

twisted.internet.defer.Deferred

set(oid_list, version, setvalue, community_name='private')[source]

Issue a setCmd to set SNMP OID states. See Modifying MIB variables for more info on setting OID states.

Parameters:

oid_list (list) – List of high-level MIB Object OIDs. The list elements should either be ObjectType, or tuples which define the OIDs.
version (int) – SNMP version for communicaton (1, 2, or 3). All versions supported here without auth or privacy. If using v3 the configured username on the SNMP device should be ‘ocs’.
setvalue (int) – Integer to set OID. For example, 0 is off and 1 is on for outletControl on the iBootPDU.

Returns:

A Deferred which will callback with the var_binds list from self._success. If successful, this will contain a list of ObjectType class instances representing MIB variables returned in SNMP response.

Return type:

twisted.internet.defer.Deferred