API References¶
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 sample scripts right into your Python interactive session.
Most of SNMP operations involve packet exchange over network. PySNMP is shipped with asyncio binding that let you run PySNMP in parallel with other tasks your application may perform.
High-level v3arch sync¶
Most simple and straightforward way to use PySNMP is by employing its Synchronous, blocking API. It used to be the default API to offer on pysnmp.hlapi sub-package import. However, it is now deprecated and removed.
Warning
First deprecated in PySNMP 6.0, and completely removed in PySNMP 6.2.
High-level v3arch 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, especially after
the introduction of async/await pattern. That greatly simplifies
development and maintenance.
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.v3arch.asyncio.UdpTransportTarget(timeout: float = 1, retries: int = 5, tagList=b'')¶
Represent UDP/IPv6 transport endpoint.
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.v3arch.asyncio import UdpTransportTarget >>> await UdpTransportTarget.create(('demo.pysnmp.com', 161)) UdpTransportTarget(('195.218.195.228', 161), timeout=1, retries=5, tagList='') >>>
- class pysnmp.hlapi.v3arch.asyncio.Udp6TransportTarget(timeout: float = 1, retries: int = 5, tagList=b'')¶
Creates UDP/IPv6 configuration entry and initialize socket API if needed.
This object can be used by
AsyncCommandGenerator
orAsyncNotificationOriginator
and their derivatives for adding new entries to Local Configuration Datastore (LCD) managed bySnmpEngine
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.v3arch.asyncio import Udp6TransportTarget >>> await Udp6TransportTarget.create(('google.com', 161)) Udp6TransportTarget(('2a00:1450:4014:80a::100e', 161), timeout=1, retries=5, tagList='') >>> await Udp6TransportTarget.create(('FEDC:BA98:7654:3210:FEDC:BA98:7654:3210', 161)) Udp6TransportTarget(('fedc:ba98:7654:3210:fedc:ba98:7654:3210', 161), timeout=1, retries=5, tagList='') >>> await Udp6TransportTarget.create(('1080:0:0:0:8:800:200C:417A', 161)) Udp6TransportTarget(('1080::8:800:200c:417a', 161), timeout=1, retries=5, tagList='') >>> await Udp6TransportTarget.create(('::0', 161)) Udp6TransportTarget(('::', 161), timeout=1, retries=5, tagList='') >>> await Udp6TransportTarget.create(('::', 161)) Udp6TransportTarget(('::', 161), timeout=1, retries=5, tagList='') >>>
High-level v3arch SNMP Engine¶
SNMP Engine is a central, stateful object used by all SNMP v3 subsystems. Calls to high-level Applications API also consume SNMP Engine object on input.
- class pysnmp.hlapi.v3arch.asyncio.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')) >>>
Create an SNMP engine object.
High-level v3arch auth¶
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.v3arch.asyncio.CommunityData(communityIndex, communityName=None, mpModel=1, contextEngineId=None, contextName='', tag='')¶
Creates SNMP v1/v2c configuration entry.
This object can be used by
AsyncCommandGenerator
orAsyncNotificationOriginator
and their derivatives for adding new entries to Local Configuration Datastore (LCD) managed bySnmpEngine
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.v3arch.asyncio 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='') >>>
Create a community data object.
User-Based¶
The UsmUserData
class provides SNMPv3 User-Based
Security Model configuration for SNMP v3 systems.
- class pysnmp.hlapi.v3arch.asyncio.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
orAsyncNotificationOriginator
and their derivatives for adding new entries to Local Configuration Datastore (LCD) managed bySnmpEngine
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:
authKey (
str
,OctetString
) – Initial value of the secret authentication key. If not set,USM_AUTH_NONE
is implied. If set and no authProtocol is specified,USM_AUTH_HMAC96_MD5
takes effect.privKey (
str
,OctetString
) – Initial value of the secret encryption key. If not set,USM_PRIV_NONE
is implied. If set and no privProtocol is specified,USM_PRIV_CBC56_DES
takes effect.authProtocol (
tuple
,ObjectIdentifier
) – An indication of whether messages sent on behalf of this USM user can be authenticated, and if so, the type of authentication protocol which is used.Supported authentication protocol identifiers are:
USM_AUTH_NONE
(default is authKey not given)USM_AUTH_HMAC96_MD5
(default if authKey is given)
- 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:
USM_PRIV_NONE
(default is privKey not given)USM_PRIV_CBC56_DES
(default if privKey is given)
- 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
USM_KEY_TYPE_LOCALIZED
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.v3arch.asyncio 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)) >>>
Create a USM user data object.
Authentication protocol identifiers
- pysnmp.hlapi.v3arch.asyncio.USM_AUTH_NONE = (1, 3, 6, 1, 6, 3, 10, 1, 1, 1)¶
No Authentication Protocol
- pysnmp.hlapi.v3arch.asyncio.USM_AUTH_HMAC96_MD5 = (1, 3, 6, 1, 6, 3, 10, 1, 1, 2)¶
The HMAC-MD5-96 Digest Authentication Protocol (RFC 3414#section-6)
- pysnmp.hlapi.v3arch.asyncio.USM_AUTH_HMAC96_SHA = (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.v3arch.asyncio.USM_AUTH_HMAC128_SHA224 = (1, 3, 6, 1, 6, 3, 10, 1, 1, 4)¶
The HMAC-SHA-2 Digest Authentication Protocols (RFC 7860)
- pysnmp.hlapi.v3arch.asyncio.USM_AUTH_HMAC192_SHA256 = (1, 3, 6, 1, 6, 3, 10, 1, 1, 5)¶
The HMAC-SHA-2 Digest Authentication Protocols (RFC 7860)
- pysnmp.hlapi.v3arch.asyncio.USM_AUTH_HMAC256_SHA384 = (1, 3, 6, 1, 6, 3, 10, 1, 1, 6)¶
The HMAC-SHA-2 Digest Authentication Protocols (RFC 7860)
- pysnmp.hlapi.v3arch.asyncio.USM_AUTH_HMAC384_SHA512 = (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.v3arch.asyncio.USM_PRIV_NONE = (1, 3, 6, 1, 6, 3, 10, 1, 2, 1)¶
No Privacy Protocol
- pysnmp.hlapi.v3arch.asyncio.USM_PRIV_CBC56_DES = (1, 3, 6, 1, 6, 3, 10, 1, 2, 2)¶
The CBC-DES Symmetric Encryption Protocol (RFC 3414#section-8)
- pysnmp.hlapi.v3arch.asyncio.USM_PRIV_CBC168_3DES = (1, 3, 6, 1, 6, 3, 10, 1, 2, 3)¶
The 3DES-EDE Symmetric Encryption Protocol (draft-reeder-snmpv3-usm-3desede-00)
- pysnmp.hlapi.v3arch.asyncio.USM_PRIV_CFB128_AES = (1, 3, 6, 1, 6, 3, 10, 1, 2, 4)¶
The CFB128-AES-128 Symmetric Encryption Protocol (RFC 3826#section-3)
- pysnmp.hlapi.v3arch.asyncio.USM_PRIV_CFB192_AES = (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. Also known as AES-192-Cisco
- pysnmp.hlapi.v3arch.asyncio.USM_PRIV_CFB256_AES = (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. Also also known as AES-256-Cisco
- pysnmp.hlapi.v3arch.asyncio.USM_PRIV_CFB192_AES_BLUMENTHAL = (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.v3arch.asyncio.USM_PRIV_CFB256_AES_BLUMENTHAL = (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.v3arch.asyncio.USM_KEY_TYPE_PASSPHRASE = 0¶
USM key material type - plain-text pass phrase (RFC 3414#section-2.6)
- pysnmp.hlapi.v3arch.asyncio.USM_KEY_TYPE_MASTER = 1¶
USM key material type - hashed pass-phrase AKA master key (RFC 3414#section-2.6)
- pysnmp.hlapi.v3arch.asyncio.USM_KEY_TYPE_LOCALIZED = 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.
High-level v3arch 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.v3arch.asyncio.ContextData(contextEngineId=None, contextName=b'')¶
Creates UDP/IPv6 configuration entry and initialize socket API if needed.
This object can be used by
AsyncCommandGenerator
orAsyncNotificationOriginator
and their derivatives 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.v3arch.asyncio 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')
Create a context data object.
High-level v1arch asyncio¶
The asyncio
module is in Python standard library since ancient
times. Main loop is built around select
dispatcher, user
code is invoked through callback callables.
Different from v3arch asyncio, v1arch asyncio API aims to avoid the complexity of the v3arch asyncio API, and to provide a simpler and more straightforward API for users who only need to perform SNMP v1 and v2c operations.
Command Generator
Notification Originator
Transport configuration¶
- class pysnmp.hlapi.v1arch.asyncio.UdpTransportTarget(timeout: float = 1, retries: int = 5, tagList=b'')¶
Represent UDP/IPv4 transport endpoint.
This object can be used for passing UDP/IPv4 configuration information to the
AsyncCommandGenerator
andAsyncNotificationOriginator
objects scheduled on I/O bySnmpDispatcher
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.v1arch.asyncio import UdpTransportTarget >>> await UdpTransportTarget.create(('demo.pysnmp.com', 161)) UdpTransportTarget(('195.218.195.228', 161), timeout=1, retries=5) >>>
- class pysnmp.hlapi.v1arch.asyncio.Udp6TransportTarget(timeout: float = 1, retries: int = 5, tagList=b'')¶
Represent UDP/IPv6 transport endpoint.
This object can be used for passing UDP/IPv6 configuration information to the
AsyncCommandGenerator
andAsyncNotificationOriginator
objects scheduled on I/O bySnmpDispatcher
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.v1arch.asyncio import Udp6TransportTarget >>> await Udp6TransportTarget.create(('google.com', 161)) Udp6TransportTarget(('2a00:1450:4014:80a::100e', 161), timeout=1, retries=5, tagList='') >>> await Udp6TransportTarget.create(('FEDC:BA98:7654:3210:FEDC:BA98:7654:3210', 161)) Udp6TransportTarget(('fedc:ba98:7654:3210:fedc:ba98:7654:3210', 161), timeout=1, retries=5, tagList='') >>> await Udp6TransportTarget.create(('1080:0:0:0:8:800:200C:417A', 161)) Udp6TransportTarget(('1080::8:800:200c:417a', 161), timeout=1, retries=5, tagList='') >>> await Udp6TransportTarget.create(('::0', 161)) Udp6TransportTarget(('::', 161), timeout=1, retries=5, tagList='') >>> await Udp6TransportTarget.create(('::', 161)) Udp6TransportTarget(('::', 161), timeout=1, retries=5, tagList='') >>>
High-level v1arch SNMP Dispatcher¶
SNMP Dispatcher is a stateful object representing asynchronous I/O event loop and also holding some caches. Calls to v1arch always require consume SNMP Dispatcher object on input.
- class pysnmp.hlapi.v1arch.SnmpDispatcher¶
Creates SNMP message dispatcher object.
SnmpDispatcher object manages send and receives SNMP PDU messages through underlying transport dispatcher and dispatches them to the callers.
SnmpDispatcher is the only stateful object, all hlapi.v1arch SNMP operations require an instance of SnmpDispatcher. Users do not normally request services directly from SnmpDispather, but pass it around to other hlapi.v1arch interfaces.
It is possible to run multiple instances of SnmpDispatcher in the application. In a multithreaded environment, each thread that works with SNMP must have its own SnmpDispatcher instance.
High-level v1arch auth¶
Calls to v1arch API require SNMP authentication object on input.
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.v1arch.CommunityData(communityName, mpModel=1)¶
Creates SNMP v1/v2c configuration entry.
This object can be used by
AsyncCommandGenerator
orAsyncNotificationOriginator
and their derivatives for conveying SNMP v1/v2c configuration.- Parameters:
communityName (py:class:str) – SNMP v1/v2c community string.
mpModel (py:class:int) – SNMP version - 0 for SNMPv1 and 1 for SNMPv2c.
Examples
>>> from pysnmp.hlapi.v1arch import CommunityData >>> CommunityData('public') CommunityData(communityName=<COMMUNITY>, mpModel=1)
Create a community data instance.
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 definitions.
- 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 OIDsingle
str
representing OID in dot-separated integers formsingle
str
representing MIB variable in dot-separated labels formsingle
str
representing MIB name. First variable defined in MIB is assumed.pair of
str
representing MIB name and variable namepair of
str
representing MIB name and variable name followed by an arbitrary number ofstr
and/orint
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
resolve_with_mib()
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)
Create an ObjectIdentity instance.
- get_mib_symbol()¶
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.resolve_with_mib(mibViewController) >>> objectIdentity.get_mib_symbol() ('SNMPv2-MIB', 'sysDescr', (0,)) >>>
- get_oid()¶
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.resolve_with_mib(mibViewController) >>> objectIdentity.get_oid() ObjectName('1.3.6.1.2.1.1.1.0') >>>
- get_label()¶
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.resolve_with_mib(mibViewController) >>> objectIdentity.get_oid() ('iso', 'org', 'dod', 'internet', 'mgmt', 'mib-2', 'system', 'sysDescr') >>>
- get_mib_node()¶
Returns MIB node object representing this MIB variable.
- Returns:
ObjectType
– class instance representing MIB variable.- Raises:
SmiError – If MIB variable conversion has not been performed.
- is_fully_resolved()¶
Returns True if MIB variable conversion has been performed.
- Returns:
bool – True if MIB variable conversion has been performed.
Examples
>>> objectIdentity = ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0) >>> objectIdentity.is_fully_resolved() False >>> objectIdentity.resolve_with_mib(mibViewController) >>> objectIdentity.is_fully_resolved() True >>>
- add_asn1_mib_source(*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
HttpReader
classes for in-depth information on ASN.1 MIB lookup.Examples
>>> ObjectIdentity('SNMPv2-MIB', 'sysDescr').add_asn1_mib_source('https://mibs.pysnmp.com/asn1/@mib@') ObjectIdentity('SNMPv2-MIB', 'sysDescr') >>>
- add_mib_source(*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').add_mib_source('/opt/pysnmp/mibs', 'pysnmp_mibs') ObjectIdentity('SNMPv2-MIB', 'sysDescr') >>>
- load_mibs(*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').load_mibs('IF-MIB', 'TCP-MIB') ObjectIdentity('SNMPv2-MIB', 'sysDescr') >>>
- resolve_with_mib(mibViewController: MibViewController, ignoreErrors=True)¶
Perform MIB variable ID conversion.
- Parameters:
mibViewController (
MibViewController
) – class instance representing MIB browsing functionality.- Other Parameters:
ignoreErrors (
bool
) – If True (default), ignore MIB object name casting failures if possible.- Returns:
ObjectIdentity
– reference to itself- Raises:
SmiError – In case of fatal MIB handling error
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.resolve_with_mib(mibViewController) ObjectIdentity('SNMPv2-MIB', 'sysDescr') >>>
- prettyPrint()¶
Return a human-friendly representation of the object.
- __repr__()¶
Return a string representation of the object.
- __str__()¶
Return a string representation of the object.
- __eq__(other)¶
Compare OID with another OID.
- __ne__(other)¶
Compare OID with another OID.
- __lt__(other)¶
Compare OID with another OID.
- __le__(other)¶
Compare OID with another OID.
- __gt__(other)¶
Compare OID with another OID.
- __ge__(other)¶
Compare OID with another OID.
- __nonzero__()¶
Return True if the OID is not empty.
- __bool__()¶
Return True if the OID is not empty.
- __getitem__(i)¶
Return the i-th element of the OID.
- __len__()¶
Return the length of the OID.
- __add__(other)¶
Add OID to the right of the other object.
- __radd__(other)¶
Add OID to the left of the other object.
- __hash__()¶
Return a hash value of the object.
- __getattr__(attr)¶
Redirect some attributes.
- class pysnmp.smi.rfc1902.ObjectType(objectIdentity, objectSyntax=<Null value object, tagSet <TagSet object, tags 0:0:5>, subtypeSpec <ConstraintsIntersection object, consts <SingleValueConstraint object, consts b''>>, encoding iso-8859-1, payload []>)¶
Create an object representing MIB variable.
Instances of
ObjectType
class are containers incorporatingObjectIdentity
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
resolve_with_mib()
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')
Create an ObjectType instance.
- __getitem__(i)¶
Return the i-th element of the ObjectType.
- __str__()¶
Return a string representation of the object.
- __repr__()¶
Return a string representation of the object.
- is_fully_resolved()¶
Returns True if MIB variable conversion has been performed.
- Returns:
bool – True if MIB variable conversion has been performed.
- add_asn1_mib_source(*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
andHttpReader
classes for in-depth information on ASN.1 MIB lookup.Examples
>>> ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr')).add_asn1_mib_source('https://mibs.pysnmp.com/asn1/@mib@') ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr')) >>>
- add_mib_source(*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')).add_mib_source('/opt/pysnmp/mibs', 'pysnmp_mibs') ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr')) >>>
- load_mibs(*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')).load_mibs('IF-MIB', 'TCP-MIB') ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr')) >>>
- resolve_with_mib(mibViewController: MibViewController, ignoreErrors=True) ObjectType ¶
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 handling error
Notes
Calling this method involves
resolve_with_mib()
method invocation.Examples
>>> from pysmi.hlapi.v3arch.asyncio import varbinds >>> mibViewController = varbinds.MibViewControllerManager.get_mib_view_controller(engine.cache) >>> objectType = ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr'), 'Linux i386') >>> objectType.resolve_with_mib(mibViewController) ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr'), DisplayString('Linux i386')) >>> str(objectType) 'SNMPv2-MIB::sysDescr."0" = Linux i386' >>>
- prettyPrint()¶
Return a human-friendly representation of the object.
- __getattr__(attr)¶
Redirect some attrs access to the OID object to behave alike.
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 definitions.
- class pysnmp.smi.rfc1902.NotificationType(objectIdentity, instanceIndex=(), objects={})¶
Create an object representing SNMP Notification.
Instances of
NotificationType
class are containers incorporatingObjectIdentity
class instance (identifying particular notification) and a collection of MIB variables IDs that NotificationOriginator should gather and put into notification message.Typical notification is defined like this (from IF-MIB.txt):
linkDown NOTIFICATION-TYPE OBJECTS { ifIndex, ifAdminStatus, ifOperStatus } STATUS current DESCRIPTION "A linkDown trap signifies that the SNMP entity..." ::= { snmpTraps 3 }
Corresponding NotificationType instantiation would look like this:
NotificationType(ObjectIdentity('IF-MIB', 'linkDown'))
To retain similarity with SNMP variable-bindings,
NotificationType
objects behave like a sequence ofObjectType
class instances.See RFC 1902#section-2 for more information on NOTIFICATION-TYPE SMI definitions.
- Parameters:
objectIdentity (
ObjectIdentity
) – Class instance representing MIB notification type identification.instanceIndex (
ObjectName
) – Trailing part of MIB variables OID identification that represents concrete instance of a MIB variable. When notification is prepared, instanceIndex is appended to each MIB variable identification listed in NOTIFICATION-TYPE->OBJECTS clause.objects (dict) – Dictionary-like object that may return values by OID key. The objects dictionary is consulted when notification is being prepared. OIDs are taken from MIB variables listed in NOTIFICATION-TYPE->OBJECTS with instanceIndex part appended.
Notes
Actual notification type and MIB variables look up occurs upon
resolve_with_mib()
invocation.Examples
>>> from pysnmp.smi.rfc1902 import * >>> NotificationType(ObjectIdentity('1.3.6.1.6.3.1.1.5.3')) NotificationType(ObjectIdentity('1.3.6.1.6.3.1.1.5.3'), (), {}) >>> NotificationType(ObjectIdentity('IP-MIB', 'linkDown'), ObjectName('3.5')) NotificationType(ObjectIdentity('1.3.6.1.6.3.1.1.5.3'), ObjectName('3.5'), {})
Create a NotificationType instance.
- __getitem__(i)¶
Return the i-th element of the NotificationType.
- __repr__()¶
Return a string representation of the object.
- add_varbinds(*varBinds)¶
Appends variable-binding to notification.
- Parameters:
varBinds (
ObjectType
) – One or moreObjectType
class instances.- Returns:
NotificationType
– reference to itself
Notes
This method can be used to add custom variable-bindings to notification message in addition to MIB variables specified in NOTIFICATION-TYPE->OBJECTS clause.
Examples
>>> nt = NotificationType(ObjectIdentity('IP-MIB', 'linkDown')) >>> nt.add_varbinds(ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0))) NotificationType(ObjectIdentity('IP-MIB', 'linkDown'), (), {}) >>>
- add_asn1_mib_source(*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:
NotificationType
– reference to itself
Notes
Please refer to
FileReader
andHttpReader
classes for in-depth information on ASN.1 MIB lookup.Examples
>>> NotificationType(ObjectIdentity('IF-MIB', 'linkDown'), (), {}).add_asn1_mib_source('https://mibs.pysnmp.com/asn1/@mib@') NotificationType(ObjectIdentity('IF-MIB', 'linkDown'), (), {}) >>>
- add_mib_source(*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:
NotificationType
– 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
>>> NotificationType(ObjectIdentity('IF-MIB', 'linkDown'), (), {}).add_mib_source('/opt/pysnmp/mibs', 'pysnmp_mibs') NotificationType(ObjectIdentity('IF-MIB', 'linkDown'), (), {}) >>>
- load_mibs(*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:
NotificationType
– reference to itself
Examples
>>> NotificationType(ObjectIdentity('IF-MIB', 'linkDown'), (), {}).load_mibs('IF-MIB', 'TCP-MIB') NotificationType(ObjectIdentity('IF-MIB', 'linkDown'), (), {}) >>>
- is_fully_resolved()¶
Return if the object is fully resolved.
- resolve_with_mib(mibViewController: MibViewController, ignoreErrors=True) NotificationType ¶
Perform MIB variable ID conversion and notification objects expansion.
- 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:
NotificationType
– reference to itself- Raises:
SmiError – In case of fatal MIB handling error
Notes
Calling this method might cause the following sequence of events (exact details depends on many factors):
pysnmp.smi.rfc1902.ObjectIdentity.resolve_with_mib()
is calledMIB variables names are read from NOTIFICATION-TYPE->OBJECTS clause,
ObjectType
instances are created from MIB variable OID and indexInstance suffix.objects dictionary is queried for each MIB variable OID, acquired values are added to corresponding MIB variable
Examples
>>> notificationType = NotificationType(ObjectIdentity('IF-MIB', 'linkDown')) >>> notificationType.resolve_with_mib(mibViewController) NotificationType(ObjectIdentity('IF-MIB', 'linkDown'), (), {}) >>>
- prettyPrint()¶
Return a human-friendly representation of the object.
- to_varbinds() tuple[ObjectType, ...] ¶
Return a sequence of MIB variables.
SNMP Base Types¶
SNMP represents real-world objects it serves along with their states in form of values. Those values each belong to one of SNMP types (RFC 1902#section-2) which, in turn, are based on ASN.1 data description language. PySNMP types are derived from PyASN1 implementation.
Null Type¶
- class pysnmp.proto.rfc1902.Null(initializer)¶
Creates an instance of SNMP Null class.
Null
type represents the absence of value.- Parameters:
initializer (str) – Python string object. Must be an empty string.
- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> Null('') Null('') >>>
Note
The NULL type actually belongs to the base ASN.1 types. It is not defined in RFC 1902#section-2 as an SNMP type. The Null type is exposed through rfc1902 module just for convenience.
Integer32 Type¶
- class pysnmp.proto.rfc1902.Integer32(initializer)¶
Creates an instance of SNMP Integer32 class.
Integer32
type represents integer-valued information between -2147483648 to 2147483647 inclusive (RFC 1902#section-7.1.1). This type is indistinguishable from theInteger
type. TheInteger32
type may be sub-typed to be more constrained than the baseInteger32
type.- Parameters:
initializer (int) – Python integer in range between -2147483648 to 2147483647 inclusive or
Integer32
.- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> Integer32(1234) Integer32(1234) >>> Integer32(1) > 2 True >>> Integer32(1) + 1 Integer32(2) >>> int(Integer32(321)) 321 >>> SmallInteger = Integer32.with_range(1,3) >>> SmallInteger(1) Integer32(1) >>> DiscreetInteger = Integer32.with_values(4, 8, 1) >>> DiscreetInteger(4) Integer32(4) >>>
- subtypeSpec = <ConstraintsIntersection object, consts <ValueRangeConstraint object, consts -2147483648, 2147483647>>¶
Set (on class, not on instance) or return a
ConstraintsIntersection
object imposing constraints on |ASN.1| type initialization values.
- classmethod with_values(*values)¶
Creates a subclass with discreet values constraint.
- classmethod with_range(minimum, maximum)¶
Creates a subclass with value range constraint.
Integer Type¶
- class pysnmp.proto.rfc1902.Integer(initializer)¶
Creates an instance of SNMP INTEGER class.
The
Integer
type represents integer-valued information as named-number enumerations (RFC 1902#section-7.1.1). This type inherits and is indistinguishable fromInteger32
class. TheInteger
type may be sub-typed to be more constrained than the baseInteger
type.- Parameters:
initializer (int) – Python integer in range between -2147483648 to 2147483647 inclusive or
Integer
class instance. In case of named-numbered enumerations, initialization is also possible by enumerated literal.- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> Integer(1234) Integer(1234) >>> Integer(1) > 2 True >>> Integer(1) + 1 Integer(2) >>> int(Integer(321)) 321 >>> SomeState = Integer.with_named_values(enable=1, disable=0) >>> SomeState(1) Integer('enable') >>> int(SomeState('disable')) 0 >>>
- classmethod with_named_values(**values)¶
Create a subclass with discreet named values constraint.
Reduce fully duplicate enumerations along the way.
OctetString Type¶
- class pysnmp.proto.rfc1902.OctetString(strValue=None, hexValue=None)¶
Creates an instance of SNMP OCTET STRING class.
The
OctetString
type represents arbitrary binary or text data (RFC 1902#section-7.1.2). It may be sub-typed to be constrained in size.- Parameters:
strValue (str) – Python string or
OctetString
class instance.- Other Parameters:
hexValue (str) – Python string representing octets in a hexadecimal notation (e.g. DEADBEEF).
- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> OctetString('some apples') OctetString('some apples') >>> OctetString('some apples') + ' and oranges' OctetString('some apples and oranges') >>> str(OctetString('some apples')) 'some apples' >>> SomeString = OctetString.with_size(3, 12) >>> str(SomeString(hexValue='deadbeef')) '\xde\xad\xbe\xef' >>>
- subtypeSpec = <ConstraintsIntersection object, consts <ValueSizeConstraint object, consts 0, 65535>>¶
Set (on class, not on instance) or return a
ConstraintsIntersection
object imposing constraints on |ASN.1| type initialization values.
- set_fixed_length(value)¶
Set fixed length.
- is_fixed_length()¶
Return if fixed length.
- get_fixed_length()¶
Return fixed length.
- clone(*args, **kwargs)¶
Clone the data.
- subtype(*args, **kwargs)¶
Subtype the data.
- classmethod with_size(minimum, maximum)¶
Creates a subclass with value size constraint.
IpAddress Type¶
- class pysnmp.proto.rfc1902.IpAddress(strValue=None, hexValue=None)¶
Creates an instance of SNMP IpAddress class.
The
IpAddress
class represents a 32-bit internet address as an OCTET STRING of length 4, in network byte-order (RFC 1902#section-7.1.5).- Parameters:
strValue (str) – The same as
OctetString
, additionally IPv4 address in dotted notation (‘127.0.0.1’).- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> IpAddress('127.0.0.1') IpAddress(hexValue='7f000001') >>> str(IpAddress(hexValue='7f000001')) '\x7f\x00\x00\x01' >>> IpAddress('\x7f\x00\x00\x01') IpAddress(hexValue='7f000001') >>>
ObjectIdentifier Type¶
- class pysnmp.proto.rfc1902.ObjectIdentifier(initializer)¶
Creates an instance of SNMP OBJECT IDENTIFIER class.
The
ObjectIdentifier
type represents administratively assigned names (RFC 1902#section-7.1.3). Supports sequence protocol where elements are integer sub-identifiers.- Parameters:
initializer (tuple, str) – Python tuple of up to 128 integers in range between 0 to 4294967295 inclusive or Python string containing OID in “dotted” form or
ObjectIdentifier
.- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> ObjectIdentifier((1, 3, 6)) ObjectIdentifier('1.3.6') >>> ObjectIdentifier('1.3.6') ObjectIdentifier('1.3.6') >>> tuple(ObjectIdentifier('1.3.6')) (1, 3, 6) >>> str(ObjectIdentifier('1.3.6')) '1.3.6' >>>
Counter32 Type¶
- class pysnmp.proto.rfc1902.Counter32(initializer)¶
Creates an instance of SNMP Counter32 class.
Counter32
type represents a non-negative integer which monotonically increases until it reaches a maximum value of 4294967295, when it wraps around and starts increasing again from zero (RFC 1902#section-7.1.6).- Parameters:
initializer (int) – Python integer in range between 0 to 4294967295 inclusive or any
Integer
-based class.- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> Counter32(1234) Counter32(1234) >>> Counter32(1) + 1 Counter32(2) >>> int(Counter32(321)) 321 >>>
Gauge32 Type¶
- class pysnmp.proto.rfc1902.Gauge32(initializer)¶
Creates an instance of SNMP Gauge32 class.
Gauge32
type represents a non-negative integer, which may increase or decrease, but shall never exceed a maximum value. The maximum value can not be greater than 4294967295 (RFC 1902#section-7.1.7).- Parameters:
initializer (int) – Python integer in range between 0 to 4294967295 inclusive or any
Integer
-based class.- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> Gauge32(1234) Gauge32(1234) >>> Gauge32(1) + 1 Gauge32(2) >>> int(Gauge32(321)) 321 >>>
Unsigned32 Type¶
- class pysnmp.proto.rfc1902.Unsigned32(initializer)¶
Creates an instance of SNMP Unsigned32 class.
Unsigned32
type represents integer-valued information between 0 and 4294967295 (RFC 1902#section-7.1.11).- Parameters:
initializer (int) – Python integer in range between 0 to 4294967295 inclusive or any
Integer
-based class.- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> Unsigned32(1234) Unsigned32(1234) >>> Unsigned32(1) + 1 Unsigned32(2) >>> int(Unsigned32(321)) 321 >>>
TimeTicks Type¶
- class pysnmp.proto.rfc1902.TimeTicks(initializer)¶
Creates an instance of SNMP TimeTicks class.
TimeTicks
type represents a non-negative integer which represents the time, modulo 4294967296, in hundredths of a second between two epochs (RFC 1902#section-7.1.8).- Parameters:
initializer (int) – Python integer in range between 0 to 4294967295 inclusive or any
Integer
-based class.- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> TimeTicks(1234) TimeTicks(1234) >>> TimeTicks(1) + 1 TimeTicks(2) >>> int(TimeTicks(321)) 321 >>>
Opaque Type¶
- class pysnmp.proto.rfc1902.Opaque(initializer)¶
Creates an instance of SNMP Opaque class.
The
Opaque
type supports the capability to pass arbitrary ASN.1 syntax. A value is encoded using the ASN.1 BER into a string of octets. This, in turn, is encoded as an OCTET STRING, in effect “double-wrapping” the original ASN.1 value (RFC 1902#section-7.1.9).- Parameters:
strValue (str) – Python string or
OctetString
-based class instance.- Other Parameters:
hexValue (str) – Python string representing octets in a hexadecimal notation (e.g. DEADBEEF).
- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> Opaque('some apples') Opaque('some apples') >>> Opaque('some apples') + ' and oranges' Opaque('some apples and oranges') >>> str(Opaque('some apples')) 'some apples' >>> str(Opaque(hexValue='deadbeef')) '\xde\xad\xbe\xef' >>>
Counter64 Type¶
- class pysnmp.proto.rfc1902.Counter64(initializer)¶
Creates an instance of SNMP Counter64 class.
Counter64
type represents a non-negative integer which monotonically increases until it reaches a maximum value of 18446744073709551615, when it wraps around and starts increasing again from zero (RFC 1902#section-7.1.10).- Parameters:
initializer (int) – Python integer in range between 0 to 4294967295 inclusive or any
Integer
-based class.- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> Counter64(1234) Counter64(1234) >>> Counter64(1) + 1 Counter64(2) >>> int(Counter64(321)) 321 >>>
Bits Type¶
- class pysnmp.proto.rfc1902.Bits(initializer)¶
Creates an instance of SNMP BITS class.
The
Bits
type represents an enumeration of named bits. This collection is assigned non-negative, contiguous values, starting at zero. Only those named-bits so enumerated may be present in a value (RFC 1902#section-7.1.4).The bits are named and identified by their position in the octet string. Position zero is the high order (or left-most) bit in the first octet of the string. Position 7 is the low order (or right-most) bit of the first octet of the string. Position 8 is the high order bit in the second octet of the string, and so on (BITS Pseudotype).
- Parameters:
strValue (str, tuple) – Sequence of bit names or a Python string (as a raw data) or
OctetString
class instance.- Other Parameters:
hexValue (str) – Python string representing octets in a hexadecimal notation (e.g. DEADBEEF).
- Raises:
PyAsn1Error : – On constraint violation or bad initializer.
Examples
>>> from pysnmp.proto.rfc1902 import * >>> SomeBits = Bits.with_named_bits(apple=0, orange=1, peach=2) >>> SomeBits(('apple', 'orange')).prettyPrint() 'apple, orange' >>> SomeBits(('apple', 'orange')) Bits(hexValue='c0') >>> SomeBits('\x80') Bits(hexValue='80') >>> SomeBits(hexValue='80') Bits(hexValue='80') >>> SomeBits(hexValue='80').prettyPrint() 'apple' >>>
Create a new instance of the class.
- static __new__(cls, *args, **kwargs)¶
Create a new instance of the class.
- prettyIn(bits)¶
Return raw bitstring.
- prettyOut(value)¶
Return named bits.
- classmethod with_named_bits(**values)¶
Creates a subclass with discreet named bits constraint.
Reduce fully duplicate enumerations along the way.