ezsnmp.session module

class ezsnmp.session.Session(hostname: str = 'localhost', version: Literal[1, 2, 3] = 3, community: str = 'public', timeout: int = 1, retries: int = 3, remote_port: int = 0, local_port: int = 0, security_level: Literal['no_auth_or_privacy', 'auth_without_privacy', 'auth_with_privacy'] = 'no_auth_or_privacy', security_username: str = 'initial', privacy_protocol: str = 'DEFAULT', privacy_password: str = '', auth_protocol: str = 'DEFAULT', auth_password: str = '', context_engine_id: str = '', security_engine_id: str = '', context: str = '', engine_boots: int = 0, engine_time: int = 0, our_identity: str = '', their_identity: str = '', their_hostname: str = '', trust_cert: str = '', use_long_names: bool = False, use_numeric: bool = False, use_sprint_value: bool = False, use_enums: bool = False, best_guess: Literal[0, 1, 2] = 0, retry_no_such: bool = False, abort_on_nonexistent: bool = False)

Bases: object

A Net-SNMP session which may be setup once and then used to query and manipulate SNMP data.

Note

This class transparently uses interface to create a session instance from the Net-SNMP library. Most variable values are not synchronized between the Session and interface. If you intend to make changes to the Session instead of creating a new one, you must manually call the update_session() method

Parameters:

hostname – hostname or IP address of SNMP agent
version – the SNMP version to use; 1, 2 (equivalent to 2c) or 3
community – SNMP community string (used for both R/W) (v1 & v2)
timeout – seconds before retry
retries – retries before failure
remote_port – allow remote UDP port to be overridden (this will communicate on port 161 at its default setting)
local_port – allow overriding of the local SNMP port
security_level – security level (no_auth_or_privacy, auth_without_privacy or auth_with_privacy) (v3)
security_username – security name (v3)
privacy_protocol – privacy protocol (v3) i.e AES, DES, etc
privacy_password – privacy passphrase (v3)
auth_protocol – authentication protocol (MD5 or SHA) (v3)
auth_password – authentication passphrase (v3)
context_engine_id – context engine ID, will be probed if not supplied (v3)
security_engine_id – security engine ID, will be probed if not supplied (v3)
context – context name (v3)
engine_boots – the number of times the SNMP engine has re-booted/re-initialized since SNMP engine ID was last configured (v3)
engine_time – the number of seconds since the engine_boots counter was last incremented (v3)
our_identity – the fingerprint or file name for the local X.509 certificate to use for our identity (run net-snmp-cert to create and manage certificates) (v3 TLS / DTLS)
their_identity – the fingerprint or file name for the local X.509 certificate to use for their identity (v3 TLS / DTLS)
their_hostname – their hostname to expect; either their_hostname or a trusted certificate plus a hostname is needed to validate the server is the proper server (v3 TLS / DTLS)
trust_cert – a trusted certificate to use for validating certificates; typically this would be a CA certificate (v3 TLS / DTLS)
use_long_names – set to True to have <tags> for getnext methods generated preferring longer Mib name convention (e.g., system.sysDescr vs just sysDescr)
use_numeric – set to True to have <tags> returned by the get methods untranslated (i.e. dotted-decimal). Setting the use_long_names value for the session is highly recommended
use_sprint_value – set to True to have return values for get and getnext methods formatted with the libraries sprint_value function. This will result in certain data types being returned in non-canonical format Note: values returned with this option set may not be appropriate for set operations
use_enums – set to True to have integer return values converted to enumeration identifiers if possible, these values will also be acceptable when supplied to set operations
best_guess – this setting controls how oids are parsed; setting to 0 causes a regular lookup. setting to 1 causes a regular expression match (defined as -Ib in snmpcmd); setting to 2 causes a random access lookup (defined as -IR in snmpcmd).
retry_no_such – if enabled NOSUCH errors in get pdus will be repaired, removing the SNMP variable in error, and resent; undef will be returned for all NOSUCH SNMP variables, when set to False this feature is disabled and the entire get request will fail on any NOSUCH error (applies to v1 only)
abort_on_nonexistent – raise an exception if no object or no instance is found for the given oid and oid index

bulkwalk(oids: List[str | Tuple[str, str]] | str | Tuple[str, str] = '.1.3.6.1.2.1', non_repeaters: int = 0, max_repetitions: int = 10) → List[SNMPVariable]

Uses SNMP GETBULK operation using the prepared session to automatically retrieve multiple pieces of information in an OID

Parameters:: oids – you may pass in a single item (multiple values currently experimental) which may be a string representing the entire OID (e.g. ‘sysDescr.0’) or may be a tuple containing the name as its first item and index as its second (e.g. (‘sysDescr’, 0))
Returns:: a list of SNMPVariable objects containing the values that were retrieved via SNMP

property connect_hostname: str

error_index: read-only, holds the snmp_err_index when appropriate

error_number: read-only, holds the snmp_err or status of last request

error_string: read-only, holds the error message assoc. w/ last request

get(oids: List[str | Tuple[str, str]]) → List[SNMPVariable]

get(oids: str | Tuple[str, str]) → SNMPVariable

Perform an SNMP GET operation using the prepared session to retrieve a particular piece of information.

Parameters:: oids – you may pass in a list of OIDs or single item; each item may be a string representing the entire OID (e.g. ‘sysDescr.0’) or may be a tuple containing the name as its first item and index as its second (e.g. (‘sysDescr’, 0))
Returns:: an SNMPVariable object containing the value that was retrieved or a list of objects when you send in a list of OIDs

get_bulk(oids: List[str | Tuple[str, str]] | str | Tuple[str, str], non_repeaters: int = 0, max_repetitions: int = 10) → List[SNMPVariable]

Performs a bulk SNMP GET operation using the prepared session to retrieve multiple pieces of information in a single packet.

Parameters:

oids – you may pass in a list of OIDs or single item; each item may be a string representing the entire OID (e.g. ‘sysDescr.0’) or may be a tuple containing the name as its first item and index as its second (e.g. (‘sysDescr’, 0))
non_repeaters – the number of objects that are only expected to return a single GETNEXT instance, not multiple instances
max_repetitions – the number of objects that should be returned for all the repeating OIDs

Returns:

a list of SNMPVariable objects containing the values that were retrieved via SNMP

get_next(oids: List[str | Tuple[str, str]]) → List[SNMPVariable]

get_next(oids: str | Tuple[str, str]) → SNMPVariable

Uses an SNMP GETNEXT operation using the prepared session to retrieve the next variable after the chosen item.

Parameters:: oids – you may pass in a list of OIDs or single item; each item may be a string representing the entire OID (e.g. ‘sysDescr.0’) or may be a tuple containing the name as its first item and index as its second (e.g. (‘sysDescr’, 0))
Returns:: an SNMPVariable object containing the value that was retrieved or a list of objects when you send in a list of OIDs

sess_ptr: internal field used to cache a created session structure

set(oid: str | Tuple[str, str], value: Any, snmp_type: str | None = None) → bool

Perform an SNMP SET operation using the prepared session.

Parameters:

oid – the OID that you wish to set which may be a string representing the entire OID (e.g. ‘sysDescr.0’) or may be a tuple containing the name as its first item and index as its second (e.g. (‘sysDescr’, 0))
value – the value to set the OID to
snmp_type – if a numeric OID is used and the object is not in the parsed MIB, a type must be explicitly supplied

Returns:

a boolean indicating the success of the operation

set_multiple(oid_values: List[Tuple[str, Any] | Tuple[str, Any, str]]) → bool

Perform an SNMP SET operation on multiple OIDs with multiple values using the prepared session.

Parameters:: oid_values – a list of tuples whereby each tuple contains a (oid, value) or an (oid, value, snmp_type)
Returns:: a list of SNMPVariable objects containing the values that were retrieved via SNMP

property timeout_microseconds: int

update_session(**kwargs: Any) → None

(Re)creates the underlying Net-SNMP session object.

While it is recommended to create a new Session instance instead, this method has been added for your convenience in case you really need it (we’ve mis-typed the community string before in our interactive sessions and totally understand your pain).

Keywords passed to the method will be assigned to the instance if they match existing attribute names. A warning will be emitted if something is passed that does not match anything that already exists.

Example usage

s = Session(version=2, community='readonly', hostname='localhost')
# Whoops, wrong hostname and community string. Let's change that
s.update_session(community='readwrite', hostname'remotehost')
# Actually I need to use version 1
s.version = 1
s.update_session()

walk(oids: List[str | Tuple[str, str]] | str | Tuple[str, str] = '.1.3.6.1.2.1') → List[SNMPVariable]

Uses SNMP GETNEXT operation using the prepared session to automatically retrieve multiple pieces of information in an OID.

Parameters:: oids – you may pass in a single item (multiple values currently experimental) which may be a string representing the entire OID (e.g. ‘sysDescr.0’) or may be a tuple containing the name as its first item and index as its second (e.g. (‘sysDescr’, 0))
Returns:: a list of SNMPVariable objects containing the values that were retrieved via SNMP

ezsnmp.session.build_varlist(oids: List[str | Tuple[str, str]] | str | Tuple[str, str]) → Tuple[List[SNMPVariable], bool]

Prepare the variable binding list which will be used by the C interface.

Parameters:: oids – an individual or list of strings or tuples representing one or more OIDs
Returns:: a tuple containing where the first item is a list of SNMPVariable objects or an individual SNMPVariable and a boolean indicating whether or not the first tuple item is a list or single item

ezsnmp.session.validate_results(varlist: List[SNMPVariable]) → None

Validates a list of SNMPVariable objects and raises any appropriate exceptions where necessary.

Parameters:: varlist – a variable list containing SNMPVariable objects to be processed
Returns: