fusnmp 1.0.3

A small but complete NetSNMP ctypes wrapper.

fusnmp: a Python ctypes-based Net-SNMP wrapper module.

:warning: NOTE: This was originally called DLNetSNMP and was written by Alessandro Iob. I have tried to contact him but was unable to. This is my fork of the last code that was posted on the dlevel.com website. This is minimally maintained to support a legacy system and I would not recommend it as a starting point for a new project.

This is a small but almost complete wrapper for the NetSNMP. This library was originally based on the "pynetsnmp" module developed by cool people at Zenoss.

The current version has been tested with Python 2.7 and NetSNMP 5.7.3.

Features

• Synchronous and asynchronous "get", "getbulk", "walk" and "set" operations.
• MIB management: set/get MIB paths, load new MIBs, get OID descriptions from MIBs, oid to name (and vice versa) translation tools.
• Session management, internal asynchronous events management, pluggable logger and meaningful error reporting.
• Multi-platform: runs under Linux (and I think other Unixes also), Windows and OS X.

Bugs and unsupported features

• Does not work if used from multiple-threads.
• Traps collection implemented but not tested.
• Tables not implemented.

You can find some simple tests and usage patters at the end of the "fusnmp.py" file.

Installation

pip install fusnmp

Usage Guide

SNMP sessions are managed by the SNMPManager class. This class is a singleton, so there is always a single instance of it.

import fusnmp
sm = fusnmp.SNMPManager()

The SNMPManager accepts the following optional parameters:

• name: the manager's name (defaults to "SNMPManager")
• log: callback function to use when logging SNMP messages. The callback must accept two parameters: priority and message.
• max_fd: maximum number of file descriptor to be used by the "select" stuff (default is 1024)
• threaded_processor: set to True (default) if the asynchronous SNMP events processor must be executed in an independent thread. If False, the "process_sessions" method must be called periodically.
• process_sessions_sleep: float specifying the number of seconds the "process_sessions" method must sleep after every loop (default is 0.01).
• local_dir: path to directory where persistent data (MIBs, etc.) is and will be stored. If not given (default is None), the module dir will be used. In the given path a directory named 'mibs' must be present: all default MIBs should be available here or you'll be presented with a lot of errors like "error : Cannot find module (IP-MIB): At line 1 in (none)".

When the SNMPManager is not needed anymore, it should be destroyed using the 'destroy' method.

MIB management methods

• set_mib_dir(PATH_TO_MIB_DIR): sets the directory where MIB files should be searched.

• add_mib_dir(PATH_TO_MIB_DIR): adds a directory to the ones already defined, where MIB files should be searched.

• add_mib_dir(PATH_TO_MIB_DIR): removes a directory from the ones searched for MIB files.

• get_mib_dir(): returns the current directories searched for MIB files.

• read_mib(PATH_TO_MIB_FILE): reads into memory a MIB file.

• refresh_mibs(): reloads all MIB definitions in use.

Sessions management methods

• add_session(name, version='1', **kargs): creates and opens a new SNMP session. The parameters are:

  • name: session unique name.
  • version: SNMP protocol version ('1', '2', '3', default is '1')
  • kargs: SNMP protocol specific session arguments. You can pass any valid session field here. Commonly used, for versions '1' and '2':
    • peername: hostname of the SNMP agent to be queried.
    • community: community string to use.
    • timeout: seconds before retry (default 1 second)
    • retries: number of retries before failure (default 5)

  Returns a Session object or raises an exception.

• add_trapd_session(name, peername, fileno=-1): creates an SNMP trap daemon session. TRAP MANAGEMENT IS NOT TESTED.

• remove_session(name): closes and removes the given section.

• find_session(sessid): returns the Session instance associated with the given session ID.

• snmp_manager_instance[SESSION_NAME]: returns the Session instance with the given name.

Session events

• bind(slot, uid, session, callback): binds a callback function to a session's event slot. The parameters are:

  • slot: slot name (see below).
  • uid: unique identifier used to reference the binding.
  • session: session name or None for all sessions.
  • callback: callback function to be called on event. The callback signature must be (slot, session_name, request_id, result).

• unbind(slot, uid, session=None): removes the binded callback. The parameters are:

  • slot: slot name.
  • uid: binding unique ID, as specified in the 'bind' call.
  • session: session name or None for all sessions.

The available slots are:

• 'get': emitted when an async 'get' response arrives.
• 'getnext': emitted when an async 'getnext' response arrives.
• 'getbulk': emitted when an async 'getbulk' response arrives.
• 'set': emitted when an async 'set' response arrives.
• 'inform': trap management (NOT TESTED).
• 'trap': trap management (NOT TESTED).
• 'trap2': trap management (NOT TESTED).
• 'report': trap management (NOT TESTED).
• 'response': emitted on any response kind, exept for 'timeout'.
• 'timeout': emitted on request timeout. The assigned callback signature must be (slot, session_name, request_id).

Session instances

• get_description(oid, width=80, buffer_size=10240): returns an OID's description from the MIB file. The parameters are:

  • oid: oid name or oid tuple.
  • width: formatting width of the returned description. The default value (80) should be almost always right.
  • buffer_size: size of the buffer where the description is stored. The default value (80) should be almost always right.

• sync_get(oids, exc_on_error=False): performs a synchronous 'get' request for given oids. The parameters are:

  • oids: list of oid names or tuples.
  • exc_on_error: True to rise an exception if request fails (default is False).

• sync_getbulk(nonrepeaters, maxrepetitions, oids, exc_on_error=False): performs a synchronous 'getbulk' for given oids. The parameters are:

  • nonrepeaters: number of non repeaters.
  • maxrepetitions: maximum repetitions.
  • oids: list of oid names or tuples.
  • exc_on_error: True to rise an exception if request fails (default is False).

• sync_walk(root, exc_on_error=False): performs a synchronous 'getnext' request for the given oid. The parameters are:

  • oids: oid name or tuple.
  • exc_on_error: True to rise an exception if request fails (default is False).

• sync_set(oids_values, exc_on_error=False): performs a synchronous 'set' request for the given oids. The parameters are:

  • oids: list of (oid name or tuple, value to set) tuples (or lists).
  • exc_on_error: True to rise an exception if request fails (default is False).

• async_get(oids, wait=False, exc_on_error=False): performs an asynchronous 'get' request for given oids. The parameters are:

  • oids: list of oid names or tuples.
  • wait: used to make async calls sync, MUST not be used and left to FALSE.
  • exc_on_error: True to rise an exception if request fails (default is False).

• async_getbulk(nonrepeaters, maxrepetitions, oids, wait=False, exc_on_error=False): performs an asynchronous 'getbulk' for given oids. The parameters are:

  • nonrepeaters: number of non repeaters.
  • maxrepetitions: maximum repetitions.
  • oids: list of oid names or tuples.
  • wait: used to make async calls sync, MUST not be used and left to FALSE.
  • exc_on_error: True to rise an exception if request fails (default is False).

• async_walk(root, wait=False, exc_on_error=False): performs an asynchronous 'getnext' request for the given oid. The parameters are:

  • oids: oid name or tuple.
  • wait: used to make async calls sync, MUST not be used and left to FALSE.
  • exc_on_error: True to rise an exception if request fails (default is False).

• async_set(oids_values, wait=False, exc_on_error=False): performs an asynchronous 'set' request for the given oids. The parameters are:

  • oids: list of (oid name or tuple, value to set) tuples (or lists).
  • wait: used to make async calls sync, MUST not be used and left to FALSE.
  • exc_on_error: True to rise an exception if request fails (default is False).

Utilities

• str_to_oid(s): converts a string to an oid tuple.

• strs_to_oids(l): converts a list of strings to a list of oid tuples.

• oid_to_str(oid): converts an oid tuple to string.

• oids_to_strs(l): converts a list of oid tuples to a list of strings.

• oid_to_dot(oid): converts an oid to a "dotted" string.

• oids_to_dots(): converts a list of oids to a list of "dotted" strings.