From 766e8f45204cc391aff99f55c72b0abcc4625160 Mon Sep 17 00:00:00 2001 From: elie Date: Wed, 23 Jan 2002 09:50:15 +0000 Subject: Source tree of completely rewritten version of PySNMP (2.x) initially committed to CVS. --- CHANGES | 444 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 24 ++++ README | 106 ++++++++++++++++ 3 files changed, 574 insertions(+) create mode 100644 CHANGES create mode 100644 LICENSE create mode 100644 README 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 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 ; + +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 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 +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 -- cgit v1.2.1