updated

3 files changed, 94 insertions, 145 deletions

diff --git a/CHANGES b/CHANGES
index a139433..e23edb3 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,4 +1,4 @@
-Wed Oct 26 19:17:53 MSD 2005
+Fri Apr  7 22:28:41 MSD 2006
 
 Changes to version 2.0.9
 ------------------------
diff --git a/LICENSE b/LICENSE
index 4ae6897..5c14d45 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,28 +1,22 @@
-Copyright (c) 1999-2005, Ilya Etingof <ilya@glas.net>, all rights reserved.
+Copyright (c) 1999-2006, Ilya Etingof <ilya@glas.net>, all rights reserved.
 
-THIS SOFTWARE IS NOT FAULT TOLERANT AND SHOULD NOT BE USED IN ANY SITUATION
-ENDANGERING HUMAN LIFE OR PROPERTY.
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
 
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
+  * Redistributions of source code must retain the above copyright notice, 
+    this list of conditions and the following disclaimer.
 
-  * Redistributions of source code must retain the above copyright notice, this
-    list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright notice, 
+    this list of conditions and the following disclaimer in the documentation 
+    and/or other materials provided with the distribution.
 
-  * Redistributions in binary form must reproduce the above copyright notice, this
-    list of conditions and the following disclaimer in the documentation and/or
-    other materials provided with the distribution.
-
-  * The name of the authors may not be used to endorse or promote products
-    derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
-TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
-BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
-ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGE. 
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' 
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY 
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
diff --git a/README b/README
index d75276a..1b4f9ae 100644
--- a/README
+++ b/README
@@ -1,124 +1,113 @@
 
-PYTHON SNMP FRAMEWORK
----------------------
+SNMP engine for Python, version 2.0.9
+-------------------------------------
 
-This is an alpha-quality revision of pure-Python, open source and free
-implementation of v1/v2c/v3 SNMP engine.
+This is a Python implementation of SNMP v.1/v.2c engine. It's 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.
 
-The PySNMP project has been sponsored by a PSF grant [10]. Thanks!
+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!).
 
-FEATURES
---------
-
-* Complete SNMPv1/v2c and SNMPv3 support
-* SMI framework for resolving MIB information and managing MIB objects
-* Complete SNMP entity implementation
-* Extensible network transports framework (UDP and UNIX domain implemented)
-* Asynchronous socket-based IO API support
-* 100% Python, works with Python 1.5 and later
-* MT-safe
-
-Features, specific to SNMPv3 model include:
-
-* USM authentication (MD5/SHA) and privacy (DES) protocols (RFC3414)
-* View-based access control to use with any SNMP model (RFC3415)
-* Built-in SNMP proxy PDU converter for building multi-lingual
-  SNMP entities (RFC2576)
-* Remote SNMP engine configuration
-* Optional SNMP engine discovery
-* Shipped with standard SNMP applications (RC3413)  
-
-MISFEATURES
------------
+This code is known to be used under Python interpreter versions 1.5.2
+to 2.4.3.
 
-* Much slower than C implementations. Some optimization still possible.
-* No pure-Python MIB compiler. But there's a workaround, read on.
+This package is distributed under terms and conditions of BSD-style
+license. See the LICENSE file for details.
 
 PRECAUTIONS
 -----------
 
-The 4.x revision of PySNMP brings an alpha-quality code, unstable APIs and
-appears to run rather 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 in future stable
-releases.
+If you are starting a new project, consider trying the 4.x branch
+of PySNMP which is written in a more standards-compliant way and is
+[hopefully] stable enough by the time of this writing.
+
+Unfortunately, version 2.x of PySNMP software is *INCOMPATIBLE* with
+its 1.x branch at the moment.
+
+While the pure-Python MIB compiler project is underway, the ASN.1
+types of Object IDs associated values must be explicitly specified
+whenever user application passes values to SNMP engine.
+
+Lack of MIB support leads to another limitation -- all the PySNMP
+methods accept and report Object IDs only in dotted numeric (that is
+not symbolic) representation.
 
 INSTALLATION
 ------------
 
-The PySNMP package uses distutils for package management. The PyASN1 [8]
-package is required. For secure SNMPv3 communication, PyCrypto [9]
-should also be installed.
-
-OPERATION
----------
+You might try distutils to install PySNMP by just typing:
 
-As of this writing, PySNMP implements two SNMP architectures -- the first
-is a legacy one specified by SNMPv1 & v2c standards [5]. It is quite 
-low-level and protocol-oriented by design. In particular, it requires
-application to manage transport failures, access issues and so on.
+$ python setup.py install
 
-The second model supported by PySNMP is aligned to SNMPv3 architecture, 
-as specified in [4]. Here is an example on querying SNMP agent
-for arbitrary value (sysDescr) over SNMP v3 with authentication and 
-privacy enabled:
+This should work on Unix and Microsoft Windows. Alternatively you can
+install PySNMP by hand:
 
-8X---------------- cut here --------------------
+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):
 
-from pysnmp.entity.rfc3413.oneliner import cmdgen
+$ cd /usr/local/lib/python/site-packages
+$ tar xvf /tmp/pysnmp-2.0.9.tar
+$ echo pysnmp-2.0.9 > pysnmp.pth
 
-userData = cmdgen.UsmUserData('test-user', 'authkey1', 'privkey1')
-targetAddr = cmdgen.UdpTransportTarget(('localhost', 161))
+Alternatively, the $PYTHONPATH environment variable can be updated to
+point to your PySNMP package location (assuming your UNIX shell is bash):
 
-errorIndication, errorStatus, \
-                 errorIndex, varBinds = cmdgen.CommandGenerator().getCmd(
-    userData, targetAddr, (('SNMPv2-MIB', 'sysDescr'), 0)
-    )
+export PYTHONPATH=/home/ilya/src/py/pysnmp-2.0.9:$PYTHONPATH
 
-if errorIndication: # SNMP engine errors
-    print errorIndication
-else:
-    if errorStatus: # SNMP agent errors
-        print '%s at %s\n' % (errorStatus, varBinds[int(errorIndex)-1])
-    else:
-        for varBind in varBinds: # SNMP agent values
-            print '%s = %s' % varBind
+The latter trick is also known to work on Windows.
 
-8X---------------- cut here --------------------
+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.
 
-For more examples, please see the examples directory in the PySNMP distribution.
+OPERATION
+---------
 
-MIB SUPPORT
------------
+Here is an example of using pysnmp package for querying SNMP agent
+(cisco router) for arbitrary value.
 
-The pysnmp.smi sub-package defines and implements data model for SNMP SMI
-objects. With that model, various objects defined in MIB file could be
-implemented in Python, loaded into SNMP entity and used for verification and
-visualisation purposes (SNMP manager side) and/or become management targets
-(SNMP agent side).
+8X---------------- cut here --------------------
 
-While MIB parser/codegenerator has not been implemented in PySNMP, the
-smidump tool of libsmi library [6] could be used for automatic convertion
-of MIB text files into Python code. The code been generated relies upon
-PySNMP SMI library.
+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 import role, v2c, asn1
+>>> req = v2c.GETREQUEST()
+>>> req['encoded_oids'] = [ asn1.OBJECTID().encode('1.3.6.1.2.1.1.1.0') ]
+>>> tr = role.manager(('router-1.glas.net', 161))
+>>> (rawrsp, src) = tr.send_and_receive(req.encode())
+>>> rsp = v2c.RESPONSE()
+>>> rsp.decode(rawrsp)
+>>> oids = map(lambda x:x[0], map(asn1.OBJECTID().decode, rsp['encoded_oids']))
+>>> print oids
+['.1.3.6.1.2.1.1.1.0']
+>>> vals = map(lambda x: x[0](), map(asn1.decode, rsp['encoded_vals']))
+>>> print vals
+['Cisco Internetwork Operating System Software \015\012IOS (tm) 5300 Software
+(C5300-J-M), Experimental Version 12.1(20001115:152556) [haag-V121_4 102]
+\015\012Copyright (c) 1986-2000 by cisco Systems, Inc.\015\012Compiled
+Mon 20-Nov-00 19:22 by haag']
+>>>
 
-In order to convert MIB text files into pysnmp.smi-compliant Python source,
-please, use the pysnmp/tools/buildmibs.sh utility. Review its source code
-before use.
+8X---------------- cut here --------------------
 
-A large set of pre-compiled MIB files is shipped along the pysnmp-mibs
-package.[2]
+See package documentation and examples/ directory for more information
+on PySNMP services.
 
 AVAILABILITY
 ------------
 
-The PySNMP software is freely available for download from project's homepage.[1]
+The PySNMP software is available for download from project's homepage:
+http://sourceforge.net/projects/pysnmp/
 
 GETTING HELP
 ------------
 
-If something does not work as expected, please, try browsing PySNMP
-mailing list archives or post your question there. [7]
+Once anything does not work as expected, please, try browsing PySNMP
+mailing list archives at http://sourceforge.net/mail/?group_id=14735
+or post your question there.
 
 FEEDBACK
 --------
@@ -127,39 +116,5 @@ 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] PySNMP project homepage:
-    http://pysnmp.sf.net
-
-[2] Pre-compiled PySNMP MIB modules:
-    http://sourceforge.net/project/showfiles.php?group_id=14735
-
-[3] PySNMP applications:
-    http://sourceforge.net/project/showfiles.php?group_id=14735
-
-[4] SNMP Version 3 specification and related
-    http://www.ibr.cs.tu-bs.de/projects/snmpv3/
-
-[5] SNMP Version 1/2 specifications:
-    http://www.ietf.org/rfc/rfc1155.txt - http://www.ietf.org/rfc/rfc1158.txt
-    http://www.ietf.org/rfc/rfc1901.txt - http://www.ietf.org/rfc/rfc1909.txt
-
-[6] libsmi homepage
-    http://www.ibr.cs.tu-bs.de/projects/libsmi/
-
-[7] PySNMP mailing list archives:
-    http://sourceforge.net/mail/?group_id=14735
-
-[8] PyASN1 project homepage:
-    http://pyasn1.sf.net
-
-[9] PyCrypto project:
-    http://www.amk.ca/python/code/crypto.html
-
-[10] Python Software Foundation
-    http://www.python.org/psf/
-
 =-=-=
 mailto: ilya@glas.net