<HTML> <HEAD> <TITLE>PySNMP tutorial</TITLE> </HEAD> <BODY BGCOLOR="#ffffff" TEXT="#000000" LINK="#0000bb" VLINK="#551a8b" ALINK="#ff0000"> <FONT SIZE=2 FACE="arial, helvetica"> <TABLE ALIGN="CENTER" WIDTH="60%"><TR><TD><TABLE ALIGN="LEFT"><TR><TD> <H4> PySNMP tutorial </H4> <I>by <A HREF=mailto:ilya@glas.net>Ilya Etingof</A>, 2007-2012</I> <P><B>Table of contents</B></P> <UL> <LI><A HREF="#NETWORK-MANAGEMENT-BASICS">1. Network management basics</A> <UL> <LI><A HREF="#SNMP-MANAGEMENT-ARCHITECTURE">1.1 SNMP management architecture</A> <LI><A HREF="#HISTORY-OF-SNMP">1.2 The history of SNMP</A> </UL> <LI><A HREF="#PYSNMP-PROGRAMMING">2. Programming with PySNMP</A> <UL> <LI><A HREF="#ONELINER-APPS">2.1 One-line Applications</A> <UL> <LI><A HREF="#SYNCH-ONELINER-APPS">2.1.1 Synchronous Applications</A> <UL> <LI><A HREF="#CommandGenerator">2.1.1.1 Command Generator</A> <LI><A HREF="#NotificationOriginator">2.1.1.2 Notification Originator</A> </UL> <LI><A HREF="#ASYNCH-ONELINER-APPS">2.1.2 Asynchronous Applications</A> <UL> <LI><A HREF="#AsynCommandGenerator">2.1.2.1 Asynchronous Command Generator</A> <LI><A HREF="#AsynNotificationOriginator">2.1.2.2 Asynchronous Notification Originator</A> </UL> <LI><A HREF="#SECURITY-CONFIGURATION">2.1.3 Security configuration</A> <UL> <LI><A HREF="#UsmUserData">2.1.3.1 User-Based Security Model configuration</A> <LI><A HREF="#CommunityData">2.1.3.2 Community-Based Security Model configuration</A> </UL> <LI><A HREF="#TRANSPORT-CONFIGURATION">2.1.4 Transport configuration</A> <UL> <LI><A HREF="#UdpTransportTarget">2.1.4.1 UDP Transport Target</A> </UL> </UL> <LI><A HREF="#MANAGED-OBJECT-NAME-VALUE">2.2 Managed Objects names and values</A> <LI><A HREF="#MIB-SERVICES">2.3 MIB services</A> <UL> <LI><A HREF="#DATA-MODEL-MANAGED-OBJECTS">2.3.1 Data model for Managed Objects</A> <LI><A HREF="#MIB-BUILDER">2.3.2 MIB builder</A> <LI><A HREF="#MIB-VIEW-CONTROLLER">2.3.3 MIB view controller</A> <LI><A HREF="#IMPLEMENTING-MANAGED-OBJECTS-INSTANCES">2.3.4 Implementing Managed Objects Instances</A> <UL> <LI><A HREF="#ASSOCIATED-VALUE-GATEWAYING">2.3.4.1 Associated value gatewaying</A> <LI><A HREF="#TAPPING-ON-MANAGEMENT-INSTRUM">2.3.4.2 Tapping on Management Instrumentation API</A> </UL> </UL> </UL> <LI><A HREF="#APPENDIXIES">Appendixies</A> <UL> <LI><A HREF="#ASN1">ASN.1 standard</A> </UL> </UL> </UL> </UL> <I> Applicable to PySNMP 4.2.3 and later. </I> <P> <A NAME="NETWORK-MANAGEMENT-BASICS"></A> <H4> 1. Network management basics </H4> <P> As networks become more complex, in terms of device population, topology and distances, it has been getting more and more important for network administrators to have some easy and convenient way for controlling all pieces of the whole network. </P> <P> Basic features of a network management system include device information retrieval and device remote control. Former often takes shape of gathering device operation statistics, while latter can be seen in device remote configuration facilities. </P> <P> For any information to be exchanged between entities, some agreement on information format and transmission procedure needs to be settled beforehand. This is what is conventionally called a <STRONG>Protocol</STRONG>. </P> <P> Large networks nowdays, may host thousands of different devices. To benefit network manager's interoperability and simplicity, any device on the network should carry out most common and important management operations in a well known, unified way. Therefore, an important feature of a network management system would be a <STRONG>Convention on management information naming and presentation</STRONG>. </P> <P> Sometimes, management operations should be performed on large number of managed devices. For a network manager to complete such a management round in a reasonably short period of time, an important feature of a network management software would be <STRONG>Performance</STRONG>. <P> Some of network devices may run on severely limited resources what invokes another property of a proper network management facility: <STRONG>Low resource consumption</STRONG>. </P> <P> In practice, the latter requirement translates into low CPU cycles and memory footprint for management software aboard device being managed. </P> <P> As networking becomes a more crucial part of our daily lives, security issues have become more apparent. As a side note, even Internet technologies, having military roots, did not pay much attention to security initially. So, the last key feature of network management appears to be <STRONG>Security</STRONG>. </P> <P> Data passed back and forth through the course of management operations should be at least authentic and sometimes hidden from possible observers. </P> <P> All these problems were approached many times through about three decades of networking history. Some solutions collapsed over time for one reason or another, while others, such as Simple Network Management Protocol (SNMP), evolve into an industry standard. </P> <A NAME="SNMP-MANAGEMENT-ARCHITECTURE"></A> <H4> 1.1 SNMP management architecture </H4> <P> The SNMP management model includes three distinct entities -- Agent, Manager and Proxy talking to each other over network. </P> <P> Agent entity is basically a software running somewhere in a networked device and having the following distinguishing properties: </P> <UL> <LI>SNMP protocol support <LI>Access to managed device's internals </UL> <P> The latter feature is a source of management information for Agent, as well as a target for remote control operations. </P> <P> Modern SNMP standards suggest splitting Agent functionality on two parts. Such Agents may run SNMP for local processes called <STRONG>Subagents</STRONG>, which interface with managed devices internals. Communication between <STRONG>Master Agent</STRONG> and its Subagents is performed using a simplified version of original SNMP protocol, known as <STRONG>AgentX</STRONG>, which is designed to run only within a single host. </P> <P> Manager entity is usually an application used by humans (or daemons) for performing various network management tasks, such as device statistics retrieval or remote control. </P> <P> Sometimes, Agents and Managers may run peer-to-peer within a single entity that is called Proxy. Proxies can often be seen in application-level firewalling or may serve as SNMP protocol translators between otherwise SNMP version-incompatible Managers and Agents. </P> <P> For Manager to request Agent for an operation on a particular part of managed device, some convention on device's components naming is needed. Once some components are identified, Manager and Agent would have to agree upon possible components' states and their semantics. </P> <A NAME="MANAGED-OBJECTS"></A> <P> SNMP approach to both problems is to represent each component of a device as a named object, similar to named variables seen in programming languages, and state of a component maps to a value associated with this imaginary variable. These are called Managed Objects in SNMP. </P> <A NAME="CONCEPTUAL-TABLES"></A> <P> For representing a group of similar components of a device, such as network interfaces, Managed Objects can be organized into a so-called <STRONG>conceptual table</STRONG>. </STRONG> <P> Manager talks to Agent by sending it messages of several types. Message type implies certain action to be taken. For example, <STRONG>GET</STRONG> message instructs Agent to report back values of Managed Objects whose names are indicated in message. </P> <P> There's also a way for Agent to notify Manager of an event occurred to Agent. This is done through so-called <STRONG>Trap</STRONG> messages. Trap message also carries Managed Objects and possibly Values, but besides that it has an ID of event in form of integer number or a Managed Object. </P> <P> For naming Managed Objects, SNMP uses the concept of <A HREF="#OID">Object Identifier</A>. As an example of Managed Object, <i>.iso.org.dod.internet.mgmt.mib-2.system.sysName.0</i> represents human-readable name of a device where Agent is running. </P> <P> Managed Objects values are always instances of <A HREF="#ASN1">ASN.1</A> types (such as Integer) or SNMP-specific subtypes (such as IpAddress). As in programming languages, type has an effect of restricting possible set of states Managed Object may ever enter. </P> <P> Whenever SNMP entities talk to each other, they refer to Managed Objects whose semantics (and value type) must be known in advance by both parties. SNMP Agent may be seen as a primary source of information on Managed Objects, as they are implemented by Agent. In this model, Manager should have a map of Managed Objects contained within each Agent to talk to. </P> <A NAME="MIB"></A> <A NAME="SMI"></A> <P> SNMP standard introduces a set of ASN.1 language constructs (such as ASN.1 subtypes and MACROs) which is called <STRONG>Structure of Management Information</STRONG> (<STRONG>SMI</STRONG>). Collections of related Managed Objects described in terms of SMI comprise <STRONG>Management Information Base</STRONG> (<STRONG>MIB</STRONG>) modules. </P> <P> Commonly used Managed Objects form core MIBs that become part of SNMP standard. The rest of MIBs are normally created by vendors who build SNMP Agents into their products. </P> <P> More often then not, Manager implementations could parse MIB files and use Managed Objects information for names resolution, value type determination, pretty printing and so on. This feature is known as <STRONG>MIB parser</STRONG> support. <A NAME="HISTORY-OF-SNMP"></A> <H4> 1.2 The history of SNMP </H4> <P> First SNMP version dates back to 1988 when a set of IETF RFC's were first published ( <A HREF="http://www.ietf.org/rfc/rfc1065.txt">RFC1065</A>, <A HREF="http://www.ietf.org/rfc/rfc1066.txt">RFC1066</A>, <A HREF="http://www.ietf.org/rfc/rfc1067.txt">RFC1067</A> ). These documents describe protocol operations (in terms of message syntax and semantics), SMI and a few core MIBs. The first version appears to be lightweight and easy to implement. Although, its poor security became notorious over years (Security? Not My Problem!), because cleartext password used for authentication (AKA <STRONG>Community String</STRONG>) is extremely easy to eavesdrop and replay, even after almost 20 years, slightly refined standard ( <A HREF="http://www.ietf.org/rfc/rfc1155.txt">RFC1155</A>, <A HREF="http://www.ietf.org/rfc/rfc1157.txt">RFC1157</A>, <A HREF="http://www.ietf.org/rfc/rfc1212.txt">RFC1212</A> ) still seems to be the most frequent encounter in modern SNMP devices. </P> <P> In effort to fix security issues of SNMPv1 and to make protocol faster for operations on large number of Managed Objects, SNMP Working Group at IETF came up with SNMPv2. This new protocol offers bulk transfers of Managed Objects information (by means of new, GETBULK message payload), improved security and re-worked SMI. But its new party-based security system turned out to be too complicated. In the end, security part of SNMPv2 has been dropped in favor of community-based authentication system used in SNMPv1. The result of this compromise is known as SNMPv2c (where "c" stands for community) and is still widely supported without being a standard ( <A HREF="http://www.ietf.org/rfc/rfc1902.txt">RFC1902</A>, <A HREF="http://www.ietf.org/rfc/rfc1903.txt">RFC1903</A>, <A HREF="http://www.ietf.org/rfc/rfc1904.txt">RFC1904</A>, <A HREF="http://www.ietf.org/rfc/rfc1905.txt">RFC1905</A>, <A HREF="http://www.ietf.org/rfc/rfc1906.txt">RFC1906</A>, <A HREF="http://www.ietf.org/rfc/rfc1907.txt">RFC1907</A>, <A HREF="http://www.ietf.org/rfc/rfc1908.txt">RFC1908</A> ). </P> <P> The other compromise targeted at offering greater security than SNMPv1, without falling into complexities of SNMPv2, has been attempted by replacing SNMPv2 party-based security system with newly developed user-based security model. This variant of protocol is known as SNMPv2u. Although neither widely implemented nor standardized, <STRONG>User Based Security Model</STRONG> (<STRONG>USM</STRONG>) of SNMPv2u got eventually adopted as one of possibly many SNMPv3 security models. </P> <P> As of this writing, SNMPv3 is current standard for SNMP. Although it's based heavily on previous SNMP specifications, SNMPv3 offers many innovations but also brings significant complexity. Additions to version 3 are mostly about protocol operations. SMI part of standard is inherited intact from SNMPv2. </P> <P> SNMPv3 system is designed as a framework that consists of a core, known as <STRONG>Message and PDU Dispatcher</STRONG>, and several abstract subsystems: <STRONG>Message Processing Subsystem</STRONG> (<STRONG>MP</STRONG>), responsible for SNMP message handling, <STRONG>Transport Dispatcher</STRONG>, used for carrying over messages, and <STRONG>Security Subsystem</STRONG>, which deals with message authentication and encryption issues. The framework defines subsystems interfaces to let feature-specific modules to be plugged into SNMPv3 core thus forming particular feature-set of SNMP system. Typical use of this modularity feature could be seen in multiprotocol systems -- legacy SNMP protocols are implemented as version-specific MP and security modules. Native SNMPv3 functionality relies upon v3 message processing and User-Based Security modules. </P> <P> Besides highly detailed SNMP system specification, SNMPv3 standard also defines a typical set of SNMP applications and their behavior. These applications are Manager, Agent and Proxy ( <A HREF="http://www.ietf.org/rfc/rfc3411.txt">RFC3411</A>, <A HREF="http://www.ietf.org/rfc/rfc3412.txt">RFC3412</A>, <A HREF="http://www.ietf.org/rfc/rfc3413.txt">RFC3413</A>, <A HREF="http://www.ietf.org/rfc/rfc3414.txt">RFC3414</A>, <A HREF="http://www.ietf.org/rfc/rfc3415.txt">RFC3415</A>, <A HREF="http://www.ietf.org/rfc/rfc3416.txt">RFC3416</A>, <A HREF="http://www.ietf.org/rfc/rfc3417.txt">RFC3417</A>, <A HREF="http://www.ietf.org/rfc/rfc3418.txt">RFC3418</A> ). </P> <A NAME="PYSNMP-PROGRAMMING"></A> <H4> 2. Programming with PySNMP </H4> <P> PySNMP is a pure-Python SNMP engine implementation. This software deals with the darkest corners of SNMP specifications all in Python programming language. </P> <P> This paper is dedicated to PySNMP revisions 4.2.3 and up. Since PySNMP API's evolve over time, older revisions may provide slightly different interfaces than those described in this tutorial. Please refer to release-specific documentation for a more precise information. </P> <P> From Programmer's point of view, the layout of PySNMP software reflects SNMP protocol evolution. It has been written from ground up, from trivial SNMPv1 up to fully featured SNMPv3. Therefore, several levels of API to SNMP functionality are available: <UL> <LI> <P> The most ancient and low-level is SNMPv1/v2c protocol scope. Here programmer is supposed to build/parse SNMP messages and their payload -- <STRONG>Protocol Data Unit</STRONG> (<STRONG>PDU</STRONG>), handle protocol-level errors, transport issues and so on. </P> <P> Although considered rather complex to deal with, this API probably gives best performance, memory footprint and flexibility, unless MIB access and/or SNMPv3 support is needed. </P> </LI> <LI> <P> Parts of SNMPv3 standard is expressed in terms of some abstract API to SNMP engine and its components. PySNMP implementation adopts this abstract API to a great extent, so it's available at Programmer's disposal. As a side effect, SNMP RFCs could be referenced for API semantics when programming PySNMP at this level. </P> <P> This API is much more higher-level than previous; here Programmer would have to manage two major issues: setting up <STRONG>Local Configuration Datastore</STRONG> (<STRONG>LCD</STRONG>) of SNMP engine and build/parse PDUs. PySNMP system is shipped multi-lingual, thus at this level all SNMPv1, SNMPv2c and SNMPv3 features are available. </P> </LI> <LI> <P> At last, the highest-level API to SNMP functionality is available through the use of standard SNMPv3 applications. These applications cover the most frequent needs. That's why this API is expected to be the first to start with. </P> <P> The Applications API further simplifies Programmer's job by hiding LCD management issues (contrary to SNMPv3 engine level). This API could be exploited in a oneliner fashion, for quick and simple prototyping. </P> </LI> </UL> <P> As for its internal structure, PySNMP consists of a handful of large, dedicated components. They normally take shape of classes which turn into linked objects at runtime. So here are the main components: </P> <UL> <LI> <P> SNMP Engine is an object holding references to all other components of the SNMP system. Typical user application has a single instance of SNMP Engine class possibly shared by many SNMP Applications of all kinds. As the other linked-in components tend to buildup various configuration and housekeeping information in runtime, SNMP Engine object appears to be expensive to configure to a usable state. </P> </LI> <LI> <P> Transport subsystem is used for sending SNMP messages to and accepting them from network. The I/O subsystem consists of an abstract Dispatcher and one or more abstract Transport classes. Concrete Dispatcher implementation is I/O method-specific, consider BSD sockets for example. Concrete Transport classes are transport domain-specific. SNMP frequently uses UDP Transport but others are also possible. Transport Dispatcher interfaces are mostly used by Message And PDU Dispatcher. However, when using the SNMPv1/v2c-native API (the lowest-level one), these interfaces would be invoked directly. </P> </LI> <LI> <P> Message And PDU Dispatcher is a heart of SNMP system. Its main responsibilities include dispatching PDUs from SNMP Applications through various subsystems all the way down to Transport Dispatcher, and passing SNMP messages coming from network up to SNMP Applications. It maintains logical connection with Management Instrumentation Controller which carries out operations on Managed Objects, here for the purpose of LCD access. </P> </LI> <LI> <P> Message Processing Modules handle message-level protocol operations for present and possibly future versions of SNMP protocol. Most importantly, these include message parsing/building and possibly invoking security services whenever required. All MP Modules share standard API used by Message And PDU Dispatcher. </P> </LI> <LI> <P> Message Security Modules perform message authentication and/or encryption. As of this writing, User-Based (for v3) and Community (for v1/2c) modules are implemented in PySNMP. All Security Modules share standard API used by Message Processing subsystem. </P> </LI> <LI> <P> Access Control subsystem uses LCD information to authorize remote access to Managed Objects. This is used when serving Agent Applications or Trap receiver in Manager Applications. </P> </LI> <LI> <P> A collection of dedicated Managed Objects Instances are used by PySNMP for its internal purposes. They are collectively called Local Configuration Datastore (LCD). In PySNMP, all SNMP engine configuration and statistics is kept in LCD. LCD Configurator is a wrapper aimed at simplifying LCD operations. </P> </LI> </UL> <P> In most cases user is expected to only deal with the top-leve oneliner API to all these PySNMP components. However implementing SNMP Agents, Proxies and some other fine features of Managers require using the Standard Applications API. In those cases general understanding of SNMP operations and SNMP Engine components would be helpful. </P> <A NAME="ONELINER-APPS"></A> <H4> 2.1 One-line Applications </H4> <P> As of this writing, oneliner Applications support generating Manager-side GET/SET/GETNEXT/GETBULK and issuing Agent-side TRAP/INFORM messages. Agent and Manager side responders are more complex and rarely used to fit them into the concise oneliner API so these should be implemented on top of standard SNMP Applications API. </P> <P> There're two kinds of APIs to oneline Applications: synchronous and asynchronous. They are very similar in terms of their API and behaviour, both are implemented by the <STRONG>pysnmp.entity.rfc3413.oneliner.cmdgen</STRONG> module. The asynchronous version is more suited for massively parallel SNMP messaging. </P> <A NAME="SYNCH-ONELINER-APPS"></A> <H4> 2.1.1 Synchronous One-line Applications </H4> <P> This is the simplest and the most high-level API to standard SNMP Applications. It's advised to employ for singular and blocking operations as well as for rapid prototyping. </P> <A NAME="CommandGenerator"></A> <H4> 2.1.1.1 Command Generator </H4> <P> All Command Generator Applications are implemented by a single class: </P> <DL> <DT>class <STRONG>CommandGenerator</STRONG>([<STRONG>snmpEngine</STRONG>])</DT> <DD> <P> Create a SNMP Command Generator object. </P> <P> Although instantiation of this class is cheap, in the course of its further use, SNMP engine configuration is built and maintained though methods invocation. Therefore it is advised to keep and reuse CommandGenerator instance (or <STRONG>snmpEngine</STRONG> instance if passed as an initializer) for as long as possible within user applicatin. </P> </DD> </DL> <P> Methods of the <STRONG>CommandGenerator</STRONG> class instances implement specific request types. </P> <A NAME="CommandGenerator.getCmd"></A> <DL> <DT><STRONG>getCmd</STRONG>( <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>*varNames</STRONG>, <STRONG>lookupNames=False</STRONG>, <STRONG>lookupValues=False</STRONG> )</DT> <DD> <P> Perform SNMP GET request and return a response or error indication. </P> <P> The <STRONG>authData</STRONG> is a SNMP <A HREF="#UsmUserData">Security Parameters object</A>, <STRONG>transportTarget</STRONG> is a SNMP <A HREF="#UdpTransportTarget">Transport Configuration object</A> and <STRONG>*varNames</STRONG> is a sequence of <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects names</A>. </P> <P> The <STRONG>getCmd</STRONG> method returns a tuple of <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG>, <STRONG>errorIndex</STRONG>, <STRONG>varBinds</STRONG>. </P> <P> Non-empty <STRONG>errorIndication</STRONG> string indicates SNMP engine-level error. </P> <P> The pair of <STRONG>errorStatus</STRONG> and <STRONG>errorIndex</STRONG> variables determines SNMP PDU-level error. These are instances of pyasn1 <A HREF="http://pyasn1.sourceforge.net/#1.1.3">Integer class</A>. If <STRONG>errorStatus</STRONG> evaluates to true, this indicates SNMP PDU error caused by Managed Object at position <STRONG>errorIndex</STRONG>-1 in <STRONG>varBinds</STRONG>. Doing <STRONG>errorStatus.prettyPrint</STRONG>() would return an explanatory text error message. </P> <P> The <STRONG>varBinds</STRONG> is a sequence of <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects</A>. Those found in response are bound by position to Managed Object names passed in request. </P> <P> If <STRONG>lookupNames</STRONG> parameter evaluates to True, PySNMP will attempt to gather more information on <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects</A> returned in <STRONG>varBinds</STRONG> by searching for relevant MIB module and looking up there. Instance of <A HREF="#MibVariable">MibVariable</A> class will be returned as Managed Object names. </P> <P> If <STRONG>lookupValues</STRONG> parameter evaluates to True, Managed Objects Instances values returned in <STRONG>varBinds</STRONG> may be converted into a more precise type (employing <A HREF="#TEXTUAL-CONVENTION-AS-A-TYPE">TEXTUAL-CONVENTION</A> data from MIB) if PySNMP has relevant MIB loaded. Otherwise response values will belong to protocol-level <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Object Instance value types</A>. </P> </DD> </DL> <P> The following code performs SNMP GET operation <UL> <LI>using SNMP v2c <LI>with community name 'public' <LI>over IPv4/UDP <LI>against an Agent listening at localhost (UDP port 161) <LI>requesting two Managed Object Instances specified by name in string form </UL> </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> from pysnmp.entity.rfc3413.oneliner import cmdgen cmdGen = cmdgen.CommandGenerator() errorIndication, errorStatus, errorIndex, varBinds = cmdGen.getCmd( cmdgen.CommunityData('public'), cmdgen.UdpTransportTarget(('localhost', 161)), '1.3.6.1.2.1.1.1.0', '1.3.6.1.2.1.1.6.0' ) # Check for errors and print out results if errorIndication: print(errorIndication) else: if errorStatus: print('%s at %s' % ( errorStatus.prettyPrint(), errorIndex and varBinds[int(errorIndex)-1] or '?' ) ) else: for name, val in varBinds: print('%s = %s' % (name.prettyPrint(), val.prettyPrint())) </PRE> </TD></TR></TABLE> <A NAME="CommandGenerator.setCmd"></A> <DL> <DT><STRONG>setCmd</STRONG>( <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>*varBinds</STRONG>, <STRONG>lookupNames=False</STRONG>, <STRONG>lookupValues=False</STRONG> )</DT> <DD> <P> Perform SNMP SET request and return a response or error indication. </P> <P> The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>lookupNames</STRONG> and <STRONG>lookupValues</STRONG> parameters have the same semantics as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method. </P> <P> The <STRONG>*varBinds</STRONG> input parameter is a sequence of <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects</A> to be modified at the Agent. </P> <P> The <STRONG>setCmd</STRONG> method returns a tuple of <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG>, <STRONG>errorIndex</STRONG>, <STRONG>varBinds</STRONG>. having the same meaning as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method. </P> </DD> </DL> <P> The following code performs SNMP SET operation <UL> <LI>using SNMP v3 <LI>with username 'usr-md5-des', MD5 authentication and DES privacy protocols <LI>over IPv4/UDP <LI>against an Agent listening at localhost (UDP port 161) <LI>setting SNMPv2-MIB::sysName.0 object to a new value </UL> </P> <P> The <A HREF="#MibVariable">MibVariable</A> object is used on input to allow symbolic Managed Object Instance name specification. Response names are requested to be returned also in form of a MibVariable object and response values converted into MIB-defined type. </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> from pysnmp.entity.rfc3413.oneliner import cmdgen cmdGen = cmdgen.CommandGenerator() errorIndication, errorStatus, errorIndex, varBinds = cmdGen.setCmd( cmdgen.UsmUserData('usr-md5-des', 'authkey1', 'privkey1'), cmdgen.UdpTransportTarget(('localhost', 161)), (cmdgen.MibVariable('SNMPv2-MIB', 'sysName', 0), 'my new value'), lookupNames=True, lookupValues=True ) # Check for errors and print out results if errorIndication: print(errorIndication) else: if errorStatus: print('%s at %s' % ( errorStatus.prettyPrint(), errorIndex and varBinds[int(errorIndex)-1] or '?' ) ) else: for name, val in varBinds: print('%s = %s' % (name.prettyPrint(), val.prettyPrint())) </PRE> </TD></TR></TABLE> <A NAME="CommandGenerator.nextCmd"></A> <DL> <DT><STRONG>nextCmd</STRONG>( <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>*varNames</STRONG>, <STRONG>lookupNames=False</STRONG>, <STRONG>lookupValues=False</STRONG>, <STRONG>lexicographicMode=False</STRONG>, <STRONG>ignoreNonIncreasingOid=False</STRONG>, <STRONG>maxRows=0</STRONG> )</DT> <DD> <P> Perform SNMP GETNEXT request and return a response or error indication. The GETNEXT request type implies referring to Managed Objects whose Object Names are "next greater" to those used in request. </P> <P> The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>lookupNames</STRONG> and <STRONG>lookupValues</STRONG> parameters have the same semantics as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method. </P> <P> The <STRONG>*varNames</STRONG> parameter is a sequence of <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects names</A> to query Agent for their "next" greater neignbours' Managed Objects Instances values. Unlike the same-named parameter of <A HREF="#CommandGenerator.getCmd">getCmd</A> method, a partial (prefix part of) Managed Objects names are allowed here. For instance, a <STRONG>'1.3.6.1'</STRONG> argument would ask the Agent to report Managed Object Instance value with the next greater name known to this Agent (which may turn out to be <STRONG>'1.3.6.1.2.1.1.1.0'</STRONG>). </P> <P> The <STRONG>nextCmd</STRONG> method returns a tuple of <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG>, <STRONG>errorIndex</STRONG>, <STRONG>varBindTable</STRONG>. </P> <P> The <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG> and <STRONG>errorIndex</STRONG> parameters have the same meaning as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method. </P> <P> The <STRONG>varBindTable</STRONG> parameter is a sequence of <STRONG>varBinds</STRONG>. Each <STRONG>varBind</STRONG> of <STRONG>varBinds</STRONG> in <STRONG>varBindTable</STRONG> represent a set of Managed Objects whose Object Names reside inside <A HREF="#OID">OID</A> sub-tree of Managed Object name passed in request. In other words, with this oneliner API, an invocation of <STRONG>nextCmd</STRONG> method for a single Managed Object might return a sequence of Managed Objects so that Object Name passed in request would be a prefix for Object Names returned in response (as a side note, the same method in Applications API would return <STRONG>varBinds</STRONG> as held in a single response, and regardless of the prefix property). </P> <P> It's possible to modify the above behaviour so that the <STRONG>varBindTable</STRONG> returned would contain *all* Managed Objects from those passed in request up to the end of the list of available Managed Objects at the Agent. This option is enabled by passing the <STRONG>lexicographicMode=True</STRONG> parameter to <STRONG>nextCmd</STRONG> method. </P> <P> In some cases application is also interested in some contiguous set of Managed Objects Instances not necessarily strictly belonging to the same subtree. The <STRONG>maxRows=NNN</STRONG> parameter to <STRONG>nextCmd</STRONG> would stop Command Generator once the required number (NNN) of Managed Objects Instances are retrieved from the Agent. </P> <P> Properties of the <STRONG>varBinds</STRONG> parameter is the same as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method. </P> </DD> </DL> <P> The following code performs SNMP GETNEXT operation against a MIB subtree <UL> <LI>using SNMP v1 <LI>with community name 'public' <LI>over IPv4/UDP <LI>against an Agent listening at localhost (UDP port 161) <LI>for some columns of the IF-MIB::ifEntry table <LI>stop reading values from Agent once response names leave the scopes of initial names (e.g. OBJECT IDENTIFIER's) </UL> </P> <P> The <A HREF="#MibVariable">MibVariable</A> object is used on input to allow symbolic MIB table columns specification. Response values are requested to be converted into MIB-defined type. </P> <P> Note: the code below needs access to IF-MIB (e.g. IF-MIB.py) which is installed with the <A HREF="https://sourceforge.net/projects/pysnmp/files/pysnmp-mibs/">pysnmp-mibs package</A> or could be <A HREF="#DATA-MODEL-MANAGED-OBJECTS">converted manually</A> into pysnmp MIB module from IF-MIB text source. </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> from pysnmp.entity.rfc3413.oneliner import cmdgen cmdGen = cmdgen.CommandGenerator() errorIndication, errorStatus, errorIndex, varBindTable = cmdGen.nextCmd( cmdgen.CommunityData('public', mpModel=0), cmdgen.UdpTransportTarget(('localhost', 161)), cmdgen.MibVariable('IF-MIB', 'ifDescr'), cmdgen.MibVariable('IF-MIB', 'ifType'), cmdgen.MibVariable('IF-MIB', 'ifMtu'), cmdgen.MibVariable('IF-MIB', 'ifSpeed'), cmdgen.MibVariable('IF-MIB', 'ifPhysAddress'), lookupValues=True ) if errorIndication: print(errorIndication) else: if errorStatus: print('%s at %s' % ( errorStatus.prettyPrint(), errorIndex and varBindTable[-1][int(errorIndex)-1] or '?' ) ) else: for varBindTableRow in varBindTable: for name, val in varBindTableRow: print('%s = %s' % (name.prettyPrint(), val.prettyPrint())) </PRE> </TD></TR></TABLE> <A NAME="CommandGenerator.bulkCmd"></A> <DL> <DT><STRONG>bulkCmd</STRONG>( <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>nonRepeaters</STRONG>, <STRONG>maxRepetitions</STRONG>, <STRONG>*varNames</STRONG>, <STRONG>lookupNames=False</STRONG>, <STRONG>lookupValues=False</STRONG>, <STRONG>lexicographicMode=False</STRONG>, <STRONG>ignoreNonIncreasingOid=False</STRONG>, <STRONG>maxRows=0</STRONG> )</DT> <DD> <P> Perform SNMP GETBULK request and return a response or error indication. The GETBULK request type has the same semantics as GETNEXT one except that the latter is able to report multiple Managed Objects per each Managed Object name passed in request. </P> <P> The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>*varNames</STRONG>, <STRONG>lookupNames</STRONG>, <STRONG>lookupValues</STRONG>, <STRONG>lexicographicMode</STRONG> and <STRONG>maxRows</STRONG> input parameters to the <STRONG>bulkCmd</STRONG> method are the same as of <STRONG>nextCmd</STRONG>. </P> <P> The <STRONG>nonRepeaters</STRONG> parameter indicates how many of <STRONG>*varNames</STRONG> passed in request should be queried for a single instance with in a request. </P> <P> The <STRONG>maxRepetitions</STRONG> parameter indicates for how many instances of Managed Objects in the rest of <STRONG>*varNames</STRONG>, besides first <STRONG>nonRepeaters</STRONG> ones, should be queried within a single request. </P> <P> The <STRONG>bulkCmd</STRONG> method returns a tuple of <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG>, <STRONG>errorIndex</STRONG>, <STRONG>varBindTable</STRONG>. having same meaning as in <A HREF="#CommandGenerator.nextCmd">nextCmd</A> method. </P> </P> </DD> </DL> <P> The following code performs SNMP GETBULK operation against a MIB subtree <UL> <LI>using SNMP v3 <LI>with SNMPv3, user 'usr-sha-aes128', SHA auth, AES128 privacy <LI>over IPv6/UDP <LI>against an Agent listening at ::1 (UDP port 161) <LI>with values non-repeaters = 0, max-repetitions = 20 <LI>for the SNMPv2-MIB::system subtree <LI>stop reading values from Agent once response names leave the scopes of initial names (e.g. OBJECT IDENTIFIER's) </UL> </P> <P> The <A HREF="#MibVariable">MibVariable</A> object is used on input to allow symbolic MIB table columns specification. </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> from pysnmp.entity.rfc3413.oneliner import cmdgen cmdGen = cmdgen.CommandGenerator() errorIndication, errorStatus, errorIndex, varBindTable = cmdGen.bulkCmd( cmdgen.UsmUserData('usr-sha-aes128', 'authkey1', 'privkey1', authProtocol=cmdgen.usmHMACSHAAuthProtocol, privProtocol=cmdgen.usmAesCfb128Protocol), cmdgen.Udp6TransportTarget(('::1', 161)), 0, 20, cmdgen.MibVariable('SNMPv2-MIB', 'system') ) if errorIndication: print(errorIndication) else: if errorStatus: print('%s at %s' % ( errorStatus.prettyPrint(), errorIndex and varBindTable[-1][int(errorIndex)-1] or '?' ) ) else: for varBindTableRow in varBindTable: for name, val in varBindTableRow: print('%s = %s' % (name.prettyPrint(), val.prettyPrint())) </PRE> </TD></TR></TABLE> <A NAME="NotificationOriginator"></A> <H4> 2.1.1.2 Notification Originator </H4> <P> The Notification Originator Application is implemented within a single class: </P> <DL> <DT>class <STRONG>NotificationOriginator</STRONG>([<STRONG>snmpContext</STRONG>])</DT> <DD> <P> Create a SNMP Notification Originator object. </P> <P> Although instantiation of this class is cheap, in the course of its further use, SNMP engine configuration is built and maintained though methods invocation. Therefore it is advised to keep and reuse NotificationOriginator instance (or <STRONG>snmpEngine</STRONG> instance if passed as an initializer) for as long as possible within user applicatin. </P> </DD> </DL> <P> All notifications are sent by in invocation of the following method: </P> </P> <A NAME="NotificationOriginator.sendNotification"></A> <DL> <DT><STRONG>sendNotification</STRONG>( <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>notifyType</STRONG>, <STRONG>notificationType</STRONG>, <STRONG>*varBinds</STRONG> )</DT> <DD> <P> Send either unconfirmed (TRAP) or confirmed (INFORM) SNMP notification and possibly return an error indication. </P> <P> The <STRONG>authData</STRONG> and <STRONG>transportTarget</STRONG> parameters have the same semantics as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method. </P> <P> The <STRONG>notifyType</STRONG> parameter determines the type of notification to be generated. Supported values include <STRONG>"trap"</STRONG> for unconfirmed notification or <STRONG>"inform"</STRONG> for a confirmed one. </P> <P> The <STRONG>notificationType</STRONG> parameter indicates the kind of event to notify Manager about in form of SMI NOTIFICATION-TYPE object name. Either <A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A> class instance, its initialization value (like '1.3.6.1.6.3.1.1.5.1') or <A HREF="#MibVariable">MibVariable</A> object can be used on input to allow MIB symbols references. For example, '1.3.6.1.6.3.1.1.5.1' or MibVariable('SNMPv2-MIB', 'coldStart') specify <I>SNMPv2-MIB::coldStart</I> type of trap. </P> <P> When sending SNMP v1 traps, the <STRONG>notificationType</STRONG> parameter encodes both <I>Generic</I> and <I>Specific</I> trap numbers hardwired into SNMP v1 TRAP PDU, but missing in SNMP v2c TRAP and INFORM PDUs. </P> <TABLE BORDER=1 WIDTH=90% ALIGN=CENTER> <TR> <TD> <STRONG>notificationType</STRONG> </TD> <TD> <I>GenericTrap</I> </TD> <TD> <I>SpecificTrap</I> </TD> </TR> <TR> <TD>1.3.6.1.6.3.1.1.5.1<TD>coldStart(0)<TD>0</TD> <TR> <TD>1.3.6.1.6.3.1.1.5.2<TD>warmStart(1)<TD>0</TD> <TR> <TD>1.3.6.1.6.3.1.1.5.3<TD>linkDown(2)<TD>0</TD> <TR> <TD>1.3.6.1.6.3.1.1.5.4<TD>linkUp(3)<TD>0</TD> <TR> <TD>1.3.6.1.6.3.1.1.5.5<TD>authenticationFailure(4)<TD>0</TD> <TR> <TD>1.3.6.1.6.3.1.1.5.6<TD>egpNeighborLoss(5)<TD>0</TD> <TR> <TD>1.3.6.1.6.3.1.1.5.0.1<TD>enterpriseSpecific(6)<TD>1</TD> <TR> <TD>1.3.6.1.6.3.1.1.5.0.999<TD>enterpriseSpecific(6)<TD>999</TD> <TR> <TD>1.3.6.1.6.3.1.1.5.0.N<TD>enterpriseSpecific(6)<TD>N</TD> </TR> </TABLE> <P> The <STRONG>*varBinds</STRONG> input parameter is a tuple of Managed Objects to be passed over to Manager along with Notification. The syntax of <STRONG>*varBinds</STRONG> is the same as in <A HREF="#CommandGenerator.getCmd">getCmd</A> </P> <P> The <STRONG>sendNotification</STRONG> method returns an <STRONG>errorIndication</STRONG> parameter which has the same meaning as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method. </P> <P> When sending SNMP traps to a SNMPv1 system, PDU parameters that are present in SNMPv1 PDU but are missing in SNMPv2c PDU are mapped one to another via special Managed Objects Inctance values in <STRONG>*varBinds</STRONG>. </P> <UL> <LI>SNMP v1 PDU <I>enterprise</I> parameter is passed as a value of 1.3.6.1.6.3.1.1.4.3.0 Managed Object Instance in <STRONG>*varBinds</STRONG>. If not specified, the default value is 1.3.6.1.6.3.1.1.5. If <I>Generic</I> encoded in <STRONG>notificationType</STRONG> is <I>enterpriseSpecific</I>, the <I>enterprise</I> parameter is implicitly initialized into <STRONG>notificationType</STRONG> value minus trailing sub-OID. <LI>SNMP v1 PDU <I>agent-addr</I> parameter is passed as a value of 1.3.6.1.6.3.18.1.3.0 Managed Object Instance in <STRONG>*varBinds</STRONG>. <LI>SNMP v1 PDU <I>time-stamp</I> parameter is passed as a value of 1.3.6.1.2.1.1.3.0 Managed Object Instance in <STRONG>*varBinds</STRONG>. </UL> </DD> </DL> <P> The following code sends SNMP v2c TRAP message: <UL> <LI>using SNMP v2c <LI>with community name 'public' <LI>over IPv4/UDP <LI>send TRAP notification <LI>with TRAP ID 'coldStart' specified as a MIB symbol <LI>include managed object information specified as a MIB symbol </UL> </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> from pysnmp.entity.rfc3413.oneliner import ntforg ntfOrg = ntforg.NotificationOriginator() errorIndication = ntfOrg.sendNotification( ntforg.CommunityData('public'), ntforg.UdpTransportTarget(('localhost', 162)), 'trap', ntforg.MibVariable('SNMPv2-MIB', 'coldStart'), (ntforg.MibVariable('SNMPv2-MIB', 'sysName', 0), 'new name') ) if errorIndication: print('Notification not sent: %s' % errorIndication) </PRE> </TD></TR></TABLE> <P>To send SNMP v1 traps using standard Notification Originator application API, one may need to pass, and possibly override some of defaulted, SNMP v1 PDU fields that are not present as such in SNMP v2c PDU and thus in the API. </P> <P> The following example sends SNMP v1 TRAP message overriding implicit defaults: <UL> <LI>using SNMP v1 <LI>with community name 'public' <LI>over IPv4/UDP <LI>send TRAP notification <LI>with Generic Trap #6 (enterpriseSpecific) and Specific Trap 432 <LI>overriding local snmpEngine's Uptime with value 12345 <LI>overriding Agent Address with '127.0.0.1' <LI>overriding Enterprise OID with 1.3.6.1.4.1.20408.4.1.1.2 <LI>include managed object information '1.3.6.1.2.1.1.1.0' = 'my system' specified as an OID-value pair </UL> </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> from pysnmp.entity.rfc3413.oneliner import ntforg from pysnmp.proto import rfc1902 ntfOrg = ntforg.NotificationOriginator() errorIndication = ntfOrg.sendNotification( ntforg.CommunityData('public', mpModel=0), ntforg.UdpTransportTarget(('localhost', 162)), 'trap', '1.3.6.1.4.1.20408.4.1.1.2.0.432', ('1.3.6.1.2.1.1.3.0', 12345), ('1.3.6.1.6.3.18.1.3.0', '127.0.0.1'), ('1.3.6.1.6.3.1.1.4.3.0', '1.3.6.1.4.1.20408.4.1.1.2'), ('1.3.6.1.2.1.1.1.0', rfc1902.OctetString('my system')) ) if errorIndication: print('Notification not sent: %s' % errorIndication) </PRE> </TD></TR></TABLE> <P> The following code sends SNMP v2c INFORM message over SNMPv3: <UL> <LI>using SNMP v3 <LI>with user 'usr-md5-des', auth: MD5, priv 3DES <LI>over IPv4/UDP <LI>send INFORM notification <LI>with TRAP ID 'warmStart' specified as a string OID <LI>include managed object information 1.3.6.1.2.1.1.5.0 = 'system name' specified as an OID-value pair </UL> </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> from pysnmp.entity.rfc3413.oneliner import ntforg from pysnmp.proto import rfc1902 ntfOrg = ntforg.NotificationOriginator() errorIndication = ntfOrg.sendNotification( ntforg.UsmUserData('usr-md5-des', 'authkey1', 'privkey1'), ntforg.UdpTransportTarget(('localhost', 162)), 'inform', '1.3.6.1.6.3.1.1.5.2', ('1.3.6.1.2.1.1.5.0', rfc1902.OctetString('system name')) ) if errorIndication: print('Notification not sent: %s' % errorIndication) </PRE> </TD></TR></TABLE> <A NAME="ASYNCH-ONELINER-APPS"></A> <H4> 2.1.2 Asynchronous One-line Applications </H4> <P> Asynchronous API to oneliner Applications is actually a foundation for <A HREF="#SYNCH-ONELINER-APPS">Synchronous</A> version, so they're very similar. This Asynchronous API is useful for purposes such as running multiple, possibly different, SNMP Applications at the same time or handling other activities inside user's program while SNMP Application is waiting for input/output. </P> <A NAME="AsynCommandGenerator"></A> <H4> 2.1.2.1 Asynchronous Command Generator </H4> <P> All Command Generator Applications are implemented within a single class: </P> <DL> <DT>class <STRONG>AsynCommandGenerator</STRONG>([<STRONG>snmpEngine</STRONG>])</DT> <DD> <P> Create an asynchronous SNMP Command Generator object. </P> <P> Although instantiation of this class is cheap, in the course of its further use, SNMP engine configuration is built and maintained though methods invocation. Therefore it is advised to keep and reuse CommandGenerator instance (or <STRONG>snmpEngine</STRONG> instance if passed as an initializer) for as long as possible within user applicatin. </P> </DD> </DL> <P> Methods of the <STRONG>AsynCommandGenerator</STRONG> class instances implement specific request types. These methods are similar to those described in the <A HREF="#CommandGenerator">CommandGenerator</A> class section except that asynchronous interface uses a callback function for delivering responses. </P> <A NAME="AsynCommandGenerator.asyncGetCmd"></A> <DL> <DT><STRONG>getCmd</STRONG>( <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>varNames</STRONG>, (<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>), <STRONG>lookupNames=False</STRONG>, <STRONG>lookupValues=False</STRONG> )</DT> <DD> <P> Prepare SNMP GET request to be dispatched. Return the <STRONG>sendRequestHandle</STRONG> value. </P> <P> The <STRONG>cbFun</STRONG> parameter is a reference to a callable object (such as a Python function) having the following signature: </P> <DL> <DT><STRONG>cbFun</STRONG>( <STRONG>sendRequestHandle</STRONG>, <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG>, <STRONG>errorIndex</STRONG>, <STRONG>varBinds</STRONG>, <STRONG>cbCtx</STRONG> )</DT> <DD> <P> Where <STRONG>sendRequestHandle</STRONG> is an integer value used for matching response to request. Its counterpart is returned on request submission by the <STRONG>getCmd</STRONG> method. </P> <P> The <STRONG>cbCtx</STRONG> parameter is a reference to the <STRONG>cbCtx</STRONG> object being passed to <STRONG>getCmd</STRONG> method. Its purpose is to carry opaque application's state from request through response methods. </P> <P> The <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG>, <STRONG>errorIndex</STRONG> and <STRONG>varBinds</STRONG> parameters have the same meaning as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method. </P> </DD> </DL> <P> The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and <STRONG>lookupValues</STRONG> parameters have the same meaning as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method except that <STRONG>varNames</STRONG> is passed as a sequence, not as individual Managed Objects Instances names. </P> <P> The <STRONG>getCmd</STRONG> method returns unique <STRONG>sendRequestHandle</STRONG> integer value used for matching subsequent response to this request. </P> </DD> </DL> <P> The following code performs multiple, simultaneous SNMP GET operations for multiple Managed Objects Instances to a single Agent. Authentication information used in this example are the same for all targets. So the GET operation is performed: <UL> <LI>using SNMP v2c <LI>with SNMPv2c community 'public' <LI>over IPv4/UDP <LI>against an Agent listening at 127.0.0.1 <LI>for the SNMPv2-MIB::sysDescr.0, SNMPv2-MIB::sysLocation.0 and SNMPv2-MIB::sysName.0 objects </UL> </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> from pysnmp.entity.rfc3413.oneliner import cmdgen def cbFun(sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds, cbCtx): if errorIndication: print(errorIndication) return if errorStatus: print('%s at %s' % \ (errorStatus.prettyPrint(), errorIndex and varBinds[int(errorIndex)-1] or '?') ) return for oid, val in varBinds: if val is None: print(oid.prettyPrint()) else: print('%s = %s' % (oid.prettyPrint(), val.prettyPrint())) cmdGen = cmdgen.AsynCommandGenerator() for varName in ( cmdgen.MibVariable('SNMPv2-MIB', 'sysDescr', 0), cmdgen.MibVariable('SNMPv2-MIB', 'sysLocation', 0), cmdgen.MibVariable('SNMPv2-MIB', 'sysName', 0) ): cmdGen.getCmd( cmdgen.CommunityData('public'), cmdgen.UdpTransportTarget(('127.0.0.1', 161)), (varName,), (cbFun, None) ) cmdGen.snmpEngine.transportDispatcher.runDispatcher() </PRE> </TABLE> <P> It is trivial to modify the above code to make it using different SNMP versions, credentials and query different Managed Objects Instances per each target. </P> <P> All queries are made in parallel, so with default timeout and retries settings, the above code will terminate in 6 seconds regardless of Agents avialability and responsiveness. </P> <A NAME="AsynCommandGenerator.asyncSetCmd"></A> <DL> <DT><STRONG>setCmd</STRONG>( <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>varBinds</STRONG>, (<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>), <STRONG>lookupNames=False</STRONG>, <STRONG>lookupValues=False</STRONG> )</DT> <DD> <P> Prepare SNMP SET request to be dispatched. Return the <STRONG>sendRequestHandle</STRONG> value. </P> <P> The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and <STRONG>lookupValues</STRONG> parameters have the same meaning as in <A HREF="#AsynCommandGenerator.setCmd">setCmd</A>. </P> <P> The <STRONG>cbFun</STRONG> and <STRONG>cbCtx</STRONG> parameters have the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd"> AsynCommandGenerator.getCmd</A> method. </P> </DD> </DL> <A NAME="AsynCommandGenerator.asyncNextCmd"></A> <DL> <DT><STRONG>nextCmd</STRONG>( <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>varNames</STRONG>, (<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>), <STRONG>lookupNames=False</STRONG>, <STRONG>lookupValues=False</STRONG> )</DT> <DD> <P> Prepare SNMP GETNEXT request to be dispatched. Return the <STRONG>sendRequestHandle</STRONG> value. </P> <P> The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and <STRONG>lookupValues</STRONG> parameters have the same meaning as in <A HREF="#CommandGenerator.nextCmd">nextCmd</A> method except that <STRONG>varNames</STRONG> is passed as a sequence, not as individual Managed Objects Instances names. </P> <P> The <STRONG>cbFun</STRONG> and <STRONG>cbCtx</STRONG> parameters have the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd"> AsynCommandGenerator.getCmd</A> method. Appliction can indicate to GETNEXT SNMP Application that it is no more interested in further information from Agent and wishes to stop by returning True from the <STRONG>cbFun</STRONG>. Otherwise it should return False. </P> <P> The <STRONG>varNames</STRONG> parameter has the same meaning as in <A HREF="#CommandGenerator.nextCmd">CommandGenerator.nextCmd</A> method except that here it is passed in as a tuple. </P> </DD> </DL> <P> The following code performs multiple, simultaneous SNMP GETNEXT operations against distinct Agents identified by their transport addresses. Authentication information and queried Managed Objects Instances used in this example are the same for all targets. So the GETNEXT operation is performed: <UL> <LI>using SNMP v3 <LI>with SNMPv3 with user 'usr-md5-des', MD5 auth and DES privacy protocols <LI>over IPv4/UDP <LI>against Agents listening at 127.0.0.1, 192.168.1.1, 10.40.1.1 (port 161) <LI>for the SNMPv2-MIB::system subtree </UL> </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> from pysnmp.entity.rfc3413.oneliner import cmdgen def cbFun(sendRequestHandle, errorIndication, \ errorStatus, errorIndex, varBindTable, cbCtx): if errorIndication: print(errorIndication) return if errorStatus: print('%s at %s' % \ (errorStatus.prettyPrint(), errorIndex and varBindTable[-1][int(errorIndex)-1] or '?') ) return for varBindRow in varBindTable: for oid, val in varBindRow: if val is None: return # stop table retrieval else: print('%s = %s' % (oid.prettyPrint(), val.prettyPrint())) return True # continue table retrieval cmdGen = cmdgen.AsynCommandGenerator() for transportTarget in ( cmdgen.UdpTransportTarget(('127.0.0.1', 161)), cmdgen.UdpTransportTarget(('192.168.1.1', 161)), cmdgen.UdpTransportTarget(('10.40.1.1', 161)) ): cmdGen.nextCmd( cmdgen.UsmUserData('usr-md5-des', 'authkey1', 'privkey1'), transportTarget, ( cmdgen.MibVariable('SNMPv2-MIB', 'system'), ), (cbFun, None) ) cmdGen.snmpEngine.transportDispatcher.runDispatcher() </PRE> </TABLE> <A NAME="AsynCommandGenerator.asyncBulkCmd"></A> <DL> <DT><STRONG>bulkCmd</STRONG>( <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>nonRepeaters</STRONG>, <STRONG>maxRepetitions</STRONG>, <STRONG>varNames</STRONG>, (<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>), <STRONG>lookupNames=False</STRONG>, <STRONG>lookupValues=False</STRONG> )</DT> <DD> <P> Prepare SNMP GETBULK request to be dispatched. Return the <STRONG>sendRequestHandle</STRONG> value. </P> <P> The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>nonRepeaters</STRONG>, <STRONG>maxRepetitions</STRONG> <STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and <STRONG>lookupValues</STRONG> parameters have the same meaning as in <A HREF="#CommandGenerator.bulkCmd">bulkCmd</A> method except that <STRONG>varNames</STRONG> is passed as a sequence, not as individual Managed Objects Instances names. </P> <P> The <STRONG>cbFun</STRONG> and <STRONG>cbCtx</STRONG> parameters have the same meaning as in <A HREF="#AsynCommandGenerator.asyncNextCmd"> AsynCommandGenerator.nextCmd</A> method. </P> </DD> </DL> <P> After one or more requests have been submitted by calling one or more of the methods above, Transport Dispatcher must be invoked to get SNMP engine running. This is done by calling: </P> <DL> <DT><STRONG> asynCommandGenerator.snmpEngine.transportDispatcher.runDispatcher </STRONG> ()</DT> <DD> <P> Where <STRONG>asynCommandGenerator</STRONG> is <STRONG>AsynCommandGenerator</STRONG> class instance. </P> </DD> </DL> <P> The <STRONG>runDispatcher</STRONG>() method terminates when no pending requests left for running Applications. </P> <A NAME="AsynNotificationOriginator"></A> <H4> 2.1.2.2 Asynchronous Notification Originator </H4> <P> The Notification Originator Application is implemented within a single class: </P> <DL> <DT>class <STRONG>AsynNotificationOriginator</STRONG>([<STRONG>snmpContext</STRONG>])</DT> <DD> <P> Create an asynchronous SNMP Notification Originator object. </P> </DD> </DL> <P> The only method of <STRONG>AsynNotificationOriginator</STRONG> class is similar to that described in the <A HREF="#NotificationOriginator"> NotificationOriginator</A> class section except that asynchronous interface uses a callback function for delivery confirmation when confirmed notification are used. </P> <A NAME="AsynNotificationOriginator.asyncSendNotification"></A> <DL> <DT><STRONG>sendNotification</STRONG>( <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>, <STRONG>notifyType</STRONG>, <STRONG>notificationType</STRONG>, <STRONG>varBinds</STRONG>, (<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>) )</DT> <DD> <P> Prepare SNMP TRAP or INFORM notification to be dispatched. Return the <STRONG>sendRequestHandle</STRONG> value. </P> <P> The <STRONG>cbFun</STRONG> parameter is a reference to a callable object (such as Python function) that takes the following parameters: </P> <DL> <DT><STRONG>cbFun</STRONG>( <STRONG>sendRequestHandle</STRONG>, <STRONG>errorIndication</STRONG>, <STRONG>cbCtx</STRONG> )</DT> <DD> <P> Where the <STRONG>sendRequestHandle</STRONG>, <STRONG>errorIndication</STRONG> and <STRONG>cbCtx</STRONG> parameters have the same meaning as in callback function in <A HREF="#AsynCommandGenerator.asyncGetCmd">AsynCommandGenerator.getCmd</A> method. </P> </DD> </DL> <P> The <STRONG>cbCtx</STRONG> parameter has the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd">AsynCommandGenerator.getCmd</A> method. </P> <P> The <STRONG>notifyType</STRONG>, <STRONG>notificationType</STRONG> and <STRONG>varBinds</STRONG> parameters have the same meaning as in <A HREF="#NotificationOriginator.sendNotification"> NotificationOriginator.sendNotification</A> method except that here it is passed in as a tuple. </P> <P> The <STRONG>sendNotification</STRONG> method returns unique <STRONG>sendRequestHandle</STRONG> integer value used for matching subsequent delivery confirmation response to arbitrary notification. </P> </DD> </DL> <P> After one or more notifications have been submitted by calling the <STRONG>sendNotification</STRONG> method, Transport Dispatcher must be invoked to get SNMP engine running. This is done by calling: </P> <DL> <DT><STRONG> asynNotificationOriginator.snmpEngine.transportDispatcher.runDispatcher </STRONG> ()</DT> <DD> <P> Where <STRONG>asynNotificationOriginator</STRONG> is <STRONG>AsynNotificationOriginator</STRONG> class instance. </P> </DD> </DL> <P> The <STRONG>runDispatcher</STRONG>() method terminates when no unconfirmed notifications left for running Applications. </P> <P> The following code sends multiple, simultaneous SNMP INFORM messages to multiple Managers. Authentication information used in this example is the same for all targets. <UL> <LI>using SNMP v2c <LI>with SNMPv2c community 'public' <LI>over IPv4/UDP <LI>against Managers listening at 127.0.0.1, 127.0.0.2, 127.0.0.3 (port 162) </UL> </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> from pysnmp.entity.rfc3413.oneliner import ntforg from pysnmp.proto import rfc1902 def cbFun(sendRequestHandle, errorIndication, cbCtx): if errorIndication: print(errorIndication) else: print('INFORM %s delivered' % sendRequestHandle) ntfOrg = ntforg.AsynNotificationOriginator() for target in ( ntforg.UdpTransportTarget(('127.0.0.1', 162)), ntforg.UdpTransportTarget(('127.0.0.2', 162)), ntforg.UdpTransportTarget(('127.0.0.3', 162)) ): ntfOrg.sendNotification( ntforg.CommunityData('public'), target, 'inform', ntforg.MibVariable('SNMPv2-MIB', 'coldStart'), ( ('1.3.6.1.2.1.1.5.0', rfc1902.OctetString('system name')), ), (cbFun, None) ) ntfOrg.snmpEngine.transportDispatcher.runDispatcher() </PRE> </TD></TR></TABLE> <P> The above script terminates as all queries are either acknowledged or timed out. With default timeout and retries settings, this will happen in no longer than 6 seconds regardless of Managers avialability and responsiveness. </P> <A NAME="SECURITY-CONFIGURATION"></A> <H4> 2.1.3 Security configuration </H4> <P> Calls to oneliner Applications API require Security Parameters and Transport configuration objects as input parameters. These classes serve as convenience shortcuts to SNMP engine configuration facilities and for keeping persistent authentication/transport configuration between SNMP engine calls. </P> <P> Security Parameters object is Security Model specific. <STRONG>UsmUserData</STRONG> class serves SNMPv3 User-Based Security Model configuration, while <STRONG>CommunityData</STRONG> class is used for Community-Based Security Model of SNMPv1/SNMPv2c. </P> <A NAME="UsmUserData"></A> <DL> <DT>class <STRONG>UsmUserData</STRONG>( <STRONG>securityName</STRONG>, <STRONG>authKey=''</STRONG>, <STRONG>privKey=''</STRONG>, <STRONG>authProtocol=usmNoAuthProtocol</STRONG>, <STRONG>privProtocol=usmNoPrivProtocol</STRONG> )</DT> <DD> <P> Create an object holding User-Based Security Model specific configuration parameters. </P> <P> Mandatory <STRONG>securityName</STRONG> parameter is SNMPv3 USM username passed in as a string. </P> <P> Optional <STRONG>authKey</STRONG> parameter is a secret key (string typed) used within USM for SNMP PDU authorization. Setting it to a non-empty value implies MD5-based PDU authentication (<STRONG>usmHMACMD5AuthProtocol</STRONG>) to take effect. Default hashing method may be changed by means of further <STRONG>authProtocol</STRONG> parameter. </P> <P> Optional <STRONG>privKey</STRONG> parameter is a secret key (string typed) used within USM for SNMP PDU encryption. Setting it to a non-empty value implies MD5-based PDU authentication (<STRONG>usmHMACMD5AuthProtocol</STRONG>) and DES-based encryption (<STRONG>usmDESPrivProtocol</STRONG>) to take effect. Default hashing and/or encryption methods may be changed by means of further <STRONG>authProtocol</STRONG> and/or <STRONG>privProtocol</STRONG> parameters. </P> <P> Optional <STRONG>authProtocol</STRONG> parameter may be used to specify non-default hash function algorithm. Possible values include: </P> <UL> <LI><STRONG>usmHMACMD5AuthProtocol</STRONG> -- MD5-based authentication protocol <LI><STRONG>usmHMACSHAAuthProtocol</STRONG> -- SHA-based authentication protocol <LI><STRONG>usmNoAuthProtocol</STRONG> -- no authentication to use </UL> <P> Optional <STRONG>privProtocol</STRONG> parameter may be used to specify non-default ciphering algorithm. Possible values include: </P> <P> <UL> <LI><STRONG>usmDESPrivProtocol</STRONG> -- DES-based encryption protocol <LI><STRONG>usmAesCfb128Protocol</STRONG> -- AES128-based encryption protocol (<A HREF="http://www.ietf.org/rfc/rfc3826.txt">RFC3826</A>) <LI><STRONG>usm3DESEDEPrivProtocol</STRONG> -- triple DES-based encryption protocol (<A HREF="http://www.snmp.com/protocol/eso.shtml">Extended Security Options</A>) <LI><STRONG>usmAesCfb192Protocol</STRONG> -- AES192-based encryption protocol (<A HREF="http://www.snmp.com/protocol/eso.shtml">Extended Security Options</A>) <LI><STRONG>usmAesCfb256Protocol</STRONG> -- AES256-based encryption protocol (<A HREF="http://www.snmp.com/protocol/eso.shtml">Extended Security Options</A>) <LI><STRONG>usmNoPrivProtocol</STRONG> -- no encryption to use </UL> <P> All these symbols are defined in <STRONG>pysnmp.entity.rfc3413.oneliner.cmdgen</STRONG> module. </P> </DD> </DL> <A NAME="CommunityData"></A> <DL> <DT>class <STRONG>CommunityData</STRONG>( <STRONG>communityName</STRONG>, <STRONG>mpModel=1</STRONG> )</DT> <DD> <P> Create an object holding Community-Based Security Model specific configuration parameters. </P> <P> Mandatory <STRONG>communityName</STRONG> parameter is SNMPv1/SNMPv2c Community name passed as a string. </P> <P> Optional <STRONG>mpModel</STRONG> parameter indicates whether SNMPv2c (mpModel=1, default) or SNMPv1 (mpModel=0) protocol should be used. </P> </DD> </DL> <A NAME="TRANSPORT-CONFIGURATION"></A> <H4> 2.1.4 Transport configuration </H4> <P> Transport configuration object is Transport domain specific. <STRONG>UdpTransportTarget</STRONG> class represents a remote network endpoint of a UDP-over-IPv4 transport. </P> <A NAME="UdpTransportTarget"></A> <DL> <DT>class <STRONG>UdpTransportTarget</STRONG>( <STRONG>transportAddr</STRONG>, <STRONG>timeout=1</STRONG>, <STRONG>retries=5</STRONG> )</DT> <DD> <P> Create an object representing a network path connecting two SNMP entities through a UDP/IPv4 socket. </P> <P> Mandatory <STRONG>transportAddr</STRONG> parameter indicates remote address in form of a tuple of <STRONG>FQDN</STRONG>, <STRONG>port</STRONG> where <STRONG>FQDN</STRONG> is a string representing either hostname or IPv4 address in quad-dotted form, <STRONG>port</STRONG> is an integer. </P> <P> Optional <STRONG>timeout</STRONG> and <STRONG>retries</STRONG> parameters may be used to modify default response timeout (1 second) and number of succesive request retries (5 times). </P> </DD> </DL> <A NAME="Udp6TransportTarget"></A> <DL> <DT>class <STRONG>Udp6TransportTarget</STRONG>( <STRONG>transportAddr</STRONG>, <STRONG>timeout=1</STRONG>, <STRONG>retries=5</STRONG> )</DT> <DD> <P> Create an object representing a network path connecting two SNMP entities through a UDP/IPv6 socket. </P> <P> Mandatory <STRONG>transportAddr</STRONG> parameter indicates remote address in form of a tuple of <STRONG>FQDN</STRONG>, <STRONG>port</STRONG> where <STRONG>FQDN</STRONG> is a string representing either hostname or IPv6 address in semicolon-separated form, <STRONG>port</STRONG> is an integer. </P> <P> Optional <STRONG>timeout</STRONG> and <STRONG>retries</STRONG> parameters may be used to modify default response timeout (1 second) and number of succesive request retries (5 times). </P> </DD> </DL> <A NAME="MANAGED-OBJECT-NAME-VALUE"></A> <H4> 2.2 Managed Objects names and values </H4> <A NAME="OIDVAL-IMPL"> On the protocol level, a Managed Object Instance is represented by a pair of Name and Value items collectively called a <STRONG>Variable-Binding</STRONG>. In PySNMP oneliner API, a Managed Object Instance is represented by a two-component sequence of two objects -- one represents Managed Object Name or Managed Object Instance Name, and the other - Managed Object Instance Value. The types of these objects may vary, details follow. </P> <A NAME="OID-IMPL"></A> <H4> 2.2.1 Managed Objects Names </H4> <P> Managed Object or Managed Object Instance Name is an instance of <STRONG>ObjectName</STRONG> class which is derived from PyASN1 <A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A>. In most cases, PySNMP oneliner API will automatically create an instance of <STRONG>ObjectName</STRONG> class from its initialization value which can be: </P> <ul> <li>a plain string of dot-separated numbers, e.g. '1.3.6.1.2.1.1.1.0' <li>a tuple of integers e.g., (1, 3, 6, 1, 2, 1, 1, 1, 0) <li>an instance of <A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A> class or its derivative such as <STRONG>ObjectName</STRONG> </ul> <A NAME="MibVariable"></A> <P> In order to make use of additional information related to Managed Objects, such as their human-friendly representation, associated value type, description of intended use and other details contained in MIBs, the <STRONG>MibVariable</STRONG> class instances may be used interchangeably instead of <STRONG>ObjectName</STRONG> objects. </P> <DL> <DT>class <STRONG>MibVariable</STRONG>( <STRONG>varName</STRONG> )</DT> <DD> <P> Create an object representing a varying amount of Managed Object Name information. At the bare minimum <STRONG>MibVariable</STRONG> object will only hold an OBJECT IDENTIFIER that identifies particular Managed Object. However more information on Managed Object may be gathered by PySNMP during the course of SNMP request processing. All the extra information comes through a lookup at a MIB where particular Managed Object is specified. </P> <P> The mandatory <STRONG>varName</STRONG> argument must hold a valid initializer for <A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A> kind of objects. </P> </DD> <P>or</P> <DT>class <STRONG>MibVariable</STRONG>( <STRONG>mibName</STRONG>, <STRONG>symName</STRONG>, *<STRONG>indices</STRONG> )</DT> <DD> <P> Create an object potentially representing all MIB information on particular Managed Object. By the moment of instantiation no additional information is acquired, but during the later stages of SNMP request processing, PySNMP will attempt to lookup additional information at the MIB named <STRONG>mibName</STRONG> for the object registered there under name <STRONG>symName</STRONG>. </P> <P> If requested MIB or symbol can not be found, the <STRONG>PySnmpError</STRONG> exception will be thrown. </P> <P> The mandatory <STRONG>mibName</STRONG> and <STRONG>symName</STRONG> arguments refer to the names under which particular Managed Object is specified in the MIB (e.g. 'IF-MIB' and 'ifTable' respectively). Both parameters are Python strings. </P> <P> The optional <STRONG>indices</STRONG> sequence semantics depend on the type of MIB Object refered by <STRONG>mibName</STRONG> and <STRONG>symName</STRONG> parameters. </P> <UL> <LI>For <STRONG>MibTableColumn</STRONG> objects <STRONG>indices</STRONG> are a sequence of Conceptual Table Instance ID in a human-friendly form (e.g. "127.0.0.1"-indexed element of a IP-MIB::ipAdEntAddr column) <LI>For <STRONG>MibScalar</STRONG> objects <STRONG>indices</STRONG> are interpreted as an sub-OBJECT IDENTIFIER </UL> </DD> </DL> <P> Methods of the <STRONG>MibVariable</STRONG> objects are as follows: </P> <A NAME="MibVariable.getMibSymbol"></A> <DL> <DT><STRONG>getMibSymbol</STRONG>( )</DT> <DD> <P> Return a sequence of <STRONG>mibName</STRONG>, <STRONG>symName</STRONG> and <STRONG>indices</STRONG> identifying arbitrary Managed Object. </P> </DD> <A NAME="MibVariable.getOid"></A> <DT><STRONG>getOid</STRONG>( )</DT> <DD> <P> Return Managed Object Name in form of <A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A> object. </P> </DD> <A NAME="MibVariable.getMibNode"></A> <DT><STRONG>getMibNode</STRONG>( )</DT> <DD> <P> Return MIB information in form of a <A HREF="#DATA-MODEL-MANAGED-OBJECTS">Managed Object</A> identified by this particular name. </P> </DD> <A NAME="MibVariable.isFullyResolved"></A> <DT><STRONG>isFullyResolved</STRONG>( )</DT> <DD> <P> Return <STRONG>True</STRONG> if MIB lookup for initial initializers was successful and complete MIB information is available. </P> </DD> </DL> <A NAME="VAL-IMPL"></A> <H4> 2.2.2 Managed Objects Values </H4> <P> Managed Object Instance Value is an instance of some <A HREF="http://pyasn1.sf.net">PyASN1</A> class or its SNMP-specific derivative. The latter case reflects SNMP-specific <A HREF="#ASN1">ASN.1</A> sub-type. </P> <P> PySNMP implementation of SNMPv3 architecture always exposes, <A HREF="#SMI">SMIv2</A> definitions for Managed Objects are always used regardless of the underlying SNMP protocol version being talked with a peer. For instance, an SNMPv3 Manager will always report SMIv2 types even when working to SNMPv1 Agent (which is SMIv1-compliant). </P> <P> The list of Managed Object Instance Value classes follows. </P> <A NAME="INTEGER-IMPL"></A> <DL> <DT>class <STRONG>Integer</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>Integer</STRONG> object. The <STRONG>value</STRONG> parameter should be an integer value. Instances of this class mimic basic properties of a Python integer. SMIv2 Integer class is derived from PyASN1 <A HREF="http://pyasn1.sourceforge.net/#1.1.3">Integer</A>. </P> </DD> </DL> <A NAME="INTEGER32-IMPL"></A> <DL> <DT>class <STRONG>Integer32</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>Integer32</STRONG> object. This object is similar to <A HREF="#INTEGER-IMPL">Integer</A> class instance. </P> </DD> </DL> <A NAME="OBJECTIDENTIFIER-IMPL"></A> <DL> <DT>class <STRONG>OctetIdentifier</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>OctetIdentifier</STRONG> object. The <STRONG>value</STRONG> parameter could be a tuple of integer sub-IDs or a human-friendly string form like ".1.3.6.1.3.1". SMIv2 OctetString class is derived from PyASN1 <A HREF="http://pyasn1.sourceforge.net/#1.1.8">OctetIdentifier</A>. </P> </DD> </DL> <A NAME="OCTETSTRING-IMPL"></A> <DL> <DT>class <STRONG>OctetString</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>OctetString</STRONG> object. The <STRONG>value</STRONG> parameter should be a string value. Instances of this class mimic basic properties of a Python string. SMIv2 OctetString class is derived from PyASN1 <A HREF="http://pyasn1.sourceforge.net/#1.1.7">OctetString</A>. </P> </DD> </DL> <A NAME="IPADDRESS-IMPL"></A> <DL> <DT>class <STRONG>IpAddress</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>IpAddress</STRONG> object. The <STRONG>value</STRONG> parameter should be an IP address expressed in quad-dotted notation (e.g. "127.0.0.1"). SMIv2 IpAddress class is derived from PyASN1 <A HREF="http://pyasn1.sourceforge.net/#1.1.7">OctetString</A>. </P> </DD> </DL> <A NAME="COUNTER32-IMPL"></A> <DL> <DT>class <STRONG>Counter32</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>Counter32</STRONG> object. Besides different value constraints, this object is similar to <A HREF="#INTEGER-IMPL">Integer</A> class instance. </P> </DD> </DL> <A NAME="GAUGE32-IMPL"></A> <DL> <DT>class <STRONG>Gauge32</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>Gauge32</STRONG> object. Besides different value constraints, this object is similar to <A HREF="#INTEGER-IMPL">Integer</A> class instance. </P> </DD> </DL> <A NAME="UNSIGNED32-IMPL"></A> <DL> <DT>class <STRONG>Unsigned32</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>Unsigned32</STRONG> object. Besides different value constraints, this object is similar to <A HREF="#INTEGER-IMPL">Integer</A> class instance. </P> </DD> </DL> <A NAME="TIMETICKS-IMPL"></A> <DL> <DT>class <STRONG>TimeTicks</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>TimeTicks</STRONG> object. Besides different value constraints, this object is similar to <A HREF="#INTEGER-IMPL">Integer</A> class instance. </P> </DD> </DL> <A NAME="OPAQUE-IMPL"></A> <DL> <DT>class <STRONG>Opaque</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>Opaque</STRONG> object. This object is similar to <A HREF="#OCTETSTRING-IMPL">OctetString</A> class instance. </P> </DD> </DL> <A NAME="COUNTER64-IMPL"></A> <DL> <DT>class <STRONG>Counter64</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>Counter64</STRONG> object. Besides different value constraints, this object is similar to <A HREF="#INTEGER-IMPL">Integer</A> class instance. </P> </DD> </DL> <A NAME="BITS-IMPL"></A> <DL> <DT>class <STRONG>Bits</STRONG>( <STRONG>value</STRONG> )</DT> <DD> <P> Create a SMIv2 <STRONG>Bits</STRONG> object. The <STRONG>value</STRONG> parameter should be sequence of names of bits raised to one. Unmentioned bits default to zero. The Bits class is derived from PyASN1 <A HREF="http://pyasn1.sourceforge.net/#1.1.7">OctetString</A>. </P> </DD> </DL> <A NAME="TEXTUAL-CONVENTION-AS-A-TYPE"></A> <P> All the above types are directly used by SNMP protocol and can be exchanged between user application and PySNMP in the course of SNMP engine operations through PySNMP APIs. However, by SNMP design, some additional information on specific Managed Objects Instances value ranges and human-friendly representation can be carried by MIBs in form of <STRONG>TEXTUAL-CONVENTION</STRONG> SMI constructs. PySNMP implements this feature in form of <STRONG>TextualConvention</STRONG> class which is actually a derivative of one of the above Managed Objects Instance Value classes so objects of these classes can be used interchangeably in all PySNMP APIs. </P> <P> For more information on SNMP Managed Value objects properties, refer to their base classes in <A HREF="http://pyasn1.sf.net">PyASN1</A> documentation. </P> <A NAME="MIB-SERVICES"></A> <H4> 2.3 MIB services </H4> <P> PySNMP supports both Manager and Agent-side operations on <A HREF="#MANAGED-OBJECTS">Managed Objects</A>, including MIB lookup and custom Managed Objects implementation. </P> <P> Managed Objects, <A HREF="#DATA-MODEL-MANAGED-OBJECTS">implemented in Python code</A>, is the basis for PySNMP MIB services. Managed Objects are collected into a pool and then managed by a <A HREF="#MIB-BUILDER">MIB builder</A>. Both Manager and Agent applications deal with their Managed Objects through role-specific <A HREF="#MibViewController">MIB view</A> and <A HREF="#MibInstrumentationController">MIB instrumentation</A>. The same set of Managed Objects could serve both Manager and Agent purposes within a single SNMP entity. </P> <A NAME="DATA-MODEL-MANAGED-OBJECTS"></A> <H4> 2.3.1 Data model for Managed Objects </H4> <P> In PySNMP, <A HREF="#MANAGED-OBJECTS">Managed Objects</A> specified in MIBs take shape of Python objects that implement various kinds of <A HREF="#SMI">SMIv2</A> definitions. Managed Objects specified in a <A HREF="#MIB">MIB</A> file translate in a one-to-one fashion into Python modules. </P> <P> Automated conversion of MIB text files into Python modules can be done through the use of smidump tool of <A HREF="http://www.ibr.cs.tu-bs.de/projects/libsmi/">libsmi</A> package and "<STRONG>build-pysnmp-mib</STRONG>" script shipped with PySNMP. </P> <P> The <STRONG>pysnmp.smi.mibs.SNMPv2-SMI</STRONG> module implements the following classes: </P> <A NAME="MibScalar"></A> <DL> <DT>class <STRONG>MibScalar</STRONG>( <STRONG>name</STRONG>, <STRONG>syntax</STRONG> )</DT> <DD> <P> A representation of a scalar Managed Object specification identified by <STRONG>name</STRONG> with associated value of type <STRONG>syntax</STRONG>. Objects of this kind never hold actual values, rather they serve the following purposes: <UL> <LI>Logically bind Managed Object Name with Value <LI>Specify value type (including TEXTUAL-CONVENTION-based constraints) <LI>Provide human-friendly Managed Object name and value representation </UL> </P> <A NAME="MANAGED-OBJECT-NAME"></A> <P> The <STRONG>name</STRONG> parameter represents an <A HREF="#OID">Object Identifier</A> which can be expressed as either a tuple of integers or tuple-like <A HREF="#OID-IMPL">Object Identifier</A> class instance. </P> <P> The <STRONG>syntax</STRONG> parameter represents Managed Object Instance <A HREF="#VAL-IMPL">value type</A>. </P> </DD> </DL> <P> The <STRONG>MibScalar</STRONG> class implements the following methods: </P> <A NAME="MibScalar.getName"></A> <DL> <DT><STRONG>getName</STRONG>()</DT> <DD> <P> Return the <STRONG>name</STRONG> initializer an <A HREF="http://pyasn1.sourceforge.net/#1.1.8">OctetIdentifier</A> object. </P> </DD> </DL> <A NAME="MibScalar.getSyntax"></A> <DL> <DT><STRONG>getSyntax</STRONG>()</DT> <DD> <P> Return the <STRONG>syntax</STRONG> initializer which is a <A HREF="#VAL-IMPL">PyASN1 object</A> including its <A HREF="#TEXTUAL-CONVENTION-AS-A-TYPE">TEXTUAL-CONVENTION</A> derivative. The <STRONG>syntax</STRONG> object does not carry any value, it denotes an acceptable type specifier and may be used for cloning compliant objects for building SNMP messages or pretty printing concrete values. </P> </DD> </DL> <A NAME="MibScalar.getUnits"></A> <DL> <DT><STRONG>getUnits</STRONG>()</DT> <DD> <P> Return value units in form of a Python string. This is mostly used for pretty printing things like "10 seconds", not just "10". </P> </DD> </DL> <A NAME="MibScalar.getDescription"></A> <DL> <DT><STRONG>getDescription</STRONG>()</DT> <DD> <P> Return a textual, human-readable description of the Managed Object semantics, meaning, uses and restrictions. Since these descriptions may be quite large, they are not loaded into memory by default. This setting can be altered through a property of <A HREF="#MibBuilder">MibBuilder</A>. </P> </DD> </DL> <A NAME="MibScalarInstance"></A> <DL> <DT>class <STRONG>MibScalarInstance</STRONG>( <STRONG>name</STRONG>, <STRONG>syntax</STRONG> )</DT> <DD> <P> A representation of scalar Managed Object Instance or <A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> element with <STRONG>name</STRONG> and associated value carried by the <STRONG>syntax</STRONG> object. This class is a subclass of <A HREF="#MibScalar">MibScalar</A> but, unlike <STRONG>MibScalar</STRONG>, it represents existing Managed Object holding a value. </P> <P> The <STRONG>name</STRONG> of Managed Object Instance is a concatination of <STRONG>name</STRONG> of a Managed Object and instance identifier. For scalar Managed Objects, instance identifier is always a single zero (0,). For <A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> elements instance identifier is a concatination of table indices. </P> <P> The <STRONG>name</STRONG> and <STRONG>syntax</STRONG> parameters have the same meaning as in <A HREF="#MibScalar">MibScalar</A> class. </P> </DD> </DL> <A NAME="MibTableColumn"></A> <DL> <DT>class <STRONG>MibTableColumn</STRONG>( <STRONG>name</STRONG>, <STRONG>syntax</STRONG> )</DT> <DD> <P> A representation of <A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> Column specification with <STRONG>name</STRONG> and associated value of type <STRONG>syntax</STRONG>. This class is a subclass of <A HREF="#MibScalar">MibScalar</A>. </P> <P> The <STRONG>name</STRONG> parameter has the same meaning as in <A HREF="#MibScalar">MibScalar</A> class. </P> <P> The <STRONG>syntax</STRONG> parameter represents <A HREF="#MANAGED-OBJECT-SYNTAX">type</A> of the value associated with columnar Managed Object. </P> </DD> </DL> <P> The <STRONG>MibTableColumn</STRONG> class implements the following methods: </P> <A NAME="MibTableColumn.setProtoInstance"></A> <DL> <DT><STRONG>setProtoInstance</STRONG>( <STRONG>instanceClass</STRONG> )</DT> <DD> <P> Configure <STRONG>MibTableColumn</STRONG> object to instantiate <STRONG>instanceClass</STRONG> when creating Columnar Objects. By default, <A HREF="#MibScalarInstance">MibScalarInstance</A> is instantiated. </P> </DD> </DL> <A NAME="MibTableRow"></A> <DL> <DT>class <STRONG>MibTableRow</STRONG>( <STRONG>name</STRONG> )</DT> <DD> <P> A representation of a <A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> Row specification with <STRONG>name</STRONG>. This class is a subclass of <A HREF="#MibScalar">MibScalar</A> although it can't have any associated value. </P> <P> The <STRONG>name</STRONG> parameter has the same meaning as in <A HREF="#MibScalar">MibScalar</A> class. </P> </DD> </DL> <P> The <STRONG>MibTableRow</STRONG> class implements the following methods: </P> <A NAME="MibTableRow.getInstIdFromIndices"></A> <DL> <DT><STRONG>getInstIdFromIndices</STRONG>( <STRONG>*indices</STRONG> )</DT> <DD> <P> Compute and return <A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> Column instance identifier from <STRONG>*indices</STRONG> using MIB Table Index definition. </P> <P> Types of <STRONG>*indices</STRONG> must coerce into Table Index syntax. </P> </DD> </DL> <A NAME="MibTableRow.getIndicesFromInstId"></A> <DL> <DT><STRONG>getIndicesFromInstId</STRONG>( <STRONG>instanceId</STRONG> )</DT> <DD> <P> Compute and return a tuple of <A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> Index values from Column instance identifier <STRONG>instanceId</STRONG> using MIB Table Index definition. </P> <P> The number of types of returned index values depend on MIB Table definition. </P> </DD> </DL> <A NAME="MibTable"></A> <DL> <DT>class <STRONG>MibTable</STRONG>( <STRONG>name</STRONG> )</DT> <DD> <P> Represents <A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> specification with <STRONG>name</STRONG>. This class is a subclass of <A HREF="#MibScalar">MibScalar</A> although it can't have any associated value. </P> <P> The <STRONG>name</STRONG> parameter has the same meaning as in <A HREF="#MibScalar">MibScalar</A> class. </P> </DD> </DL> <P> The following examples explain how MIB text could be expressed in terms of PySNMP SMI data model. First example is on a scalar: </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> myManagedObject = MibScalar((1, 3, 6, 1, 4, 1, 20408, 2, 1), OctetString()).setMaxAccess("readonly") </PRE> </TD></TR></TABLE> <P> Managed Object Instance can be put into a stand-alone PySNMP SMI module or be implemented inside Agent application. Managed Object Instance will be associated with its parent Managed Object, by the <A HREF="#MIB-BUILDER">MIB building part of PySNMP</A>, on the basis of their names relation. </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> myManagedObjectInstance = MibScalarInstance(myManagedObject.getName() + (0,), myManagedObject.getSyntax().clone('my string')) </PRE> </TD></TR></TABLE> <P> Let's consider SNMP Conceptual Table created in an "MY-MIB.py" file: </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> myTable = MibTable((1, 3, 6, 1, 4, 1, 20408, 2, 1)) myTableEntry = MibTableRow(myTable.getName() + (1,)).setIndexNames( (0, "MY-MIB", "myTableIndex") ) myTableIndex = MibTableColumn(myTableEntry.getName() + (1,), Integer()) myTableValue = MibTableColumn(myTableEntry.getName() + (2,), OctetString()) </PRE> </TD></TR></TABLE> <P> Populate Managed Objects table with Managed Objects Instance in the first column. </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> myTableValueInstance = MibScalarInstance(myTableValue.getName() + (1,), myTableValue.getSyntax().clone('my value')) </PRE> </TD></TR></TABLE> <P> For more real-life cases, refer to modules in <B>pysnmp.smi.mibs</B> sub-package. </P> <A NAME="MIB-BUILDER"></A> <H4> 2.3.2 MIB builder </H4> <P> The pythonized MIB modules are then managed by the <STRONG>MibBuilder</STRONG> class from <STRONG>pysnmp.smi.builder</STRONG> module. </P> <A NAME="MibBuilder"></A> <DL> <DT>class <STRONG>MibBuilder</STRONG>()</DT> <DD> <P> Create MIB modules loader/evaluator/indexer. </P> </DD> </DL> <A NAME="MibBuilder.loadModules"></A> <DL> <DT><STRONG>loadModules</STRONG>( <STRONG>*modNames</STRONG> )</DT> <DD> <P> Locate in search path and evaluate each of <STRONG>*modNames</STRONG> through Python <STRONG>execfile</STRONG>() passing a reference to <STRONG>MibBuilder</STRONG> class instance to module's global scope. Evaluating modules might register their objects at <STRONG>MibBuilder</STRONG> through <A HREF="#MibBuilder.exportSymbols">exportSymbols</A>() call. </P> <P> MIB builder would then create an in-memory index of registered MIB objects by MIB names. </P> <P> Search path is managed by the <STRONG>getMibPath()</STRONG> and <STRONG>setMibPath()</STRONG> methods. </P> <P> The <STRONG>loadModules</STRONG> method may be further invoked recursively on dependent MIB modules import. </P> </DD> </DL> <A NAME="MibBuilder.unloadModules"></A> <DL> <DT><STRONG>unloadModules</STRONG>( <STRONG>*modNames</STRONG> )</DT> <DD> <P> Drop all references to Python objects previously created through calling <STRONG>loadModules</STRONG>() method against [here optional] <STRONG>*modNames</STRONG>. This method would invoke <A HREF="#MibBuilder.unexportSymbols">unexportSymbols</A>() against MIB symbols previously registered under each of <STRONG>*modNames</STRONG>. </P> <P> Missing <STRONG>*modNames</STRONG> implies all currently loaded modules. </P> </DD> </DL> <A NAME="MibBuilder.importSymbols"></A> <DL> <DT><STRONG>importSymbols</STRONG>( <STRONG>modName</STRONG>, <STRONG>*symNames</STRONG> )</DT> <DD> <P> Return a tuple of <STRONG>Managed Objects</STRONG> looked up by their MIB names <STRONG>*symNames</STRONG>. <STRONG>Managed Objects</STRONG> returned in tuple are position-bound to <STRONG>*symNames</STRONG> parameters. </P> <P> If MIB module <STRONG>modName</STRONG> is not yet loaded, the <A HREF="#MibBuilder.importSymbols">importSymbols</A>() method would be invoked implicitly. </P> </DD> </DL> <A NAME="MibBuilder.exportSymbols"></A> <DL> <DT><STRONG>exportSymbols</STRONG>( <STRONG>modName</STRONG>, <STRONG>*anonymousSyms</STRONG>, <STRONG>**namedSyms</STRONG> )</DT> <DD> <P> Register Managed Objects <STRONG>*anonymousSyms</STRONG> and/or <STRONG>**namedSyms</STRONG> at <STRONG>MibBuilder</STRONG> within MIB module <STRONG>modName</STRONG> scope. </P> <P> Managed Objects defined in MIB are always named. These are exported using <STRONG>**namedSyms</STRONG> parameter(s). Managed Objects Instances don't have to have MIB names, unless Application wants to access Managed Objects Instances by MIB name, so these may be exported through <STRONG>*anonymousSyms</STRONG>. </P> </DD> </DL> <A NAME="MibBuilder.unexportSymbols"></A> <DL> <DT><STRONG>unexportSymbols</STRONG>( <STRONG>modName</STRONG>, <STRONG>*symNames</STRONG> )</DT> <DD> <P> Drop all references to Python objects previously registered under <STRONG>*symNames</STRONG> within <STRONG>modName</STRONG> through <A HREF="#MibBuilder.exportSymbols">exportSymbols</A>() call. </P> <P> Missing <STRONG>*symNames</STRONG> implies all symbols currently registered within <STRONG>modName</STRONG> module. </P> </DD> </DL> <P> In the following example MIB builder will be created, MIB modules loaded up and Managed Object definition looked up by symbolic name: </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> >>> from pysnmp.smi import builder >>> >>> # create MIB builder ... mibBuilder = builder.MibBuilder().loadModules('SNMPv2-MIB', 'IF-MIB') >>> >>> # get Managed Object definition by symbol name ... mibNode, = mibBuilder.importSymbols('SNMPv2-MIB', 'sysDescr') >>> print(mibNode.getName()) (1, 3, 6, 1, 2, 1, 1, 1) >>> print(repr(mibNode.getSyntax())) DisplayString('') >>> </PRE> </TD></TR></TABLE> </P> <A NAME="MIB-VIEW-CONTROLLER"></A> <H4> 2.3.3 MIB view controller </H4> <P> The following facilities are intended for Manager-side access to MIB definitions. The <STRONG>pysnmp.smi.view</STRONG> module contains the following items: </P> <A NAME="MibViewController"></A> <DL> <DT>class <STRONG>MibViewController</STRONG>(<STRONG>mibBuilder</STRONG>)</DT> <DD> <P> The <STRONG>MibViewController</STRONG> class instance tackles <A HREF="#DATA-MODEL-MANAGED-OBJECTS">Managed Objects</A>, constructed by <A HREF="#MibBuilder">MibBuilder</A>, for their properties and provide efficient/ordered access to Managed Objects properties. Most important of these are OID names and labels. </P> <P> The <STRONG>mibBuilder</STRONG> argument is an instance of <A HREF="#MibBuilder">MibBuilder</A> class. </P> </DD> </DL> <P> The <STRONG>MibViewController</STRONG> class implements the following methods: </P> <A NAME="MibViewController.getNodeName"></A> <DL> <DT><STRONG>getNodeName</STRONG>(<STRONG>name</STRONG>)</DT> <A NAME="MIB-VIEW-MANAGED-OBJECT-NAME"></A> <DD> <P> The <STRONG>name</STRONG> parameter is <A HREF="#MANAGED-OBJECTS">Managed Object</A> name. It can be either a tuple representing sub-<A HREF="#OID">OID</A>s or <A HREF="#OID-IMPL">Object Identifier</A> class instance. Sub-OIDs can be a mix of integers and string labels. For example, the following are valid values of <STRONG>name</STRONG>: </P> <UL> <LI> (1, 3, 6, 1) <LI> ('iso', 'org', 'dod', 'internet') <LI> ('iso', 2, 'dod', 1) <LI> pysnmp.proto.rfc1902.ObjectIdentifier("1.3.6.1") </UL> </P> <P> The <STRONG>getNodeName</STRONG> method returns a tuple of (<STRONG>oid</STRONG>, <STRONG>label</STRONG>, <STRONG>suffix</STRONG>) where: <UL> <LI>The <STRONG>oid</STRONG> and <STRONG>label</STRONG> are tuples of sub-OIDs of best (longest) matched Managed Object in integer and label forms respectively. <LI>The <STRONG>suffix</STRONG> parameter is the unmatched, trailing part of original <STRONG>name</STRONG> parameter. <P> If a Managed Object is looked up with <STRONG>getNodeName</STRONG> method and an exact match occured, <STRONG>suffix</STRONG> would be an empty tuple. </P> <P> If <STRONG>suffix</STRONG> is not empty, it indicates either an index part of <A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> instance name (which can be further parsed into index values by <A HREF="#MibTableRow.getInstIdFromIndices">MibTableRow class methods</A>) or a partial Managed Object name match. </P> <P>In order to distinguish MIB Table element match from a failure, see if closest matched Managed Object <STRONG>oid</STRONG> (MIB symbol <STRONG>label</STRONG>[-1]) is an instance of <A HREF="#MibTableColumn">MibTableColumn</A> class. </P> <P> If even partial match fails, the <STRONG>SmiError</STRONG> exception is raised. </P> </UL> </P> </UL> </P> </DD> </DL> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> >>> from pysnmp.smi import builder, view >>> >>> mibBuilder = builder.MibBuilder().loadModules('SNMPv2-MIB') >>> mibViewController = view.MibViewController(mibBuilder) >>> >>> oid, label, suffix = mibViewController.getNodeName( (1,3,6,1,2,'mib-2',1,'sysDescr') ) >>> print(oid) (1, 3, 6, 1, 2, 1, 1, 1) >>> print(label) ('iso', 'org', 'dod', 'internet', 'mgmt', 'mib-2', 'system', 'sysDescr') >>> print(suffix) () </PRE> </TD></TR></TABLE> </P> <A NAME="MibViewController.getNextNodeName"></A> <DL> <DT><STRONG>getNextNodeName</STRONG>( <STRONG>name</STRONG>, <STRONG>modName</STRONG>='' )</DT> <DD> <P> The <STRONG>getNextNodeName</STRONG> method works the same as <A HREF="#MibViewController.getNodeName">getNodeName</A> but it deals with Managed Object whose name appears to be next to the <STRONG>name</STRONG> given on input. </P> <P> The <STRONG>modName</STRONG> parameter is MIB module name as seen by <A HREF="#MibBuilder">MibBuilder</A>. Use this parameter to restrict by-<STRONG>name</STRONG> to particular MIB module's scope. </P> </DD> </DL> <A NAME="MibViewController.getFirstNodeName"></A> <DL> <DT><STRONG>getFirstNodeName</STRONG>(<STRONG>modName</STRONG>='')</DT> <DD> <P> The <STRONG>getFirstNodeName</STRONG> method works the same as <A HREF="#MibViewController.getNodeName">getNodeName</A> but it returns Managed Object whose name appears to be the first among others within MIB module <STRONG>modName</STRONG>. </P> <P> If no <STRONG>modName</STRONG> is given, the whole OID namespace is assumed. </P> </DD> </DL> <A NAME="MibViewController.getNodeLocation"></A> <DL> <DT><STRONG>getNodeLocation</STRONG>(<STRONG>name</STRONG>)</DT> <DD> <P> The <STRONG>getNodeLocation</STRONG> method returns MIB location of Managed Object by OID <STRONG>name</STRONG> as a tuple of (<STRONG>modName</STRONG>, <STRONG>mibName</STRONG>, <STRONG>suffix</STRONG>). </P> <P> <P> The <STRONG>modName</STRONG> and <STRONG>mibName</STRONG> parameters are as used in <A HREF="#MibBuilder">MibBuilder</A> interface. The <STRONG>suffix</STRONG> parameter is as described in <A HREF="#MIB-VIEW-MANAGED-OBJECT-NAME">getNodeName</A>() method. </P> </DD> </DL> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> >>> from pysnmp.smi import builder, view >>> >>> mibBuilder = builder.MibBuilder().loadModules('SNMPv2-MIB') >>> mibViewController = view.MibViewController(mibBuilder) >>> >>> modName, symName, suffix = mibViewController.getNodeLocation( (1,3,6,1,2,1,1,1,123) ) >>> print(modName) SNMPv2-MIB >>> print(symName) sysDescr >>> print(suffix) (123,) </PRE> </TD></TR></TABLE> </P> <A NAME="IMPLEMENTING-MANAGED-OBJECTS-INSTANCES"></A> <H4> 2.3.4 Implementing Managed Objects Instances </H4> <P> The following chapter explains SNMP Agent-controlled Managed Object Instances to real-life objects mapping. </P> <P> SNMP defines four types of operations on Managed Objects Instances. For scalars, these are: <UL> <LI>Get Managed Object Instance value (though SNMP GET request) <LI>Modify Managed Object Instance value (though SNMP SET request) </UL> </P> <P> Conceptual Tables additionaly support: </P> <P> <UL> <LI>Table row creation (through SNMP SET against a special-purpose <B>RowStatus</B> column instance) <LI>Table row removal (similary, through SNMP SET against <B>RowStatus</B> column instance) </UL> </P> <P> PySNMP Managed Objects Instances are implemented by the <A HREF="#MibScalarInstance">MibScalarInstance</A> objects while a value associated with Managed Object Instance is represented by its <B>syntax</B> initialization parameter. </P> <P> There are two distinct approaches to Managed Objects Instances implementation in PySNMP. The first one is simpler to use but it only works for relatively static Managed Objects. The other is universal but it is more complex to deal with. </P> <A NAME="ASSOCIATED-VALUE-GATEWAYING"></A> <H4> 2.3.4.1 Associated value gatewaying </H4> <P> This method only works for scalars and static tables (meaning no row creation and deletion is performed through SNMP). Also, it is not safe with this method to modify dependent values though a single request as failed modification won't roll back others in the bulk. </P> <P> Whenever SNMP Agent receives read or modification request against arbitrary Managed Object Instance, it ends up <B>clone</B>()'ing <B>syntax</B> parameter of <A HREF="#MibScalarInstance">MibScalarInstance</A> object. Read queries (e.g. GET/GETNEXT/GETBULK) trigger <B>clone</B> method invocation without passing it new value, while new value will be fed to the <B>clone</B> method on modification request. </P> <P> This value-based gatewaying method works by listening on the <B>clone</B>() method of <B>MibScalarInstance</B> associated value thus fetching current or applying new state of some outer system represented by arbitrary Managed Object Instance. </P> <P> Consider SMI-to-filesystem gateway for example, where a Managed Object Instance would represent particular file contents. File contents would be solely dependent on SNMP updates. </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> class MyFile(OctetString): def clone(self, value=None): if value is not None: # SNMP SET open('/tmp/myfile', 'w').write(value) # SNMP S/GET* return OctetString.clone(self, open('/tmp/myfile', 'r').read()) mibBuilder.exportSymbols( 'MYFILE-MIB', MibScalarInstance((1, 3, 6, 1, 4, 1, 20408, 1), MyFile()) ) </PRE> </TD></TR></TABLE> </P> <P> A variation of this through-value SMI gatewaying method would be for a third-party system to keep Managed Object Instance value synchronized with system's current state. Take file size monitor for instance -- the following code would be run periodically to measure most recent file size and re-build its SMI projection: </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> myManagedObjectInstance = MibScalarInstance( (1, 3, 6, 1, 4, 1, 20408, 1), Integer(os.stat('/var/adm/messages')[6]) ) mibBuilder.exportSymbols( 'FILESIZE-MIB', myManagedObjectInstance=myManagedObjectInstance ) </PRE> </TD></TR></TABLE> <A NAME="TAPPING-ON-MANAGEMENT-INSTRUM"></A> <H4> 2.3.4.2 Tapping on Management Instrumentation API </H4> <P> This is a generic SMI Managed Objects Instances to real-life objects mapping method. It works for scalars and tables of any origin, though, programming with it involves customization of PySNMP SMI base classes what adds up to usage complexity. </P> <P> A single SNMP request may invoke an operation on multiple Managed Objects Instances. In SNMP design, it must either succeed on all Managed Objects Instances or be rolled back and reported as a failure otherwise. </P> <A NAME="MANAGEMENT-INSTRUMENTATION-API"></A> <P> SNMP engine talks to its Managed Objects through a protocol which is comprised from a collection of API methods (further refered to as <B>Management Instrumentation API</B>), implemented by <A HREF="#DATA-MODEL-MANAGED-OBJECTS">Managed Objects classes</A> and a definite sequence of their invocation. Default handlers implemented in Managed Objects classes read/modify/create the <STRONG>syntax</STRONG> parameter, passed on instantiation, to <A HREF="#MibScalarInstance">MibScalarInstance</A> objects for scalars and <A HREF="#MibTableColumn">MibTableColumn</A> for tables. The essence of this Management Instrumentation Tapping technique is to listen on Management Instrumentation API methods for gaining control over particular Managed Object at request processing points. </P> <P> Formal parameters of Management Instrumentation API methods don't make much sense to custom implementation, so they are partially documented here and, in most cases, should be blindly <B>passed down</B> as-is to the overloaded method to not to interfere with behind-the-scene SMI workings. </P> <P> Value read methods implemented by <A HREF="#DATA-MODEL-MANAGED-OBJECTS">Managed Objects</A> and invoked by SNMP engine in response to SNMP GET/GETNEXT/GETBULK requests are: </P> <P> <A NAME="readTest"></A> <DL> <DT><STRONG>readTest</STRONG>( *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>readTest</STRONG> method is invoked by SNMP engine prior to performing actual Managed Object Instance value read to give implementation a chance to ensure that subsequent value read is likely to succeed. </P> </DD> </DL> </P> <P> <A NAME="readGet"></A> <DL> <DT><STRONG>readGet</STRONG>( *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>readGet</STRONG> method is invoked by SNMP engine to fetch Managed Object Instance's value. This method must return a tuple of (<STRONG>name</STRONG>, <STRONG>value</STRONG>) which is returned by overloaded method invocation. Custom implementation may replace the <STRONG>value</STRONG> part by its own version taken from third-party sources. </P> </DD> </DL> </P> <P> <A NAME="readTestNext"></A> <DL> <DT><STRONG>readTestNext</STRONG>( *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>readTestNext</STRONG> method is invoked by SNMP engine prior to performing actual Managed Object Instance value read to give implementation a chance to ensure that subsequent value read is likely to succeed. </P> </DD> </DL> </P> <P> <A NAME="readGetNext"></A> <DL> <DT><STRONG>readGetNext</STRONG>( *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>readGetNext</STRONG> method is invoked by SNMP engine to fetch Managed Object Instance's value. This method must return a tuple of (<STRONG>name</STRONG>, <STRONG>value</STRONG>) which is returned by overloaded method invocation. Custom implementation may replace the <STRONG>value</STRONG> part by its own version taken from third-party sources. </P> </DD> </DL> </P> <P> The following is a re-implementation of file size monitor: </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> class FileWatcherInstance(MibScalarInstance): def readTest(self, name, val, idx, (acFun, acCtx)): MibScalarInstance.readTest(self, name, val, idx, (acFun, acCtx)) try: os.stat('/var/adm/messages') except StandardError, why: raise ResourceUnavailableError(idx=idx, name=name) def readGet(self, name, val, idx, (acFun, acCtx)): name, val = MibScalarInstance.readGet(self, name, val, idx, (acFun, acCtx)) try: return name, val.clone(os.stat('/var/adm/messages')[6]) except StandardError, why: raise ResourceUnavailableError(idx=idx, name=name) mibBuilder.exportSymbols( 'FILESIZE-MIB', FileWatcherInstance((1,3,6,1,4,1,20408,1), Integer()) ) </PRE> </TD></TR></TABLE> <P> Value modification methods implemented by <A HREF="#DATA-MODEL-MANAGED-OBJECTS">Managed Objects</A> and invoked by SNMP engine in response to SNMP SET request: </P> <P> <A NAME="writeTest"></A> <DL> <DT><STRONG>writeTest</STRONG>( <STRONG>name</STRONG>, <STRONG>value</STRONG>, *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>writeTest</STRONG> method is invoked by SNMP engine prior to performing actual Managed Object Instance value modification to give implementation a chance to ensure that subsequent value modification is likely to succeed. </P> <P> Upon successful completion, this method brings Managed Object Instance into a state of pending modification which ends through either calling <A HREF="#writeCleanup">writeCleanup</A>() on success or <A HREF="#writeUndo">writeUndo</A>() on failure. </DD> </DL> </P> <P> <A NAME="writeCommit"></A> <DL> <DT><STRONG>writeCommit</STRONG>( *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>writeCommit</STRONG> method is invoked by SNMP engine by way of request processing in attempt to apply pending <STRONG>value</STRONG>, previously passed to Managed Object Instance through <A HREF="#writeTest">writeTest</A> method. Custom implementation may attempt to apply pending <STRONG>value</STRONG> to a third-party system. </P> </DD> </DL> </P> <P> <A NAME="writeCleanup"></A> <DL> <DT><STRONG>writeCleanup</STRONG>( *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>writeCleanup</STRONG> method is invoked by SNMP engine by way of request processing to bring Managed Object Instance out of pending value modification state. Custom implementation may attempt to bring a third-party system out of value modification state. </P> </DD> </DL> </P> <P> <A NAME="writeUndo"></A> <DL> <DT><STRONG>writeUndo</STRONG>( *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>writeUndo</STRONG> method is invoked by SNMP engine by way of request processing to drop the <STRONG>value</STRONG> applied to Managed Object Instance by the previously called <A HREF="#writeCommit">writeCommit</A>() method and re-assign previous value. This method also brings Managed Object Instance out of pending value modification state. Custom implementation may attempt to bring a third-party system out of value modification state. </P> </DD> </DL> </P> <P> The following is a re-implementation of SMI-to-filesystem binding for file modification: </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> class MyFileInstance(MibScalarInstance): def writeTest(self, name, val, idx, (acFun, acCtx)): MibScalarInstance.writeTest(self, name, val, idx, (acFun, acCtx)) try: open('/tmp/myfile.new', 'w').write(val) except StandardError, why: raise ResourceUnavailableError(idx=idx, name=name) def writeCommit(self, name, val, idx, (acFun, acCtx)): MibScalarInstance.writeCommit(self, name, val, idx, (acFun, acCtx)) try: os.rename('/tmp/myfile', '/tmp/myfile.old') os.rename('/tmp/myfile.new', /tmp/myfile') except StandardError, why: raise ResourceUnavailableError(idx=idx, name=name) def writeCleanup(self, name, val, idx, (acFun, acCtx)): MibScalarInstance.writeCleanup(self, name, val, idx, (acFun, acCtx)) try: os.unlink('/tmp/myfile.old') except StandardError, why: raise ResourceUnavailableError(idx=idx, name=name) def writeUndo(self, name, val, idx, (acFun, acCtx)): MibScalarInstance.writeUndo(self, name, val, idx, (acFun, acCtx)) try: os.rename('/tmp/myfile.old', '/tmp/myfile') except StandardError, why: raise ResourceUnavailableError(idx=idx, name=name) mibBuilder.exportSymbols( 'MYFILE-MIB', MyFileInstance((1,3,6,1,4,1,20408,1), OctetString()) ) </PRE> </TD></TR></TABLE> <P> Table row creation methods implemented by <A HREF="#DATA-MODEL-MANAGED-OBJECTS">Managed Objects</A> and invoked by SNMP engine in response to SNMP SET request against a non-existent or <B>SNMPv2-TC::RowStatus</B> type Table Column Instance (table cell) object: </P> <P> <A NAME="createTest"></A> <DL> <DT><STRONG>createTest</STRONG>( <STRONG>name</STRONG>, <STRONG>value</STRONG>, *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>createTest</STRONG> method is invoked by SNMP engine as a first step of Columnar Instance (e.g. Managed Object Instance) creation to make sure the column instance could be created and optionally supplied value is good. Custom implementation may attempt to create a new object at a third-party system. </P> <P> The <STRONG>name</STRONG> and <STRONG>value</STRONG> parameters hold OID/value pair as arrived in request. </P> <P> Upon successful completion, this method brings Managed Object Instance into a state of pending creation which ends through either calling <A HREF="#createCleanup">createCleanup</A>() on success or <A HREF="#createUndo">createUndo</A>() on failure. </P> </DD> </DL> </P> <P> <A NAME="createCommit"></A> <DL> <DT><STRONG>createCommit</STRONG>( *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>createCommit</STRONG> method is invoked by SNMP engine by way of Columnar Object creation to indicate that newly created Columnar Object has been brough on-line and in attempt to apply [optional] pending <STRONG>value</STRONG>, as passed through <A HREF="#createTest">createTest</A>() method. Custom implementation may bring previously created object on-line at a third-party system. </P> </DD> </DL> </P> <P> <A NAME="createCleanup"></A> <DL> <DT><STRONG>createCleanup</STRONG>( *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>createCleanup</STRONG> method is invoked by SNMP engine by way of Columnar Instance creation to indicate a success. Custom implementation may pass this information to a third-party system. </P> </DD> </DL> </P> <P> <A NAME="createUndo"></A> <DL> <DT><STRONG>createUndo</STRONG>( *<STRONG>args</STRONG> )</DT> <DD> <P> The <STRONG>createUndo</STRONG> method is invoked by SNMP engine by way of Columnar Instance creation to indicate a failure. Custom implementation may destroy previously created object at a third-party system. </P> </DD> </DL> </P> <P> The following is a SMI-to-filesystem binding for file creation: </P> <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD> <PRE> class MyFileInstance(MibScalarInstance): def createTest(self, name, val, idx, (acFun, acCtx)): MibScalarInstance.createTest(self, name, val, idx, (acFun, acCtx)) # Build path to file to create from column index myFileEntry, = mibBuilder.importSymbols('MYFILE-MIB', 'myFileEntry') indices = myFileEntry.getIndicesFromInstId(name[myFileEntry.getName()+1:]) self.__myFile = apply(os.path.join, indices) try: open('%s.new' % self.__myFile, 'w') except StandardError, why: raise ResourceUnavailableError(idx=idx, name=name) def createCommit(self, name, val, idx, (acFun, acCtx)): MibScalarInstance.createCommit(self, name, val, idx, (acFun, acCtx)) try: os.rename(self.__myFile, '%s.old' % self.__myFile) os.rename('%s.new' % self.__myFile, self.__myFile) except StandardError, why: raise ResourceUnavailableError(idx=idx, name=name) def createCleanup(self, name, val, idx, (acFun, acCtx)): MibScalarInstance.createCleanup(self, name, val, idx, (acFun, acCtx)) try: os.unlink('%s.old' % self.__myFile) except StandardError, why: raise ResourceUnavailableError(idx=idx, name=name) def createUndo(self, name, val, idx, (acFun, acCtx)): MibScalarInstance.createUndo(self, name, val, idx, (acFun, acCtx)) try: os.rename('%s.old' % self.__myFile, self.__myFile) except StandardError, why: raise ResourceUnavailableError(idx=idx, name=name) # Register custom Managed Object Instance at Column myFileColumn, = mibBuilder.importSymbols('MYFILE-MIB', 'myFileColumn') myFileColumn.setProtoInstance(MyFileInstance) </PRE> </TD></TR></TABLE> <P> In the above example, it is assumed that there is a MIB module named <STRONG>MYFILE-MIB</STRONG> where <A HREF="#MibTableColumn">a MIB table column</A> named <STRONG>myFileColumn</STRONG> is defined. </P> <HR> <A NAME="APPENDIXIES"></A> <H4> Appendixies </H4> <A NAME="ASN1"> <H4> ASN.1 standard </H4> <P> SNMP relies on Abstract Syntax Notation One (ASN.1) <A HREF="http://www.itu.int/ITU-T/studygroups/com17/languages/index.html"> ITU-T standard </A>. It is actually a family of standards targeting network systems interoperability and protocols development automation. </P> <P> In theory, ASN.1 technology provides a complete solution for protocol development: new protocol could be expressed in terms of data structures described in a specialized formal language. </P> <P> The ASN.1 notation is designed purely for data description. All data structures there are based on a small set of elementary data types, such as INTEGER or SEQUENCE OF some other types. </P> <P> Whenever protocol designer wants to define a more precise, narrow set of valid values for a field, a <STRONG>subtype</STRONG> can be created from a base ASN.1 type or another subtype by tearing up a <STRONG>constraint</STRONG> on various data properties to parent ASN.1 type. For example, a subtype of in INTEGER may allow only arbitrary values of an integer. </P> <P> Another way to create a <STRONG>subtype</STRONG> from existing type is to add or replace ASN.1 <STRONG>tag</STRONG>, which serves like an ID for a type. In this new type has all the same properties of its parent type but is now known under a different name. </P> <P> Once something gets expressed in ASN.1 notation, it could then be automatically translated into a variety of platform-specific implementations. They are often take shape of a program written in some common programming language like C or Python. </P> <P> This is where the major feature of ASN.1 emerges. ASN.1 text could be automatically compiled into a high-quality code, that handles all the nightmares of platform-specifics, virtually for free. This code would handle byte-ordering and value ranges, data structures validations and consistency issues. </P> <P> But the most useful feature is its ability to represent data in a way suitable for transmission over a communication medium. This is called <A HREF="#ASN1-ENCODING">encoding</A> in ASN.1, and also known as <STRONG>concrete or transfer syntax</STRONG> in computer science. </P> <P> SNMP uses these features of ASN.1 for handling Managed Objects and guiding protocol operations. </P> <A NAME="OID"> <H4> Object Identifier </H4> <P> This technique is a simple, unambiguous, decentralized and extensible method of naming anything. It was developed within ASN.1 standard as one of its build-in data types. </P> <P> An Object Identifier consists of a sequence of integers. Each integer in this sequence maps to a node in a tree, so iterating an OID traverses this tree from root to leaf, forming a branch. Nodes in OID tree hold a group of conceptually related objects. Nodes become more specific from root to leaves. Sub-trees, or parts of OID space, often become a courtesy of various organizations and individuals. </P> <P> OIDs are conventionally written as a dot-separated sequence of integers, from left to right as from root to leaves. For example, .1.3.6.1 is an arbitrary OID. </P> <P> For the purpose of making OIDs human-readable, integers in OIDs (AKA sub-OIDs) can be replaced with a textual labels. Consider .org.iso.dod.internet as a labeled version of the previous example. The numeric and labeled OID representations are invariant and may mix within a single OID. </P> <A NAME="ASN1-ENCODING"> <H4> ASN.1 data encoding </H4> <P> For several entities to exchange ASN.1 data items some common transmission protocol is needed. This protocol would have to be able to represent ASN.1 values in a platform-native way. This might require handling hardware and/or software specific issues such as varying integer sizes, byte ordering, character encoding and so on. </P> <P> Besides data representation issues, this communication protocol would have to break up data being transmitted into small chunks. The reason is that most data transmission technologies handle only a few bits in a channel at any moment of time. After buffering and packing up few bits into larger chunks, most link-level protocols still handle information in small grains. Typical measurement is eight bit or octet. </P> <P> For all the reasons mentioned above, ASN.1 family of standards suggests several methods of two-way ASN.1 data conversion protocols. They are sometimes referred to as data <STRONG>encoding</STRONG> or <STRONG>serialization</STRONG>. </P> <P> SNMP uses somewhat restricted flavor of <STRONG>Basic Encoding Rules</STRONG> (BER) for its ASN.1 data serialization purposes. The SNMP-specific restrictions make BER encoding deterministic -- with these restrictions applied, there is a one-to-one mapping between ASN.1 value and octet-stream produced by BER encoder. Determinism in encoding makes it possible for trivial SNMP entities to reduce their SNMP engine implementation to opaque octet-streams manipulations. </P> <HR> </TR></TD></TABLE> </TR></TD></TABLE> </BODY> </HTML>