
                        python-netsnmpagent Module
         Copyright (c) 2013 Pieter Hollants <pieter@hollants.com>
           Licensed under the GNU Public License (GPL) version 3


WHAT IS IT?

python-netsnmpagent is a Python module that facilitates writing Net-SNMP
subagents in Python. Subagents connect to a locally running Master agent
(snmpd) over a Unix domain socket (eg. "/var/run/agentx/master") and using the
AgentX protocol (RFC2747). They implement custom Management Information Base
(MIB) modules that extend the local node's MIB tree. Usually, this requires
writing a MIB as well, ie. a text file that specifies the structure, names
and data types of the information within the MIB module.

python-netsnmpagent was written after a lot of frustration trying to fix the
python-agentx module hosted on Sourceforge. I fixed some smaller issues there
but when it came to making sure that you could actually walk the whole MIB, not
just the variables registered, I realized that it would not make much sense to
reimplement the complete behavior of a proper SNMP agent when the NetSNMP API
actually can handle those things for you. Also, to be honest, I don't get
python-agentx's design :-)

python-netsnmpagent, by contrast, in the first line focusses on making the
net-snmp C agent API accessible from Python. Though I will try not to just
pass through every library call 1:1 but wrap them in a useful manner.

net-snmp itself also comes with a Python module (see the "python" subdirectory
in the source distribution), however it seems to offer bindings that implement
the client side only, not the agent side.


REQUIREMENTS

python-netsnmpagent requires the net-snmp libraries to be installed,
libnetsnmpagent to be precisely. The runtime library is enough, development
files are not necessary.


DOWNLOAD

The PyPI page with distribution archives is available at

  http://pypi.python.org/pypi/netsnmpagent

Binary RPMs for SuSE distributions are available via search.opensuse.org and
the Open Build Service Project page at

  https://build.opensuse.org/package/show?package=python-netsnmpagent&project=home%3Apfhllnts

If you wish to follow development more closely clone the GitHub:

  https://github.com/pief/python-netsnmpagent.git


INSTALLATION

If you do not use a ready package for your Linux distribution, you can install
directly from source using

  python setup.py install

This will most probably require appropriate rights (eg. being "root").


EXAMPLE USAGE

There is a well-commented example subagent included, example.py, together with
an example MIB, surprisingly named EXAMPLE-MIB.txt. Here's some step-by-step
instructions:

1. Make sure net-snmp is installed, snmpd in particular.

2. Run the included "run_example_agent.sh" script. This scripts runs snmpd with
   a special configuration file on TCP port 5555 and starts the included
   example agent.

3. From a separate console, run the example SNMP client utilities as written
   to the screen, eg.:

   $ snmpwalk -v 2c -c public -M+. localhost EXAMPLE-MIB::exampleMIB
   EXAMPLE-MIB::exampleUnsigned.0 = Gauge32: 0
   EXAMPLE-MIB::exampleUnsignedRO.0 = Gauge32: 0
   EXAMPLE-MIB::exampleInteger.0 = INTEGER: 0
   EXAMPLE-MIB::exampleIntegerRO.0 = INTEGER: 0
   [...]

   The "-v" option selects version 2c of the SNMP protocol, "-c" specifies the
   community to use. The special configuration used here uses a read-only
   community string "public" and a read-write community string "example" (for
   use with eg. snmpset).

   The "-M" option modifies the search path for referenced MIBs. Since
   we reference EXAMPLE-MIB in the specification of the root OID to walk and
   we have not copied EXAMPLE-MIB.txt to the system's MIBs directory
   /usr/share/snmp/mibs, we extend (the plus sign "+") the search path with the
   current directory (which should be the python-netsnmpagent directory).

   EXAMPLE-MIB::exampleMIB references the root node in the EXAMPLE-MIB. If you
   haven't looked at the MIB yet, you should probably do so now.

If you wish to run the example agent against your system-wide snmpd instance,
your /etc/snmp/snmpd.conf (path may vary) should contain lines similar to the
following:
   
  # Required to allow subagents to connect to snmpd via AgentX protocol
  master agentx
   
  # Required for read-only access from localhost
  rocommunity public 127.0.0.1
   
  # Required for read-write access from localhost
  rwcommunity <yoursecret> 127.0.0.1
     
For SNMP versions 1 and 2c (which are basically those I care about for now),
replace "<yoursecret>" with a secret not too obvious, since it is the only
protection against unauthorized write access, safe for the localhost access
restriction.

Because connecting to the system-wide snmpd's AgentX socket requires root
rights, start the example agent using sudo:
   
  $ sudo python example.py 
  username's password:
  NET-SNMP version 5.7.1 AgentX subagent connected
  Serving SNMP requests, press ^C to terminate...


API

Admittedly the API for writing your own subagents in Python is nowhere next to
stable yet. For now, please see the example_agent.py source code for info on
how to use the python-netsnmpagent module, but notice that this may change at
any time. You might want to follow development on the GitHub repo:

  https://github.com/pief/python-netsnmpagent.git


TODO

- stabilize API
- unit tests


CREDITS

python-netsnmpagent was inspired by python-agentx, courtesy of Bozhin Zafirov
<bozhin@abv.bg>. I blatantly ripped some ideas and some lines of code, shame
on me.

SNMP contexts support and various other additions were implemented by Steven
Hiscocks <steven@hiscocks.me.uk>.
