		  The Python 'netsnmp' Extension Module
		      for the Net-SNMP Library

Contents:
   Introduction:
   Availability:
   Contact:
   Supported Platforms:
   Release Notes:
   Installation:
   Operational Description:
   Trouble Shooting:
   Acknowledgments:
   License/Copyright:

Introduction:

   This is the Python 'netsnmp' extension module. The 'netsnmp' module
   provides a full featured, tri-lingual SNMP (SNMPv3, SNMPv2c,
   SNMPv1) client API. The 'netsnmp' module internals rely on the
   Net-SNMP toolkit library. For information on the Net-SNMP library
   see the documentation provided with the Net-SNMP distribution or
   the project web page available on 'Source Forge':

   http://www.net-snmp.org/

Availability:

   The most recent release of the Python 'netsnmp' module can be found
   bundled with the latest Net-SNMP distribution available from:

     http://www.net-snmp.org/download.html

Contact:

   The following mailing list should be consider the primary support
   mechanism for this module:

   net-snmp-users@lists.sourceforge.net mail list

   (see http://www.net-snmp.org/lists/users/ to subscribe)

Supported Platforms:

   Linux 2.x
   Other UNIX/POSIX variants (untested)
   MS Windows (untested)

   Let us know where it *doesn't* work, as it should on most systems

Release Notes:

   This initial alpha release of the Python 'netsnmp' extension module
   has been developed against net-snmp 5.4.pre1.

   Only syncronous, client-side functionality is implemented.

   Access to the parsed MIB database is not yet implemented.

KNOWN BUGS:

   Too many to mention at this point

Installation:

   Build and install the Net-SNMP package - see Net-SNMP README and
   INSTALL docs.

   Unix:

   cd net-snmp/python
   python setup.py build
   python setup.py test (requires a locally running agent w/ config provided)
   python setup.py install


Operational Description:

   The basic operations of the SNMP protocol are provided by this
   module through an object oriented interface for modularity and ease
   of use.  The primary class is netsnmp.Session which encapsulates
   the persistent aspects of a connection between the management
   application and the managed agent. This class supplies 'get',
   'getnext', 'getbulk', 'set' and other method calls. 

   A description of the fields which can be specified when instantiating an
   netsnmp.Session follows:

   netsnmp.Session(<tag>=<value>, ... )

    DestHost    - default 'localhost', hostname or ip addr of SNMP agent
    Version     - default '3', [1, 2 (equiv to 2c), 3]
    RemotePort  - default '161', allow remote UDP port to be overridden
    Timeout     - default '500000', micro-seconds before retry
    Retries     - default '3', retries before failure
    RetryNoSuch - default '0', if enabled NOSUCH errors in 'get' pdus will
                  be repaired, removing the varbind in error, and resent -
                  undef will be returned for all NOSUCH varbinds, when set
                  to '0' this feature is disabled and the entire get request
                  will fail on any NOSUCH error (applies to v1 only)
    UseLongNames - set to non-zero to have <tags> for 'getnext' methods 
                  generated preferring longer Mib name convention (e.g., 
		  system.sysDescr vs just sysDescr)
    UseSprintValue - set to non-zero to have return values
                  for 'get' and 'getnext' methods formatted with the libraries
                  sprint_value function. This will result in certain data types
                  being returned in non-canonical format Note: values returned
                  with this option set may not be appropriate for 'set' 
                  operations (see discussion of value formats in <vars> 
                  description section)
    UseEnums    - set to non-zero to have integer return values
                  converted to enumeration identifiers if possible, 
                  these values will also be acceptable when supplied to 
                  'set' operations
    UseNumeric  - set to non-zero to have <tags> returned by the 'get'
                  methods untranslated (i.e. dotted-decimal).  Setting the
                  UseLongNames value for the session is highly recommended.
    BestGuess   - this setting controls how <tags> are parsed.  setting 
                  to 0 causes a regular lookup.  setting to 1 causes a regular 
                  expression match (defined as -Ib in snmpcmd). setting to 2 
                  causes a random access lookup (defined as -IR in snmpcmd).
    ErrorStr    - read-only, holds the error message assoc. w/ last request
    ErrorNum    - read-only, holds the snmp_err or status of last request
    ErrorInd    - read-only, holds the snmp_err_index when appropriate

   SNMPv1/SNMPv2c options:
    Community   - default 'public', SNMP community string (used for both R/W)

   SNMPv3 Options:
    SecName     - default 'initial', security name (v3)
    SecLevel    - default 'noAuthNoPriv', security level [noAuthNoPriv,
                  authNoPriv, authPriv] (v3)
    ContextEngineId - default <SecEngineId>, context engineID, will be
                      probed if not supplied (v3)
    Context     - default '', context name (v3)

   SNMPv3 over TLS or DTLS options:
    OurIdentity   - The fingerprint or file name for the local X.509
                    certificate to use for our identity.  Run
                    net-snmp-cert to create and manage certificates.
    TheirIdentity - The fingerprint or file name for the local X.509
                    certificate to use for their identity.  
    TrustCert     - A trusted certificate to use for validating
                    certificates.  Typically this would be a CA
                    certificate.
    TheirHostname - Their hostname to expect.  Either "TheirIdentity"
    		    or a trusted certificate plus a hostname is needed
    		    to validate the server is the proper server.
    
   SNMPv3 with USM security Options:
    SecEngineId - default <none>, security engineID, will be probed if not
                  supplied (v3)
    AuthProto   - default 'MD5', authentication protocol [MD5, SHA] (v3)
    AuthPass    - default <none>, authentication passphrase
    PrivProto   - default 'DES', privacy protocol [DES] (v3)
    PrivPass    - default <none>, privacy passphrase (v3)

   private:
    sess_ptr    - internal field used to cache a created session structure

   methods:

    get(<netsnmp.VarList object>)
                    - SNMP GET a netsnmp.VarList object must be supplied,
		      returns a tuple of values for each varbind in list

    getnext(<netsnmp.VarList object>)
                    - SNMP GETNEXT, a netsnmp.VarList object must be supplied
                      returns retrieved value(s), VarList passed as arguments
		      are updated to return a list of next lexicographical 
		      Varbind objects. returns a tuple of values for each 
		      varbind in list

    set(<netsnmp.VarList object>)
                    - SNMP SET, a netsnmp.VarList object must be supplied
                      the value field in all Varbinds must be in a canonical
                      format (i.e., well known format) to ensure unambiguous
                      translation to SNMP MIB data value (see discussion of
                      canonical value format <vars> description section),
                      returns true on success or None on error. 

    getbulk(<non-repeaters>, <max-repeaters>, <netsnmp.VarList object>)
                    - SNMP GETBULK, a netsnmp.VarList object must be supplied
                      the single next lexico instance is fetched for the first 
		      n Varbinds in the list as defined by <non-repeaters>. 
                      For the remaining Varbinds, the next m lexico instances 
                      are retrieved each of the remaining Varbinds, 
                      where m is <max-repeaters>. Returns a tuple of values 
		      retrieved.

    walk(<netsnmp.VarList object>)
             	    - Performs multiple GETNEXT requests in order to
             	      return a tuple of values retrieved from the MIB
             	      below the Varbind passed in.  The VarList passed
             	      in will be updated to contain a complete set of
             	      Varbinds created for the results of the walk.

             	      Note that only one varbind should be contained in the
             	      VarList passed in.  The code is structured to maybe
             	      handle this is the the future, but right now walking
             	      multiple trees at once is not yet supported and will
             	      produce insufficient results.


   Acceptable variable formats:

    netsnmp.VarList:  - represents an list of Varbind objects to get or set.
                        takes are arguments and unspecified number of Varbinds,
			or tuples which will be converted to Varbinds.


    netsnmp.Varbind:  - represents a single MIB object to get or set
			implemented as Python[<tag>, <iid>, <val>, <type>].
			<tag>  - one of the following forms:
                           1) leaf identifier (e.g., 'sysDescr') assumed to be
                           unique for practical purposes
                           2) fully qualified identifier (e.g.,
   			   '.iso.org.dod.internet.mgmt.mib-2.system.sysDescr')
                           3) fully qualified, dotted-decimal, numeric OID 
			   (e.g., '.1.3.6.1.2.1.1.1')
                      <iid>  - the dotted-decimal, instance identifier. for
                               scalar MIB objects use '0'
   		      <val>  - the SNMP data value retrieved from or being set
                               to the agents MIB. for set operations the <val> 
                               format must be canonical to ensure unambiguous 
			       translation. The canonical forms are as follows:
			    OBJECTID => dotted-decimal (e.g., .1.3.6.1.2.1.1.1)
			    OCTETSTR => perl scalar containing octets,
			    INTEGER => decimal signed integer (or enum),
			    NETADDR => dotted-decimal,
			    IPADDR => dotted-decimal,
			    COUNTER => decimal unsigned integer,
			    COUNTER64  => decimal unsigned integer,
			    GAUGE,  => decimal unsigned integer,
			    UINTEGER,  => decimal unsigned integer,
			    TICKS,  => decimal unsigned integer,
			    OPAQUE => perl scalar containing octets,
			    NULL,  => perl scalar containing nothing,

                      <type> - SNMP data type (see list above), this field is
                               populated by 'get' and 'getnext' operations. In
                               some cases the programmer needs to populate this
                               field when passing to a 'set' operation. this
                               field need not be supplied when the attribute
                               indicated by <tag> is already described in the
                               parsed MIB. for 'set's, if a numeric OID is used
                               and the object is not in the parsed MIB,
                               the <type> field must be supplied


   Python 'netsnmp' package variables and functions:


    netsnmp.verbose       - default '0', 
                            controls warning/info output of themodule 
			    0 => no output, 
			    1 => enables warning/info

(needs implementation)
    $SNMP::debugging     - default '0', controls debugging output level
                           within SNMP module and libsnmp
                           1 => enables 'SNMP::verbose' (see above)
                           2 => level 1 plus snmp_set_do_debugging(1),
                           3 => level 2 plus snmp_set_dump_packet(1)

    $SNMP::dump_packet   - default '0', set [non-]zero to independently set
                           snmp_set_dump_packet()

   Exported 'netsnmp' package utility functions:

   snmpget(<Varbind/VarList>, <Session args>) 
             - takes args of netsnmp.Session preceded by those of the 
               corresponding netsnmp.Session method. Returns a tuple with 
               Varbind values fetched, and input is updated to contain
               complete Varbinds fetched. 

   snmpgetnext(<Varbind/VarList>, <Session args>)
             - takes args of netsnmp.Session preceded by those of the
               corresponding netsnmp.Session method. Returns a tuple with 
               Varbind values fetched, and input is updated to contain
               complete Varbinds fetched. 

   snmpgetbulk(nonrepeaters, maxrepetitions,<VarList>, <Session args>)
             - takes args of netsnmp.Session preceded by those of the
               corresponding netsnmp.Session method. Returns a tuple with 
               Varbind values fetched, and VarList is updated to contain
               complete Varbinds fetched. 

   snmpset(<Varbind/VarList>, <Session args>)
             - takes args of netsnmp.Session preceded by those of the
               corresponding netsnmp.Session method. returns True on success,
               otherwise False.

   snmpwalk(<Varbind/VarList>, <Session args>)) 
             - takes args of netsnmp.Session preceded by a Varbind or
               VarList from which the 'walk' operation will start.
               Returns a tuple of values retrieved from the MIB below
               the Varbind passed in.  If a VarList is passed in it
               will be updated to contain a complete set of VarBinds
               created for the results of the walk.  It is not
               recommended to pass in just a Varbind since you loose
               the ability to examine the returned OIDs.  But, if only
               a Varbind is passed in it will be returned unaltered.

               Note that only one varbind should be contained in the
               VarList passed in.  The code is structured to maybe
               handle this is the the future, but right now walking
               multiple trees at once is not yet supported and will
               produce insufficient results.

Trouble Shooting:

   If problems occur there are number areas to look at to narrow down the
   possibilities.

   The first step should be to test the Net-SNMP installation
   independently from the Python 'netsnmp' Extension.

   Try running the apps from the Net-SNMP distribution.

   Make sure your agent (snmpd) is running and properly configured with
   read-write access for the community you are using.

   Ensure that your MIBs are installed and environment variables are set
   appropriately (see man mib_api)

   Be sure to ensure headers and libraries from old CMU installations are
   not being used by mistake (see -NET-SNMP-PATH).

   If the problem occurs during compilation/linking check that the snmp
   library being linked is actually the Net-SNMP library (there have been
   name conflicts with existing snmp libs).

   Also check that the header files are correct and up to date.

   Sometimes compiling the Net-SNMP library with
   'position-independent-code' enabled is required (HPUX specifically).

   If you cannot resolve the problem you can email 
   net-snmp-users@lists.sourceforge.net.

   Please give sufficient information to analyze the problem (OS type,
   versions for OS/python/net-SNMP/compiler, complete error output, etc.)

Acknowledgments:

   Giovanni Marzot (the original author)
   ScienceLogic, LLC sponsored the initial development of this module.
   Wes Hardaker and the net-snmp-coders

   Thanks in advance to any who supply patches, suggestions and feedback.

License:

   Please see the LICENSE file contained with this package

Copyright:

   Copyright (c) 2006 G. S. Marzot. All rights reserved.
   This program is free software; you can redistribute it and/or
   modify it under the same terms as Net-SNMP itself.

   Copyright (c) 2006 SPARTA, Inc.  All Rights Reserved.  This
   program is free software; you can redistribute it and/or modify
   it under the same terms as Net-SNMP itself.