diff options
| author | elie <elie> | 2015-09-14 05:39:35 +0000 |
|---|---|---|
| committer | elie <elie> | 2015-09-14 05:39:35 +0000 |
| commit | 8a2ab3c327b5d9128577b56e58bb93db396d59ed (patch) | |
| tree | 982658337a44b1898b97cfd6b302917676f26cba | |
| parent | 2f24177c361ba4d9deba2d7378f84aa96111db80 (diff) | |
| download | pysnmp-8a2ab3c327b5d9128577b56e58bb93db396d59ed.tar.gz | |
documentation reworked and converted to Sphinx (in NumPy style)
37 files changed, 1604 insertions, 3807 deletions
diff --git a/MANIFEST.in b/MANIFEST.in index bcce267..4553703 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,3 @@ include *.txt recursive-include examples *.py -recursive-include docs *.txt *.html *.gif *.conf +recursive-include docs *.txt *.rst *.conf Makefile diff --git a/docs/README.txt b/docs/README.txt new file mode 100644 index 0000000..31e4fad --- /dev/null +++ b/docs/README.txt @@ -0,0 +1,11 @@ +You need Sphinx too build this documentation. Or you can read it in ASCII. ;) + +Better run: + +# pip sphinx + +and once Sphinx is installed on your system, run: + +$ make html + +To build a copy of HTML'ed PySNMP documentation. diff --git a/docs/pysnmp-arch.gif b/docs/pysnmp-arch.gif Binary files differdeleted file mode 100644 index 15ccf9c..0000000 --- a/docs/pysnmp-arch.gif +++ /dev/null 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> diff --git a/docs/source/.static/css/rtdimproved.css b/docs/source/.static/css/rtdimproved.css new file mode 100644 index 0000000..981f84e --- /dev/null +++ b/docs/source/.static/css/rtdimproved.css @@ -0,0 +1,10 @@ +@import url("../pygments.css"); +@import url("theme.css"); + +/* fix horizontal padding to accomodate adsense banners */ +.wy-nav-content { + padding: 1.618em 2.236em; + height: 100%; + /* max-width: 800px; */ + margin: auto; +} diff --git a/docs/source/.templates/analytics.html b/docs/source/.templates/analytics.html new file mode 100644 index 0000000..72b6a40 --- /dev/null +++ b/docs/source/.templates/analytics.html @@ -0,0 +1,10 @@ +<script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-34689015-5', 'auto'); + ga('send', 'pageview'); + +</script> diff --git a/docs/source/.templates/bottom.html b/docs/source/.templates/bottom.html new file mode 100644 index 0000000..377e758 --- /dev/null +++ b/docs/source/.templates/bottom.html @@ -0,0 +1,10 @@ +<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script> +<!-- _pysmi bottom --> +<ins class="adsbygoogle" + style="display:block" + data-ad-client="ca-pub-9731411670727851" + data-ad-slot="5936755463" + data-ad-format="auto"></ins> +<script> +(adsbygoogle = window.adsbygoogle || []).push({}); +</script> diff --git a/docs/source/.templates/layout.html b/docs/source/.templates/layout.html new file mode 100644 index 0000000..0f25e0e --- /dev/null +++ b/docs/source/.templates/layout.html @@ -0,0 +1,185 @@ +{# TEMPLATE VAR SETTINGS #} +{%- set url_root = pathto('', 1) %} +{%- if url_root == '#' %}{% set url_root = '' %}{% endif %} +{%- if not embedded and docstitle %} + {%- set titlesuffix = " — "|safe + docstitle|e %} +{%- else %} + {%- set titlesuffix = "" %} +{%- endif %} + +<!DOCTYPE html> +<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]--> +<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]--> +<head> + <meta charset="utf-8"> + {{ metatags }} + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + {% block htmltitle %} + <title>{{ title|striptags|e }}{{ titlesuffix }}</title> + {% endblock %} + + {# FAVICON #} + {% if favicon %} + <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/> + {% endif %} + + {# CSS #} + + {# OPENSEARCH #} + {% if not embedded %} + {% if use_opensearch %} + <link rel="search" type="application/opensearchdescription+xml" title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}" href="{{ pathto('_static/opensearch.xml', 1) }}"/> + {% endif %} + + {% endif %} + + {# RTD hosts this file, so just load on non RTD builds #} + {% if not READTHEDOCS %} + <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" /> + {% endif %} + + {% for cssfile in css_files %} + <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" /> + {% endfor %} + + {% for cssfile in extra_css_files %} + <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" /> + {% endfor %} + + {%- block linktags %} + {%- if hasdoc('about') %} + <link rel="author" title="{{ _('About these documents') }}" + href="{{ pathto('about') }}"/> + {%- endif %} + {%- if hasdoc('genindex') %} + <link rel="index" title="{{ _('Index') }}" + href="{{ pathto('genindex') }}"/> + {%- endif %} + {%- if hasdoc('search') %} + <link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}"/> + {%- endif %} + {%- if hasdoc('copyright') %} + <link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}"/> + {%- endif %} + <link rel="top" title="{{ docstitle|e }}" href="{{ pathto('index') }}"/> + {%- if parents %} + <link rel="up" title="{{ parents[-1].title|striptags|e }}" href="{{ parents[-1].link|e }}"/> + {%- endif %} + {%- if next %} + <link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}"/> + {%- endif %} + {%- if prev %} + <link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}"/> + {%- endif %} + {%- endblock %} + {%- block extrahead %} {% endblock %} + + {# Keep modernizr in head - http://modernizr.com/docs/#installing #} + <script src="_static/js/modernizr.min.js"></script> + +</head> + +<body class="wy-body-for-nav" role="document"> + + <div class="wy-grid-for-nav"> + + {# SIDE NAV, TOGGLES ON MOBILE #} + <nav data-toggle="wy-nav-shift" class="wy-nav-side"> + <div class="wy-side-nav-search"> + {% block sidebartitle %} + + {% if logo and theme_logo_only %} + <a href="{{ pathto(master_doc) }}"> + {% else %} + <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }} + {% endif %} + + {% if logo %} + {# Not strictly valid HTML, but it's the only way to display/scale it properly, without weird scripting or heaps of work #} + <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" /> + {% endif %} + </a> + + {% include "searchbox.html" %} + + {% endblock %} + </div> + + <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> + {% block menu %} + {% set toctree = toctree(maxdepth=4, collapse=True, includehidden=True) %} + {% if toctree %} + {{ toctree }} + {% else %} + <!-- Local TOC --> + <div class="local-toc">{{ toc }}</div> + {% endif %} + {% endblock %} + </div> + + </nav> + + <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> + + {# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #} + <nav class="wy-nav-top" role="navigation" aria-label="top navigation"> + <i data-toggle="wy-nav-top" class="fa fa-bars"></i> + <a href="{{ pathto(master_doc) }}">{{ project }}</a> + </nav> + + + {# PAGE CONTENT #} + <div class="wy-nav-content"> + <div class="rst-content"> + {% include "breadcrumbs.html" %} + <div role="main" class="document"> + {% include "top.html" %} + {% block body %}{% endblock %} + {% include "bottom.html" %} + {% include "analytics.html" %} + <hr/> + </div> + {% include "footer.html" %} + </div> + </div> + + </section> + + </div> + {% include "versions.html" %} + + {% if not embedded %} + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT:'{{ url_root }}', + VERSION:'{{ release|e }}', + COLLAPSE_INDEX:false, + FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}', + HAS_SOURCE: {{ has_source|lower }} + }; + </script> + {%- for scriptfile in script_files %} + <script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script> + {%- endfor %} + + {% endif %} + + {# RTD hosts this file, so just load on non RTD builds #} + {% if not READTHEDOCS %} + <script type="text/javascript" src="{{ pathto('_static/js/theme.js', 1) }}"></script> + {% endif %} + + {# STICKY NAVIGATION #} + {% if theme_sticky_navigation %} + <script type="text/javascript"> + jQuery(function () { + SphinxRtdTheme.StickyNav.enable(); + }); + </script> + {% endif %} + + {%- block footer %} {% endblock %} + +</body> +</html> diff --git a/docs/source/.templates/top.html b/docs/source/.templates/top.html new file mode 100644 index 0000000..384b5b6 --- /dev/null +++ b/docs/source/.templates/top.html @@ -0,0 +1,11 @@ +<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script> +<!-- _pysmi top --> +<ins class="adsbygoogle" + style="display:block" + data-ad-client="ca-pub-9731411670727851" + data-ad-slot="7553089460" + data-ad-format="auto"></ins> +<script> +(adsbygoogle = window.adsbygoogle || []).push({}); +</script> +<hr/> diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 0000000..b67b1a6 --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1,6 @@ + +Changelog +========= + +.. include:: ../../CHANGES.txt + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..ecabef1 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,314 @@ +# -*- coding: utf-8 -*- +# +# PySNMP documentation build configuration file, created by +# sphinx-quickstart on Sat Jun 27 23:15:54 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import shlex + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'contents' + +# General information about the project. +project = u'PySNMP' +copyright = u'2015, Ilya Etingof <ilya@glas.net>' +author = u'Ilya Etingof <ilya@glas.net>' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '4.3' +# The full version, including alpha/beta/rc tags. +release = '4.3' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +#html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['.static'] + +# Custom CSS theme +html_style = 'css/rtdimproved.css' + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +html_show_sphinx = False + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PySNMPdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'PySNMP.tex', u'PySNMP Documentation', + u'Ilya Etingof \\textless{}ilya@glas.net\\textgreater{}', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'pysnmp', u'PySNMP Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'PySNMP', u'PySNMP Documentation', + author, 'PySNMP', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { 'python': ('https://docs.python.org/', None), + 'pysmi': ('http://pysmi.sf.net/', None) } + +# this merges constructor docstring with class docstring +autoclass_content = 'both' + +# Napoleon settings +napoleon_google_docstring = False +napoleon_numpy_docstring = True +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = True +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = False +napoleon_use_admonition_for_references = False +napoleon_use_ivar = False +napoleon_use_param = False +napoleon_use_rtype = False diff --git a/docs/source/contents.rst b/docs/source/contents.rst new file mode 100644 index 0000000..e17fcc4 --- /dev/null +++ b/docs/source/contents.rst @@ -0,0 +1,114 @@ + +SNMP library for Python +======================= + +.. toctree:: + :maxdepth: 2 + +PySNMP is a cross-platform, pure-`Python <http://www.python.org/>`_ +`SNMP <http://en.wikipedia.org/wiki/Simple_Network_Management_Protocol>`_ +engine implementation. It features fully-functional SNMP engine capable +to act in Agent/Manager/Proxy roles, talking SNMP v1/v2c/v3 protocol +versions over IPv4/IPv6 and other network transports. + +Despite its name, SNMP is not a really simple protocol. For instance its +third version introduces complex and open-ended security framework, +multilingual capabilities, remote configuration and other features. +PySNMP implementation closely follows intricate system details and features +bringing most possible power and flexibility to its users. + +Current PySNMP stable version is 4.3.0. It runs with Python 2.4 through 3.5 +and is recommended for new applications as well as for migration from older, +now obsolete, PySNMP releases. All site documentation and examples are written +for the 4.3.0 and later versions in mind. Older materials are still +available under the obsolete section. + +Besides the libraries, a set of pure-Python command-line tools are shipped +along with the system. Those tools mimic the interface and behaviour of +popular Net-SNMP snmpget/snmpset/snmpwalk utilities. They may be useful +in a cross-platform situations as well as a testing and prototyping +instrument for pysnmp users. + +PySNMP software is free and open-source. It's being distributed under a +liberal BSD-style license. PySNMP development has been initially sponsored +by a `PSF <http://www.python.org/psf/>`_ grant. + +Quick start +----------- + +You already know something about SNMP and have no courage to dive into +this implementation? Try out quick start page! + + .. toctree:: + :maxdepth: 2 + + /quick-start + +Documentation +------------- + +This is so boring to read... Now imagine how boring it was to write this! ;-) + +.. toctree:: + :maxdepth: 2 + + /snmp-overview + /docs/contents + +Examples +-------- + + .. toctree:: + :maxdepth: 2 + + /examples/contents + +Download +-------- + +Best way is usually to + +.. code-block:: bash + + # pip install pysnmp + +If that does not work for you for some reason, you might need to read the +following page. + + .. toctree:: + :maxdepth: 2 + + /download + +FAQ +--- + + .. toctree:: + :maxdepth: 2 + + /faq + +Development +----------- + +We fanatically document all fixes, changes and new features in changelog. +There you could also download the latest unreleased pysnmp tarball +containing the latest fixes and improvements. + + .. toctree:: + :maxdepth: 1 + + /changelog + +Our development plans and new features we consider for eventual implementation +are collected in the following section. + + .. toctree:: + :maxdepth: 2 + + /development + +License +------- + +.. include:: ../../LICENSE.txt diff --git a/docs/source/development.rst b/docs/source/development.rst new file mode 100644 index 0000000..abe9cba --- /dev/null +++ b/docs/source/development.rst @@ -0,0 +1,100 @@ + +Further development +------------------- + +Although PySNMP is already a mature software and it is being used at many +places, the ultimate goal of the project is to implement most of the useful +features that SNMP standards can offer. What follows is a list of most +prominent missing features that PySNMP developers are planning to put their +hands on in the future. + +PySNMP library +++++++++++++++ + +#. Built-in MIB parser. PySNMP uses a data model of its own to work with + information contained in MIB files. To convert ASN.1-based MIB texts + into Python modules, an off-line, third-party tool is employed. As it + turns out, this approach has two major drawback: one is that PySNMP + users may need to pre-process MIB texts to use them with their + PySNMP-based applications. Another is that LibSMI's Python driver + seems to miss some information carried by MIBs. Thus the solution would + be to write another MIB parser and code generator which would produce + PySNMP compliant Python code right from MIB text files all by itself. + + **Done:** see `PySMI project <http://pysmi.sf.net>`_ in conjuction with the latest PySNMP codebase. + +#. Reverse MIB index. The variable-bindings received by the system whilst + in Manager role could be post-processed using the information kept in + MIB files to include human-friendly OIDs names, tables indices and + values representation. However, there is currently no provisioning in + the PySNMP system for locating and loading up MIB files containing + additional information on arbitrary OIDs. So the idea is to maintain + an OID-to-MIB index to let PySNMP load relevant MIB automatically on + demand. + +#. Stream sockets support. Currently, PySNMP transport subsystem only + supports datagram-type network sockets. That covers UDP-over-IPv4 and + UDP-over-IPv6. However, SNMP engine can potentially run over + stream-oriented protocols what would let it support TCP-over-IPv4, + TCP-over-IPv6 and SSL/TSL transports. Neither of these is currently + implemented with PySNMP. + +#. AgentX implementation. We anticipate many uses of this. For instance, + having AgentX protocol support in pure-Python would let us write AgentX + modules in pure-Python and attach them to high-performance Net-SNMP + Agent. Or we could build and maintain a fully-featured, stand-alone + PySNMP-based Agent so that users would write their own AgentX extensions + what would comprise a complete SNMP Agent solution at lesser effort. + +#. A DBMS-based SMI. Currently implemented SMI takes shape of live Python + objects that let user hook up his own handler on any existing Managed + Object Instance. That's flexible and working approach in many cases, + however sometimes, for instance when Management Instrumentation is + inherently DBMS-based, it may be more efficient to move the entire + SMI/MIB subsystem into a database. PySNMP engine would talk to it + through its simple and well defined SMI API. + + +Stand-alone PySNMP-based tools +++++++++++++++++++++++++++++++ + +#. SNMP Proxy Forwarder. That would be a stand-alone, application-level + proxy service supporting all SNMP versions, multiple network transports, + Command and Notification SNMP message types. Its anticipated features + include extensive configuration facilities, fine-graned access + control and logging. + + **Done:** see `SNMP Proxy Forwarder <http://snmpfwd.sf.net>`_. + +#. SNMP Trap Receiver. We see this application as a simple yet flexible + SNMP TRAP collector. It would listen on network sockets of different + types receiving SNMP TRAP/INFORM notifications over any SNMP version + and putting all the details into a database and possibly triggering + external events. + +#. Database backend for SNMP Simulator. We have already built a tool for + simulating SNMP Agents based on a snapshot of their Management + Instrumentation state. Current implementation uses a plain-text file + for keeping and possibly managing the snapshot. Many users of the + Simulator software requested a value variation feature to be supported + so that simulated Agents would look live, not static. We consider this + variation and also dependencies features would be best implemented as + a relational database application. So we are planning to put some more + efforts into the Simulator project as time permits. + + **Done:** since `snmpsim-0.2.4 <http://snmpsim.sf.net>`_ + +If you need some particular feature - please, +`drop us a note <http://pysnmp.sourceforge.net/contact.html>`_ . Once we +see a greater demand in particular area, we would re-arrange our +development resources to meet it sooner. + +You could greater speed up the development of particular feature by +sponsoring it. Please get back to us to discuss details. + +Contributions to the PySNMP source code is greatly appreciated as well. +We require contributed code to run with Python 2.4 through the latest +Python version (which is 3.3 at the time of this writing). Contributed +code will be redistributed under the terms of the same +`license <http://pysnmp.sourceforge.net/license.html>`_ as PySNMP is. + diff --git a/docs/source/docs/contents.rst b/docs/source/docs/contents.rst new file mode 100644 index 0000000..12568a9 --- /dev/null +++ b/docs/source/docs/contents.rst @@ -0,0 +1,62 @@ + +Library reference +================= + +.. toctree:: + :maxdepth: 2 + +As dealing with +many features may overwhelm developers who aim at a quick and trivial task, +PySNMP employs a layered architecture approach where the topmost programming +API tries to be as simple as possible to allow immediate solutions for most +common use cases. For instance it will let you perform SNMP GET/SET/WALK +operations by pasting code snippets from this web-site right into your +Python interactive session. + +.. toctree:: + /docs/v3arch/asyncore/oneliner/contents + +At the basic level, PySNMP offers a complete set of Standard SNMP +Applications to give you maximum flexibility with integration of SNMP +facilities into other applications, building special purpose SNMP Agents, +TRAP collectors, Proxy entities and all kinds of SNMP-related things. + +Many user applications are built within some input/output framework. +PySNMP offers native bindings to some of these framework. + +.. toctree:: +.. /docs/v3arch/asyncore/contents +.. /docs/v3arch/asyncio/contents +.. /docs/v3arch/trollius/contents +.. /docs/v3arch/twisted/contents + +At the other end of the complexity spectrum, PySNMP offers packet-level +ASN.1 data structures that let you build, parse and analyze SNMP messages +travelling over network. This extremely low-level programming interface is +explained by the SNMPv1/v2c example scripts. If your goal is to conduct +experiments on the protocol level or optimize for highest possible +performance - this is a way to go. + +.. toctree:: +.. /docs/v1arch/asyncore/contents + +.. comment:: + MIB support + ----------- + + SNMP suite of standards defines a data model for objects being managed + (known as `SMI <http://en.wikipedia.org/wiki/Structure_of_Management_Information>`_), + it takes shape of `MIB <http://en.wikipedia.org/wiki/Management_information_base>`_ + files semi-formally listing and describing capabilities of a SNMP-managed + system. In PySNMP, MIB files are converted into Python code objects which + could be loaded and executed at run-time by both SNMP Manager (for purposes + of data presentation to human beings) and SNMP Agents (as a gateway to + backend systems like DBMS). + + MIB conversion is handled automatically by `PySMI <http://pysmi.sf.net>`_ + library. Large collection of original MIB files is maintained at + `our MIB repository <http://mibs.snmplabs.com/asn1/>`_ . + + .. toctree:: + .. /docs/smi/contents + diff --git a/docs/source/docs/smi/contents.rst b/docs/source/docs/smi/contents.rst new file mode 100644 index 0000000..0e2ee9f --- /dev/null +++ b/docs/source/docs/smi/contents.rst @@ -0,0 +1,20 @@ + +Oneliner MIB lookup service +=========================== + +PySNMP MIB architecture +======================= + +MIB types and objects +--------------------- + +MIB Builder +----------- + +MIB View Controller +------------------- + +MIB Instrumentation Controller +------------------------------ + + diff --git a/docs/source/docs/smi/mib-notification-types.rst b/docs/source/docs/smi/mib-notification-types.rst new file mode 100644 index 0000000..118c615 --- /dev/null +++ b/docs/source/docs/smi/mib-notification-types.rst @@ -0,0 +1,14 @@ + +MIB notification types +====================== + +ASN.1 macro definition -- NOTIFICATION-TYPE conveys MIB variables to +be gathered and reported in SNMP Notification. The +:py:mod:`~pysnmp.smi.rfc1902` module implements :RFC:`1902#section-2` +macro definiitons. + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.smi.rfc1902.NotificationType + :members: diff --git a/docs/source/docs/smi/mib-variables.rst b/docs/source/docs/smi/mib-variables.rst new file mode 100644 index 0000000..3d6cb4a --- /dev/null +++ b/docs/source/docs/smi/mib-variables.rst @@ -0,0 +1,19 @@ + +MIB Variables +============= + +SNMP MIB variable is identified by an OBJECT IDENTIFIER (OID) and is +accompanied by a value belonging to one of SNMP types (:RFC:`1902#section-2`). +This pair is collectively called a variable-binding in SNMP parlance. + +The :py:mod:`~pysnmp.smi.rfc1902` module implements :RFC:`1902#section-2` +MACRO definiitons. + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.smi.rfc1902.ObjectIdentity + :members: + +.. autoclass:: pysnmp.smi.rfc1902.ObjectType + :members: diff --git a/docs/source/docs/v1arch/asyncore/contents.rst b/docs/source/docs/v1arch/asyncore/contents.rst new file mode 100644 index 0000000..e803a1d --- /dev/null +++ b/docs/source/docs/v1arch/asyncore/contents.rst @@ -0,0 +1,3 @@ +Packet-level SNMP with Asyncore +=============================== + diff --git a/docs/source/docs/v3arch/asyncore/contents.rst b/docs/source/docs/v3arch/asyncore/contents.rst new file mode 100644 index 0000000..b385865 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/contents.rst @@ -0,0 +1,2 @@ +Standard SNMP Apps with Asyncore +================================ diff --git a/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/contents.rst b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/contents.rst new file mode 100644 index 0000000..80966d7 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/contents.rst @@ -0,0 +1,12 @@ + +Synchronous Notification Originator +=================================== + +Functions dscribed in this section return generators that perform +blocking SNMP queries. See :RFC:`3413#section-3.2` for more information +on the Notification Originator Applications. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/agent/ntforg/notification diff --git a/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/notification.rst b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/notification.rst new file mode 100644 index 0000000..b6061ad --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/notification.rst @@ -0,0 +1,8 @@ + +Notification Originator +======================= + +.. toctree:: + :maxdepth: 2 + +.. autofunction:: pysnmp.entity.rfc3413.oneliner.ntforg.sendNotification diff --git a/docs/source/docs/v3arch/asyncore/oneliner/contents.rst b/docs/source/docs/v3arch/asyncore/oneliner/contents.rst new file mode 100644 index 0000000..5bd2df3 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/contents.rst @@ -0,0 +1,95 @@ + +High-level SNMP +=============== + +There are a handful of most basic SNMP Applications defined by RFC3413 and +called Standard Applications. Those implementing Manager side of the system +(:RFC:`3411#section-3.1.3.1`) are Command Generator (initiating GET, SET, +GETNEXT, GETBULK operations) and Notification Receiver (handling arrived +notifications). On Agent side (:RFC:`3411#section-3.1.3.2`) there are +Command Responder (handling GET, SET, GETNEXT, GETBULK operations) and +Notification Originator (issuing TRAP and INFORM notifications). In +PySNMP Standard Applications are implemented on top of SNMPv3 framework. + +There're two kinds of high-level programming interfaces to Standard SNMP +Applications: synchronous and asynchronous. They are similar in terms of +call signatures but differ in behaviour. Synchronous calls block the whole +application till requested operation is finished. Asynchronous interface +breaks its synchronous version apart - at first required data are prepared +and put on the outgoing queue. The the application is free to deal with +other tasks till pending message is sent out (by I/O dispacher) and +response is arrived. At that point a previously supplied callback function +will be invoked and response data will be passed along. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/manager/cmdgen/contents + /docs/v3arch/asyncore/oneliner/agent/ntforg/contents + +The asynchronous version is best suited for massively parallel SNMP +messaging possibly handling other I/O activities in the same time. The +synchronous version is advised to employ for singular and blocking +operations as well as for rapid prototyping. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/manager/cmdgen/async.rst + /docs/v3arch/asyncore/oneliner/agent/ntforg/async.rst + +SNMP security configuration is conveyed to SNMP engine via +:py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityName` +and :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` +classes: + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/security-configuration + +Type of network transport SNMP engine uses along with transport +options is summarized by +:py:class:`~pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget` +and +:py:class:`~pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget` +container classes: + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/transport-configuration + +SNMP engine may serve several instances of the same MIB within +possibly multiple SNMP entities. SNMP context is a method to +unambiguously identify a collection of MIB variables behind +SNMP engine. +See :RFC:`3411#section-3.3.1` for details. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/snmp-context + +MIB variables represent a collection of managed objects, +residing in MIBs. Command Generator applications refer +to MIB variables and their values using +:py:class:`~pysnmp.smi.rfc1902.ObjectType` and +:py:class:`~pysnmp.smi.rfc1902.ObjectIdentity` classes. + +.. toctree:: + :maxdepth: 2 + + /docs/smi/mib-variables + +SNMP Notifications are enumerated and imply including certain +set of MIB variables. +Notification Originator applications refer to MIBs for MIB notifications +that are represented by +:py:class:`~pysnmp.smi.rfc1902.NotificationType` class instances. + +.. toctree:: + :maxdepth: 2 + + /docs/smi/mib-notification-types + diff --git a/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/bulkcmd.rst b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/bulkcmd.rst new file mode 100644 index 0000000..5882ca3 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/bulkcmd.rst @@ -0,0 +1,8 @@ + +GETBULK Command Generator +========================= + +.. toctree:: + :maxdepth: 2 + +.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.bulkCmd diff --git a/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/contents.rst b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/contents.rst new file mode 100644 index 0000000..a72c8da --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/contents.rst @@ -0,0 +1,15 @@ + +Synchronous Command Generator +============================= + +Functions dscribed in this section return generators that perform +blocking SNMP queries. See :RFC:`3413#section-3.1` for more information +on the Command Generator Applications. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/manager/cmdgen/getcmd + /docs/v3arch/asyncore/oneliner/manager/cmdgen/setcmd + /docs/v3arch/asyncore/oneliner/manager/cmdgen/nextcmd + /docs/v3arch/asyncore/oneliner/manager/cmdgen/bulkcmd diff --git a/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/getcmd.rst b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/getcmd.rst new file mode 100644 index 0000000..cf97515 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/getcmd.rst @@ -0,0 +1,8 @@ + +GET Command Generator +===================== + +.. toctree:: + :maxdepth: 2 + +.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.getCmd diff --git a/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/nextcmd.rst b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/nextcmd.rst new file mode 100644 index 0000000..626ff48 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/nextcmd.rst @@ -0,0 +1,8 @@ + +GETNEXT Command Generator +========================= + +.. toctree:: + :maxdepth: 2 + +.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.nextCmd diff --git a/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/setcmd.rst b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/setcmd.rst new file mode 100644 index 0000000..e458c9f --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/setcmd.rst @@ -0,0 +1,8 @@ + +SET Command Generator +===================== + +.. toctree:: + :maxdepth: 2 + +.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.setCmd diff --git a/docs/source/docs/v3arch/asyncore/oneliner/security-configuration.rst b/docs/source/docs/v3arch/asyncore/oneliner/security-configuration.rst new file mode 100644 index 0000000..86bee25 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/security-configuration.rst @@ -0,0 +1,39 @@ + +Security Parameters +=================== + +Calls to oneliner Applications API consume Security Parameters +configuration object on input. The shortcut classes described in +this section convey configuration information to SNMP engine's +Local Configuration Datastore (:RFC:`2271#section-3.4.2`). +Once committed to LCD, SNMP engine saves its configuration for +the lifetime of SNMP engine object. + +Security Parameters object is Security Model specific. +:py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` class +serves SNMPv3 User-Based Security Model configuration, while +:py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData` +class is used for Community-Based Security Model of SNMPv1/SNMPv2c. + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.auth.CommunityData(communityIndex, communityName=None, mpModel=1, contextEngineId=None, contextName='', tag='') + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.auth.UsmUserData(userName, authKey=None, privKey=None, authProtocol=usmNoAuthProtocol, privProtocol=usmNoPrivProtocol, securityEngineId=None) + +Identification of Authentication and Privacy Protocols is done +via constant OIDs: + +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmNoAuthProtocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmHMACMD5AuthProtocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmHMACSHAAuthProtocol + +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmNoPrivProtocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmDESPrivProtocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usm3DESEDEPrivProtocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmAesCfb128Protocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmAesCfb192Protocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmAesCfb256Protocol + + diff --git a/docs/source/docs/v3arch/asyncore/oneliner/snmp-context.rst b/docs/source/docs/v3arch/asyncore/oneliner/snmp-context.rst new file mode 100644 index 0000000..04fb5f1 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/snmp-context.rst @@ -0,0 +1,23 @@ + +SNMP Context +============ + +Calls to oneliner Applications API consume SNMP Context +configuration object on input. The shortcut class described in +this section convey this MIB instance identification information +to SNMP PDU for further communication to peer SNMP engine +(:RFC:`3411#section-4.1`). + +.. note:: + + SNMP context is only defined within SNMPv3 framework. For SNMPv1/v2c + architecture integration :RFC:`2576#section-5.1` introduces + interoperability aid which is available through + :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData`. + + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.ctx.ContextData + diff --git a/docs/source/docs/v3arch/asyncore/oneliner/transport-configuration.rst b/docs/source/docs/v3arch/asyncore/oneliner/transport-configuration.rst new file mode 100644 index 0000000..3aff429 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/transport-configuration.rst @@ -0,0 +1,25 @@ + +Transport configuration +======================= + +Calls to oneliner Applications API consume Transport configuration +object on input. The following shortcut classes convey configuration +information to SNMP engine's Local Configuration Datastore +(:RFC:`2271#section-3.4.2`) as well as to underlying socket API. Once committed +to LCD, SNMP engine saves its configuration for the lifetime of SNMP +engine object. + +Transport configuration is specific to Transport domain - +:py:class:`~pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget` +class represents remote network endpoint of a UDP-over-IPv4 transport, +whereas +:py:class:`~pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget` +is specific to UDP-over-IPv6 communication. + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget + diff --git a/docs/source/docs/v3arch/asynio/contents.rst b/docs/source/docs/v3arch/asynio/contents.rst new file mode 100644 index 0000000..4a416e0 --- /dev/null +++ b/docs/source/docs/v3arch/asynio/contents.rst @@ -0,0 +1,2 @@ +Standard SNMP Apps with Asyncio +=============================== diff --git a/docs/source/docs/v3arch/trollius/contents.rst b/docs/source/docs/v3arch/trollius/contents.rst new file mode 100644 index 0000000..a7e650b --- /dev/null +++ b/docs/source/docs/v3arch/trollius/contents.rst @@ -0,0 +1,2 @@ +Standard SNMP Apps with Trollius +================================ diff --git a/docs/source/docs/v3arch/twisted/contents.rst b/docs/source/docs/v3arch/twisted/contents.rst new file mode 100644 index 0000000..885aac3 --- /dev/null +++ b/docs/source/docs/v3arch/twisted/contents.rst @@ -0,0 +1,2 @@ +Standard SNMP Apps with Twisted +=============================== diff --git a/docs/source/download.rst b/docs/source/download.rst new file mode 100644 index 0000000..44dd72a --- /dev/null +++ b/docs/source/download.rst @@ -0,0 +1,74 @@ +Download PySNMP +=============== + +.. toctree:: + :maxdepth: 2 + +The PySNMP software is provided under terms and conditions of BSD-style +license, and can be freely downloaded from Source Forge +`download servers <http://sourceforge.net/projects/pysnmp/files/>`_ or +`PyPI <http://pypi.python.org/pypi/pysnmp/>`_. + +Please, note that there are frequently release candidate versions (marked rc) +also available for download. These are potentially less stable in terms of +implementation and public interfaces. However they are first to contain +fixes to the issues, discovered in latest stable branch. + +But the simplest way to obtain PySNMP is to run: + +.. code-block:: bash + + $ easy_install pysnmp + +or + +.. code-block:: bash + + $ pip install pysnmp + +Those Python package managers will download PySNMP along with all its +dependencies and install them all on your system. + +In case you do not have the easy_install command on your system but still +would like to use the on-line package installation method, please install +`setuptools <http://pypi.python.org/pypi/setuptools>`_ package by +downloading and running `ez_setup.pz <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_ bootstrap: + +.. code-block:: bash + + # wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py + # python ez_setup.py + +In case you are installing PySNMP on an off-line system, the following +packages need to be downloaded and installed for PySNMP to become +operational: + +* `PyASN1 <http://pypi.python.org/packages/source/p/pyasn1/>`_, + used for handling ASN.1 objects +* `PySNMP <http://pypi.python.org/packages/source/p/pysnmp/>`_, + SNMP engine implementation + +Optional, but recommended: + +* `PyCrypto <http://pypi.python.org/packages/source/p/pycrypto/>`_, + used by SNMPv3 crypto features (Windows users need + `precompiled version <http://www.voidspace.org.uk/python/modules.shtml>`_) +* `PySMI <http://pypi.python.org/packages/source/p/pysmi/>`_ for automatic + MIB download and compilation. That helps visualizing more SNMP objects +* `Ply <http://pypi.python.org/packages/source/p/ply/>`_, parser generator + required by PySMI + +The installation procedure for all the above packages is as follows +(on UNIX-based systems): + +.. code-block:: bash + + $ tar zxf package-X.X.X.tar.gz + $ cd package-X.X.X + # python setup.py install + # cd .. + # rm -rf package-X.X.X + +In case of any issues, please `let us know <http://pysnmp.sourceforge.net/contact.html>`_ so we could try to help out. + + diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 0000000..18ce967 --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,17 @@ + +FAQ +=== + +Here we have an ever-growing list of frequently asked questions regarding +PySNMP usage issues. If you got an issue that you think is worth noting +here, please `drop us a note <http://pysnmp.sourceforge.net/contact.html>`_. + +Keep in mind that some the answers below may not be universally applicable +to any PySNMP revision. + +.. toctree:: + :maxdepth: 2 + :glob: + + /faq/* + diff --git a/docs/source/quick-start.rst b/docs/source/quick-start.rst new file mode 100644 index 0000000..8bcf6bb --- /dev/null +++ b/docs/source/quick-start.rst @@ -0,0 +1,53 @@ + +Quick start +=========== + +.. toctree:: + :maxdepth: 2 + +Once you downloaded and installed PySNMP library on your Linux/Windows/OS-X +system, you should be able to solve the very basic SNMP task right from +your Python prompt - fetch some data from a remote SNMP Agent (you'd need +at least version 4.3.0 to run code from this page). + +Fetch SNMP variable +------------------- + +So just cut&paste the following code right into your Python prompt. The +code will performs SNMP GET operation for a sysDescr.0 object at a +publically available SNMP Agent at **demo.snmplabs.com**: + +.. literalinclude:: /../../examples/v3arch/asyncore/oneliner/manager/cmdgen/get-v1.py + :start-after: """# + :language: python + +:download:`Download</../../examples/v3arch/asyncore/oneliner/manager/cmdgen/get-v1.py>` script. + +If everything works as it should you will get: + +.. code-block:: python + + ... + SNMPv2-MIB::sysDescr."0" = SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m + >>> + +on your console. + +Send SNMP TRAP +-------------- + +To send a trivial TRAP message to your local Notification Receiver +just cut&paste the following code into your interactive Python session: + +.. literalinclude:: /../../examples/v3arch/asyncore/oneliner/agent/ntforg/trap-v2c-with-mib-lookup.py + :start-after: """# + :language: python + +:download:`Download</../../examples/v3arch/asyncore/oneliner/agent/ntforg/trap-v2c-with-mib-lookup.py>` script. + +For more sophisticated examples and uses cases please refer to the examples +and documentation pages. + + + + diff --git a/docs/source/snmp-overview.rst b/docs/source/snmp-overview.rst new file mode 100644 index 0000000..b532f66 --- /dev/null +++ b/docs/source/snmp-overview.rst @@ -0,0 +1,313 @@ + +.. toctree:: + :maxdepth: 2 + +SNMP overview +============= + +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. + +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. + +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 Protocol. + +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 Convention on management information naming +and presentation. + +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 Performance. + +Some of network devices may run on severely limited resources what invokes +another property of a proper network management facility: Low resource +consumption. + +In practice, the latter requirement translates into low CPU cycles and +memory footprint for management software aboard device being managed. + +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 +Security. + +Data passed back and forth through the course of management operations +should be at least authentic and sometimes hidden from possible observers. + +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. + +SNMP management architecture +---------------------------- + +The SNMP management model includes three distinct entities -- Agent, +Manager and Proxy talking to each other over network. + +Agent entity is basically a software running somewhere in a networked +device and having the following distinguishing properties: + +* SNMP protocol support +* Access to managed device's internals + +The latter feature is a source of management information for Agent, as well +as a target for remote control operations. + +Modern SNMP standards suggest splitting Agent functionality on two parts. +Such Agents may run SNMP for local processes called Subagents, which +interface with managed devices internals. Communication between Master +Agent and its Subagents is performed using a simplified version of original +SNMP protocol, known as AgentX, which is designed to run only within a +single host. + +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. + +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. + +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. + +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. + +For representing a group of similar components of a device, such as network +interfaces, Managed Objects can be organized into a so-called conceptual +table. + +Manager talks to Agent by sending it messages of several types. Message +type implies certain action to be taken. For example, GET message instructs +Agent to report back values of Managed Objects whose names are indicated in +message. + +There's also a way for Agent to notify Manager of an event occurred to +Agent. This is done through so-called Trap 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. + +For naming Managed Objects, SNMP uses the concept of Object Identifier. As +an example of Managed Object, +.iso.org.dod.internet.mgmt.mib-2.system.sysName.0 represents human-readable +name of a device where Agent is running. + +Managed Objects values are always instances of ASN.1 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. + +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. + +SNMP standard introduces a set of ASN.1 language constructs (such as ASN.1 +subtypes and MACROs) which is called Structure of Management Information +(SMI). Collections of related Managed Objects described in terms of SMI +comprise Management Information Base (MIB) modules. + +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. + +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 MIB parser support. + +The history of SNMP +------------------- + +First SNMP version dates back to 1988 when a set of IETF RFC's were first +published (`RFC1065 <http://www.ietf.org/rfc/rfc1065.txt>`_ , +`RFC1066 <http://www.ietf.org/rfc/rfc1066.txt>`_ , +`RFC1067 <http://www.ietf.org/rfc/rfc1067.txt>`_ ). +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 +Community String) is extremely easy to eavesdrop and replay, even after +almost 20 years, slightly refined standard ( +`RFC1155 <http://www.ietf.org/rfc/rfc1155.txt>`_ , +`RFC1157 <http://www.ietf.org/rfc/rfc1157.txt>`_ , +`RFC1212 <http://www.ietf.org/rfc/rfc1212.txt>`_ ) +still seems to be the most frequent encounter in modern SNMP devices. + +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 ( +`RFC1902 <http://www.ietf.org/rfc/rfc1902.txt>`_, +`RFC1903 <http://www.ietf.org/rfc/rfc1903.txt>`_, +`RFC1904 <http://www.ietf.org/rfc/rfc1904.txt>`_, +`RFC1905 <http://www.ietf.org/rfc/rfc1905.txt>`_, +`RFC1906 <http://www.ietf.org/rfc/rfc1906.txt>`_, +`RFC1907 <http://www.ietf.org/rfc/rfc1907.txt>`_, +`RFC1908 <http://www.ietf.org/rfc/rfc1908.txt>`_ ). + +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, User Based Security +Model (USM) of SNMPv2u got eventually adopted as one of possibly many +SNMPv3 security models. + +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. + +SNMPv3 system is designed as a framework that consists of a core, known as +Message and PDU Dispatcher, and several abstract subsystems: Message +Processing Subsystem (MP), responsible for SNMP message handling, Transport +Dispatcher, used for carrying over messages, and Security Subsystem, 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. + +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 ( +`RFC3411 <http://www.ietf.org/rfc/rfc3411.txt>`_, +`RFC3412 <http://www.ietf.org/rfc/rfc3412.txt>`_, +`RFC3413 <http://www.ietf.org/rfc/rfc3413.txt>`_, +`RFC3414 <http://www.ietf.org/rfc/rfc3414.txt>`_, +`RFC3415 <http://www.ietf.org/rfc/rfc3415.txt>`_, +`RFC3416 <http://www.ietf.org/rfc/rfc3416.txt>`_, +`RFC3417 <http://www.ietf.org/rfc/rfc3417.txt>`_, +`RFC3418 <http://www.ietf.org/rfc/rfc3418.txt>`_ ). + +PySNMP architecture +------------------- + +PySNMP is a pure-Python SNMP engine implementation. This software deals +with the darkest corners of SNMP specifications all in Python programming +language. + +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. + +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: + +* The most ancient and low-level is SNMPv1/v2c protocol scope. Here + programmer is supposed to build/parse SNMP messages and their payload -- + Protocol Data Unit (PDU), handle protocol-level errors, transport issues + and so on. + + 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. + +* 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. + + This API is much more higher-level than previous; here Programmer would + have to manage two major issues: setting up Local Configuration Datastore + (LCD) 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. + +* 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. + + 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. + +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: + +* 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. + +* 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. + +* 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. + +* 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. + +* 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. + +* 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. + +* 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. + +In most cases user is expected to only deal with the high-level, 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. |
