diff options
Diffstat (limited to 'docs/pysnmp-tutorial.html')
| -rw-r--r-- | docs/pysnmp-tutorial.html | 3806 |
1 files changed, 0 insertions, 3806 deletions
diff --git a/docs/pysnmp-tutorial.html b/docs/pysnmp-tutorial.html deleted file mode 100644 index 42f1edd..0000000 --- a/docs/pysnmp-tutorial.html +++ /dev/null @@ -1,3806 +0,0 @@ -<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> |