Skip to content

gufo.snmp

Gufo SNMP: The accelerated Python SNMP client library.

Attributes:

Name Type Description
__version__ str

Current version

Aes128Key

Bases: BasePrivKey

AES-128 Key.

DesKey

Bases: BasePrivKey

Des Key.

Md5Key

Bases: BaseAuthKey

MD5 Key.

Sha1Key

Bases: BaseAuthKey

SHA-1 Key.

SnmpSession

Bases: object

SNMP client session.

Should be used either directly or via asynchronous context manager.

Parameters:

Name Type Description Default
addr str

SNMP agent address, either IPv4 or IPv6.

 required
port int

SNMP agent port.

 161
community str

SNMP community (v1, v2c).

 'public'
engine_id Optional[bytes]

SNMP Engine id (v3).

 None
user Optional[User]

User instance (v3).

 None
version Optional[SnmpVersion]

Protocol version. Autodetect if omitted:

  • v3: if user is set.
  • v2c: otherwise.
 None
timeout float

Request timeout in seconds.

 10.0
tos int

Set ToS/DSCP mark on egress packets.

 0
send_buffer int

Send buffer size for UDP socket. 0 - use default size.

 0
recv_buffer int

Receive buffer size for UDP socket. 0 - use default size.

 0
max_repetitions int

Default max_repetitions for getbulk.

 20
allow_bulk bool

Allow using GETBULK in SnmpSession.fetch() whenever possible.

 True
policer Optional[BasePolicer]

Optional BasePolicer instance to limit outgoing requests. Overrides limit_rps parameter.

 None
limit_rps Optional[Union[int, float]]

Limit outgouing requests to limit_rps requests per second.

 None
Example 
session = SnmpSession("127.0.0.1")
r = await session.get("1.3.6.1.2.1.1.6.0")
Example 
async with SnmpSession("127.0.0.1") as session:
    r = await session.get("1.3.6.1.2.1.1.6.0")

__aenter__() async

Asynchronous context manager entry.

__aexit__(exc_type, exc_val, exc_tb) async

Asynchronous context manager exit.

fetch(oid)

Iterate over oids using fastest method available.

When SnmpSession's allow_bulk is set, use SnmpSession.getbulk() on SNMPv2, otherwise use SnmpSession.getnext().

Parameters:

Name Type Description Default
oid str

Starting oid

 required

Returns:

Type Description
AsyncIterator[Tuple[str, ValueType]]

Asynchronous iterator yielding pair of (oid, value)
Example 
async for oid, value in session.fetch("1.3.6"):
    print(oid, value)

get(oid) async

Send SNMP GET request and await for response.

Parameters:

Name Type Description Default
oid str

OID in numeric format, no leading dot.

 required

Returns:

Type Description
ValueType

Request result. Return type depends on requested oid.

Raises:

Type Description
ValueError

On invalid oid format.
OSError

When unable to send request.
TimeoutError

When timed out.
NoSuchInstance

When requested key is not found.
SnmpError

On other SNMP-related errors.

get_engine_id()

Get effective engine id.

Returns:

Type Description
bytes

Engine id as bytes.

get_many(oids) async

Send SNMP GET request for multiple oids and await for response.

Parameters:

Name Type Description Default
oids Iterable[str]

Iterable of oids in numeric format, no leading dots.

 required

Returns:

Type Description
Dict[str, ValueType]

Dict where keys are requested oids, values are returned values.
Dict[str, ValueType]

Types of values are depends on requested oids.
Note

There is no guarante that all requested oids are present in result dict. Some values may be missed if not returned by agent.

Raises:

Type Description
ValueError

On invalid oid format.
OSError

When unable to send request.
TimeoutError

When timed out.
RuntimeError

On Python runtime failure.
SnmpError

On other SNMP-related errors.

getbulk(oid, max_repetitions=None)

Iterate over oids.

Parameters:

Name Type Description Default
oid str

Starting oid

 required
max_repetitions Optional[int]

Maximal amount of items per response. Override the SnmpSession's defaults.

 None

Returns:

Type Description
AsyncIterator[Tuple[str, ValueType]]

Asynchronous iterator yielding pair of (oid, value)
Example 
async for oid, value in session.getbulk("1.3.6"):
    print(oid, value)

getnext(oid)

Iterate over oids.

Parameters:

Name Type Description Default
oid str

Starting oid

 required

Returns:

Type Description
AsyncIterator[Tuple[str, ValueType]]

Asynchronous iterator yielding pair of (oid, value)
Example 
async for oid, value in session.getnext("1.3.6"):
    print(oid, value)

refresh() async

Send and receive REPORT to refresh authentication state.

SNMPv3 only.

Refresh sent automatically on entering the SnmpSession and should be resent manually if over 150 seconds left from the last request.

SnmpVersion

Bases: IntEnum

SNMP protocol version.

User

Bases: object

SNMPv3 user.

Parameters:

Name Type Description Default
name str

user name.

 required
auth_key Optional[BaseAuthKey]

Optional authentication key.

 None
priv_key Optional[BasePrivKey]

Optional privacy key.

 None

snmpd_create_user: str property

createUser part of snmpd.conf.

Returns:

Type Description
str

createUser configuration directive.

snmpd_rouser: str property

rouser part of snmpd.conf.

Returns:

Type Description
str

rouser configuration directive.

get_auth_alg()

Auth algorithm index with key type mask.

Algorithms
  • 0 - No auth
  • 1 - MD5
  • 2 - SHA1

KeyType.mask applied

get_auth_key()

Authentication key.

get_priv_alg()

Privacy algorithm index.

Algorithms
  • 0 - No privacy
  • 1 - DES
  • 2 - AES-128

KeyType.mask applied

get_priv_key()

Privacy key.

require_auth()

Chech if user requires authentication.

Returns:

Type Description
bool

True, if user requires authetication