diff --git a/CHANGES.txt b/CHANGES.txt new file mode 100644 index 0000000..9f7d015 --- /dev/null +++ b/CHANGES.txt @@ -0,0 +1,4 @@ +Oct 27 2010 +----------- + +Initial public release. \ No newline at end of file diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..a034708 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,29 @@ +Copyright (c) 2010, Ilya Etingof , 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: + + * 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. + + * 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. diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..e6e00ca --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,2 @@ +include *.txt +recursive-include devices *.snmprec diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..5bd69c4 --- /dev/null +++ b/README.txt @@ -0,0 +1,222 @@ + +SNMP Simulator +-------------- + +This software is intended for testing SNMP Managers against SNMP Agents +built into various network devices. + +Typical use case for this software starts with recording a snapshot of +SNMP objects of a donor Agent into a text file using "snmprec" tool. Then +Simulator daemon would be run over the snapshots so that it could respond +to SNMP queries in the same way as donor SNMP Agent did at the time of +recording. + +Technically, SNMP Simulator is a multi-context SNMP Agent. That means that +it handles multiple sets of Managed Object all at once. Each device is +simulated as a dedicated SNMP context. + +SNMPv3 Manager talking to Simulator has to specify SNMP context name in +queries, while SNMPv1/v2c Manager can use specific SNMP community name +(logically bound to SNMP context) to access particular set of Managed Objects. + +Recording SNMP snapshots +------------------------ + +To record an SNMP snapshot you need to run the snmprec tool against your +donor device. This tool will execute a series of SNMP GETNEXT queries +for a specified range of OIDs over a chosen SNMP protocol version and store +response data in a text file (AKA device file). + +Device file format is optimized to be compact, human-readable and +inexpensive to parse. It's also important to store full and exact +response information in a most intact form. Here's an example device +file content: + +1.3.6.1.2.1.1.1.0|4|Linux 2.6.25.5-smp SMP Tue Jun 19 14:58:11 CDT 2007 i686 +1.3.6.1.2.1.1.2.0|6|1.3.6.1.4.1.8072.3.2.10 +1.3.6.1.2.1.1.3.0|67|233425120 +1.3.6.1.2.1.2.2.1.6.2|4x|00127962f940 +1.3.6.1.2.1.4.22.1.3.2.192.21.54.7|64x|c3dafe61 + +There is a pipe-separated triplet of OID-tag-value items where: + +* OID is a dot-separated set of numbers. +* Tag is a BER-encoded ASN.1 tag. When value is hexified, an 'x' literal + is appended. +* Value is either a printable string, a number or a hexifed value. + +Device file recording would look like this: + +$ snmprec.py -h +Usage: snmprec.py [--help] [--debug=] [--quiet] [--v1|2c|3] [--community=] [--v3-user=] [--v3-auth-key=] [--v3-priv-key=] [--v3-auth-proto=] [--v3-priv-proto=] [--context=] [--agent-address=] [--agent-port] [--start-oid=] [--stop-oid=] [--output-file=] +$ +$ snmprec.py --agent-address 127.0.0.1 --start-oid=1.3.6.1.2.1.2.1.0 --stop-oid=1.3.6.1.2.1.5 --output-file=devices/linux/slackware/1.3.6.1.2.1/127.0.0.1\@public.snmprec +OIDs dumped: 304, elapsed: 1.94 sec, rate: 157.00 OIDs/sec +$ +$ ls -l devices/linux/slackware/1.3.6.1.2.1/127.0.0.1\@public.snmprec +-rw-r--r-- 1 ilya users 16252 Oct 26 14:49 devices/linux/slackware/1.3.6.1.2.1/127.0.0.1@public.snmprec +$ +$ head devices/linux/slackware/1.3.6.1.2.1/127.0.0.1\@public.snmprec +1.3.6.1.2.1.2.2.1.1.1|2|1 +1.3.6.1.2.1.2.2.1.1.2|2|2 +1.3.6.1.2.1.2.2.1.2.1|4|lo +1.3.6.1.2.1.2.2.1.2.2|4|eth0 +1.3.6.1.2.1.2.2.1.3.1|2|24 +1.3.6.1.2.1.2.2.1.3.2|2|6 +1.3.6.1.2.1.2.2.1.4.1|2|16436 +1.3.6.1.2.1.2.2.1.4.2|2|1500 +1.3.6.1.2.1.2.2.1.5.1|66|10000000 +1.3.6.1.2.1.2.2.1.5.2|66|100000000 + +There are no special requirements for device file name and location. Note, +that Simulator treats device file path as an SNMPv1/v2c community string +and its MD5 hash constitutes SNMPv3 context name. + +Simulating SNMP Agents +---------------------- + +Your collection of device files should look like this: + +$ find devices +devices +devices/linux +devices/linux/slackware +devices/linux/slackware/1.3.6.1.2.1 +devices/linux/slackware/1.3.6.1.2.1/127.0.0.1@public.snmprec +devices/linux/slackware/1.3.6.1.2.1/127.0.0.1@public.dbm +devices/3com +devices/3com/switch8800 +devices/3com/switch8800/1.3.6.1.4.1 +devices/3com/switch8800/1.3.6.1.4.1/172.17.1.22@public.snmprec +devices/3com/switch8800/1.3.6.1.4.1/172.17.1.22@public.dbm +... + +Notice those .dbm files -- they are by-OID indices of device files used +for fast lookup. These indices are created and updated automatically by +Simulator. + +Getting help: + +$ snmpsimd.py -h +Usage: snmpsimd.py [--help] [--debug=] [--device-dir=] [--agent-address=] [--agent-port=] [--v2c-arch ] [--v3-user=] [--v3-auth-key=] [--v3-priv-key=] [--v3-priv-proto=] + +Running Simulator: + +$ snmpsimd.py --agent-port=1161 +Index ./devices/linux/slackware/1.3.6.1.2.1/127.0.0.1@public.dbm out of date +Indexing device file ./devices/linux/slackware/1.3.6.1.2.1/127.0.0.1@public.snmprec... +...303 entries indexed +Device file ./devices/linux/slackware/1.3.6.1.2.1/127.0.0.1@public.snmprec, dbhash-indexed, closed +SNMPv1/2c community name: @linux/slackware/1.3.6.1.2.1/127.0.0.1@public +SNMPv3 context name: 6d42b10f70ddb49c6be1d27f5ce2239e + +Device file ./devices/3com/switch8800/1.3.6.1.4.1/172.17.1.22@public.dump, dbhash-indexed, closed +SNMPv1/2c community name: @3com/switch8800/1.3.6.1.4.1/172.17.1.22@public +SNMPv3 context name: 1a80634d11a76ee4e29b46bc8085d871 + + +SNMPv3 credentials: +Username: simulator +Authentication key: auctoritas +Encryption (privacy) key: privatus +Encryption protocol: (1, 3, 6, 1, 6, 3, 10, 1, 2, 2) + +Listening at ('127.0.0.1', 1161) +... + +An unprivileged port is chosen in this example to avoid running as root. + +At this point you can run you favorite SNMP Manager to talk to either +of the two simulated devices. For instance, to talk to simulated Linux +box over SNMP v2: + +$ snmpwalk -On -v2c -c '@linux/slackware/1.3.6.1.2.1/127.0.0.1@public' localhost:1161 .1.3.6 +.1.3.6.1.2.1.2.2.1.1.1 = INTEGER: 1 +.1.3.6.1.2.1.2.2.1.1.2 = INTEGER: 2 +.1.3.6.1.2.1.2.2.1.2.1 = STRING: lo +.1.3.6.1.2.1.2.2.1.2.2 = STRING: eth0 +.1.3.6.1.2.1.2.2.1.3.1 = INTEGER: softwareLoopback(24) +.1.3.6.1.2.1.2.2.1.3.2 = INTEGER: ethernetCsmacd(6) +.1.3.6.1.2.1.2.2.1.4.1 = INTEGER: 16436 +.1.3.6.1.2.1.2.2.1.4.2 = INTEGER: 1500 +.1.3.6.1.2.1.2.2.1.5.1 = Gauge32: 10000000 +.1.3.6.1.2.1.2.2.1.5.2 = Gauge32: 100000000 +... + +To walk simulated 3com switch over SNMPv3 we'd run: + +$ snmpwalk -On -n 1a80634d11a76ee4e29b46bc8085d871 -u simulator -A auctoritas -X privatus -lauthPriv localhost:1161 .1.3.6 +.1.3.6.1.2.1.1.1.0 = STRING: 3Com SuperStackII Switch 1000, SW Version:2.0 +.1.3.6.1.2.1.1.2.0 = OID: .1.3.6.1.4.1.3.1.8.3 +.1.3.6.1.2.1.1.5.0 = STRING: Switch 1000 +.1.3.6.1.2.1.1.6.0 = STRING: 3Com +.1.3.6.1.2.1.11.11.0 = Counter32: 0 +.1.3.6.1.2.1.11.12.0 = Counter32: 0 +.1.3.6.1.2.1.11.13.0 = Counter32: 1942 +.1.3.6.1.2.1.11.16.0 = Counter32: 1384 +.1.3.6.1.2.1.11.17.0 = Counter32: 0 +.1.3.6.1.2.1.11.18.0 = Counter32: 0 +... + +Notice "-n " parameter passed to snmpwalk to address particular +simulated device at Simulator. + +Performance improvement +----------------------- + +The SNMPv3 architecture is inherently computationally heavy so Simulator +is somewhat slow. It can run faster if it would use a much lighter and +lower-level SNMPv2c architecture at the expense of not supporting v3 +operations. + +Use the --v2c-arch command line parameter to switch Simulator into SNMPv2c +operation mode. + +Installation +------------ + +First, download Simulator from SourceForge download servers. + +https://sourceforge.net/projects/snmpsim + +Then you can either install the scripts with standard + +$ python setup.py install + +or simply run them off your home directory. + +To run Simulator you need to have pysnmp-4 and pyasn1 packages +available on your system. + +http://sourceforge.net/projects/pyasn1/ +http://sourceforge.net/projects/pysnmp/ + +For secure SNMPv3 communication,PyCrypto should also be installed: + +http://www.pycrypto.org + +Getting help +------------ + +If something does not work as expected, please try browsing snmpsim +mailing list archives: + +http://lists.sourceforge.net/mailman/listinfo/snmpsim-users + +or post your question to + +Feedback +-------- + +I'm interested in bug reports and fixes, suggestions and improvements. + +I'm also interested in collecting SNMP snapshots taken from various +devices, so I'd eventually distribute it with the Simulator software +to let people test their SNMP Managers against many different devices. + +If you wish to contribute such a snapshot - please, run snmprec for +your device and send me its output file. Make sure that your device +does not have any private information. + +--- +Written by Ilya Etingof , 2010 diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..759d353 --- /dev/null +++ b/setup.py @@ -0,0 +1,39 @@ +#!/usr/bin/env python +import sys +import glob + +def howto_install_setuptools(): + print """Error: You need setuptools Python package! + +It's very easy to install it, just type (as root on Linux): + wget http://peak.telecommunity.com/dist/ez_setup.py + python ez_setup.py +""" + +try: + from setuptools import setup +except ImportError: + for arg in sys.argv: + if "egg" in arg: + howto_install_setuptools() + sys.exit(1) + from distutils.core import setup + +options = { + 'name': "snmpsim", + 'version': "0.0.8", + 'description': "SNMP devices simulator", + 'author': "Ilya Etingof", + 'author_email': "ilya@glas.net ", + 'url': "http://sourceforge.net/projects/snmpsim/", + 'scripts': [ 'snmpsimd.py', 'snmprec.py' ], + 'license': "BSD" + } + +if "py2exe" in sys.argv: + import py2exe + # fix executables + options['console'] = options['scripts'] + del options['scripts'] + +apply(setup, (), options)