/usr/share/doc/python-pysnmp4-doc/pysnmp-tutorial.html

<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>

<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 stands for a pure-Python SNMP 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 from 4.1.x and up. Previous
PySNMP versions do not follow the architecture and interfaces described
in this tutorial.
</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 one-liner fashion, for quick and simple prototyping.
</P>
</LI>
</UL>

<P>
The following figure draws major components of PySNMP system along with
standard Applications.
</P>

<P ALIGN=CENTER>
<IMG SRC="pysnmp-arch.gif" USEMAP="#pysnmp-arch" ALT="PySNMP architecture"
BORDER=0>
<MAP ID="pysnmp-arch" NAME="pysnmp-arch">
<!--
<AREA SHAPE ="rect" COORDS ="445,114,602,146" HREF="#HIGH-LEVEL-PDU-API" 
ALT="PDU Management" />
<AREA SHAPE ="rect" COORDS ="479,171,564,206" HREF="#PDU-API" 
ALT="SNMP PDU" />
<AREA SHAPE ="rect" COORDS ="428,58,617,216" HREF="#APPS-API" 
ALT="Applications" />
<AREA SHAPE ="rect" COORDS ="208,124,333,184" HREF="#LCD-API" 
ALT="LCD" />
-->
<AREA SHAPE ="rect" COORDS ="196,16,629,225" HREF="#ONELINER-APPS" 
ALT="One-line Applications" />
<!--
<AREA SHAPE ="rect" COORDS ="18,405,145,464" HREF="#TSP-API" 
ALT="Transport Dispatcher" />
<AREA SHAPE ="rect" COORDS ="240,279,554,342" HREF="#SNMP-ENGINE-API" 
ALT="SNMP Engine" />
-->
</MAP>
</P>

<P>
These standard SNMP applications, such as GET/SET command generators and 
responders or TRAP notificators and receivers, translate into a set of
classes designed by the Visitor pattern. Application classes 
implement concrete SNMP operations in terms of specific PDU handling,
while SNMP Engine class acts as a Visitor. A single SNMP Engine can serve 
many Applications of different types at the same time.
</P>

<P>
One of the design choices of SNMPv3 standard is to use a set of dedicated 
Managed Objects for SNMP engine internal purposes. One reason for that 
design involves making SNMP engine remotely configurable via SNMP.
These internally used Managed Objects 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. Technically, LCD Configurator is a set of 
functions whose names clearly reflect their semantics.
</P>

<P>
SNMP Engine, on the above figure, is a Composite class holding references
to all components of SNMP system. Typical user application has a single
instance of SNMP Engine class possibly shared by many SNMP Applications
of all kinds.
</P>

<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. Dispatcher/Transport classes are designed after
the Visitor pattern -- Transport instances are Dispatcher visitors. 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>

<P>
The rest of components are not normally accessed directly. They're mentioned
here for clarification purposes.
</P>

<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>

<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>

<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>

<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>

<A NAME="ONELINER-APPS"></A>
<H4>
2.1 One-line Applications
</H4>

<P>
As of this writing, one-line Applications currently cover Manager-side 
operations. Agent and Proxy roles could be implemented on top of
native Applications API.
</P>

<P>
There're two kinds of APIs to one-line Applications: synchronous and
asynchronous. Both are implemented within the
<STRONG>pysnmp.entity.rfc3413.oneliner.cmdgen</STRONG> module.
</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>

<P>
All Command Generator Applications are implemented within a single class:
</P>

<A NAME="CommandGenerator"></A>
<DL>
<DT>class <STRONG>CommandGenerator</STRONG>([<STRONG>snmpEngine</STRONG>])</DT>
<DD>
<P>
Create a SNMP Command Generator object.
</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>
)</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 tuple 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>
</DD>
</DL>

<P>
The following code performs SNMP GET operation over SNMPv1:
</P>

<TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
<PRE>
>>> from pysnmp.entity.rfc3413.oneliner import cmdgen
>>> errorIndication, errorStatus, errorIndex, varBinds = cmdgen.CommandGenerator().getCmd(
... cmdgen.CommunityData('my-agent', 'public', 0),
... cmdgen.UdpTransportTarget(('localhost', 161)),
... '1.3.6.1.2.1.1.1.0',
... '1.3.6.1.2.1.1.2.0'
... )
>>> print(errorIndication)
None
>>> print(errorStatus)
0
>>> print(varBinds)
[(ObjectName(1.3.6.1.2.1.1.1.0), OctetString('Linux saturn 2.6.37.6-smp 
    #2 SMP Sat Apr 9 23:39:07 CDT 2011 i686')), 
(ObjectName(1.3.6.1.2.1.1.2.0), ObjectIdentifier(1.3.6.1.4.1.8072.3.2.10))]
</PRE>
</TD></TR></TABLE>

<A NAME="CommandGenerator.setCmd"></A>
<DL>
<DT><STRONG>setCmd</STRONG>(
<STRONG>authData</STRONG>,
<STRONG>transportTarget</STRONG>,
<STRONG>*varBinds</STRONG>
)</DT>

<DD>
<P>
Perform SNMP SET request and return a response or error indication.
</P>

<P>
The <STRONG>authData</STRONG> and <STRONG>transportTarget</STRONG> parameters
have he same semantics as in <A HREF="#CommandGenerator.getCmd">getCmd</A>
method.
</P>

<P>
The <STRONG>*varBinds</STRONG> input parameter is a sequence of
Managed Objects to be applied at Agent. The syntax of
<STRONG>*varBinds</STRONG> is the same as in
<A HREF="#CommandGenerator.getCmd">getCmd</A> method.
</P>

<P>
The <STRONG>setCmd</STRONG> method returns a tuple of
<STRONG>errorIndication</STRONG>, 
<STRONG>errorStatus</STRONG>,
<STRONG>errorIndex</STRONG>,
<STRONG>varBinds</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>

</DD>
</DL>

<P>
The following code performs SNMP SET operation over SNMPv2c:
</P>

<TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
<PRE>
>>> from pysnmp.entity.rfc3413.oneliner import cmdgen
>>> from pysnmp.proto import rfc1902
>>> errorIndication, errorStatus, errorIndex, varBinds = cmdgen.CommandGenerator().setCmd(
... cmdgen.CommunityData('my-agent', 'public', 1),
... cmdgen.UdpTransportTarget(('localhost', 161)),
... ((1,3,6,1,2,1,1,1,0), rfc1902.OctetString('my system description'))
... )
>>> print(errorIndication)
None
>>> print(errorStatus)
17
>>> print(errorStatus.prettyPrint())
notWritable(17)
</PRE>
</TD></TR></TABLE>

<A NAME="CommandGenerator.nextCmd"></A>
<DL>
<DT><STRONG>nextCmd</STRONG>(
<STRONG>authData</STRONG>,
<STRONG>transportTarget</STRONG>,
<STRONG>*varNames</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 to those used in request.
</P>

<P>
Input parameters to the <STRONG>nextCmd</STRONG> method are the same as to 
<A HREF="#CommandGenerator.getCmd">getCmd</A>.
</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 tuple 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 also possible to modify the above behaviour so that the 
<STRONG>varBindTable</STRONG> returned would contain *all*
Managed Objects from those passed in request up till the end of
the list of available Managed Objects at the Agent. This option
is enabled by setting the <STRONG>lexicographicMode</STRONG>
attribute of the <STRONG>CommandGenerator</STRONG> class instance
to True.
</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
over SNMPv3:
</P>

<TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
<PRE>
>>> from pysnmp.entity.rfc3413.oneliner import cmdgen
>>> errorIndication, errorStatus, errorIndex, varBindTable = cmdgen.CommandGenerator().nextCmd(
... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
... cmdgen.UdpTransportTarget(('localhost', 161)),
... (1,3,6,1,2,1,1)
... )
>>> print(errorIndication)
None
>>> print(errorStatus)
0
>>> for varBindTableRow in varBindTable:
...     print(varBindTableRow)
...
[(ObjectName('1.3.6.1.2.1.1.1.0'), OctetString("'Linux saturn 2.6.21 
    #2 Mon Mar 19 17:07:18 MSD 2006 i686'"))]
[(ObjectName('1.3.6.1.2.1.1.2.0'), ObjectIdentifier('1.3.6.1.4.1.8072.3.2.10'))]
[ skipped ]
[(ObjectName('1.3.6.1.2.1.1.9.1.4.9'), TimeTicks('17'))]
>>>
</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>
)</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 queries a bulk of Managed Objects at once.
</P>

<P>
The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
<STRONG>*varNames</STRONG> input parameters to the <STRONG>bulkCmd</STRONG> 
method are the same as to  <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 with 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>.
</P>

<P>
The <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG>,
<STRONG>errorIndex</STRONG> and <STRONG>varBindTable</STRONG> parameters have
the same meaning as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method.
</P>
</DD>
</DL>

<P>
The following code performs SNMP GETBULK operation against a MIB subtree
over SNMPv3:
</P>

<TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
<PRE>
>>> from pysnmp.entity.rfc3413.oneliner import cmdgen
>>> errorIndication, errorStatus, errorIndex, varBindTable = cmdgen.CommandGenerator().bulkCmd(
... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
... cmdgen.UdpTransportTarget(('localhost', 161)),
... 0, 25, # nonRepeaters, maxRepetitions
... (1,3,6,1,2,1,1)
... )
>>> print(errorIndication)
None
>>> print(errorStatus)
0
>>> for varBindTableRow in varBindTable:
...     print(varBindTableRow)
...
[(ObjectName('1.3.6.1.2.1.1.1.0'), OctetString("'Linux saturn 2.6.21 
     #2 Mon Mar 19 17:07:18 MSD 2006 i686'"))]
[(ObjectName('1.3.6.1.2.1.1.2.0'), ObjectIdentifier('1.3.6.1.4.1.8072.3.2.10'))]
[ skipped ]
[(ObjectName('1.3.6.1.2.1.1.9.1.4.9'), TimeTicks('17'))]
>>>
</PRE>
</TD></TR></TABLE>

<P>
Notification Originator Applications are implemented within a single class:
</P>

<A NAME="NotificationOriginator"></A>
<DL>
<DT>class <STRONG>NotificationOriginator</STRONG>([<STRONG>snmpContext</STRONG>])</DT>
<DD>
<P>
Create a SNMP Notification Originator object.
</P>
</DD>
</DL>

<P>
The following method of <STRONG>NotificationOriginator</STRONG> class instance 
implements specific notifications types.
</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>
Be advised, that when using confirmed notification, Notification Receiver
must know ContextEngineID of Notification Originator to be able to
process and acknowledge confirmed notification.
</P>

<P>
The <STRONG>notificationType</STRONG> parameter indicates the kind of
event to notify Manager about in form of SMI NOTIFICATION-TYPE object
name. For instance, (('SNMPv2-MIB', 'coldStart'),) or (1,3,6,1,6,3,1,1,5,1)
is a value of coldStart notification type as defined in SNMPv2-MIB module.
</P>

<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>

</DD>
</DL>

<P>
The following code sends SNMP TRAP over SNMPv3:
</P>

<TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
<PRE>
>>> from pysnmp.entity.rfc3413.oneliner import cmdgen, ntforg
>>> from pysnmp.proto.api import v2c
>>> errorIndication = ntforg.NotificationOriginator().sendNotification(
... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
... cmdgen.UdpTransportTarget(('localhost', 162)),
... 'trap',
... (('SNMPv2-MIB', 'coldStart'),),
... ((1,3,6,1,2,1,1,3,0), v2c.TimeTicks(44100))
)
>>> print(errorIndication)
None
>>> print(errorStatus)
0
</PRE>
</TD></TR></TABLE>

<A NAME="ASYNCH-ONELINER-APPS"></A>
<H4>
2.1.2 Asynchronous One-line Applications
</H4>

<P>
Asynchronous API to one-line 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>

<P>
All Command Generator Applications are implemented within a single class:
</P>

<A NAME="AsynCommandGenerator"></A>
<DL>
<DT>class <STRONG>AsynCommandGenerator</STRONG>([<STRONG>snmpEngine</STRONG>])</DT>
<DD>
<P>
Create an asynchronous SNMP Command Generator object.
</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>asyncGetCmd</STRONG>(
<STRONG>authData</STRONG>,
<STRONG>transportTarget</STRONG>,
<STRONG>varNames</STRONG>,
(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</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 Python function) that takes the following parameters:
</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>asyncGetCmd</STRONG> method.
</P>

<P>
The <STRONG>cbCtx</STRONG> parameter is a reference to the
<STRONG>cbCtx</STRONG> object being passed to <STRONG>asyncGetCmd</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>

<P>
If <STRONG>cbFun</STRONG> has no more requests pending and want to complete, 
it must return a true value. Otherwise, it returns false.
</P>
</DD>
</DL>

<P>
The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG> and
<STRONG>varNames</STRONG> parameters have the same meaning as in
<A HREF="#CommandGenerator.getCmd">getCmd</A>
method.
</P>

<P>
The <STRONG>asyncGetCmd</STRONG> method returns unique
<STRONG>sendRequestHandle</STRONG> integer value used for
matching subsequent response to this request.
</P>
</DD>
</DL>

<A NAME="AsynCommandGenerator.asyncSetCmd"></A>
<DL>
<DT><STRONG>asyncSetCmd</STRONG>(
<STRONG>authData</STRONG>,
<STRONG>transportTarget</STRONG>,
<STRONG>varBinds</STRONG>,
(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>)
)</DT>

<DD>
<P>
Prepare SNMP SET request to be dispatched. Return the 
<STRONG>sendRequestHandle</STRONG> value.
</P>

<P>
The <STRONG>authData</STRONG> and <STRONG>transportTarget</STRONG>
parameters have the same meaning as in 
<A HREF="#CommandGenerator.getCmd">CommandGenerator.getCmd</A> method.
</P>

<P>
The <STRONG>cbFun</STRONG> and <STRONG>cbCtx</STRONG> parameters
have the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd">
AsynCommandGenerator.asyncGetCmd</A> method.
</P>

<P>
The <STRONG>varBinds</STRONG> parameter has the same meaning as in 
<A HREF="#CommandGenerator.setCmd">CommandGenerator.setCmd</A> method
except that here it is passed in as a tuple.
</P>
</DD>
</DL>

<A NAME="AsynCommandGenerator.asyncNextCmd"></A>
<DL>
<DT><STRONG>asyncNextCmd</STRONG>(
<STRONG>authData</STRONG>,
<STRONG>transportTarget</STRONG>,
<STRONG>varNames</STRONG>,
(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>)
)</DT>

<DD>
<P>
Prepare SNMP GETNEXT request to be dispatched. Return the 
<STRONG>sendRequestHandle</STRONG> value.
</P>

<P>
The <STRONG>authData</STRONG> and <STRONG>transportTarget</STRONG>
parameters have the same meaning as in 
<A HREF="#CommandGenerator.nextCmd">CommandGenerator.nextCmd</A> method.
</P>

<P>
The <STRONG>cbFun</STRONG> and <STRONG>cbCtx</STRONG> parameters
have the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd">
AsynCommandGenerator.asyncGetCmd</A> method.
</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>

<A NAME="AsynCommandGenerator.asyncBulkCmd"></A>
<DL>
<DT><STRONG>asyncBulkCmd</STRONG>(
<STRONG>authData</STRONG>,
<STRONG>transportTarget</STRONG>,
<STRONG>nonRepeaters</STRONG>,
<STRONG>maxRepetitions</STRONG>,
<STRONG>varNames</STRONG>,
(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</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> and <STRONG>maxRepetitions</STRONG>
parameters have the same meaning as in 
<A HREF="#CommandGenerator.nextCmd">CommandGenerator.nextCmd</A> method.
</P>

<P>
The <STRONG>cbFun</STRONG> and <STRONG>cbCtx</STRONG> parameters
have the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd">
AsynCommandGenerator.asyncGetCmd</A> method.
</P>

<P>
The <STRONG>varNames</STRONG> parameter has the same meaning as in 
<A HREF="#CommandGenerator.bulkCmd">CommandGenerator.bulkCmd</A> method
except that here it is passed in as a tuple.
</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>

<P>
The following code performs SNMP GET operation asynchronously through
SNMPv3:
</P>

<TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
<PRE>
>>> from pysnmp.entity.rfc3413.oneliner import cmdgen
>>>
>>> def cbFun(sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds, cbCtx):
...     print('sendRequestHandle = %d' % sendRequestHandle)
...     print('errorIndication = %s' % errorIndication)
...     print('errorStatus = %s' % errorStatus)
...     print('varBinds = %s' % (varBinds,))
...     print('cbCtx = %s' % cbCtx)
...
>>> asynCommandGenerator = cmdgen.AsynCommandGenerator()
>>> # This is a non-blocking call
>>> sendRequestHandle = asynCommandGenerator.asyncGetCmd(
... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'), 
... cmdgen.UdpTransportTarget(('localhost', 161)), 
... ((1,3,6,1,2,1,1,1,0),), 
... (cbFun, None))
>>> print(sendRequestHandle)
1
>>> asynCommandGenerator.snmpEngine.transportDispatcher.runDispatcher()
sendRequestHandle = 1
errorIndication = None
errorStatus = 0
varBinds = [(ObjectName('1.3.6.1.2.1.1.1.0'), OctetString("'Linux saturn 
     2.6.21 #2 Mon Mar 19 17:07:18 MSD 2006 i686'"))]
cbCtx = None
>>>
</PRE>
</TD></TR></TABLE>

<P>
The <STRONG>AsynNotificationOriginator</STRONG> class implements specific 
notification types.
</P>

<A NAME="AsynNotificationOriginator"></A>
<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>asyncSendNotification</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.asynGetCmd</A> method.
</P>

</DD>
</DL>

<P>
The <STRONG>cbCtx</STRONG> parameter has the same meaning as in 
<A HREF="#AsynCommandGenerator.asyncGetCmd">AsynCommandGenerator.asyncGetCmd</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>asyncSendNotification</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 SNMP INFORM notification asynchronously through
SNMPv3:
</P>

<TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
<PRE>
>>> from pysnmp.entity.rfc3413.oneliner import cmdgen, ntforg
>>> from pysnmp.proto.api import v2c
>>>
>>> def cbFun(sendRequestHandle, errorIndication, cbCtx):
...     print('sendRequestHandle = %d' % sendRequestHandle)
...     print('errorIndication = %s' % errorIndication)
...     print('cbCtx = %s' % (cbCtx,))
...
>>> asynNotificationOriginator = ntforg.AsynNotificationOriginator()
>>> # This is a non-blocking call
>>> sendRequestHandle = asynNotificationOriginator.asyncSendNotification(
... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
... cmdgen.UdpTransportTarget(('localhost', 162)),
... 'inform',
... ('SNMPv2-MIB', 'coldStart'),
... ((1,3,6,1,2,1,1,1,0), v2c.TimeTicks(44100)),
... (cbFun, None))
>>> print(sendRequestHandle)
1
>>> asynNotificationOriginator.snmpEngine.transportDispatcher.runDispatcher()
sendRequestHandle = 1
errorIndication = None
cbCtx = None
>>>
</PRE>
</TD></TR></TABLE>

<A NAME="SECURITY-CONFIGURATION"></A>
<H4>
2.1.3 Security configuration
</H4>
<P>
Calls to one-line 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 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 and DES-based encryption 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>securityName</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>securityName</STRONG> parameter is Community-Based Security 
Model username passed in as a string. For most purposes this can be an
arbitrary string.
</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 an Agent
accessible through UDP domain 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 single Agent accessible through UDP socket.
</P>
<P>
Mandatory <STRONG>transportAddr</STRONG> parameter indicates destination
Agent address in form of tuple of <STRONG>FQDN</STRONG>, <STRONG>port</STRONG>
where <STRONG>FQDN</STRONG> is a string and <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">
<P>
At the protocol level, each <A HREF="#MANAGED-OBJECTS">Managed Object</A>
instance is represented by a pair of Name and Value collectively called
a <STRONG>Variable-Binding</STRONG>.
</P>

<P>
In PySNMP programming context, at the high-level API, each Managed Object is
represented by a tuple of two class instances -- one represents Managed 
Object Instance Name, and another -- its value.
</P>

<A NAME="OID-IMPL">
<P>
Managed Object 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 APIs will automatically create an instance of
ObjectIdentifier class from its initialization value. Therefore it's
allowed to use a plain tuple of integers as a Managed Object Name.
</P>

<A NAME="VAL-IMPL">
<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. The list of Managed Object 
Instance Value classes follow.
</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>

<P>
It's PySNMP design decision to always use <A HREF="#SMI">SMIv2</A>
definitions for Managed Objects at the high-level API regardless of SNMP
protocol version being used. For instance, an SNMPv3 Manager will always report
SMIv2 types even when talking to SNMPv1 Agent (which is SMIv1-compliant).
</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> take shape of 
Python class instances that implement various
<A HREF="#SMI">SMIv2</A> items. Collections of Managed Objects, or
<A HREF="#MIB">MIB</A>s, 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>
Create a definition of scalar Managed Object with name 
<STRONG>name</STRONG> and associated value of type 
<STRONG>syntax</STRONG>.
</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's
<A HREF="#MANAGED-OBJECT-SYNTAX">value type</A>.
</P>
</DD>
</DL>

<P>
The <STRONG>MibScalar</STRONG> class implements the following methods:
</P>

<A NAME="MibScalar.getName"></A>
<A NAME="MibScalar.getSyntax"></A>
<A NAME="MibScalar.getMaxAccess"></A>
<A NAME="MibScalar.getUnits"></A>
<A NAME="MibScalar.getStatus"></A>
<A NAME="MibScalar.getDescription"></A>
<DL>
<DT><STRONG>getName</STRONG>()</DT>
<DT><STRONG>getSyntax</STRONG>()</DT>
<DT><STRONG>getMaxAccess</STRONG>()</DT>
<DT><STRONG>getUnits</STRONG>()</DT>
<DT><STRONG>getStatus</STRONG>()</DT>
<DT><STRONG>getDescription</STRONG>()</DT>
<DD>
<P>
Each of these methods return certain property of Managed Object.
</P>
</DD>
</DL>

<A NAME="MibScalarInstance"></A>
<DL>
<DT>class <STRONG>MibScalarInstance</STRONG>(
<STRONG>name</STRONG>, <STRONG>syntax</STRONG>
)</DT>
<DD>
<P>
Create an instance of scalar Managed Object or 
<A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> element
with name <STRONG>name</STRONG> and associated value
<STRONG>syntax</STRONG>.
</P>

<P>
The <STRONG>name</STRONG> of Managed Object instance is a concatination
of <STRONG>name</STRONG> of Managed Object definition and some
instance identifier. For scalar types, instance identifier is 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>
Create a definition of 
<A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> Column with
name <STRONG>name</STRONG> and associated value of type 
<STRONG>syntax</STRONG>.
</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>
Create a definition of 
<A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> Row with
name <STRONG>name</STRONG>.
</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>
Create a definition of 
<A HREF="#CONCEPTUAL-TABLES">Conceptual Table</A> with name
<STRONG>name</STRONG>.
</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=100%><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=100%><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=100%><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=100%><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=100%><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=100%><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=100%><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=100%><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=100%><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=100%><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=100%><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=100%><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>

<I>
<P>
Disclaimer: this document is a work-in-progress. 
It is neither complete nor accurate. 
Take it with a grain of salt!
</P>
</I>

</TR></TD></TABLE>
</TR></TD></TABLE>

</BODY>
</HTML>
python-pysnmp4-doc 4.2.2-1 / usr / share / doc / python-pysnmp4-doc / pysnmp-tutorial.html
