Library reference

Dealing with many SNMP features may quickly overwhelm developers who aim at a quick and trivial task, PySNMP employs a layered architecture approach where the topmost programming API tries to be as simple as possible to allow immediate solutions for most common use cases. It will let you perform SNMP GET/SET/WALK and TRAP/INFORM operations by pasting code snippets from PySNMP documentation and example scripts right into your Python interactive session.

Most of SNMP operations involve packet exchange over network. PySNMP is shipped with a set of bindings to popular asynchronous Python I/O frameworks that let you run PySNMP in parallel with other tasks your application may perform.

Synchronous SNMP

Most simple and strightforward way to use PySNMP is by employing its Synchronous, blocking API. It’s also the default API offered by users on pysnmp.hlapi sub-package import.

Command Generator

Notification Originator

Transport configuration

The following shortcut classes convey configuration information to SNMP engine’s Local Configuration Datastore (RFC 2271#section-3.4.2) as well as to underlying socket API. Once committed to LCD, SNMP engine saves its configuration for the lifetime of SNMP engine object.

class pysnmp.hlapi.UdpTransportTarget(transportAddr, timeout=1, retries=5, tagList=b'')

Creates UDP/IPv4 configuration entry and initialize socket API if needed.

This object can be used for adding new entries to Local Configuration Datastore (LCD) managed by SnmpEngine class instance.

See RFC 1906#section-3 for more information on the UDP transport mapping.

Parameters

  • transportAddr (tuple) – Indicates remote address in Python socket module format which is a tuple of FQDN, port where FQDN is a string representing either hostname or IPv4 address in quad-dotted form, port is an integer.

  • timeout (int) – Response timeout in seconds.

  • retries (int) – Maximum number of request retries, 0 retries means just a single request.

  • tagList (str) – Arbitrary string that contains a list of space-separated tag strings used to select target addresses and/or SNMP configuration (see RFC 3413#section-4.1.1, RFC 2576#section-5.3 and CommunityData object).

Examples

>>> from pysnmp.hlapi.asyncore import UdpTransportTarget
>>> UdpTransportTarget(('demo.snmplabs.com', 161))
UdpTransportTarget(('195.218.195.228', 161), timeout=1, retries=5, tagList='')
>>>
setLocalAddress(iface)

Set source address.

Parameters

iface (tuple) – Indicates network address of a local interface from which SNMP packets will be originated. Format is the same as of transportAddress.

Returns

self

class pysnmp.hlapi.Udp6TransportTarget(transportAddr, timeout=1, retries=5, tagList=b'')

Creates UDP/IPv6 configuration entry and initialize socket API if needed.

This object can be used for adding new entries to Local Configuration Datastore (LCD) managed by SnmpEngine class instance.

See RFC 1906#section-3, RFC 2851#section-4 for more information on the UDP and IPv6 transport mapping.

Parameters

  • transportAddr (tuple) – Indicates remote address in Python socket module format which is a tuple of FQDN, port where FQDN is a string representing either hostname or IPv6 address in one of three conventional forms (RFC 1924#section-3), port is an integer.

  • timeout (int) – Response timeout in seconds.

  • retries (int) – Maximum number of request retries, 0 retries means just a single request.

  • tagList (str) – Arbitrary string that contains a list of tag values which are used to select target addresses for a particular operation (RFC 3413#section-4.1.4).

Examples

>>> from pysnmp.hlapi.asyncore import Udp6TransportTarget
>>> Udp6TransportTarget(('google.com', 161))
Udp6TransportTarget(('2a00:1450:4014:80a::100e', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('FEDC:BA98:7654:3210:FEDC:BA98:7654:3210', 161))
Udp6TransportTarget(('fedc:ba98:7654:3210:fedc:ba98:7654:3210', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('1080:0:0:0:8:800:200C:417A', 161))
Udp6TransportTarget(('1080::8:800:200c:417a', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('::0', 161))
Udp6TransportTarget(('::', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('::', 161))
Udp6TransportTarget(('::', 161), timeout=1, retries=5, tagList='')
>>>
setLocalAddress(iface)

Set source address.

Parameters

iface (tuple) – Indicates network address of a local interface from which SNMP packets will be originated. Format is the same as of transportAddress.

Returns

self

Asynchronous: asyncore

The asyncore module is in Python standard library since ancient times. Main loop is built around select dispatcher, user code is invoked through callback callables.

Command Generator

Notification Originator

Transport configuration

class pysnmp.hlapi.asyncore.UdpTransportTarget(transportAddr, timeout=1, retries=5, tagList=b'')

Creates UDP/IPv4 configuration entry and initialize socket API if needed.

This object can be used for adding new entries to Local Configuration Datastore (LCD) managed by SnmpEngine class instance.

See RFC 1906#section-3 for more information on the UDP transport mapping.

Parameters

  • transportAddr (tuple) – Indicates remote address in Python socket module format which is a tuple of FQDN, port where FQDN is a string representing either hostname or IPv4 address in quad-dotted form, port is an integer.

  • timeout (int) – Response timeout in seconds.

  • retries (int) – Maximum number of request retries, 0 retries means just a single request.

  • tagList (str) – Arbitrary string that contains a list of space-separated tag strings used to select target addresses and/or SNMP configuration (see RFC 3413#section-4.1.1, RFC 2576#section-5.3 and CommunityData object).

Examples

>>> from pysnmp.hlapi.asyncore import UdpTransportTarget
>>> UdpTransportTarget(('demo.snmplabs.com', 161))
UdpTransportTarget(('195.218.195.228', 161), timeout=1, retries=5, tagList='')
>>>
setLocalAddress(iface)

Set source address.

Parameters

iface (tuple) – Indicates network address of a local interface from which SNMP packets will be originated. Format is the same as of transportAddress.

Returns

self

class pysnmp.hlapi.asyncore.Udp6TransportTarget(transportAddr, timeout=1, retries=5, tagList=b'')

Creates UDP/IPv6 configuration entry and initialize socket API if needed.

This object can be used for adding new entries to Local Configuration Datastore (LCD) managed by SnmpEngine class instance.

See RFC 1906#section-3, RFC 2851#section-4 for more information on the UDP and IPv6 transport mapping.

Parameters

  • transportAddr (tuple) – Indicates remote address in Python socket module format which is a tuple of FQDN, port where FQDN is a string representing either hostname or IPv6 address in one of three conventional forms (RFC 1924#section-3), port is an integer.

  • timeout (int) – Response timeout in seconds.

  • retries (int) – Maximum number of request retries, 0 retries means just a single request.

  • tagList (str) – Arbitrary string that contains a list of tag values which are used to select target addresses for a particular operation (RFC 3413#section-4.1.4).

Examples

>>> from pysnmp.hlapi.asyncore import Udp6TransportTarget
>>> Udp6TransportTarget(('google.com', 161))
Udp6TransportTarget(('2a00:1450:4014:80a::100e', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('FEDC:BA98:7654:3210:FEDC:BA98:7654:3210', 161))
Udp6TransportTarget(('fedc:ba98:7654:3210:fedc:ba98:7654:3210', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('1080:0:0:0:8:800:200C:417A', 161))
Udp6TransportTarget(('1080::8:800:200c:417a', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('::0', 161))
Udp6TransportTarget(('::', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('::', 161))
Udp6TransportTarget(('::', 161), timeout=1, retries=5, tagList='')
>>>
setLocalAddress(iface)

Set source address.

Parameters

iface (tuple) – Indicates network address of a local interface from which SNMP packets will be originated. Format is the same as of transportAddress.

Returns

self

Asynchronous: asyncio

The asyncio module first appeared in standard library since Python 3.3 (in provisional basis). Its main design feature is that it makes asynchronous code looking like synchronous one. That greately simplifies development and maintanence.

Command Generator

Notification Originator

Transport configuration

class pysnmp.hlapi.asyncio.UdpTransportTarget(transportAddr, timeout=1, retries=5, tagList=b'')

Creates UDP/IPv4 configuration entry and initialize socket API if needed.

This object can be used for adding new entries to Local Configuration Datastore (LCD) managed by SnmpEngine class instance.

See RFC 1906#section-3 for more information on the UDP transport mapping.

Parameters

  • transportAddr (tuple) – Indicates remote address in Python socket module format which is a tuple of FQDN, port where FQDN is a string representing either hostname or IPv4 address in quad-dotted form, port is an integer.

  • timeout (int) – Response timeout in seconds.

  • retries (int) – Maximum number of request retries, 0 retries means just a single request.

  • tagList (str) – Arbitrary string that contains a list of tag values which are used to select target addresses for a particular operation (RFC 3413#section-4.1.4).

Examples

>>> from pysnmp.hlapi.asyncio import UdpTransportTarget
>>> UdpTransportTarget(('demo.snmplabs.com', 161))
UdpTransportTarget(('195.218.195.228', 161), timeout=1, retries=5, tagList='')
>>>
setLocalAddress(iface)

Set source address.

Parameters

iface (tuple) – Indicates network address of a local interface from which SNMP packets will be originated. Format is the same as of transportAddress.

Returns

self

class pysnmp.hlapi.asyncio.Udp6TransportTarget(transportAddr, timeout=1, retries=5, tagList=b'')

Creates UDP/IPv6 configuration entry and initialize socket API if needed.

This object can be used by AsyncCommandGenerator or AsyncNotificationOriginator and their derevatives for adding new entries to Local Configuration Datastore (LCD) managed by SnmpEngine class instance.

See RFC 1906#section-3, RFC 2851#section-4 for more information on the UDP and IPv6 transport mapping.

Parameters

  • transportAddr (tuple) – Indicates remote address in Python socket module format which is a tuple of FQDN, port where FQDN is a string representing either hostname or IPv6 address in one of three conventional forms (RFC 1924#section-3), port is an integer.

  • timeout (int) – Response timeout in seconds.

  • retries (int) – Maximum number of request retries, 0 retries means just a single request.

  • tagList (str) – Arbitrary string that contains a list of tag values which are used to select target addresses for a particular operation (RFC 3413#section-4.1.4).

Examples

>>> from pysnmp.hlapi.asyncio import Udp6TransportTarget
>>> Udp6TransportTarget(('google.com', 161))
Udp6TransportTarget(('2a00:1450:4014:80a::100e', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('FEDC:BA98:7654:3210:FEDC:BA98:7654:3210', 161))
Udp6TransportTarget(('fedc:ba98:7654:3210:fedc:ba98:7654:3210', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('1080:0:0:0:8:800:200C:417A', 161))
Udp6TransportTarget(('1080::8:800:200c:417a', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('::0', 161))
Udp6TransportTarget(('::', 161), timeout=1, retries=5, tagList='')
>>> Udp6TransportTarget(('::', 161))
Udp6TransportTarget(('::', 161), timeout=1, retries=5, tagList='')
>>>
setLocalAddress(iface)

Set source address.

Parameters

iface (tuple) – Indicates network address of a local interface from which SNMP packets will be originated. Format is the same as of transportAddress.

Returns

self

Asynchronous: trollius

An almost compatible alternative to asyncio for pre-3.3 Python is Trollius module. PySNMP’s asyncio bindings automatically work with Trolleus.

Please refer to Trollius examples for more information.

Asynchronous: Twisted

Twisted is one of the earliest and hugely popular asynchronous I/O framework. It introduced a concept of Deferred for representing work-in-progress that is not blocking the rest of I/O operations. PySNMP provides Twisted bindings.

Command Generator

Notification Originator

Transport configuration

class pysnmp.hlapi.twisted.UdpTransportTarget(transportAddr, timeout=1, retries=5, tagList=b'')

Creates UDP/IPv4 configuration entry and initialize socket API if needed.

This object can be used for adding new entries to Local Configuration Datastore (LCD) managed by SnmpEngine class instance.

See RFC 1906#section-3 for more information on the UDP transport mapping.

Parameters

  • transportAddr (tuple) – Indicates remote address in Python socket module format which is a tuple of FQDN, port where FQDN is a string representing either hostname or IPv4 address in quad-dotted form, port is an integer.

  • timeout (int) – Response timeout in seconds.

  • retries (int) – Maximum number of request retries, 0 retries means just a single request.

  • tagList (str) – Arbitrary string that contains a list of tag values which are used to select target addresses for a particular operation (RFC 3413#section-4.1.4).

Examples

>>> from pysnmp.hlapi.twisted import UdpTransportTarget
>>> UdpTransportTarget(('demo.snmplabs.com', 161))
UdpTransportTarget(('195.218.195.228', 161), timeout=1, retries=5, tagList='')
>>>
setLocalAddress(iface)

Set source address.

Parameters

iface (tuple) – Indicates network address of a local interface from which SNMP packets will be originated. Format is the same as of transportAddress.

Returns

self

SNMP Engine

SNMP Engine is a central, stateful object used by all SNMP v3 substsems. Calls to high-level Applications API also consume SNMP Engine object on input.

class pysnmp.hlapi.SnmpEngine(snmpEngineID=None)

Creates SNMP engine object.

SNMP engine object is central in SNMP v3 architecture. It is an umbrella object that coordinates interactions between all parts of SNMP v3 system. See RFC 3412#section-2.1 (where it is termed The Dispatcher).

With PySNMP design, SnmpEngine is the only stateful object, all SNMP v3 operations require an instance of SNMP engine. Users do not normally request services directly from SnmpEngine, but pass it around to other PySNMP interfaces.

It is possible to run multiple instances of SnmpEngine in the application. In a multithreaded environment, each thread that works with SNMP must have its own SnmpEngine instance.

Parameters

snmpEngineID (OctetString) – Unique and unambiguous identifier of an SNMP engine. If not given, snmpEngineID is autogenerated and stored on the filesystem. See RFC 3411#section-3.1.1 for details.

Examples

>>> SnmpEngine()
SnmpEngine(snmpEngineID=OctetString(hexValue='0x80004fb80567726f6d6d69742'))
>>>

Security Parameters

Calls to high-level Applications API consume Security Parameters configuration object on input. The shortcut classes described in this section convey configuration information to SNMP engine’s Local Configuration Datastore (RFC 2271#section-3.4.2). Once committed to LCD, SNMP engine saves its configuration for the lifetime of SNMP engine object.

Community-based

Security Parameters object is Security Model specific. The CommunityData class is used for configuring Community-Based Security Model of SNMPv1/SNMPv2c.

class pysnmp.hlapi.CommunityData(communityIndex, communityName=None, mpModel=1, contextEngineId=None, contextName='', tag='')

Creates SNMP v1/v2c configuration entry.

This object can be used by AsyncCommandGenerator or AsyncNotificationOriginator and their derivatives for adding new entries to Local Configuration Datastore (LCD) managed by SnmpEngine class instance.

See RFC 2576#section-5.3 for more information on the SNMP-COMMUNITY-MIB::snmpCommunityTable.

Parameters

  • communityIndex (str, OctetString) – Unique index value of a row in snmpCommunityTable. If it is the only positional parameter, it is treated as a communityName.

  • communityName (str, OctetString) – SNMP v1/v2c community string.

  • mpModel (int) – SNMP message processing model AKA SNMP version. Known SNMP versions are:

    • 0 - for SNMP v1

    • 1 - for SNMP v2c (default)

contextEngineId: str, OctetString

Indicates the location of the context in which management information is accessed when using the community string specified by the above communityName.

contextName: str, OctetString

The context in which management information is accessed when using the above communityName.

tag: str

Arbitrary string that specifies a set of transport endpoints from which a command responder application will accept management requests with given communityName or to which notification originator application will send notifications when targets are specified by a tag value(s).

The other way to look at the tag feature is that it can make specific communityName only valid for certain targets.

The other use-case is when multiple distinct SNMP peers share the same communityName – binding each instance of communityName to transport endpoint lets you distinguish SNMP peers from each other (e.g. resolving communityName into proper securityName).

For more technical information on SNMP configuration tags please refer to RFC 3413#section-4.1.1 and RFC 2576#section-5.3 (e.g. the snmpCommunityTransportTag object).

See also: UdpTransportTarget

Warning

If the same communityIndex value is supplied repeatedly with different communityName (or other parameters), the later call supersedes all previous calls.

Make sure not to configure duplicate communityName values unless they have distinct mpModel and/or tag fields. This will make communityName based database lookup ambiguous.

Examples

>>> from pysnmp.hlapi import CommunityData
>>> CommunityData('public')
CommunityData(communityIndex='s1410706889', communityName=<COMMUNITY>, mpModel=1, contextEngineId=None, contextName='', tag='')
>>> CommunityData('public', 'public')
CommunityData(communityIndex='public', communityName=<COMMUNITY>, mpModel=1, contextEngineId=None, contextName='', tag='')
>>>

User-based

The UsmUserData class provides SNMPv3 User-Based Security Model configuration for SNMP v3 systems.

class pysnmp.hlapi.UsmUserData(userName, authKey=None, privKey=None, authProtocol=usmNoAuthProtocol, privProtocol=usmNoPrivProtocol, securityEngineId=None, authKeyType=usmKeyTypePassphrase, privKeyType=usmKeyTypePassphrase)

Creates SNMP v3 User Security Model (USM) configuration entry.

This object can be used by AsyncCommandGenerator or AsyncNotificationOriginator and their derivatives for adding new entries to Local Configuration Datastore (LCD) managed by SnmpEngine class instance.

See RFC 3414#section-5 for more information on the SNMP-USER-BASED-SM-MIB::usmUserTable.

Parameters

userName (str, OctetString) – A human readable string representing the name of the SNMP USM user.

Other Parameters
securityEngineId: OctetString

The snmpEngineID of the authoritative SNMP engine to which a dateRequest message is to be sent. Will be automatically discovered from peer if not given, unless localized keys are used. In the latter case securityEngineId must be specified.

See RFC 3414#section-2.5.1 for technical explanation.

securityName: str, OctetString

Together with the snmpEngineID it identifies a row in the SNMP-USER-BASED-SM-MIB::usmUserTable that is to be used for securing the message.

See RFC 3414#section-2.5.1 for technical explanation.

privProtocol: tuple, ObjectIdentifier

An indication of whether messages sent on behalf of this USM user be encrypted, and if so, the type of encryption protocol which is used.

Supported encryption protocol identifiers are:

authKeyType: int

Type of authKey material. See RFC 3414#section-2.6 for technical explanation.

Supported key types are:

privKeyType: int

Type of privKey material. See RFC 3414#section-2.6 for technical explanation.

Supported key types are:

Notes

If usmKeyTypeLocalized is used when running a non-authoritative SNMP engine, USM key localization mechanism is not invoked. As a consequence, local SNMP engine configuration won’t get automatically populated with remote SNMP engine’s securityEngineId.

Therefore peer SNMP engine’s securityEngineId must be added to local configuration and associated with its localized keys.

Alternatively, the magic securityEngineId value of five zeros (0x0000000000) can be used to refer to the localized keys that should be used with any unknown remote SNMP engine. This feature is specific to pysnmp.

Examples

>>> from pysnmp.hlapi import UsmUserData
>>> UsmUserData('testuser', authKey='authenticationkey')
UsmUserData(userName='testuser', authKey=<AUTHKEY>, privKey=<PRIVKEY>, authProtocol=(1,3,6,1,6,3,10,1,1,2), privProtocol=(1,3,6,1,6,3,10,1,2,1))
>>> UsmUserData('testuser', authKey='authenticationkey', privKey='encryptionkey')
UsmUserData(userName='testuser', authKey=<AUTHKEY>, privKey=<PRIVKEY>, authProtocol=(1,3,6,1,6,3,10,1,1,2), privProtocol=(1,3,6,1,6,3,10,1,2,2))
>>>

Authentication protocol identifiers

pysnmp.hlapi.usmNoAuthProtocol = (1, 3, 6, 1, 6, 3, 10, 1, 1, 1)

No Authentication Protocol

pysnmp.hlapi.usmHMACMD5AuthProtocol = (1, 3, 6, 1, 6, 3, 10, 1, 1, 2)

The HMAC-MD5-96 Digest Authentication Protocol (RFC 3414#section-6)

pysnmp.hlapi.usmHMACSHAAuthProtocol = (1, 3, 6, 1, 6, 3, 10, 1, 1, 3)

The HMAC-SHA-96 Digest Authentication Protocol AKA SHA-1 (RFC 3414#section-7)

pysnmp.hlapi.usmHMAC128SHA224AuthProtocol = (1, 3, 6, 1, 6, 3, 10, 1, 1, 4)

The HMAC-SHA-2 Digest Authentication Protocols (RFC 7860)

pysnmp.hlapi.usmHMAC192SHA256AuthProtocol = (1, 3, 6, 1, 6, 3, 10, 1, 1, 5)

The HMAC-SHA-2 Digest Authentication Protocols (RFC 7860)

pysnmp.hlapi.usmHMAC256SHA384AuthProtocol = (1, 3, 6, 1, 6, 3, 10, 1, 1, 6)

The HMAC-SHA-2 Digest Authentication Protocols (RFC 7860)

pysnmp.hlapi.usmHMAC384SHA512AuthProtocol = (1, 3, 6, 1, 6, 3, 10, 1, 1, 7)

The HMAC-SHA-2 Digest Authentication Protocols (RFC 7860)

Privacy (encryption) protocol identifiers

pysnmp.hlapi.usmNoPrivProtocol = (1, 3, 6, 1, 6, 3, 10, 1, 2, 1)

No Privacy Protocol

pysnmp.hlapi.usmDESPrivProtocol = (1, 3, 6, 1, 6, 3, 10, 1, 2, 2)

The CBC-DES Symmetric Encryption Protocol (RFC 3414#section-8)

pysnmp.hlapi.usm3DESEDEPrivProtocol = (1, 3, 6, 1, 6, 3, 10, 1, 2, 3)

The 3DES-EDE Symmetric Encryption Protocol (draft-reeder-snmpv3-usm-3desede-00)

pysnmp.hlapi.usmAesCfb128Protocol = (1, 3, 6, 1, 6, 3, 10, 1, 2, 4)

The CFB128-AES-128 Symmetric Encryption Protocol (RFC 3826#section-3)

pysnmp.hlapi.usmAesCfb192Protocol = (1, 3, 6, 1, 4, 1, 9, 12, 6, 1, 101)

The CFB128-AES-192 Symmetric Encryption Protocol (draft-blumenthal-aes-usm-04) with Reeder key localization

pysnmp.hlapi.usmAesCfb256Protocol = (1, 3, 6, 1, 4, 1, 9, 12, 6, 1, 102)

The CFB128-AES-256 Symmetric Encryption Protocol (draft-blumenthal-aes-usm-04) with Reeder key localization

pysnmp.hlapi.usmAesBlumenthalCfb192Protocol = (1, 3, 6, 1, 4, 1, 9, 12, 6, 1, 1)

The CFB128-AES-192 Symmetric Encryption Protocol (draft-blumenthal-aes-usm-04)

pysnmp.hlapi.usmAesBlumenthalCfb256Protocol = (1, 3, 6, 1, 4, 1, 9, 12, 6, 1, 2)

The CFB128-AES-256 Symmetric Encryption Protocol (draft-blumenthal-aes-usm-04)

Key material types

pysnmp.hlapi.usmKeyTypePassphrase = 0

USM key material type - plain-text pass phrase (RFC 3414#section-2.6)

pysnmp.hlapi.usmKeyTypeMaster = 1

USM key material type - hashed pass-phrase AKA master key (RFC 3414#section-2.6)

pysnmp.hlapi.usmKeyTypeLocalized = 2

USM key material type - hashed pass-phrase hashed with Context SNMP Engine ID (RFC 3414#section-2.6)

Note

SNMP authentication and encryption keys must be at least 8 and at most 32 octets long.

Transport configuration is I/O framework specific and is described in respective sections.

SNMP Context

SNMP engine may serve several instances of the same MIB within possibly multiple SNMP entities. SNMP context is a tool for unambiguously identifying a collection of MIB variables behind the SNMP engine. See RFC 3411#section-3.3.1 for details.

Note

The SNMP context information is not tied to SNMPv3/USM user, but it is transferred in SNMPv3 message header.

Legacy SNMPv1/v2c protocols do not accommodate the SNMP context information at all.

To fit legacy SNMPv1/SNMPv2c systems into unified SNMPv3 architecture, the mapping procedure is introduced by RFC 2576#section-5.1 which essentially lets you first configure and then supply the missing items (e.g. contextName, contextEngineId and other) to the upper layers of SNMP stack based on SNMPv1/v2c communityName and transport endpoint.

The SNMP context information necessary for this mapping procedure to operate is supplied through the CommunityData object.

class pysnmp.hlapi.ContextData(contextEngineId=None, contextName=b'')

Creates UDP/IPv6 configuration entry and initialize socket API if needed.

This object can be used by AsyncCommandGenerator or AsyncNotificationOriginator and their derevatives for forming SNMP PDU and also adding new entries to Local Configuration Datastore (LCD) in order to support SNMPv1/v2c with SNMPv3 interoperability.

See RFC 3411#section-4.1 for SNMP Context details.

Parameters

  • contextEngineId (str) – Uniquely identifies an SNMP entity that may realize an instance of a MIB with a particular contextName (RFC 3411#section-3.3.2). More frequently than not, ContextEngineID is the same as authoritative SnmpEngineID, however if SNMP Engine serves multiple SNMP Entities, their ContextEngineIDs would be distinct. Default is authoritative SNMP Engine ID.

  • contextName (str) – Used to name an instance of MIB (RFC 3411#section-3.3.3). Default is empty string.

Examples

>>> from pysnmp.hlapi import ContextData
>>> ContextData()
ContextData(contextEngineId=None, contextName='')
>>> ContextData(OctetString(hexValue='01020ABBA0'))
ContextData(contextEngineId=OctetString(hexValue='01020abba0'), contextName='')
>>> ContextData(contextName='mycontext')
ContextData(contextEngineId=None, contextName='mycontext')

MIB services

MIB Variables

SNMP MIB variable is identified by an OBJECT IDENTIFIER (OID) and is accompanied by a value belonging to one of SNMP types (RFC 1902#section-2). This pair is collectively called a variable-binding in SNMP parlance.

The rfc1902 module implements RFC 1902#section-2 MACRO definiitons.

class pysnmp.smi.rfc1902.ObjectIdentity(*args, **kwargs)

Create an object representing MIB variable ID.

At the protocol level, MIB variable is only identified by an OID. However, when interacting with humans, MIB variable can also be referred to by its MIB name. The ObjectIdentity class supports various forms of MIB variable identification, providing automatic conversion from one to others. At the same time ObjectIdentity objects behave like tuples of py:obj:int sub-OIDs.

See RFC 1902#section-2 for more information on OBJECT-IDENTITY SMI definitions.

Parameters

args – initial MIB variable identity. Recognized variants:

  • single tuple or integers representing OID

  • single str representing OID in dot-separated integers form

  • single str representing MIB variable in dot-separated labels form

  • single str representing MIB name. First variable defined in MIB is assumed.

  • pair of str representing MIB name and variable name

  • pair of str representing MIB name and variable name followed by an arbitrary number of str and/or int values representing MIB variable instance identification.

Other Parameters

kwargs – MIB resolution options(object):

  • whenever only MIB name is given, resolve into last variable defined in MIB if last=True. Otherwise resolves to first variable (default).

Notes

Actual conversion between MIB variable representation formats occurs upon resolveWithMib() invocation.

Examples

>>> from pysnmp.smi.rfc1902 import ObjectIdentity
>>> ObjectIdentity((1, 3, 6, 1, 2, 1, 1, 1, 0))
ObjectIdentity((1, 3, 6, 1, 2, 1, 1, 1, 0))
>>> ObjectIdentity('1.3.6.1.2.1.1.1.0')
ObjectIdentity('1.3.6.1.2.1.1.1.0')
>>> ObjectIdentity('iso.org.dod.internet.mgmt.mib-2.system.sysDescr.0')
ObjectIdentity('iso.org.dod.internet.mgmt.mib-2.system.sysDescr.0')
>>> ObjectIdentity('SNMPv2-MIB', 'system')
ObjectIdentity('SNMPv2-MIB', 'system')
>>> ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0)
ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0)
>>> ObjectIdentity('IP-MIB', 'ipAdEntAddr', '127.0.0.1', 123)
ObjectIdentity('IP-MIB', 'ipAdEntAddr', '127.0.0.1', 123)
getMibSymbol()

Returns MIB variable symbolic identification.

Returns

  • str – MIB module name

  • str – MIB variable symbolic name

  • ObjectName – class instance representing MIB variable instance index.

Raises

SmiError – If MIB variable conversion has not been performed.

Examples

>>> objectIdentity = ObjectIdentity('1.3.6.1.2.1.1.1.0')
>>> objectIdentity.resolveWithMib(mibViewController)
>>> objectIdentity.getMibSymbol()
('SNMPv2-MIB', 'sysDescr', (0,))
>>>
getOid()

Returns OID identifying MIB variable.

Returns

ObjectName – full OID identifying MIB variable including possible index part.

Raises

SmiError – If MIB variable conversion has not been performed.

Examples

>>> objectIdentity = ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0)
>>> objectIdentity.resolveWithMib(mibViewController)
>>> objectIdentity.getOid()
ObjectName('1.3.6.1.2.1.1.1.0')
>>>
getLabel()

Returns symbolic path to this MIB variable.

Meaning a sequence of symbolic identifications for each of parent MIB objects in MIB tree.

Returns

tuple – sequence of names of nodes in a MIB tree from the top of the tree towards this MIB variable.

Raises

SmiError – If MIB variable conversion has not been performed.

Notes

Returned sequence may not contain full path to this MIB variable if some symbols are now known at the moment of MIB look up.

Examples

>>> objectIdentity = ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0)
>>> objectIdentity.resolveWithMib(mibViewController)
>>> objectIdentity.getOid()
('iso', 'org', 'dod', 'internet', 'mgmt', 'mib-2', 'system', 'sysDescr')
>>>
addAsn1MibSource(*asn1Sources, **kwargs)

Adds path to a repository to search ASN.1 MIB files.

Parameters

*asn1Sources – one or more URL in form of str identifying local or remote ASN.1 MIB repositories. Path must include the @mib@ component which will be replaced with MIB module name at the time of search.

Returns

ObjectIdentity – reference to itself

Notes

Please refer to FileReader, HttpReader and FtpReader classes for in-depth information on ASN.1 MIB lookup.

Examples

>>> ObjectIdentity('SNMPv2-MIB', 'sysDescr').addAsn1Source('http://mibs.snmplabs.com/asn1/@mib@')
ObjectIdentity('SNMPv2-MIB', 'sysDescr')
>>>
addMibSource(*mibSources)

Adds path to repository to search PySNMP MIB files.

Parameters

*mibSources – one or more paths to search or Python package names to import and search for PySNMP MIB modules.

Returns

ObjectIdentity – reference to itself

Notes

Normally, ASN.1-to-Python MIB modules conversion is performed automatically through PySNMP/PySMI interaction. ASN1 MIB modules could also be manually compiled into Python via the mibdump.py tool.

Examples

>>> ObjectIdentity('SNMPv2-MIB', 'sysDescr').addMibSource('/opt/pysnmp/mibs', 'pysnmp_mibs')
ObjectIdentity('SNMPv2-MIB', 'sysDescr')
>>>
loadMibs(*modNames)

Schedules search and load of given MIB modules.

Parameters

*modNames – one or more MIB module names to load up and use for MIB variables resolution purposes.

Returns

ObjectIdentity – reference to itself

Examples

>>> ObjectIdentity('SNMPv2-MIB', 'sysDescr').loadMibs('IF-MIB', 'TCP-MIB')
ObjectIdentity('SNMPv2-MIB', 'sysDescr')
>>>
resolveWithMib(mibViewController)

Perform MIB variable ID conversion.

Parameters

mibViewController (MibViewController) – class instance representing MIB browsing functionality.

Returns

ObjectIdentity – reference to itself

Raises

SmiError – In case of fatal MIB hanling errora

Notes

Calling this method might cause the following sequence of events (exact details depends on many factors):

  • ASN.1 MIB file downloaded and handed over to MibCompiler for conversion into Python MIB module (based on pysnmp classes)

  • Python MIB module is imported by SNMP engine, internal indices created

  • MibViewController looks up the rest of MIB identification information based on whatever information is already available, ObjectIdentity class instance gets updated and ready for further use.

Examples

>>> objectIdentity = ObjectIdentity('SNMPv2-MIB', 'sysDescr')
>>> objectIdentity.resolveWithMib(mibViewController)
ObjectIdentity('SNMPv2-MIB', 'sysDescr')
>>>
class pysnmp.smi.rfc1902.ObjectType(objectIdentity, objectSyntax=None)

Create an object representing MIB variable.

Instances of ObjectType class are containers incorporating ObjectIdentity class instance (identifying MIB variable) and optional value belonging to one of SNMP types (RFC 1902).

Typical MIB variable is defined like this (from SNMPv2-MIB.txt):

sysDescr OBJECT-TYPE
    SYNTAX      DisplayString (SIZE (0..255))
    MAX-ACCESS  read-only
    STATUS      current
    DESCRIPTION
            "A textual description of the entity.  This value should..."
    ::= { system 1 }

Corresponding ObjectType instantiation would look like this:

ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr'), 'Linux i386 box')

In order to behave like SNMP variable-binding (RFC 1157#section-4.1.1), ObjectType objects also support sequence protocol addressing objectIdentity as its 0-th element and objectSyntax as 1-st.

See RFC 1902#section-2 for more information on OBJECT-TYPE SMI definitions.

Parameters

  • objectIdentity (ObjectIdentity) – Class instance representing MIB variable identification.

  • objectSyntax – Represents a value associated with this MIB variable. Values of built-in Python types will be automatically converted into SNMP object as specified in OBJECT-TYPE->SYNTAX field.

Notes

Actual conversion between MIB variable representation formats occurs upon resolveWithMib() invocation.

Examples

>>> from pysnmp.smi.rfc1902 import *
>>> ObjectType(ObjectIdentity('1.3.6.1.2.1.1.1.0'))
ObjectType(ObjectIdentity('1.3.6.1.2.1.1.1.0'), Null(''))
>>> ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0), 'Linux i386')
ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0), 'Linux i386')
addAsn1MibSource(*asn1Sources, **kwargs)

Adds path to a repository to search ASN.1 MIB files.

Parameters

*asn1Sources – one or more URL in form of str identifying local or remote ASN.1 MIB repositories. Path must include the @mib@ component which will be replaced with MIB module name at the time of search.

Returns

ObjectType – reference to itself

Notes

Please refer to FileReader, HttpReader and FtpReader classes for in-depth information on ASN.1 MIB lookup.

Examples

>>> ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr')).addAsn1Source('http://mibs.snmplabs.com/asn1/@mib@')
ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr'))
>>>
addMibSource(*mibSources)

Adds path to repository to search PySNMP MIB files.

Parameters

*mibSources – one or more paths to search or Python package names to import and search for PySNMP MIB modules.

Returns

ObjectType – reference to itself

Notes

Normally, ASN.1-to-Python MIB modules conversion is performed automatically through PySNMP/PySMI interaction. ASN1 MIB modules could also be manually compiled into Python via the mibdump.py tool.

Examples

>>> ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr')).addMibSource('/opt/pysnmp/mibs', 'pysnmp_mibs')
ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr'))
>>>
loadMibs(*modNames)

Schedules search and load of given MIB modules.

Parameters

*modNames – one or more MIB module names to load up and use for MIB variables resolution purposes.

Returns

ObjectType – reference to itself

Examples

>>> ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr')).loadMibs('IF-MIB', 'TCP-MIB')
ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr'))
>>>
resolveWithMib(mibViewController, ignoreErrors=True)

Perform MIB variable ID and associated value conversion.

Parameters

mibViewController (MibViewController) – class instance representing MIB browsing functionality.

Other Parameters

ignoreErrors (bool) – If True (default), ignore MIB object name or value casting failures if possible.

Returns

ObjectType – reference to itself

Raises

SmiError – In case of fatal MIB hanling errora

Notes

Calling this method involves resolveWithMib() method invocation.

Examples

>>> from pysmi.hlapi import varbinds
>>> mibViewController = varbinds.AbstractVarBinds.getMibViewController( engine )
>>> objectType = ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr'), 'Linux i386')
>>> objectType.resolveWithMib(mibViewController)
ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr'), DisplayString('Linux i386'))
>>> str(objectType)
'SNMPv2-MIB::sysDescr."0" = Linux i386'
>>>

MIB notification types

SNMP Notifications are enumerated and imply including certain set of MIB variables. Notification Originator applications refer to MIBs for MIB notifications through NOTIFICATION-TYPE ASN.1 macro. It conveys a set of MIB variables to be gathered and reported in SNMP Notification. The rfc1902 module implements RFC 1902#section-2 macro definiitons.

class