Source tree of completely rewritten version of PySNMP (2.x) initially

committed to CVS.

3 files changed, 574 insertions, 0 deletions

diff --git a/CHANGES b/CHANGES
new file mode 100644
index 0000000..bfdddce
--- /dev/null
+++ b/CHANGES
@@ -0,0 +1,444 @@
+Wed Jan  23 18:55:09 MSK 2002
+
+Changes to version 2.0.1
+------------------------
+
+- The whole package has been completely redesigned and rewritten
+  in a more object-oriented fashion.
+
+  Major changes from user's point of view include:
+
+  * SNMP v.2c support added;
+
+  * SNMP agent (server) support added to SNMP transport code;
+ 
+  * API level compatibility with previous PySNMP versions is
+    not preserved at the moment. The 2.0.1 version will not be
+    released until the compatibility layer is written (work is
+    in progress).
+
+Changes to version 1.6.5
+------------------------
+
+- Distutils support added by drt@un.bewaff.net.
+
+Tue Sep  25 18:34:56 MSK 2001
+
+Changes to version 1.6.4
+------------------------
+
+- The snmpagent.py script previously contributed by Cayce Ullman
+  updated by Ivan Begtin to run with the latest versions of PySNMP.
+
+- Oddly handled exceptions fixed to msession.multisession() class. Thanks
+  to Chris Green for pointing out.
+
+- Inconsistent default return value fixed in multisession.retrieve() method.
+  This bug may lead to IndexError on timed out SNMP request. Thanks to
+  Chris Green for a patch.
+
+Fri Jun  22 08:55:39 MSK 2001
+
+Changes to version 1.6.3
+------------------------
+
+- Bug fixed in examples/async_snmpget.py: this example script misses
+  async_session() class structure change introduced in version 1.6.1.
+  Thanks to Chris Green for a patch.
+
+- Also, a minor improvement has been made to examples/async_snmpget.py
+  script -- now this script handles cases when remote SNMP agent returns
+  SNMP error in reply.
+
+Sat Jun  16 11:06:34 MSK 2001
+
+Changes to version 1.6.2
+------------------------
+
+- Missing "opaque" ASN.1 data type support committed to BER engine. Thanks
+  to Carl Bray for providing a patch for it.
+
+Sat May  5 10:02:40 MSK 2001
+
+Changes to version 1.6.1
+------------------------
+
+- SNMP traps support has finally been completed. Example agent and manager
+  along with some documentation included. Thanks to Ted Crossman for initial
+  traps handling code.
+
+- The ber.decode_ipaddress() method renamed to ber.decode_ipaddr() to
+  look as a counterpart to ber.encode_ipaddr(). Compatibility stub
+  ber.encode_ipaddress() remained.
+
+- __doc__ strings improved throughout the code.
+
+- BER engine code slightly optimized for a little bit better performance.
+
+Thu Mar 22 08:37:02 MSK 2001 
+
+Changes to version 1.5.5
+------------------------
+
+- In objid.objid(), the str variable name replaced with txt to avoid
+  interferention with str() builtin function. Thanks to Kal Lin for
+  pointing it out.
+
+- Bug fixed in ber.encode_an_integer() and ber.decode_integer() methods.
+  They used to handle negative integers in a wrong way. Thanks to
+  Tim Kwiatkowski <jtk@bluesky.ecas.ou.edu> who has fixed this problem
+  by rewriting corresponding code from the scratch.
+
+Fri Mar  9 19:02:56 MSK 2001
+
+Changes to version 1.5.4
+------------------------
+
+- Package documentation added (still not quite complete).
+
+- The implementation of ber.encode_oid() method replaced with a more
+  consistent one, as suggested by Jarkko Torppa. This also removes a
+  limitation on the size of sub-Object IDs to be encoded.
+
+- Bug fixed in pysnmp.asynsnmp module -- import of pysnmp components was
+  incorrect.
+
+- Bug fixed in multisession.retrieve() -- trick SNMP failures to empty
+  responses.
+
+- The multisession.initialize() method added to facilitate class instances
+  reuse.
+
+- In async_session.send_request(), the 'type' argument moved to the last
+  position of the argument list and assigned the default value ('GETREQUEST').
+  Unfortunately, this change may cause API incompatibility with the
+  previous versions of PySNMP.
+
+- The async_session.open() method introduced as a result of splitting
+  apart the async_session.__init__() method. This is done to let user
+  of async_session class modify class instance private variables (port,
+  iface) before they take effect. This change may also cause API
+  incompatibility.
+
+- In async_session.__init__(), verify the callback_fun argument to make sure
+  it's callable.
+
+- In message.__init__(), the 'version' argument moved to the very end of
+  argument list, as it is never need to be modified. This change may cause
+  API incompatibility.
+
+- In message.message() class, the 'decode_pdu' method renamed into
+  'decode_snmp_pdu' for a more consistent view. This change might not
+  affect API compatibility.
+
+- In error.py, the 'BERError' class renamed into 'BEREngineError' while
+  'EngineError' one renamed into 'SNMPEngineError'. This change may cause
+  API incompatibility.
+
+- In examples/*.py, the repr() builtin replaced with str() one as it looks
+  more appropriate for printing.
+
+- In message.message() class, default values for 'type', 'encoded_oids'
+  and 'encoded_vals' arguments in method encode_request() removed.
+
+- In message.message() class, default value for 'response' arguments in
+  method decode_response() removed.
+
+- Receive buffers of SNMP engines enlarged up to maximum UDP datagram
+  size (65536 bytes) to accomodate possible huge Object IDs' values
+  in replies.
+
+- In multisession.retrieve(), delete the list of SNMP sessions on finish
+  to save memory.
+
+- More explanation messages added to exception class instantiations.
+
+Tue Mar  6 18:06:56 MSK 2001
+
+Changes to version 1.5.3
+------------------------
+
+- Example code in README fixed. Thanks to Jeff Wong and Charles Kong for
+  it pointing out.
+
+Fri Feb 23 12:28:59 MSK 2001
+
+Changes to version 1.5.2
+------------------------
+
+- The ber.encode_length() & ber.decode_length() methods modified to allocate
+  up to three extra bytes for storing the length of BER encoded data item or
+  raise an exception if data item is too large (>16MB).
+
+Sun Jan 21 13:56:41 MSK 2001
+
+Changes to version 1.5.1
+------------------------
+
+- The pysnmp module converted into pysnmp package. This change might
+  cause an incompatibility with previous PySNMP versions, as it
+  affects the way how user refers to pysnmp components.
+
+- All the PySNMP components converted to use class-based exceptions.
+
+- Comments to files converted to module __doc__ attribute.
+
+- The arguments to all objid.objid() methods as well as caller_fun argument
+  to asynsnmp.async_session() class constructor becomes mandatory.
+
+- Fixed a bug caused an infinit loop in msession.dispatch(), thanks to
+  Case Van Horsen for tracking it down.
+
+- The repr() function is used in examples/ scripts in place of %
+  for a more consistent result types coercion.
+
+- The documentation has been taked out of the distribution for a re-work
+  to get it reflecting 1.5.x changes.
+
+Thu Jan 11 11:42:13 MSK 2001
+
+Changes to version 1.4.2
+------------------------
+
+- Argument verification for the most of ber.ber() methods removed,
+  as it looks exessive (user must follow API specs).
+
+- A bug is fixed in ber.decode_uptime(), thanks to Case Van Horsen for
+  pointing it out.
+
+- The pysnmp.multisession() class has been re-written. The new version
+  is based on Case Van Horsen's code. Most importantly, a bug which
+  may cause some agents' responses get lost is fixed. Also, the new code
+  makes more efficient use of sockets.
+
+  From the pysnmp.multisession() API perspective, the
+  multisession.encoded_pairs attribute has been removed from class
+  definition, as it seems to be of no use. The multisession.retrieve()
+  method should be used instead.
+
+Sat Dec 30 21:25:56 MSK 2000
+
+Changes to version 1.4.1
+------------------------
+
+It's a major rewrite meant to remove known oddities. Unfortunately,
+the API had to be changed a bit. The changes follow:
+
+- The SNMP errors reported by remote SNMP process are now indicated
+  with the single exception (pysnmp.SNMP_ERROR) while the details
+  are supplied along with the exception associated value (see docs).
+
+- Class constructor of pysnmp.session() class now accepts only a few
+  arguments (agent, community). The rest of arguments (such as UDP port
+  number, SNMP version etc.) are now available as the attributes of
+  pysnmp.session() class instances (see docs).
+
+- Instances of pysnmp.session() class now have the 'iface' attribute
+  which carries the address of local interface SNMP engine is to bind()
+  to (see docs).
+
+- The pysnmp.bad_parameters exception has been replaced with
+  pysnmp.bad_argument one as they seem to have very similar
+  semantics.
+
+- Class constructor of pysnmp.multisession() class does not accept any
+  arguments. SNMP engine parameters are now avaliable as class instances 
+  attributes (see the comment on pysnmp.session() class constructor above).
+
+- The asynsnmp.async_session() class now subclasses the pysnmp.session()
+  class for the purpose of inheriting the API of pysnmp.session() class.
+  Consequently, the asynsnmp.async_session() class constructor now accepts
+  only a few [major] parameters. The minor ones should be referred as class
+  instance attributes (see docs).
+
+- In async_session.handle_read(), when calling caller specified callback
+  function, pass caller a reference to ourselves along with a reference to
+  caller specific data. N.B. This leads to callback function's arguments list
+  change what may cause incompatibility problem to the user of asyncsnmp()
+  class!
+
+- The pysnmp.packet() class renamed to pysnmp.message() as it better represents
+  its functionality. This also may cause some incompatibilities, though, I do
+  not expect great many people explicitly refer to it from their applications.
+
+- Some comments in the code turned to objects' doc strings.
+
+- The examples/ stuff has been re-written for a more consistent view;
+
+- Module documentation added.
+
+Thu Nov 16 08:49:14 MSK 2000
+
+Changes to version 1.3.14
+-------------------------
+
+- The license of the PySNMP package changed for a [more relaxed] BSD License;
+
+Fri Nov  3 19:20:02 MSK 2000
+
+Changes to version 1.3.13
+-------------------------
+
+- Fixed wrong (non-tuple type) argument passed to socket.connect() method in
+  session.open();
+
+Mon Sep 11 11:47:12 MSD 2000
+
+Changes to version 1.3.12
+-------------------------
+
+- bug fixed in IP address encapsulation method (ber.encode_ipaddr()). Thanks
+  to Jarkko Torppa for pointing it out!
+
+Fri Sep  8 11:51:34 MSD 2000
+
+Changes to version 1.3.11
+-------------------------
+
+- the obsolete standard Python module 'rand' replaced with 'whrandom'
+  in pysnmp.py for better portability. The random numbers generator is
+  used for SNMP RequestID initialization. This change also enlarges the
+  range of possible RequestID values from 0 to 0x7fffffff.
+
+- contribution/ directory introduced and Cayce Ullman's PySNMP based
+  SNMP agent put there as an example of possible PySNMP use;
+
+Mon Sep  4 15:04:05 MSD 2000
+
+Changes to version 1.3.10
+-------------------------
+
+- catch all possible SNMP related exceptions in async_session.handle_read()
+  and convert them into (None, None) result as they would arrive out of
+  context at that point (this is subject for further re-work);
+
+- a syntax error fixed in ber.encode_ipaddr() thanks to Stefan Sami-Soueiha
+  who pointed this out;
+
+Fri Aug  4 09:50:37 MSD 2000
+
+Changes to version 1.3.9
+------------------------
+
+- initialize SNMP Request-Id to a random value (by means of rand.rand())
+  in pysnmp.packet class constructor. This makes sense when user doesn't re-use
+  pysnmp object for subsequent SNMP queries but re-creates new pysnmp
+  object for every request;
+
+- convert possible pysnnp exceptions when decoding SNMP reply in
+  async_session.handle_read() into (None, None) result as a pysnmp
+  exception at that point would arrive out of context;
+
+- do not destroy pysnmp.session object in async_session.handle_read()
+  method as pysnmp.session object may be re-used;
+
+Tue May 30 18:32:23 MSD 2000 
+
+Changes to version 1.3.8
+------------------------
+
+- a bunch of changes to pysnmp.multisession class suggested by Case Van Horsen.
+  These changes make objects of multisession class handling socket exceptions
+  rather than passing them up to mother application;
+- socket variable at pysnmp.py: replaced with sock as Case Van Horsen
+  reported that it interferes with the socket module;
+
+Mon Mar 20 18:48:54 MSK 2000
+
+Changes to version 1.3.7
+------------------------
+
+- pysnmp.objid class moved to a dedicated module objid.py;
+- ber.ber now superclasses objid.objid class;
+- pysnmp.session.__init__() doesn't create an instance of pysnmp.objid()
+  class (THIS MAY CAUSE BACKWARD INCOMPATIBILITY, please, let me know
+  if you think I should maintain backward compatibility at this point
+  of code);
+- ber.decode_value() now attempts to decode an Object-Id type argument
+  as suggested by Case Van Horsen;
+- examples/*.py changed to utilize ber.decode_value() method against
+  Object-ID's;
+- tabs converted to spaces through all the *.py files;
+- a few cosmetic changes applied to code;
+
+Tue Jan 25 00:22:18 MSK 2000
+
+Changes to version 1.3.6
+------------------------
+
+- the README example corrected, thanks to Carl Bray <cbray@Orchestream.com>;
+
+Wed Jan 19 14:43:31 MSK 2000
+
+Changes to version 1.3.5
+------------------------
+
+- the asynchronous SNMP manager class previously founded in
+  examples/async_snmpget.py moved to a separate module asynsnmp.py;
+- examples/async_snmpget.py now imports asynchronous SNMP manager class
+  from asynsnmp.py module;
+
+Mon Jan 17 15:50:04 MSK 2000
+
+Changes to version 1.3.4
+------------------------
+
+- session.open() now returns the socket object it created;
+- added a session.get_socket() method which returns socket object
+  previously created with session.open() method;
+- examples/async_snmpget.py added;
+
+Thu Nov 25 16:42:59 MSK 1999
+
+Changes to version 1.3.3
+------------------------
+
+- added a method which figures out if one OBJID is a prefix of another OBJID
+  (this is used in table retrieval;
+- example/snmptable.py added;
+
+Sat Nov 13 23:43:08 MSK 1999
+
+Changes to version 1.3.2
+------------------------
+
+- community argument of examples/* tools is now obligatory;
+- multisession example of snmpget tool converted to snmpbulk tool;
+
+Wed Nov 10 18:06:34 MSK 1999
+
+Changes to version 1.3.1
+------------------------
+
+- a couple of bugfixes for BER [en,de]coders reported by 
+  Steve Cochran <steve@more.net> commited to the distribution;
+
+Thu Oct 28 17:40:09 MSD 1999
+
+Changes to version 1.3
+----------------------
+
+- example/snmpset.py added;
+
+Sun Oct 17 17:42:31 MSD 1999
+
+Changes to version 1.2
+----------------------
+
+- examples/* tools now support command line arguments;
+- order of the arguments of session.__init__() and multisession.submit_request()
+  changed to better use defaults;
+- order of the arguments of session.decode_response() changed, response type
+  may now be ommited;
+
+Sat Oct 16 19:19:00 MSD 1999
+
+Changes to version 1.1
+----------------------
+
+- more checks against inconsistent arguments passed to various methods added;
+- SMTP request type can now be passed to the packet constructing methods;
+- more comments added to the code;
+- a Object ID's convertion class (pysnmp.objid) added;
+- examples/* updated (snmpwalk.py added);
+- a few significant bugs fixed;
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..ab10c26
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,24 @@
+Copyright (c) 1999, 2000, 2001, Ilya Etingof <ilya@glas.net>
+All rights reserved.
+
+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 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.
+
+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
new file mode 100644
index 0000000..caf2ecf
--- /dev/null
+++ b/README
@@ -0,0 +1,106 @@
+
+SNMP engine for Python, version 2.0.1
+-------------------------------------
+
+This is a Python implementation of SNMP v.1 engine. It's general
+functionality is to assemble/disassemble SNMP v.1 message from/into
+given SNMP Object IDs along with associated values. As an additional
+benefit, PySNMP provides a few transport methods specific to TCP/IP
+networking.
+
+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!).
+
+This code is known to be used under Python interpreter versions 1.5.2,
+1.6 and 2.0.
+
+This package is distributed under terms and conditions of BSD-style
+license. See the LICENSE file for details.
+
+PRECAUTIONS
+-----------
+
+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
+------------
+
+You might try distutils to install PySNMP by just typing:
+
+$ 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-2.0.1.tar
+$ echo pysnmp-2.0.1 > 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-2.0.1:$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.
+
+OPERATION
+---------
+
+Here is an example of using pysnmp package for querying SNMP agent
+(cisco router) for arbitrary value.
+
+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 import session
+>>> s = session.session ('cisco0.sovam.com', 'public')
+>>> encoded_objid = s.encode_oid ([1, 3, 6, 1, 2, 1, 1, 1, 0])
+>>> question = s.encode_request ('GETREQUEST', [encoded_objid], [])
+>>> answer = s.send_and_receive (question)
+>>> (encoded_objids, encoded_values) = s.decode_response (answer)
+>>> objids = map (s.decode_value, encoded_objids)
+>>> objids
+['.1.3.6.1.2.1.1.1.0']
+>>> values = map (s.decode_value, encoded_values)
+>>> values
+['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']
+>>> 
+
+8X---------------- cut here --------------------
+
+See package documentation and examples/ directory for more information
+on PySNMP services.
+
+AVAILABILITY
+------------
+
+The PySNMP software is available for download from project's homepage:
+http://sourceforge.net/projects/pysnmp/
+
+FEEDBACK
+--------
+
+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!
+
+=-=-=
+mailto: ilya@glas.net