ezsnmp.session module — Ez SNMP V1.1.0 documentation

# 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: