1 The Python 'netsnmp' Extension Module
2 for the Net-SNMP Library
3
4Contents:
5 Introduction:
6 Availability:
7 Contact:
8 Supported Platforms:
9 Release Notes:
10 Installation:
11 Operational Description:
12 Trouble Shooting:
13 Acknowledgments:
14 License/Copyright:
15
16Introduction:
17
18 This is the Python 'netsnmp' extension module. The 'netsnmp' module
19 provides a full featured, tri-lingual SNMP (SNMPv3, SNMPv2c,
20 SNMPv1) client API. The 'netsnmp' module internals rely on the
21 Net-SNMP toolkit library. For information on the Net-SNMP library
22 see the documentation provided with the Net-SNMP distribution or
23 the project web page available on 'Source Forge':
24
25 http://www.net-snmp.org/
26
27Availability:
28
29 The most recent release of the Python 'netsnmp' module can be found
30 bundled with the latest Net-SNMP distribution available from:
31
32 http://www.net-snmp.org/download.html
33
34Contact:
35
36 The following mailing list should be consider the primary support
37 mechanism for this module:
38
39 net-snmp-users@lists.sourceforge.net mail list
40
41 (see http://www.net-snmp.org/lists/users/ to subscribe)
42
43Supported Platforms:
44
45 Linux 2.x
46 Other UNIX/POSIX variants (untested)
47 MS Windows (untested)
48
49 Let us know where it *doesn't* work, as it should on most systems
50
51Release Notes:
52
53 This initial alpha release of the Python 'netsnmp' extension module
54 has been developed against net-snmp 5.4.pre1.
55
56 Only syncronous, client-side functionality is implemented.
57
58 Access to the parsed MIB database is not yet implemented.
59
60KNOWN BUGS:
61
62 Too many to mention at this point
63
64Installation:
65
66 Build and install the Net-SNMP package - see Net-SNMP README and
67 INSTALL docs.
68
69 Unix:
70
71 cd net-snmp/python
72 python setup.py build
73 python setup.py test (requires a locally running agent w/ config provided)
74 python setup.py install
75
76
77Operational Description:
78
79 The basic operations of the SNMP protocol are provided by this
80 module through an object oriented interface for modularity and ease
81 of use. The primary class is netsnmp.Session which encapsulates
82 the persistent aspects of a connection between the management
83 application and the managed agent. This class supplies 'get',
84 'getnext', 'getbulk', 'set' and other method calls.
85
86 A description of the fields which can be specified when instantiating an
87 netsnmp.Session follows:
88
89 netsnmp.Session(<tag>=<value>, ... )
90
91 DestHost - default 'localhost', hostname or ip addr of SNMP agent
92 Version - default '3', [1, 2 (equiv to 2c), 3]
93 RemotePort - default '161', allow remote UDP port to be overridden
94 Timeout - default '500000', micro-seconds before retry
95 Retries - default '3', retries before failure
96 RetryNoSuch - default '0', if enabled NOSUCH errors in 'get' pdus will
97 be repaired, removing the varbind in error, and resent -
98 undef will be returned for all NOSUCH varbinds, when set
99 to '0' this feature is disabled and the entire get request
100 will fail on any NOSUCH error (applies to v1 only)
101 UseLongNames - set to non-zero to have <tags> for 'getnext' methods
102 generated preferring longer Mib name convention (e.g.,
103 system.sysDescr vs just sysDescr)
104 UseSprintValue - set to non-zero to have return values
105 for 'get' and 'getnext' methods formatted with the libraries
106 sprint_value function. This will result in certain data types
107 being returned in non-canonical format Note: values returned
108 with this option set may not be appropriate for 'set'
109 operations (see discussion of value formats in <vars>
110 description section)
111 UseEnums - set to non-zero to have integer return values
112 converted to enumeration identifiers if possible,
113 these values will also be acceptable when supplied to
114 'set' operations
115 UseNumeric - set to non-zero to have <tags> returned by the 'get'
116 methods untranslated (i.e. dotted-decimal). Setting the
117 UseLongNames value for the session is highly recommended.
118 BestGuess - this setting controls how <tags> are parsed. setting
119 to 0 causes a regular lookup. setting to 1 causes a regular
120 expression match (defined as -Ib in snmpcmd). setting to 2
121 causes a random access lookup (defined as -IR in snmpcmd).
122 ErrorStr - read-only, holds the error message assoc. w/ last request
123 ErrorNum - read-only, holds the snmp_err or status of last request
124 ErrorInd - read-only, holds the snmp_err_index when appropriate
125
126 SNMPv1/SNMPv2c options:
127 Community - default 'public', SNMP community string (used for both R/W)
128
129 SNMPv3 Options:
130 SecName - default 'initial', security name (v3)
131 SecLevel - default 'noAuthNoPriv', security level [noAuthNoPriv,
132 authNoPriv, authPriv] (v3)
133 ContextEngineId - default <SecEngineId>, context engineID, will be
134 probed if not supplied (v3)
135 Context - default '', context name (v3)
136
137 SNMPv3 over TLS or DTLS options:
138 OurIdentity - The fingerprint or file name for the local X.509
139 certificate to use for our identity. Run
140 net-snmp-cert to create and manage certificates.
141 TheirIdentity - The fingerprint or file name for the local X.509
142 certificate to use for their identity.
143 TrustCert - A trusted certificate to use for validating
144 certificates. Typically this would be a CA
145 certificate.
146 TheirHostname - Their hostname to expect. Either "TheirIdentity"
147 or a trusted certificate plus a hostname is needed
148 to validate the server is the proper server.
149
150 SNMPv3 with USM security Options:
151 SecEngineId - default <none>, security engineID, will be probed if not
152 supplied (v3)
153 AuthProto - default 'MD5', authentication protocol [MD5, SHA] (v3)
154 AuthPass - default <none>, authentication passphrase
155 PrivProto - default 'DES', privacy protocol [DES] (v3)
156 PrivPass - default <none>, privacy passphrase (v3)
157
158 private:
159 sess_ptr - internal field used to cache a created session structure
160
161 methods:
162
163 get(<netsnmp.VarList object>)
164 - SNMP GET a netsnmp.VarList object must be supplied,
165 returns a tuple of values for each varbind in list
166
167 getnext(<netsnmp.VarList object>)
168 - SNMP GETNEXT, a netsnmp.VarList object must be supplied
169 returns retrieved value(s), VarList passed as arguments
170 are updated to return a list of next lexicographical
171 Varbind objects. returns a tuple of values for each
172 varbind in list
173
174 set(<netsnmp.VarList object>)
175 - SNMP SET, a netsnmp.VarList object must be supplied
176 the value field in all Varbinds must be in a canonical
177 format (i.e., well known format) to ensure unambiguous
178 translation to SNMP MIB data value (see discussion of
179 canonical value format <vars> description section),
180 returns true on success or None on error.
181
182 getbulk(<non-repeaters>, <max-repeaters>, <netsnmp.VarList object>)
183 - SNMP GETBULK, a netsnmp.VarList object must be supplied
184 the single next lexico instance is fetched for the first
185 n Varbinds in the list as defined by <non-repeaters>.
186 For the remaining Varbinds, the next m lexico instances
187 are retrieved each of the remaining Varbinds,
188 where m is <max-repeaters>. Returns a tuple of values
189 retrieved.
190
191 walk(<netsnmp.VarList object>)
192 - Performs multiple GETNEXT requests in order to
193 return a tuple of values retrieved from the MIB
194 below the Varbind passed in. The VarList passed
195 in will be updated to contain a complete set of
196 Varbinds created for the results of the walk.
197
198 Note that only one varbind should be contained in the
199 VarList passed in. The code is structured to maybe
200 handle this is the the future, but right now walking
201 multiple trees at once is not yet supported and will
202 produce insufficient results.
203
204
205 Acceptable variable formats:
206
207 netsnmp.VarList: - represents an list of Varbind objects to get or set.
208 takes are arguments and unspecified number of Varbinds,
209 or tuples which will be converted to Varbinds.
210
211
212 netsnmp.Varbind: - represents a single MIB object to get or set
213 implemented as Python[<tag>, <iid>, <val>, <type>].
214 <tag> - one of the following forms:
215 1) leaf identifier (e.g., 'sysDescr') assumed to be
216 unique for practical purposes
217 2) fully qualified identifier (e.g.,
218 '.iso.org.dod.internet.mgmt.mib-2.system.sysDescr')
219 3) fully qualified, dotted-decimal, numeric OID
220 (e.g., '.1.3.6.1.2.1.1.1')
221 <iid> - the dotted-decimal, instance identifier. for
222 scalar MIB objects use '0'
223 <val> - the SNMP data value retrieved from or being set
224 to the agents MIB. for set operations the <val>
225 format must be canonical to ensure unambiguous
226 translation. The canonical forms are as follows:
227 OBJECTID => dotted-decimal (e.g., .1.3.6.1.2.1.1.1)
228 OCTETSTR => perl scalar containing octets,
229 INTEGER => decimal signed integer (or enum),
230 NETADDR => dotted-decimal,
231 IPADDR => dotted-decimal,
232 COUNTER => decimal unsigned integer,
233 COUNTER64 => decimal unsigned integer,
234 GAUGE, => decimal unsigned integer,
235 UINTEGER, => decimal unsigned integer,
236 TICKS, => decimal unsigned integer,
237 OPAQUE => perl scalar containing octets,
238 NULL, => perl scalar containing nothing,
239
240 <type> - SNMP data type (see list above), this field is
241 populated by 'get' and 'getnext' operations. In
242 some cases the programmer needs to populate this
243 field when passing to a 'set' operation. this
244 field need not be supplied when the attribute
245 indicated by <tag> is already described in the
246 parsed MIB. for 'set's, if a numeric OID is used
247 and the object is not in the parsed MIB,
248 the <type> field must be supplied
249
250
251 Python 'netsnmp' package variables and functions:
252
253
254 netsnmp.verbose - default '0',
255 controls warning/info output of themodule
256 0 => no output,
257 1 => enables warning/info
258
259(needs implementation)
260 $SNMP::debugging - default '0', controls debugging output level
261 within SNMP module and libsnmp
262 1 => enables 'SNMP::verbose' (see above)
263 2 => level 1 plus snmp_set_do_debugging(1),
264 3 => level 2 plus snmp_set_dump_packet(1)
265
266 $SNMP::dump_packet - default '0', set [non-]zero to independently set
267 snmp_set_dump_packet()
268
269 Exported 'netsnmp' package utility functions:
270
271 snmpget(<Varbind/VarList>, <Session args>)
272 - takes args of netsnmp.Session preceded by those of the
273 corresponding netsnmp.Session method. Returns a tuple with
274 Varbind values fetched, and input is updated to contain
275 complete Varbinds fetched.
276
277 snmpgetnext(<Varbind/VarList>, <Session args>)
278 - takes args of netsnmp.Session preceded by those of the
279 corresponding netsnmp.Session method. Returns a tuple with
280 Varbind values fetched, and input is updated to contain
281 complete Varbinds fetched.
282
283 snmpgetbulk(nonrepeaters, maxrepetitions,<VarList>, <Session args>)
284 - takes args of netsnmp.Session preceded by those of the
285 corresponding netsnmp.Session method. Returns a tuple with
286 Varbind values fetched, and VarList is updated to contain
287 complete Varbinds fetched.
288
289 snmpset(<Varbind/VarList>, <Session args>)
290 - takes args of netsnmp.Session preceded by those of the
291 corresponding netsnmp.Session method. returns True on success,
292 otherwise False.
293
294 snmpwalk(<Varbind/VarList>, <Session args>))
295 - takes args of netsnmp.Session preceded by a Varbind or
296 VarList from which the 'walk' operation will start.
297 Returns a tuple of values retrieved from the MIB below
298 the Varbind passed in. If a VarList is passed in it
299 will be updated to contain a complete set of VarBinds
300 created for the results of the walk. It is not
301 recommended to pass in just a Varbind since you loose
302 the ability to examine the returned OIDs. But, if only
303 a Varbind is passed in it will be returned unaltered.
304
305 Note that only one varbind should be contained in the
306 VarList passed in. The code is structured to maybe
307 handle this is the the future, but right now walking
308 multiple trees at once is not yet supported and will
309 produce insufficient results.
310
311Trouble Shooting:
312
313 If problems occur there are number areas to look at to narrow down the
314 possibilities.
315
316 The first step should be to test the Net-SNMP installation
317 independently from the Python 'netsnmp' Extension.
318
319 Try running the apps from the Net-SNMP distribution.
320
321 Make sure your agent (snmpd) is running and properly configured with
322 read-write access for the community you are using.
323
324 Ensure that your MIBs are installed and environment variables are set
325 appropriately (see man mib_api)
326
327 Be sure to ensure headers and libraries from old CMU installations are
328 not being used by mistake (see -NET-SNMP-PATH).
329
330 If the problem occurs during compilation/linking check that the snmp
331 library being linked is actually the Net-SNMP library (there have been
332 name conflicts with existing snmp libs).
333
334 Also check that the header files are correct and up to date.
335
336 Sometimes compiling the Net-SNMP library with
337 'position-independent-code' enabled is required (HPUX specifically).
338
339 If you cannot resolve the problem you can email
340 net-snmp-users@lists.sourceforge.net.
341
342 Please give sufficient information to analyze the problem (OS type,
343 versions for OS/python/net-SNMP/compiler, complete error output, etc.)
344
345Acknowledgments:
346
347 Giovanni Marzot (the original author)
348 ScienceLogic, LLC sponsored the initial development of this module.
349 Wes Hardaker and the net-snmp-coders
350
351 Thanks in advance to any who supply patches, suggestions and feedback.
352
353License:
354
355 Please see the LICENSE file contained with this package
356
357Copyright:
358
359 Copyright (c) 2006 G. S. Marzot. All rights reserved.
360 This program is free software; you can redistribute it and/or
361 modify it under the same terms as Net-SNMP itself.
362
363 Copyright (c) 2006 SPARTA, Inc. All Rights Reserved. This
364 program is free software; you can redistribute it and/or modify
365 it under the same terms as Net-SNMP itself.
366