Updates for 4.x alpha-revision

1 files changed, 96 insertions, 65 deletions

diff --git a/README b/README
index c8a829e..98ee33c 100644
--- a/README
+++ b/README
@@ -1,74 +1,63 @@
 
-SNMP engine for Python, version 3.x
------------------------------------
+SNMP framework for Python, version 4.x
+--------------------------------------
 
-This is a Python implementation of SNMP v.1/v.2c engine. Its general
-functionality is to assemble/disassemble SNMP messages from/into
-given SNMP Object IDs along with associated values. PySNMP also provides
-a few transport methods specific to TCP/IP networking.
+This is a pure-Python implementation of multi-protocol SNMP engine. At the
+time of this writing, only SNMP protocol version 1 and 2c are fully 
+supported. However, this framework is designed along the lines of SNMPv3
+architecture [1], so it should seamlessly host SNMP version 3, and hopefully
+future SNMP versions, whenever corresponding protocol-specific modules
+would be implemented (work's in progress).
 
-PySNMP is written entirely in Python and is self-sufficient in terms
-that it does not rely on any third party tool (it is not a wrapper!).
+The basic features of SNMP engine include SNMP messages processing and
+exchange between processes, as well as MIB information access and MIB
+instrumentation management.
+
+PySNMP is written entirely in Python and is self-sufficient (it is not a 
+wrapper!).
 
 The PySNMP package is distributed under terms and conditions of BSD-style
-license. See the LICENSE file for details.
+license. See LICENSE at PySNMP homepage [2].
 
 FEATURES
 --------
 
 * Complete SNMPv1 and SNMPv2c support
-* Seamless SNMP manager and agent roles support
-* Both synchronous and asynchronous IO API support
-* Fully documented API with many examples
-* Generic, objective ASN.1 framework
-* 100% Python, works with Python 1.x and later
+* Complete SNMP entity implementation (SNMP manager and agent roles)
+* SMI framework for looking up MIB information and managing MIB 
+  instrumentation
+* Multiple network transport methods (UDP and UNIX domain at the moment)
+* Both synchronous and asynchronous socket-based IO API support
+* 100% Python, works with Python 1.5 and later
 * MT-safe
 
 MISFEATURES
 -----------
 
-* No MIB compiler (though, it's possible to compile ASN.1 code into PySNMP
-  classes by hand, oh...)
-* No SNMP v.3 support (though, it's partially implemented, check CVS at SF)
+* No pure-Python MIB compiler. However, there's a tools/libsmi2pysnmp 
+  script in the PySNMP distribution which may be used for converting MIB
+  text files into pysnmp's SMI-compliant Python modules. There's also a
+  large set of pre-compiled MIB files in the pysnmp-mibs package [3].
+* No SNMP v.3 support
 
 PRECAUTIONS
 -----------
 
-For notes on backward compatibility with previous PySNMP revisions, please,
-refer to the COMPATIBILITY file in the PySNMP distribution.
-
-Since MIB support is not integrated into PySNMP package at the moment, this
-software accept and report Object IDs only in a non-symbolic (dotted) notation.
+The 4.x revision of PySNMP brings an alpha-quality code, unstable APIs and
+appears to run really slow. Also, the 4.x APIs are quite incompatible
+with their 2.x/3.x counterparts as of this early release. Chances are that,
+at least, high-level compatibility interfaces would appear by stable
+releases.
 
 INSTALLATION
 ------------
 
-You might try distutils to install PySNMP by just typing:
+The PySNMP package uses distutils for installation:
 
+$ tar zxf pysnmp-4.0.0.tar.gz
+$ cd pysnmp-4.0.0
 $ python setup.py install
 
-This should work on Unix and Microsoft Windows. Alternatively you can
-install PySNMP by hand:
-
-On UNIX, the pysnmp package can be put into the python/site-packages/
-directory in the following way (assuming your Python distribution
-resides under /usr/local/lib/python):
-
-$ cd /usr/local/lib/python/site-packages
-$ tar xvf /tmp/pysnmp-3.3.5.tar
-$ echo pysnmp-3.3.5 > pysnmp.pth
-
-Alternatively, the $PYTHONPATH environment variable can be updated to
-point to your PySNMP package location (assuming your UNIX shell is bash):
-
-export PYTHONPATH=/home/ilya/src/py/pysnmp-3.3.5:$PYTHONPATH
-
-The latter trick is also known to work on Windows.
-
-I've been told, that on Windows 2000, one needs to go to "Control panel"
--> "System" -> "Advanced" -> "Environment variables" and add/update the
-PYTHONPATH environment variable there.
-
 TESTING
 -------
 
@@ -83,36 +72,57 @@ list (see below).
 OPERATION
 ---------
 
-Here is an example of using pysnmp package for querying SNMP agent
-(cisco router) for arbitrary value.
+As of this writing, PySNMP implements two SNMP architectures -- the first
+is a legacy one used in SNMPv1 & v2c specifications [4]. It is quite 
+protocol-oriented and, in particular, requires application to manage
+transport failures, MIB access issues and so on.
+
+Here is an example on querying an SNMP agent (cisco router) for arbitrary
+value (sysDescr):
 
 8X---------------- cut here --------------------
 
-Python 1.5.2 (#3, Aug 25 1999, 19:14:24)  [GCC 2.8.1] on sunos5
-Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
->>> from pysnmp.proto import v1
->>> from pysnmp.proto.api import generic
->>> from pysnmp.mapping.udp import role
->>> req = v1.GetRequest()
->>> req.apiGenGetPdu().apiGenSetVarBind([('1.3.6.1.2.1.1.1.0', v1.Null())])
->>> tr = role.manager(('router-1.glas.net', 161))
->>> (answer, src) = tr.send_and_receive(req.encode())
->>> rsp = v1.GetResponse()
->>> rsp.decode(answer)
->>> vars = rsp.apiGenGetPdu().apiGenGetVarBind()
->>> print vars
-[('.1.3.6.1.2.1.1.1.0', OctetString('Cisco Internetwork Operating System Software \015\012IOS (tm) 5400 Software(C5400-JS-M), Version 12.2(11.8b), MAINTENANCE INTERIM SOFTWARE\015\012 Copyright (c) 1986-2002 by cisco Systems, Inc.\015\012Compiled Tue 30-Jul-02 19:02 by pwade'))]
+from pysnmp.carrier.asynsock.dispatch import AsynsockDispatcher
+from pysnmp.carrier.asynsock.dgram.udp import UdpSocketTransport
+from pysnmp.proto.api import alpha
+
+ver = alpha.protoVersions[alpha.protoVersionId1]
+
+def cbRecvFun(tspDsp, transportDomain, transportAddress, wholeMsg):
+    rsp = ver.Message()
+    rsp.berDecode(wholeMsg)
+    for varBind in rsp.apiAlphaGetPdu().apiAlphaGetVarBindList():
+        print varBind.apiAlphaGetOidVal()
+    tspDsp.doDispatchFlag = 0
+    return ''
+ 
+req = ver.Message()
+req.apiAlphaSetCommunity('public')
+req.apiAlphaSetPdu(ver.GetRequestPdu())
+req.apiAlphaGetPdu().apiAlphaSetVarBindList(
+    ((1,3,6,1,2,1,1,1,0), ver.Null())
+)
+
+tspDsp = AsynsockDispatcher(udp=UdpSocketTransport().openClientMode())
+tspDsp.registerRecvCbFun(cbRecvFun)
+tspDsp.sendMessage(req.berEncode(), 'udp', ('router-1.glas.net', 161))
+tspDsp.runDispatcher(liveForever=1)
 
 8X---------------- cut here --------------------
 
-See package documentation and examples/ directory for more information
-on PySNMP services.
+The second model supported by PySNMP resembles the SNMPv3 architecture, 
+as specified by [1]. The model is somewhat complex for this introductory
+README, so for more information, please, follow the pysnmp/examples 
+directory at the PySNMP distribution.
+
+MIB SUPPORT
+-----------
+
 
 AVAILABILITY
 ------------
 
-The PySNMP software is available for download from project's homepage:
-http://sourceforge.net/projects/pysnmp/
+The PySNMP software is available for download from project's homepage. [2]
 
 GETTING HELP
 ------------
@@ -128,5 +138,26 @@ I'm interested in bug reports and fixes, suggestions and improvements.
 I'd be happy knowning whenever you used the PySNMP software for whatever
 purpose. Please, send me a note then. Thanks!
 
+REFERENCES
+----------
+
+[1] SNMP Version 3 specification and related
+    http://www.ibr.cs.tu-bs.de/projects/snmpv3/
+
+[2] SNMP Version 1/2 specifications
+
+
+[2] libsmi homepage
+
+[2] PySNMP project homepage:
+    http://pysnmp.sf.net
+
+[4] PySNMP mailing list archives:
+    http://sourceforge.net/mail/?group_id=14735
+
+[3] Pre-compiled MIB files:
+    http://sourceforge.net/project/showfiles.php?group_id=14735
+
+
 =-=-=
 mailto: ilya@glas.net