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.
6eecf339c0