« back to all changes in this revision
Viewing changes to .pc/07_docfiles.patch/FAQ
- browse files at revision 44
- compare with another revision
- download diff
- download tarball
- view history from revision 44
- Committer: Bazaar Package Importer
- Author(s): Chuck Short
- Date: 2010-06-28 14:59:36 UTC
- mfrom: (1.2.3 upstream) (1.1.12 sid)
- Revision ID: james.westby@ubuntu.com-20100628145936-cbiallic69pn044g
Tags: 5.4.3~dfsg-1ubuntu1
* Merge from debian unstable. Remaining changes:
- Set Ubuntu maintainer address.
- net-snmp-config: Use bash. (LP: #104738)
- Removed multiuser option when calling update-rc.d. (LP: #254261)
- debian/snmpd.init: LSBify the init script.
- debian/patches/52_fix_snmpcmd_1_typo.patch: Adjust a typo in snmpcmd.1
(LP: #250459)
- debian/snmpd.postinst: source debconf before doing work, LP: #589056
- debian/snmp.preinst, debian/snmp.prerm: kill any/all processes owned by
snmp user before install/uninstall, LP: #573391
- Add apport hook (LP: #533603):
- debian/{snmp,snmpd}.apport: Added.
- debian/control: Build-depends on dh-apport.
- debian/rules:
+ Add --with apport.
+ override_dh_apport to install hook on snmpd package only.
* Dropped patches:
- debian/patches/99-fix-ubuntu-div0.patch: Fix dvision by zero..
- Set Ubuntu maintainer address.
- net-snmp-config: Use bash. (LP: #104738)
- Removed multiuser option when calling update-rc.d. (LP: #254261)
- debian/snmpd.init: LSBify the init script.
- debian/patches/52_fix_snmpcmd_1_typo.patch: Adjust a typo in snmpcmd.1
(LP: #250459)
- debian/snmpd.postinst: source debconf before doing work, LP: #589056
- debian/snmp.preinst, debian/snmp.prerm: kill any/all processes owned by
snmp user before install/uninstall, LP: #573391
- Add apport hook (LP: #533603):
- debian/{snmp,snmpd}.apport: Added.
- debian/control: Build-depends on dh-apport.
- debian/rules:
+ Add --with apport.
+ override_dh_apport to install hook on snmpd package only.
* Dropped patches:
- debian/patches/99-fix-ubuntu-div0.patch: Fix dvision by zero..
- files added:
- .pc
- .pc/02_statistics.patch
- .pc/02_statistics.patch/agent
- .pc/02_statistics.patch/agent/mibgroup
- .pc/02_statistics.patch/agent/mibgroup/mibII
- .pc/03_makefiles.patch
- .pc/03_makefiles.patch/local
- .pc/03_makefiles.patch/mibs
- .pc/05_searchdirs.patch
- .pc/05_searchdirs.patch/local
- .pc/06_extramibs.patch
- .pc/06_extramibs.patch/mibs
- .pc/07_docfiles.patch
- .pc/08_defaultconfig.patch
- .pc/25_duplicate_iftable.patch
- .pc/25_duplicate_iftable.patch/agent
- .pc/25_duplicate_iftable.patch/agent/mibgroup
- .pc/25_duplicate_iftable.patch/agent/mibgroup/if-mib
- .pc/25_duplicate_iftable.patch/agent/mibgroup/if-mib/data_access
- .pc/25_duplicate_iftable.patch/agent/mibgroup/if-mib/ifTable
- .pc/25_duplicate_iftable.patch/snmplib
- .pc/26_kfreebsd.patch
- .pc/26_kfreebsd.patch/agent
- .pc/26_kfreebsd.patch/agent/mibgroup
- .pc/26_kfreebsd.patch/agent/mibgroup/hardware
- .pc/26_kfreebsd.patch/agent/mibgroup/hardware/cpu
- .pc/26_kfreebsd.patch/include
- .pc/26_kfreebsd.patch/include/net-snmp
- .pc/26_kfreebsd.patch/include/net-snmp/system
- .pc/32_mnttab_path.patch
- .pc/44_nlist_kvm.patch
- .pc/56_manpage.patch
- .pc/56_manpage.patch/man
- .pc/60_libsensors_api.patch
- .pc/60_libsensors_api.patch/agent
- .pc/60_libsensors_api.patch/agent/mibgroup
- .pc/60_libsensors_api.patch/agent/mibgroup/ucd-snmp
- .pc/61_vacm_missing_dependency_check.patch
- .pc/61_vacm_missing_dependency_check.patch/agent
- .pc/61_vacm_missing_dependency_check.patch/apps
- .pc/62_add_lib_cflags.patch
- debian/source
- files removed:
- debian/README.source
- files modified:
- CHANGES
- dist/extractnews *
added
removed
.pc/07_docfiles.patch/FAQ
1
Frequently Asked Questions (FAQ) for the UCD/Net-SNMP package
2
=============================================================
3
FAQ Author: Dave Shield
4
Net-SNMP Version: 5.4.3 SVN branch
5
Net-SNMP/UCD-SNMP Project Leader: Wes Hardaker
6
Email: net-snmp-coders@lists.sourceforge.net
7
8
TABLE OF CONTENTS
9
=================
10
11
TABLE OF CONTENTS
12
GENERAL
13
What is it?
14
Where can I get it?
15
What documentation is available?
16
Are there binaries available?
17
What's the difference between UCD-SNMP and Net-SNMP?
18
What operating systems does it run on?
19
What happens if mine isn't listed?
20
Does it run on Windows?
21
How do I find out about new releases?
22
How can I find out what other people are doing?
23
How do I submit a patch or bug report?
24
Can I reuse the code in my commercial application?
25
What's the difference between SNMPv1, SNMPv2 and SNMPv3?
26
What's the difference between SNMPv2 and SNMPv2c?
27
Which versions of SNMP are supported in this package?
28
Can I use SNMPv1 requests with an SNMPv2 MIB (or vice versa)?
29
How can I monitor my system with SNMP?
30
Where can I find more information about network management?
31
What ports does SNMP use?
32
Is Net-SNMP thread safe?
33
APPLICATIONS
34
How do I add a MIB?
35
How do I add a MIB to the tools?
36
Why can't I see anything from the agent?
37
Why doesn't the agent respond?
38
I can see the system group, but nothing else. Why?
39
Why can't I see values in the <ENTERPRISE> tree?
40
The agent worked for a while, then stopped responding. Why?
41
Requesting an object fails with "Unknown Object Identifier" Why?
42
Why do I get "noSuchName" when asking for "sysUpTime" (or similar)?
43
Why do I sometimes get "End of MIB" when walking a tree, and sometimes not?
44
How do I use SNMPv3?
45
Why can't I set any variables in the MIB?
46
Variables seem to disappear when I try to set them. Why?
47
Why can't I change sysLocation (or sysContact)?
48
I get an error when trying to set a negative value - why?
49
I get an error when trying to query a string-indexed table value - why?
50
How should I specify string-indexed table values?
51
How do I send traps and notifications?
52
How do I receive traps and notifications?
53
How do I receive SNMPv1 traps?
54
Why don't I receive incoming traps?
55
My traphandler script doesn't work when run like this - why not?
56
How can the agent receive traps and notifications?
57
How big can an SNMP request (or reply) be?
58
How can I monitor my systems (disk, memory, etc)?
59
Applications complain about entries in your example 'snmp.conf' file. Why?
60
OK, what should I put in snmp.conf?
61
How do I specify IPv6 addresses in tools command line arguments?
62
PERL
63
What is the purpose of the Perl SNMP module?
64
Where can I get the Perl SNMP package?
65
How do I install the Perl SNMP modules?
66
But compiling this fails! Why?
67
Compiling the Perl module works OK, but 'make test' fails. Why?
68
Why can't mib2c (or tkmib) locate SNMP.pm?
69
Why can't mib2c (or tkmib) load SNMP.so?
70
Why can't tkmib locate Tk.pm?
71
Why does your RPM complain about missing Perl modules?
72
I've got a problem with the Net-SNMP module. Can you help?
73
MIBS
74
Where can I find a MIB compiler?
75
Why aren't my MIB files being read in?
76
Where should I put my MIB files?
77
What does "Cannot find module (XXX-MIB)" mean?
78
I'm getting answers, but they're all numbers. Why?
79
What does "unlinked OID" mean?
80
The parser doesn't handle comments properly. Why not?
81
How can I get more information about problems with MIB files?
82
What's this about "too many imported symbols"?
83
Do I actually need the MIB files?
84
AGENT
85
What MIBs are supported?
86
What protocols are supported?
87
How do I configure the agent?
88
How do I remove a MIB from the agent?
89
I've installed a new MIB file. Why can't I query it?
90
How do I add a MIB to the agent?
91
What's the difference between 'exec', 'sh', 'extend' and 'pass'?
92
What's the difference between AgentX, SMUX and proxied SNMP?
93
What is the purpose of 'dlmod'?
94
Which should I use?
95
Can I use AgentX when running under Windows?
96
How can I run AgentX with a different socket address?
97
How can I turn off SMUX support?
98
How can I combine two copies of the 'mib2' tree from separate subagents?
99
What traps are sent by the agent?
100
Where are these traps sent to?
101
How can I send a particular trap to selected destinations?
102
When I run the agent it runs and then quits without staying around. Why?
103
After a while the agent stops responding, and starts eating CPU time. Why?
104
How can I stop other people getting at my agent?
105
How can I listen on just one particular interface?
106
The agent is complaining about 'snmpd.conf'. Where is this?
107
Why does the agent complain about 'no access control information'?
108
How do I configure access control?
109
How do I configure SNMPv3 users?
110
The 'createUser' line disappears when I start the agent. Why?
111
What's the difference between /var/net-snmp and /usr/local/share/snmp?
112
My new agent is ignoring the old snmpd.conf file. Why?
113
Where should the snmpd.conf file go?
114
Why am I getting "Connection refused"?
115
Why can't I see values in the UCDavis 'extensible' or 'disk' trees?
116
Why can't I see values in the UCDavis 'memory' or 'vmstat' tree?
117
What do the CPU statistics mean - is this the load average?
118
How do I get percentage CPU utilization using ssCpuRawIdle?
119
What about multi-processor systems?
120
The speed/type of my network interfaces is wrong - how can I fix it?
121
The interface statistics for my subinterfaces are all zero - why?
122
Does the agent support the RMON-MIB?
123
What does "klread: bad address" mean?
124
What does "nlist err: wombat not found" (or similar) mean?
125
What does "Can't open /dev/kmem" mean?
126
The system uptime (sysUpTime) returned is wrong!
127
Can the agent run multi-threaded?
128
Can I use AgentX (or an embedded SNMP agent) in a threaded application?
129
COMPILING
130
How do I control the environment used to compile the software?
131
How do I control the environment used to compile the software under Windows?
132
Why does the compilation complain about missing libraries?
133
How can I reduce the memory footprint?
134
How can I reduce the installation footprint or speed up compilation?
135
How can I compile the project for use on an embedded system?
136
How can I compile the project to use static linking?
137
Why does 'make test' skip various tests?
138
Why does 'make test' complain about a pid file?
139
CODING
140
How do I write C code to integrate with the agent?
141
How does the agent fetch the value of a MIB variable from the system?
142
Mib2c complains about a missing "mib reference" - what does this mean?
143
Mib2c complains about not having a "valid OID" - what does this mean?
144
Why doesn't mib2c like the MIB file I'm giving it?
145
Mib2c ignores my MIB and generates a pair of 'mib-2' code files. Why?
146
What's the difference between the various mib2c configuration files?
147
Which mib2c configuration file should I use?
148
How can I have mib2c generate code for both scalars and tables?
149
Are there any examples, or documentation for developing MIB modules?
150
Where should I put the files produced by 'mib2c'?
151
Why doesn't my new MIB module report anything?
152
Why does the iterator call my get_{first,next} routines so often?
153
How can I get the agent to generate a trap (or inform)?
154
How can I get an AgentX sub-agent to generate a trap (or inform)?
155
How can I get the agent to send an SNMPv1 (or SNMPv2c) trap?
156
How can I get the agent to include varbinds with an SNMPv1 trap?
157
How can I get the agent to send an SNMPv1 enterprise-specific trap?
158
How can I get the agent to send an SNMPv3 trap (or inform)?
159
Why does calling 'send_v2trap' generate an SNMPv1 trap (or vice versa)?
160
How can I register a MIB module in a different (SNMPv3) context?
161
MISC
162
What ASN.1 parser is used?
163
What is the Official Slogan of the net-snmp-coders list?
164
165
166
GENERAL
167
=======
168
169
What is it?
170
----------
171
172
- Various tools relating to the Simple Network Management Protocol
173
including:
174
175
* An extensible agent
176
* An SNMP library
177
* tools to request or set information from SNMP agents
178
* tools to generate and handle SNMP traps
179
* a version of the unix 'netstat' command using SNMP
180
* a graphical Perl/Tk/SNMP based mib browser
181
182
This package is originally based on the Carnegie Mellon University
183
SNMP implementation (version 2.1.2.1), but has developed significantly
184
since then.
185
186
187
188
Where can I get it?
189
------------------
190
191
Download:
192
- http://www.net-snmp.org/download/
193
- ftp://ftp.net-snmp.org/pub/sourceforge/net-snmp/
194
Web page:
195
- http://www.net-snmp.org/
196
Sourceforge Project page:
197
- http://www.net-snmp.org/project/
198
Mirrors (note that sourceforge download servers are mirrored themselves):
199
- US: ftp://ftp.freesnmp.com/mirrors/net-snmp/
200
- Greece: ftp://ftp.ntua.gr/pub/net/snmp/net-snmp/
201
202
203
What documentation is available?
204
-------------------------------
205
206
This FAQ (!)
207
README and individual READMEs for various platforms
208
README.thread (discusses threading issues)
209
INSTALL
210
PORTING
211
EXAMPLE.conf
212
man pages for the individual tools, files and the API
213
A guide for extending the agent
214
Tutorials for both ucd-snmp v4 and net-snmp v5
215
at http://www.net-snmp.org/tutorial/
216
and http://www.net-snmp.org/tutorial-5/ respectively
217
218
Most of this documentation (plus archives of the mailing lists)
219
is also available on our web page:
220
221
http://www.net-snmp.org/
222
223
There is also a Wiki (including a community-maintained version
224
of this FAQ) at
225
226
http://www.net-snmp.org/wiki/
227
228
229
230
Are there binaries available?
231
----------------------------
232
233
There are binaries for some versions/systems available under
234
the "net-snmp binaries" package on the SourceForge "Files"
235
page, which is linked to from the main project download web
236
page at http://www.net-snmp.org/download.html.
237
238
These binaries are also available on the project FTP site,
239
with a link on the same web page.
240
241
There is also a mirror at ftp://ftp.freesnmp.org/mirrors/net-snmp/
242
243
244
245
What's the difference between UCD-SNMP and Net-SNMP?
246
---------------------------------------------------
247
248
Not a great deal, really.
249
Although the project originally started at UC Davis (hence the name),
250
and it has always been based there, most of the contributors have had
251
little or no connection with this institution.
252
253
The move to SourceForge was intended to provide a more flexible
254
environment for the project, and to distribute the administrative
255
workload more evenly. The change of name simply reflects this move,
256
which was the last remaining link with UC Davis.
257
258
The 4.2.x line saw the last releases made using the ucd-snmp name,
259
and all releases on this line have been been bug-fixes only. Release
260
5.0 was the first version released under the Net-SNMP name, and all
261
further development is being done on the 5.x code base. The 4.2.x
262
code line is now effectively closed down, as are the older 5.x branches.
263
264
Much of the work done for the various 5.x releases has involved
265
some fairly significant changes to the code - in particular the
266
architecture of the agent. However attempts have been made to retain
267
backwards compatibility as much as possible, and most code written
268
for earlier releases should continue to work. The most visible
269
change from the 4.2.x UCD suite to the 5.x Net-SNMP releases was a
270
restructuring of the header file organisation - not least a change
271
from <ucd-snmp/xxx.h> to <net-snmp/yyy.h>.
272
273
But given the maturity of the Net-SNMP code, this should be less
274
of a consideration for most current SNMP development projects.
275
276
277
278
What operating systems does it run on?
279
-------------------------------------
280
281
Both the applications and the agent have been reported as running
282
(at least in part) on the following operating systems:
283
284
* Linux (kernels 2.6 to 1.3)
285
* Solaris/SPARC (11 to 2.3), Solaris/Intel (10, 9) -- see
286
README.solaris
287
* HP-UX (11.31 to 9.01) -- see README.hpux11
288
* Mac OS X (10.5 to 10.1) -- see README.osX
289
* NetBSD (2.0 to 1.0)
290
* FreeBSD (7.0 to 2.2)
291
* OpenBSD (4.0 to 2.6)
292
* BSDi (4.0.1 to 2.1)
293
* AIX (6.1, 5.3, 5.2, 5.1, 4.3.3, 4.1.5, 3.2.5) -- see README.aix
294
* IRIX (6.5 to 5.1)
295
* OSF (4.0, 3.2 and Tru64 Unix 5.1B) -- see README.tru64
296
* SunOS 4 (4.1.4 to 4.1.2)
297
* Ultrix (4.5 to 4.2)
298
* Dynix/PTX 4.4
299
* QNX 6.2.1A
300
301
We have also been informed about a port to the Stratus VOS.
302
See http://ftp.stratus.com/vos/network/network.html for details.
303
304
See the next question but one for the status of Windows support.
305
306
Certain systems fail to compile particular portions of the agent.
307
These can usually be persuaded to compile (at the loss of some
308
functionality) by omitting the modules affected.
309
See the next question for more details.
310
311
Also note that the presence of a particular configuration in this
312
list does not imply a perfect or complete implementation. This
313
is simply what various people have reported as seeming to work.
314
(Or more frequently, the configurations where people have reported
315
problems that we think we've subsequently fixed!)
316
317
318
319
What happens if mine isn't listed?
320
---------------------------------
321
322
It's probably worth trying to compile it anyway. Unless your
323
system is significantly different to the supported configurations,
324
most of the code (library, applications and the agent infrastructure)
325
should probably compile with little or no difficulty. The most
326
likely source of problems will be MIB modules within the agent,
327
as this tends to be where the most system-specific code is found.
328
329
If only a few modules fail to compile, try removing them from
330
the agent by running "configure --with-out-mib-module=xxx,yyy",
331
and re-compiling. If a large number of modules fail, then it
332
might be easier to start from a relatively bare system, using
333
"configure --enable-mini-agent --with-defaults". Then if this
334
minimal agent compiles and runs successfully, try adding each of
335
the missing mibgroups individually using the configure option
336
'--with-mib-module'.
337
338
If configure fails with "invalid configuration" messages, or
339
you get completely stuck, contact the coders list for advice.
340
Similarly, if you manage to get this working on a new system,
341
please let us know of any code changes that you needed to make,
342
together with details of the hardware you're using, and what
343
versions of the operating system you've tried it on. The entry
344
'host' in the file 'config.status' should show this information.
345
Oh, and congratulations!
346
347
348
349
Does it run on Windows?
350
----------------------
351
352
The suite should compile and run on Win32 platforms, including
353
the library, command-line tools and the basic agent framework.
354
Note that the agent now includes support for the MIB-II module,
355
but this requires Microsoft's Core Platform SDK. Instructions
356
for how to install this are given in README.win32.
357
358
Pre-compiled binaries are available from the project web site.
359
360
As of v5.4, the Net-SNMP agent is able to load the Windows SNMP
361
service extension DLLs by using the Net-SNMP winExtDLL extension.
362
363
Some other Net-SNMP MIB modules, including the UCD pass-through
364
extensions, do not currently work under Windows. Volunteers to assist
365
with these missing modules are likely to welcomed with open arms :-)
366
367
Further details of Windows support (currently Visual C++, MinGW
368
and Cygnus cygwin32) is available in the file README.win32.
369
370
371
372
How do I find out about new releases?
373
------------------------------------
374
375
There is a mailing list for these announcements
376
377
net-snmp-announce@lists.sourceforge.net
378
379
To be added to (or removed from) this list, visit
380
http://www.net-snmp.org/lists/net-snmp-announce/
381
Or you can send a message to the address
382
net-snmp-announce-request@lists.sourceforge.net
383
with a subject line of 'subscribe' (or 'unsubscribe' as appropriate).
384
385
Advance notice of upcoming releases are also made on the
386
net-snmp-users list (for "release candidates") for a week
387
or two before the full release, and on the net-snmp-coders
388
list (for "pre-releases") during the period prior to this.
389
390
Major code revisions may be announced more widely, but these
391
lists are the most reliable way to keep in touch with the
392
status of the package.
393
394
Patches to fix known problems are also made available via the web site:
395
396
http://www.net-snmp.org/patches/
397
398
399
400
How can I find out what other people are doing?
401
----------------------------------------------
402
403
There is a general purpose discussion list
404
405
net-snmp-users@lists.sourceforge.net
406
407
To be added to (or removed from) this list, visit
408
http://www.net-snmp.org/lists/net-snmp-users/
409
Or you can send a message to the address
410
net-snmp-users-request@lists.sourceforge.net
411
with a subject line of 'subscribe' (or 'unsubscribe' as appropriate).
412
413
To find out what the developers are doing, and to help them
414
out, please read the PORTING file enclosed with the package.
415
416
There is also a #net-snmp IRC channel set up on the freenode.net
417
chat system. You can connect to this via chat.freenode.net.
418
See http://www.freenode.net/ for more information on getting
419
started with IRC.
420
Several core developers hang out on this channel on a fairly
421
regular basis.
422
423
424
425
How do I submit a patch or bug report?
426
-------------------------------------
427
428
The best way to submit a bug report is via the bug database through
429
the interface found at
430
http://www.net-snmp.org/bugs/
431
Be sure to include the version of the package that you've been working
432
with, the output of the command 'uname -a', the precise configuration
433
or command that triggers the problem and a copy of any output produced.
434
435
Questions about using the package should be directed at the
436
net-snmp-users@lists.sourceforge.net mailing list. Note that this
437
mailing list is relatively busy, and the people answering these
438
questions are doing so out of the goodness of their hearts, and in
439
addition to their main employment. Please note the following:
440
441
- use plain text mail, rather than HTML
442
- don't resend questions more than once
443
(even if no-one answered immediately)
444
- include full details of exact commands and error messages
445
("I've tried everything, and it doesn't work" isn't much use!)
446
- do *NOT* send messages to -users and -coders mailing lists
447
(most developers read both anyway)
448
- don't mail the developers privately - keep everything on the list
449
450
We can't promise to be able to solve all problems, but we'll
451
certainly try and help. But remember that this is basically an
452
unsupported package. It's Open Source, so if you need something
453
fixing badly enough, fundamentally it's up to you to do the work.
454
455
All patches should be submitted to the patch manager at
456
http://www.net-snmp.org/patches/
457
If possible, submit a bug report describing the patch as well
458
(referencing it by its patch number) since the patch manager
459
doesn't contain a decent description field.
460
461
The best way to submit patch (diff) information is by checking out
462
the current code from the development SVN trunk, making your changes
463
and then running "svn diff" after you're done.
464
465
If you're working from a source code distribution, and comparing old
466
and new versions of a code file, use "diff -u OLDFILE NEWFILE"
467
468
469
470
Can I reuse the code in my commercial application?
471
-------------------------------------------------
472
473
The details of the COPYRIGHTs on the package can be found in the COPYING
474
file. You should have your lawyer read this file if you wish to use the
475
code in your commercial application. We will not summarize here what is
476
in the file, as we're not lawyers and are unqualified to do so.
477
478
479
480
What's the difference between SNMPv1, SNMPv2 and SNMPv3?
481
-------------------------------------------------------
482
What's the difference between SNMPv2 and SNMPv2c?
483
------------------------------------------------
484
485
A full description is probably beyond the scope of this FAQ.
486
Very briefly, the original protocol and admin framework was
487
described in RFCs 1155-1157, and is now known as SNMPv1.
488
489
Practical experience showed up various problems and deficiencies
490
with this, and a number of revised frameworks were developed to try
491
and address these problems. Unfortunately, it proved difficult to
492
achieve any sort of agreement - particularly over the details of
493
the administrative framework to use.
494
495
There was less disagreement over the proposed changes to the
496
protocol operations. These included:
497
* increasing the range of errors that could be reported
498
* introducing "exception values"
499
(so a single missing value didn't affect
500
the other varbinds in the same request)
501
* a new GETBULK operation
502
(a supercharged GETNEXT)
503
* new notification PDUs
504
(closer in structure to the other request PDUs)
505
506
Strictly speaking, it's this revised protocol (originally defined
507
in RFC 1905, and most recently in RFC 3416) that is "SNMPv2".
508
509
The only framework based on this protocol that saw a significant
510
level of use was "Community-based SNMPv2" or "SNMPv2c" (defined
511
in RFC 1901). This retained the same administrative framework
512
as SNMPv1 (with all of the accompanying limitations), but using
513
the new protocol operations.
514
515
More recently, a new administrative framework has been developed,
516
building on the various competing SNMPv2 proposals, and using the
517
same SNMPv2 protocol operations. This is SNMPv3, which is defined
518
in RFCs 3411-3418. It addresses some of the deficiencies of the
519
community-based versions, including significant improvements to
520
the security of SNMP requests (like it finally has some!).
521
SNMPv3 is now a full IETF standard protocol.
522
523
Strictly speaking, SNMPv3 just defines a fairly abstract framework,
524
based around the idea of "Security Models" and "Access Control Models".
525
It's this combination of SNMPv3 plus accompanying models that actually
526
provides a working SNMP system.
527
However, the only models in common use are the "User-based Security
528
Model" (RFC 3414) and the "View-based Access Control Model" (RFC 3415).
529
So "SNMPv3" is frequently used to mean the combination of the basic
530
SNMPv3 framework with these two particular models.
531
This is also sometimes described as "SNMPv3/USM".
532
533
534
So in brief:
535
- SNMPv2c updated the protocol operations
536
but left the administrative framework unchanged.
537
- SNMPv3 updated the administrative framework
538
but left the protocol operations unchanged.
539
540
541
542
Which versions of SNMP are supported in this package?
543
----------------------------------------------------
544
545
This package currently supports the original SNMPv1 (RFC 1157),
546
Community-based SNMPv2 (RFCs 1901-1908), and SNMPv3 (RFCs 3411-3418).
547
The agent will respond to requests using any of these protocols,
548
and all the tools take a command-line option to determine which
549
version to use.
550
551
Support for SNMPv2 classic (a.k.a. "SNMPv2 historic" - RFCs 1441-1452)
552
was dropped with the 4.0 release of the UCD-snmp package.
553
554
555
556
Can I use SNMPv1 requests with an SNMPv2 MIB (or vice versa)?
557
------------------------------------------------------------
558
559
Yes.
560
561
The syntax used to specify a MIB file (better referred
562
to as SMIv1 or SMIv2) is purely concerned with how to define
563
the characteristics of various management objects. This is
564
(almost) completely unrelated to the versions of the protocol
565
used to operate on these values. So it is quite reasonable to
566
use SNMPv1 requests on objects defined using SMIv2, or SNMPv2
567
(or SNMPv3) requests on objects defined using SMIv1.
568
569
The one exception is objects of syntax Counter64, which are
570
only accessible using SNMPv2 or higher. SNMPv1 requests will
571
either treat such objects as an error, or skip them completely.
572
573
Note that SMIv1 is effectively obsolete, and all new MIBs
574
should be written using SMIv2.
575
576
577
578
How can I monitor my system with SNMP?
579
-------------------------------------
580
581
There are two main methods of using SNMP for monitoring. One is to regularly
582
query the SNMP agent for information of interest, graphing these values and/or
583
saving them for later analysis. That's not really the focus of the Net-SNMP
584
project - our tools are more low-level, single-shot commands. For this sort
585
of high-level management, you're really looking at a management console
586
application (such as Nagios or OpenNMS), or a data logging application
587
(such as RRDtool, or one of its front-ends - MRTG, Cacti, etc).
588
589
The other approach is to configure the SNMP agent to monitor the relevant
590
information itself, and issue an alert when the values pass suitable limits.
591
See the section ACTIVE MONITORING in the snmpd.conf(5) man page for details.
592
593
Note that this entry makes no reference as to _what_ you should monitor, or
594
what values might be significant. That's because it is impossible to provide
595
a universal answer to these questions. The information to monitor, and the
596
normal operating values will ultimately depend on your local environment.
597
SNMP is simply a tool to _help_ you manage your systems - it isn't a magic
598
panacea - you still have to think for yourself!
599
600
601
602
Where can I find more information about network management?
603
----------------------------------------------------------
604
605
There are a number of sites with network management information on
606
the World Wide Web. Some of the most useful are
607
608
http://www.simpleweb.org/
609
http://www.snmplink.org/
610
http://www.mibdepot.com/
611
612
The SNMP Usenet newsgroup is now mostly defunct, but although the
613
FAQ hasn't been updated for a while, it still contains a large
614
amount of useful information relating to SNMP, including books,
615
software, other sites, how to get an enterprise number, etc, etc.
616
This is available from
617
618
ftp://rtfm.mit.edu/pub/usenet/comp.protocols.snmp/
619
620
or via any of the Web sites above.
621
622
623
624
What ports does SNMP use?
625
------------------------
626
627
There are three main network ports (and one named socket), which are
628
typically used by SNMP. These are:
629
630
- UDP port 161 - SNMP requests (GET* and SET)
631
- UDP port 162 - SNMP notifications (Traps/Informs)
632
- TCP port 705 - AgentX
633
- /var/agentx/master - AgentX
634
635
However, these are simply the default "well-known" ports for these purposes,
636
and it is perfectly possible to accept requests on other ports.
637
638
639
640
Is Net-SNMP thread safe?
641
-----------------------
642
643
Strictly speaking, no. However, it is possible to use the library within
644
a multi-threaded management application. This is covered in detail in
645
the file README.thread (shipped with the standard distribution), but can
646
be summarised as follows:
647
648
- Call 'snmp_sess_init()' prior to activating any threads.
649
This reads in and parses MIB information (which isn't thread-safe)
650
as well as preparing a session structure for subsequent use.
651
652
- Open an SNMP session using 'snmp_sess_open()' which returns an
653
opaque session handle, which is essentially independent of any
654
other sessions (regardless of thread).
655
656
- Resource locking is not handled within the library, and is the
657
responsibility of the main application.
658
659
The Net-SNMP agent has not been designed for multi-threaded use. It
660
should be safe to use the agent library to embed a subagent within a
661
threaded application as long as *all* SNMP-related activity (including
662
generating traps, and parsing MIBs) is handled within a single thread.
663
664
The command-line tools shipped as part of the Net-SNMP distribution
665
are simple single-threaded applications, and are not designed for
666
multi-threaded use. Adapting these to a threaded model is left as
667
an exercise for the student.
668
The same holds true for the notification receiver (snmptrapd).
669
670
Unfortunately, the SNMPv3 support was added about the same time as
671
the thread support and since they occurred in parallel the SNMPv3
672
support was never checked for multi-threading correctness. It is
673
most likely that it is not thread-safe at this time.
674
675
676
APPLICATIONS
677
============
678
679
How do I add a MIB?
680
------------------
681
682
This is actually two separate questions, depending on whether you
683
are referring to the tools, or the agent (or both).
684
See the next question or the next section respectively.
685
686
687
688
How do I add a MIB to the tools?
689
-------------------------------
690
691
Adding a MIB to the client-side tools has two main effects:
692
693
- it allows you to refer to MIB objects by name
694
(rather than having to use the numeric OIDs)
695
- it allows the results to be displayed in a more immediately
696
meaningful fashion. Not just giving the object names, but
697
also showing named enumeration values, and interpreting table
698
indexes properly (particularly for string and OID index values).
699
700
There are two steps required to add a new MIB file to the tools.
701
Firstly, copy the MIB file into the appropriate location:
702
703
cp MY-MIB.txt /usr/local/share/snmp/mibs
704
(which makes it available to everyone on the system)
705
or
706
mkdir $HOME/.snmp
707
mkdir $HOME/.snmp/mibs
708
cp MY-MIB.txt $HOME/.snmp/mibs
709
(which makes it available to you only)
710
711
Note that the location of the shared MIB directory may be different
712
from that given here - see the FAQ entry "Where should I put my MIB
713
files?" for more information.
714
715
716
Secondly, tell the tools to load this MIB:
717
718
snmpwalk -m +MY-MIB .....
719
(load it for this command only)
720
or
721
export MIBS=+MY-MIB
722
(load it for this session only)
723
or
724
echo "mibs +MY-MIB" >> $HOME/.snmp/snmp.conf
725
(load it every time)
726
727
Note that the value for this variable is the name of the MIB
728
module, *not* the name of the MIB file. These are typically the
729
same (apart from the .txt suffix), but if in doubt, check the contents
730
of the file. The value to use is the token immediately before the
731
word DEFINITIONS at the start of the file.
732
733
Or use the special value "all" to have the tools load all available
734
MIBs (which may slow them down, particularly if you have a large
735
number of MIB files.
736
737
Note that you need *both* steps.
738
739
740
Adding a MIB in this way does *not* mean that the agent will
741
automatically return values from this MIB. The agent needs to be
742
explicitly extended to support the new MIB objects, which typically
743
involves writing new code.
744
See the AGENT section for details.
745
746
Most of the tools (apart from 'snmptable') will work quite happily
747
without any MIB files at all - although the results won't be displayed
748
in quite the same way. Similarly, the agent doesn't need MIB files
749
either (other than to handle MIB object names in the configuration file).
750
751
752
753
Why can't I see anything from the agent?
754
---------------------------------------
755
756
Fundamentally, there are two basic reasons why a request may go
757
unanswered. Either the management application does not like the
758
request (so never sends it), or the agent does not like the request
759
(so never responds). The simplest way to distinguish between the
760
two is to run the command with the command-line option '-d'.
761
762
If this doesn't display a hex dump of the raw outgoing packet, then
763
it's the client side which is dropping the request. Hopefully you
764
should also see an error message, to help identify what's wrong.
765
766
If this displays one or more outgoing dumps (but nothing coming back),
767
then the request is failing at the agent end. See the next entry for
768
more details.
769
770
771
There are three further possibilities to consider:
772
773
One is that the agent may return a response to the original query,
774
but the management application may not like this response, and refuse
775
to display it. This is relatively unusual, and typically indicates
776
a flaw with the remote agent. (I hope you're not contemplating the
777
suggestion that the Net-SNMP command-line tools might contain bugs!)
778
779
The typical symptoms of this would be that the '-d' option would
780
display a sequence of sending and received packet dumps, with the
781
same contents each time. Ask on the mailing list for advice.
782
783
784
Alternatively, the agent may simply not support the MIB objects being
785
requested. This is most commonly seen when using the "snmpwalk" tool
786
(particularly with SNMPv1).
787
788
The symptoms here would be that '-d' would show two pairs of raw
789
packet dumps - one a GETNEXT request (A1 in the sending packet),
790
followed by a GET request (A0). Repeating the same request with the
791
"snmpgetnext" command-line tool should show the information (if any)
792
that the agent returned, which was then discarded by snmpwalk as
793
irrelevant.
794
795
Note that this is how snmpwalk was designed to work. It is not an error.
796
797
798
Finally, it may be that the agent is simply taking too long to respond.
799
The easiest way to test for this is to add the command-line options
800
"-t 60 -r 0", which will send a single request (with no repetitions)
801
and wait for a minute before giving up. This ought to be long enough
802
for all but the most-overloaded agent, or inefficient MIB module!
803
804
If this turns out to be the cause, then ask on the mailing list for
805
advice on options for improving the performance.
806
807
808
809
Why doesn't the agent respond?
810
-----------------------------
811
812
Assuming that the tests outlined in the previous entry indicate that
813
the problem lies with the agent not responding, the obvious question
814
is "why not".
815
816
Again, there are two basic possibilities - either the agent never
817
sees the request, or it receives it but is unwilling (or unable) to
818
process it. If the remote system is running the Net-SNMP agent,
819
then the easiest way to distinguish between these two cases is to
820
shut down the agent, and re-start it manually using the options
821
-f -Le -d
822
Then send the same query as before. This should display raw dumps of
823
packets seen (or sent) by the agent, just as with the client side in
824
the previous entry.
825
826
827
If the agent does not display anything, then it is simply not receiving
828
the requests. This may be because they are being blocked by network
829
or local firewall settings ('iptables -L'), or the agent may not be
830
listening on the expected interfaces ('netstat -a').
831
832
This is most commonly encountered when running queries from a remote
833
host, particularly if the same request succeeds when run on the same
834
system as the agent itself.
835
836
837
If the agent displays a dump of the incoming request, but nothing going
838
out, then the most likely cause is access control settings. See the
839
relevant entries in the AGENT section for details. Note that if the agent
840
receives an SNMPv1 or SNMPv2c request with a unknown community string,
841
then it will not return an error response - the request is simply discarded.
842
843
Another possibility is that the request may be rejected by settings in
844
/etc/hosts.{allow,deny}. Again, '-d' will display an incoming packet
845
dump but no corresponding outgoing response. However in this situation,
846
the agent should also log a message that the request is being refused.
847
848
849
Running the agent with '-d' can also help identify situations where the
850
agent *is* responding to the request, but only after a long delay. This
851
would be indicated by a series of incoming packet dumps (showing various
852
retries from the client side), followed by several outgoing dumps - possibly
853
long after the client tool has given up in disgust.
854
See the entry
855
The agent worked for a while, then stopped responding. Why?
856
later in this section.
857
858
859
860
I can see the system group, but nothing else. Why?
861
--------------------------------------------------
862
863
This is almost definitely due to the access configuration of the agent.
864
Many pre-configured systems (such as most Linux distributions) will only
865
allow access to the system group by default, and need to be configured
866
to enable more general access.
867
868
The easiest way to test this is to try a GETNEXT request on one of
869
the other standard groups
870
e.g.
871
snmpgetnext ..... interfaces
872
873
If the agent responds with "hrSystemUptime.0" or "end of MIB", then it
874
is clearly configured in this way. See the entries on access control
875
in the AGENT section for more information.
876
877
878
879
Why can't I see values in the <ENTERPRISE> tree?
880
-----------------------------------------------
881
882
If you can see most of the standard information (not just the system and
883
hrSystem groups), but not in the vendor-specific 'enterprises' tree, then
884
once again there are several possible causes.
885
886
Firstly, it's possible that the agent does not implement this particular
887
enterprise tree. Remember that adding a MIB to the client tools does
888
*not* automatically add support for these object to the agent. See the
889
AGENT section for more information.
890
891
892
Alternatively, it may be that the agent does implement some or all of this
893
enterprise tree, but the access control settings are configured to block
894
access to it.
895
896
The simplest way to checks whether the agent implements a given portion
897
of the OID tree is to run
898
899
snmpwalk .... nsModuleName
900
901
and look for index values that fall in the area of interest.
902
(Always assuming that you have access to this particular section
903
of the Net-SNMP enterprise tree, of course!)
904
905
Checking the access control settings can be done by examining the tables
906
vacmAccessTable and vacmViewTreeFamilyTable. Note that these are used
907
to configure access control for *all* versions of SNMP - not just SNMPv3.
908
909
910
The third possibility is that simply isn't any information in the specified
911
tree. For example, several of the tables in the UCDavis enterprise tree
912
(such as prTable, extTable, dskTable and fileTable) require explicit
913
configuration in the snmpd.conf file. If you query this particular tables
914
without the necessary configuration entries, then they will be empty.
915
916
917
Finally, if you can't see anything from *any* enterprise-specific tree,
918
then this may be down to how you are asking for the information. By
919
default, if "snmpwalk" is run without an explicitly starting OID, then
920
it will display the contents of the 'mib-2' tree, containing most of the
921
IETF-standard management information supported by the agent.
922
923
When the agent reaches the end of this tree, it will return the first
924
enterprise-specific value, 'snmpwalk' will recognise that this marks the
925
end of the (implicit) requested tree, and stop. No enterprise-specific
926
information will be displayed.
927
928
To walk the whole tree, and see *all* the information that the
929
agent supports, specify a starting point of '.iso' or '.1'.
930
To walk a specific enterprise subtree, specify the root of this tree
931
as the starting point - e.g:
932
933
snmpwalk -v1 -c public localhost UCD-SNMP-MIB::ucdavis
934
935
There is more information about particular UCD-specific subtrees in
936
the AGENT section.
937
938
939
940
The agent worked for a while, then stopped responding. Why?
941
-----------------------------------------------------------
942
943
There are three basic possibilities:
944
- the agent has crashed
945
- it is hanging
946
- it is temporarily overloaded
947
948
Detecting whether the agent has crashed should be fairly straighforward.
949
If you can reliably reproduce this crash (e.g. by sending a particular
950
SNMP request), then contact the coders list for advice.
951
It's the other two cases that are probably more significant.
952
953
To tell the difference between these two, try leaving the agent
954
undisturbed for a while, and then probe it using a single 'snmpget'
955
request, specifying a longer timeout (e.g. '-t 120'). If it now
956
responds, then something was probably sending requests (including
957
duplicate retries) faster than the agent could process them, and it
958
was building up a backlog. Try adjusting the timeout period and retry
959
frequency of these client requests, or look at improving the efficiency
960
of the implementation of the relevant MIB objects.
961
962
If the agent remains unresponsive (particularly if the load on the
963
system is steadily climbing), then it's probably hanging, and all
964
you can really do is restart the agent. If you can identify what
965
causes this to happen, then contact the coders list for advice.
966
967
968
969
Requesting an object fails with "Unknown Object Identifier" Why?
970
----------------------------------------------------------------
971
972
If a general snmpwalk shows a particular entry, but asking for it more
973
specifically gives a "sub-identifier not found:" or "Unknown Object
974
Identifier" error, then that's a problem with the tool, rather than
975
the agent.
976
977
Firstly, make sure that you're asking for the object by the right name.
978
Object descriptors are case-sensitive, so asking for 'sysuptime' will
979
not be recognised, but 'sysUpTime' will.
980
981
Alternatively, the object may be defined in a MIB that hasn't been
982
loaded. Try loading in all the MIB files:
983
984
snmpget -m ALL -v1 -c public localhost sysUpTime.0
985
986
or specify the name of the appropriate MIB explicitly:
987
988
snmpget -v1 -c public myhost SNMPv2-MIB::sysUpTime.0
989
990
Note that this uses the name of the *module*, not the name of the file.
991
However, if 'snmpwalk' displays the object by name, this is unlikely to
992
be the cause, and you should look closely at the exact object name you
993
are using. In particular, see the next entry.
994
995
996
997
Why do I get "noSuchName" when asking for "sysUpTime" (or similar)?
998
------------------------------------------------------------------
999
1000
Assuming that you do have access to this object, the most likely cause
1001
is forgetting the instance subidentifier.
1002
1003
If you try walking the 'system' group (or any other part of the MIB tree),
1004
you should notice that all of the results have a number after the object
1005
name. This is the "instance subidentifier" of that particular MIB instance.
1006
1007
For values in tables (such as the sysORTable), this acts as an index into
1008
the table - a very familiar concept. But *all* SNMP values will display an
1009
instance number, whether or not they are part of a table. For non-table
1010
objects ("scalars"), this instance subidentifier will always be '0',
1011
and it *must* be included when making a GET request.
1012
1013
Compare the following:
1014
1015
$ snmpget -v1 -c public localhost sysUpTime
1016
Error in packet
1017
Reason: (noSuchName) There is no such variable name in this MIB.
1018
This name doesn't exist: system.sysUpTime
1019
1020
$ snmpget -v1 -c public localhost sysUpTime.0
1021
system.sysUpTime.0 = Timeticks: (69189271) 8 days, 0:11:32.71
1022
1023
This is a little less obscure when using SNMPv2c or v3 requests:
1024
1025
$ snmpget -v 2c -c public localhost sysUpTime
1026
system.sysUpTime = No Such Instance currently exists
1027
1028
1029
1030
Why do I sometimes get "End of MIB" when walking a tree, and sometimes not?
1031
--------------------------------------------------------------------------
1032
1033
This depends on which MIB modules are supported by the agent you are
1034
querying and exactly what you're asking for.
1035
1036
Note that a tree is walked by repeatedly asking for "the next entry" until
1037
all the values under that tree have been retrieved. However, the agent has
1038
no idea that this is what's happening - all it sees is a request for "the
1039
next entry after X".
1040
1041
If the object X happens to be the last entry in a sub-tree, the agent will
1042
provide the next object supported (as requested) even though this will be
1043
in a different subtree. It's up to the querying tool to recognise that
1044
this last result lies outside the area of interest, and simply discard it.
1045
1046
If the object X happens to be the last entry supported by the agent, it
1047
doesn't have another object to provide, so returns an "end of MIB"
1048
indication. The Net-SNMP tools report this with the message above.
1049
1050
But in either case, the actual information provided will be the same.
1051
1052
1053
1054
How do I use SNMPv3?
1055
-------------------
1056
1057
The simplest form of SNMPv3 request is unauthenticated and unencrypted
1058
(noAuthNoPriv). It simply requires a user name, and would look something
1059
like:
1060
1061
snmpget -v 3 -l noAuthNoPriv -u dave localhost sysUpTime.0
1062
1063
However this approach foregoes the security protection which is the
1064
main advantage of using SNMPv3 (and the agent must also be explicitly
1065
configured to allow unauthenticated requests from that user).
1066
1067
The most common form of SNMPv3 request is authenticated but not encrypted
1068
(authNoPriv). This specifies the pass phrase to authenticate with:
1069
1070
snmpget -v 3 -l authNoPriv -u dave -A "Open the Door"
1071
localhost sysUpTime.0
1072
1073
A fully secure (i.e. encrypted) request (authPriv) would also specify
1074
the privacy pass phrase:
1075
1076
snmpget -v 3 -l authPriv -u dave -A "Open the Door"
1077
-X "Bet you can't see me" localhost sysUpTime.0
1078
1079
In practise, most of these would probably be set via configuration
1080
directives in a personal $HOME/.snmp/snmp.conf file (note, *not* the
1081
agent's snmpd.conf file).
1082
The equivalent settings for the third example would be:
1083
1084
defSecurityName dave
1085
defSecurityLevel authPriv
1086
defAuthPassphrase "Open the Door"
1087
defPrivPassphrase "Bet you can't see me"
1088
1089
If the AuthPassphrase and the PrivPassphrase are the same, then you
1090
can use the single setting
1091
defPassphrase "Open the Door and see me"
1092
instead.
1093
1094
See the AGENT section for how to configure the agent for SNMPv3 access.
1095
1096
1097
1098
Why can't I set any variables in the MIB?
1099
----------------------------------------
1100
1101
There are three possible reasons for this:
1102
1103
Many MIB objects are defined as "read-only" and inherently cannot be
1104
changed via SET requests. Attempts to do so will typically be rejected
1105
by the 'snmpset' command without ever being sent to the agent.
1106
1107
Of those objects that can in principle be changed, the agent may not
1108
include the code necessary to support SET requests. (GET and GETNEXT
1109
are much easier to handle - particularly for objects relating to the
1110
internals of the underlying operating system).
1111
1112
Even if SET support has been implemented, the agent may not be configured
1113
to allow write access to this object.
1114
1115
Ready-installed distributions (such as those shipped with Linux) tend
1116
to be configured with read-only access to part of the mib tree (typically
1117
just the system group) and no write access at all.
1118
1119
To change this, you will need to set up the agent's access control
1120
configuration. See the AGENT section for more details.
1121
1122
Note that neither the community string "public" nor "private" can be
1123
used to set variables in a typical default configuration.
1124
1125
1126
1127
Variables seem to disappear when I try to set them. Why?
1128
--------------------------------------------------------
1129
1130
This is actually the same as the previous question - it just isn't
1131
particularly obvious, particularly when using SNMPv1. A typical
1132
example of this effect would be
1133
1134
$ snmpget -v1 -c public localhost sysLocation.0
1135
sysLocation.0 = somewhere nearby
1136
1137
$ snmpset -v1 -c public localhost sysLocation.0 s "right here"
1138
Error in packet.
1139
Reason: (noSuchName) There is no such variable name in this MIB.
1140
This name doesn't exist: sysLocation.0
1141
1142
Trying the same request using SNMPv2 or above is somewhat more informative:
1143
1144
$ snmpset -v 2c -c public localhost sysLocation.0 s "right here"
1145
Error in packet.
1146
Reason: notWritable
1147
1148
The SNMPv1 error 'noSuchName' actually means:
1149
1150
"You can't do that to this variable"
1151
1152
rather than "this variable doesn't exist".
1153
It may be the case that it doesn't exist at all. It may exist but you
1154
don't have access to it (although different administrative credentials
1155
might be accepted). Or it may exist, but you simply can't perform that
1156
particular operation (e.g. changing it).
1157
Similarly, the SNMPv2 error 'notWritable' means "not writable in this
1158
particular case" rather than "not writable under any circumstances".
1159
1160
If you are sure that the object is both defined as writable, and has been
1161
implemented as such, then you probably need to look at the agent access
1162
control. See the AGENT section for more details.
1163
But see the next entry first.
1164
1165
1166
1167
Why can't I change sysLocation (or sysContact)?
1168
----------------------------------------------
1169
1170
There is one final possibility to consider for why a SET request might
1171
be rejected.
1172
1173
The values for certain MIB objects (including 'sysLocation' and 'sysContact')
1174
can be configured via the snmpd.conf file. If this is done, then these
1175
particular objects become read-only, and cannot be updated via SET commands,
1176
even if the access control settings would otherwise allow it.
1177
1178
This may seem perverse, but there is good reason for it. If there is a
1179
configuration setting for one of these objects, then that value will be
1180
used whenever the agent re-starts. If the object was allowed to be updated
1181
using SET, this new value would be forgotten the next time the agent was
1182
re-started.
1183
1184
Hence the Net-SNMP agent rejects such requests if there's a value configured
1185
via the 'snmpd.conf' file. If there isn't such a config setting, then the
1186
write request will succeed (assuming suitable access control settings), and
1187
the new value will be retained the next time the agent restarts.
1188
1189
1190
1191
I get an error when trying to set a negative value - why?
1192
--------------------------------------------------------
1193
1194
This is a different problem. What's happening here is that the
1195
routine that parses the arguments to the 'snmpset' command is seeing
1196
the '-' of the new value, and treating it as a command-line option.
1197
This normally generates an error (since digits typically aren't valid
1198
command line options).
1199
1200
The easiest way to solve this is include the "end-of-option"
1201
indicator '--' in the command line, somewhere before the new value
1202
(but after all of the options, obviously). For example:
1203
1204
snmpset -v 2c -c public localhost -- versionRestartAgent.0 i -1
1205
1206
(This command will still fail, since -1 isn't an acceptable value for
1207
this particular object, but that's not the point here!)
1208
1209
1210
1211
I get an error when trying to query a string-indexed table value - why?
1212
----------------------------------------------------------------------
1213
1214
The Net-SNMP library will normally try to interpret string-based
1215
index values, and display them in a meaningful manner:
1216
1217
$ snmpgetnext .... vacmGroupName
1218
vacmGroupName.3."dave" = theWorkers
1219
1220
The command-line tools will also accept string-valued indexes within
1221
an OID, and convert them into the appropriate numeric form before
1222
sending an SNMP request. However the Unix shell will typically
1223
swallow the quotes around the string index value, before the SNMP
1224
tools can get a chance to interpret them.
1225
1226
The answer is to escape the quotes, to protect them from the shell,
1227
and allow them to be passed through to the OID parser:
1228
1229
snmpget .... vacmGroupName.3.\"dave\"
1230
or
1231
snmpget .... 'vacmGroupName.3."dave"'
1232
1233
1234
Another alternative is to avoid trying to specify the index value as
1235
a string, and provide the numeric subidentifiers directly:
1236
1237
snmpget .... vacmGroupName.3.4.100.97.118.101
1238
1239
(where '3' indicates SNMPv3, '4' is the length of the string index,
1240
followed by the ASCII values of the individual characters).
1241
1242
The command-line option '-Ob' will display the results of querying
1243
a string-indexed table in this format:
1244
1245
$ snmpgetnext -Ob .... vacmGroupName
1246
vacmGroupName.3.4.100.97.118.101 = theWorkers
1247
1248
1249
1250
How should I specify string-indexed table values?
1251
------------------------------------------------
1252
1253
There's one other aspect of string-indexed tables that can cause
1254
problems - the difference between implicit- and explicit-length
1255
strings, and how to represent these when making an SNMP query.
1256
1257
The most common style of string index uses an explicit length,
1258
followed by the individual ASCII character values:
1259
1260
"dave" = 4.'d'.'a'.'v'.'e'
1261
1262
(as shown in the previous entry).
1263
1264
However if the string index is defined in the MIB file as IMPLIED
1265
(or if it has a fixed length, such as a physical ethernet address),
1266
then the length subidentifier is omitted, and the index simply
1267
consists of the character values:
1268
1269
"dave" = 'd'.'a'.'v'.'e'
1270
1271
Note that IMPLIED index objects can only appear as the *last* index
1272
for a table.
1273
1274
The Net-SNMP library uses double quotes (i.e. "dave) to indicate an
1275
explicit length string index value, and single quotes (i.e. 'dave')
1276
to indicate an implicit length one. If you use the wrong style of
1277
quotes, then the resulting OID will be incorrect, and you'll get
1278
confusing results to your query.
1279
1280
1281
1282
How do I send traps and notifications?
1283
---------------------------------------
1284
1285
Traps and notifications can be sent using the command 'snmptrap'.
1286
The following examples generate the generic trap 'warmStart(1)' and a
1287
(dummy) enterprise specific trap '99' respectively:
1288
1289
snmptrap -v 1 -c public localhost "" "" 1 0 ""
1290
snmptrap -v 1 -c public localhost "" "" 6 99 ""
1291
1292
The empty parameters "" will use suitable defaults for the relevant
1293
values (enterprise OID, address of sender and current sysUptime).
1294
1295
An SNMPv2 or SNMPv3 notification (either trap or inform) takes
1296
the OID of the trap to send:
1297
1298
snmptrap -v 2c -c public localhost "" UCD-SNMP-MIB::ucdStart
1299
snmptrap -v 2c -c public localhost "" .1.3.6.1.4.1.2021.251.1
1300
1301
(These two are equivalent ways of specifying the same trap). Again,
1302
the empty parameter "" will use a suitable default for the relevant
1303
value (sysUptime).
1304
1305
Any of these commands can be followed by one or more varbinds,
1306
using the same (OID/type/value) syntax as for 'snmpset':
1307
1308
snmptrap -v 2c -c public localhost "" ucdStart sysContact.0 s "Dave"
1309
1310
Generating traps from within the agent, or other applications, is
1311
covered in the AGENT and CODING sections.
1312
1313
You should also read the snmptrap tutorial at
1314
http://www.net-snmp.org/tutorial-5/commands/snmptrap.html
1315
which will help you understand everything you need to know about traps.
1316
1317
1318
1319
How do I receive traps and notifications?
1320
----------------------------------------
1321
1322
Handling incoming traps is the job of a "notification receiver".
1323
The Net-SNMP suite include the tool 'snmptrapd' to act in this role.
1324
This can log traps to a file or via the syslog mechanism, forward them
1325
to another notification receiver and/or invoke a specified command
1326
whenever a particular notification is received.
1327
1328
Logging notifications would be done by starting snmptrapd as:
1329
snmptrapd -Ls 7 (log to syslog using 'LOCAL7')
1330
or
1331
snmptrapd -f -Lo (log to standard output)
1332
1333
Invoking a command to process a received notification uses one or
1334
more 'traphandle' directives in the configuration file 'snmptrapd.conf'.
1335
A typical configuration might look something like:
1336
1337
traphandle .1.3.6.1.6.3.1.5.1 /path/to/page_me up
1338
traphandle .1.3.6.1.4.1.2021.251.1 /path/to/page_me up
1339
traphandle .1.3.6.1.4.1.2021.251.2 /path/to/page_me down
1340
traphandle default /path/to/log_it
1341
1342
where 'page_me' and 'log_it' are the commands to be run.
1343
1344
Forwarding notifications to another receiver would be done using
1345
similar 'snmptrapd.conf' directives:
1346
1347
forward .1.3.6.1.4.1.8072.4.0.3 10.0.0.1
1348
forward default 10.0.0.2
1349
1350
There's a tutorial with more details on the web site at
1351
http://www.net-snmp.org/tutorial-5/commands/snmptrap.html
1352
1353
1354
1355
How do I receive SNMPv1 traps?
1356
-----------------------------
1357
1358
Directives in the 'snmptrapd.conf' file use the (SNMPv2) snmpTrapOID
1359
value to identify individual notifications. This applies to *all*
1360
versions of SNMP - including SNMPv1 traps. See the co-existence spec
1361
(RFC 2576) for details of mapping SNMPv1 traps to SNMPv2 OIDs.
1362
1363
Note that the first traphandle directive in the previous entry uses
1364
the OID corresponding to the SNMPv1 'coldStart' trap.
1365
1366
1367
1368
Why don't I receive incoming traps?
1369
----------------------------------
1370
1371
Starting with net-snmp 5.3, snmptrapd will no longer automatically
1372
accept all incoming traps. It must be configured with authorized
1373
SNMPv1/v2c community strings and/or SNMPv3 users. Non-authorized
1374
traps/informs will be dropped.
1375
Please refer to the snmptrapd.conf(5) manual page for details.
1376
1377
1378
1379
My traphandler script doesn't work when run like this - why not?
1380
---------------------------------------------------------------
1381
1382
If a traphandler script works fine when run manually from the
1383
command line, but fails or generates an error when triggered by
1384
an incoming notification, then there are two likely causes.
1385
1386
Firstly, the interactive shell environment may not be precisely
1387
the same as that for programs executed by the snmptrapd daemon.
1388
In particular, it's quite possible that the PATH environmental
1389
variable may not include all the additional directories that are
1390
commonly set up for a personal login configuration. To avoid this
1391
problem (particularly for traphandler shell scripts), it's worth
1392
giving the full path to all programs used within the script.
1393
1394
Secondly, the snmptrapd daemon may not always recognise the
1395
appropriate interpreter to use for a particular trap handler.
1396
If this is the case, then you can specify this interpreter
1397
explicitly as part of the trap handle directive:
1398
1399
traphandle default /usr/bin/perl /usr/local/bin/log_it
1400
1401
In this case, it's almost certain that you'll also
1402
need to give the full path to the traphandle script (as shown)
1403
1404
1405
1406
How can the agent receive traps and notifications?
1407
-------------------------------------------------
1408
1409
It can't.
1410
1411
The primary purpose of an SNMP agent is to handle requests for
1412
information from management applications. In SNMP terminology,
1413
it acts as a "command responder".
1414
1415
It may also issue traps to report significant events or conditions
1416
("notification generator"). But responding to such notifications
1417
is a significantly different role, and this is handled by a separate
1418
application ('snmptrapd'). Note that it is perfectly possible (even
1419
normal) for both agent and trap receiver to run on the same host.
1420
1421
1422
1423
How big can an SNMP request (or reply) be?
1424
-----------------------------------------
1425
1426
The protocol definition specifies a "minimum maximum" packet size
1427
(484 bytes for UDP), which all systems must support, but does not
1428
attempt to define an upper bound for this maximum size. This is left
1429
to each individual implementation.
1430
1431
The UCD software used a fixed size buffer of 1472 bytes to hold the
1432
encoded packet, so all requests and responses had to fit within this.
1433
The Net-SNMP releases handle packet buffers rather differently, and
1434
are not subject to the same fixed restrictions.
1435
1436
1437
1438
How can I monitor my systems (disk, memory, etc)?
1439
------------------------------------------------
1440
1441
In general, the Net-SNMP suite consists of relatively low-level
1442
tools, and there is nothing included that is designed for high-level,
1443
long-term monitoring of trends in network traffic, disk or memory
1444
usage, etc.
1445
1446
There are a number of packages available that are designed for this
1447
purpose. Two of the most widely used are MRTG (http://www.mrtg.org/)
1448
and RRDtool (http://oss.oetiker.ch/rrdtool/). There are also several
1449
frontends built on top of RRDtool, including Cacti (http://www.cacti.net/)
1450
and Cricket (http://cricket.sourceforge.net/). There are details of
1451
how to set up Cricket to monitor some of the UCD extensions at
1452
http://www.afn.org/~jam/software/cricket/
1453
1454
We have also set up a page that describes in detail how MRTG
1455
can be set up to monitor disk, memory and cpu activity at
1456
http://www.net-snmp.org/tutorial-5/mrtg/index.html
1457
1458
There is also a web-based network configuration system "Net-Policy",
1459
based upon SNMP. This is not strictly connected to the Net-SNMP project,
1460
but a number of the core developers are also involved with that system.
1461
See http://net-policy.sourceforge.net for more details.
1462
1463
1464
1465
Applications complain about entries in your example 'snmp.conf' file. Why?
1466
--------------------------------------------------------------------------
1467
1468
There *is* no example 'snmp.conf' shipped with the standard distribution.
1469
1470
The configuration file 'EXAMPLE.conf' is designed as a config for
1471
the agent, and should be installed as 'snmpd.conf' (note the 'd').
1472
The file 'snmp.conf' is intended for general configuration options,
1473
applicable to all applications (via the SNMP library).
1474
Rename (or merge) the 'snmp.conf' file to 'snmpd.conf', and this
1475
should fix the problem.
1476
1477
See the AGENT section or the 'snmpd.conf(5)' man page for more information
1478
about what should go in this file.
1479
1480
1481
1482
OK, what should I put in snmp.conf?
1483
----------------------------------
1484
1485
This is used to set common configuration values for most of the
1486
applications, to avoid having to specify them every time. Examples
1487
are the SNMPv3 settings mentioned above, defaults for which MIBs to
1488
load and where from (see the second entry in this section),
1489
and the default SNMP version, port and (if appropriate) community
1490
string to use.
1491
1492
Some of these (such as MIB information), might be best put in a
1493
shared snmp.conf file (typically /usr/local/share/snmp/snmp.conf or
1494
/etc/snmp/snmp.conf) to apply to all users of the system. Others
1495
(particularly the SNMPv3 security settings), are more likely to refer
1496
to a particular user, and should probably go in a personal snmp.conf
1497
file (typically $HOME/.snmp/snmp.conf).
1498
1499
See 'snmpget -H' and/or the snmp.conf(5) man page for more details.
1500
1501
You can also use the "snmpconf" command to help you generate your
1502
snmp.conf configuration file (just run it and answer its questions).
1503
1504
1505
1506
How do I specify IPv6 addresses in tools command line arguments?
1507
---------------------------------------------------------------
1508
1509
IPv6 addresses pose a particular problem for the Net-SNMP command
1510
line tools, which parse host names into pieces. In particular, normally
1511
if you specify a simple host name, it assumes you want UDP in IPv4 on
1512
port 161. By default, these two commands are actually the same:
1513
1514
snmpget 127.0.0.1 sysUpTime.0
1515
snmpget udp:127.0.0.1:161 sysUpTime.0
1516
1517
However, for IPv6 this causes a problem because IPv6 addresses also use
1518
a colon to separate addressing parts. Thus you need to enclose the address
1519
in square brackets ( [ and ] ).
1520
Because most shells use these brackets too, you also likely need to quote it:
1521
1522
snmpget 'udp6:[::1]:161' sysUpTime.0
1523
1524
1525
1526
PERL
1527
====
1528
1529
What is the purpose of the Perl SNMP module?
1530
-------------------------------------------
1531
1532
Short, comprehensive (but ultimately unhelpful) anwer - to provide a
1533
perl interface for SNMP operations.
1534
1535
Longer, incomplete (but more useful) answer - there are probably two
1536
main uses for the Perl SNMP module. The first is for developing client
1537
management applications, using perl to send SNMP requests, and manipulating
1538
or displaying the results. As such, this is a straight alternative to
1539
various other SNMP toolkits currently available (for both perl and other
1540
programming languages).
1541
1542
The second is as a means for extending the functionality of the Net-SNMP
1543
agent, by implementing new MIB modules. This is an alternative to the
1544
other script-based extension mechanisms, but is more tightly bound to the
1545
Net-SNMP agent (and hence more efficient), while still avoiding the need
1546
to write C code.
1547
1548
It is also possible to use the perl SNMP module in the snmpd.conf file,
1549
or to process incoming notifications, but the above are probably the
1550
two primary uses.
1551
1552
1553
1554
Where can I get the Perl SNMP package?
1555
-------------------------------------
1556
1557
Joe Marzot's excellent Perl 'SNMP' module, is included in the Net-SNMP
1558
source releases. It can be found located in the perl/SNMP subdirectory
1559
of the source tree. This is accompanied by a number of Perl modules
1560
grouped together under the NetSNMP namespace.
1561
1562
The basic SNMP module (though not the NetSNMP additions), can also
1563
be found at any Comprehensive Perl Archive Network (CPAN) mirror site,
1564
under modules/by-module/SNMP. To find the CPAN site nearest you,
1565
please see http://www.cpan.org/SITES.html.
1566
1567
These Perl modules need to be used in conjunction with a compatible
1568
version of the Net-SNMP library. Consult the README file in the SNMP
1569
Perl distribution to find out which version of the library it needs.
1570
1571
1572
1573
How do I install the Perl SNMP modules?
1574
--------------------------------------
1575
1576
Assuming you have a reasonably new (and properly configured) Perl system,
1577
this should be simply:
1578
1579
cd perl
1580
perl Makefile.PL
1581
(press RETURN when prompted for host and community)
1582
make
1583
make test
1584
make install (probably as root)
1585
1586
1587
It might be possible to install the basic module using
1588
1589
perl -MCPAN -e shell ; "install SNMP"
1590
1591
but this has not been reliably tested, and very much relies on
1592
having the correct version of the Net-SNMP library.
1593
1594
There may also be appropriate pre-compiled versions of the Perl modules
1595
available from the Net-SNMP project website, or your O/S vendor.
1596
1597
1598
1599
But compiling this fails! Why?
1600
-----------------------------
1601
1602
The Perl module tends to delve quite deeply into the internals of the
1603
main Net-SNMP library, and so is quite sensitive to changes within the
1604
library. It's important to use the correct version of the module, that
1605
corresponds to the version of the library you have installed. If you're
1606
working with a Net-SNMP source distribution, the appropriate versions of
1607
the Perl modules are shipped as part of the source code, but you *must*
1608
have run "make install" on the main Net-SNMP distribution *first*.
1609
1610
If you're working with a ready-installed version of the library, make
1611
sure you obtain a compatible version of the Perl module.
1612
1613
Note that the Perl modules will be compiled using the compiler
1614
(and compiler settings) used for compiling the original perl binary,
1615
*not* those used for compiling the Net-SNMP (or UCD) library.
1616
If these are different (e.g. 'gcc' used for one and 'cc' for the other)
1617
then this may well cause problems. It's much safer to use a consistent
1618
environment for both. This issue is discussed in greater detail in
1619
the README.solaris file.
1620
1621
Also note that the v5 Net-SNMP suite *must* be configured to provide
1622
shared libraries in order for the Perl modules to work correctly. This
1623
is not necessary with the v4 UCD-SNMP libraries.
1624
1625
1626
1627
Compiling the Perl module works OK, but 'make test' fails. Why?
1628
--------------------------------------------------------------
1629
1630
That's difficult to answer in general.
1631
Some of the Perl tests are rather picky, so this may simply be
1632
some minor inconsistency between your precise setup, and the
1633
expectations of the test environment.
1634
1635
Check that you are working with the Perl distribution that matches
1636
the SNMP libraries (use the 'perl/SNMP' in preference to CPAN), and
1637
that you have installed the main libraries successfully (uninstall
1638
any old versions if you're having trouble).
1639
1640
If all this looks OK, and if most of the tests pass, then it's
1641
probably safe to run 'make install' anyway. Probably.
1642
1643
1644
1645
Why can't mib2c (or tkmib) locate SNMP.pm?
1646
-----------------------------------------
1647
1648
That's probably because the SNMP Perl module hasn't been installed.
1649
It's not part of the standard Perl distribution, nor is it included
1650
in the default Fedora Linux installation (for example).
1651
You'll need to install it yourself.
1652
1653
See the second entry in this section.
1654
1655
1656
1657
Why can't mib2c (or tkmib) load SNMP.so?
1658
---------------------------------------
1659
1660
This is probably the same problem. Either the SNMP module
1661
hasn't been installed, or it's the wrong version. See the
1662
previous questions.
1663
1664
1665
1666
Why can't tkmib locate Tk.pm?
1667
----------------------------
1668
1669
Tk.pm is another Perl package that needs to be installed before tkmib
1670
will run. It's also available on Perl CPAN. We suggest using version
1671
"Tk800.011" or later. It can be installed by issuing the command:
1672
1673
perl -MCPAN -e shell ; "install Tk"
1674
1675
1676
1677
Why does your RPM complain about missing Perl modules?
1678
-----------------------------------------------------
1679
1680
This has been particularly noted on RedHat 9, complaining about the
1681
module "perl(Term::ReadKey)" - even if this is actually present (e.g.
1682
having been installed directly from CPAN). In fact, this is not
1683
specific to Perl modules - the same issue can potentially arise with
1684
other RPM dependencies.
1685
1686
The problem is that the RPM mechanism keeps a local database of what
1687
software packages have been installed, and checks this for any other
1688
features that this RPM requires. If software is installed "manually"
1689
rather than via rpm packages, then it will not appear in this database.
1690
Attempting to install another RPM that rely on this functionality will
1691
then complain about the "missing" package, because the RPM system doesn't
1692
know that's it's actually available.
1693
1694
The ideal solution is to *always* install software using a consistent
1695
mechanism (which may involve building RPMs locally, or looking for a
1696
suitable pre-built version).
1697
1698
Failing this, it's possible to tell the "rpm" command to ignore such
1699
dependencies, and install the package anyway. Try:
1700
1701
rpm -i --nodeps {package}
1702
1703
In this situation, it's then up to you to make sure that any other
1704
necessary packages *are* actually present on the system.
1705
1706
1707
1708
I've got a problem with the Net-SNMP module. Can you help?
1709
----------------------------------------------------------
1710
1711
Sorry, despite the similar-sounding name, the Net-SNMP (or Net::SNMP)
1712
module is nothing to do with this package, or the NetSNMP modules.
1713
Net::SNMP is a "pure-perl" implementation of SNMP support, developed
1714
by David Town. The developers of the (C-based) Net-SNMP suite do
1715
not have any significant experience in using this particular module,
1716
and you'll probably be better off asking for help via CPAN or some
1717
other perl-related forum.
1718
1719
1720
1721
MIBS
1722
====
1723
1724
Where can I find a MIB compiler?
1725
-------------------------------
1726
1727
That depends what you mean by a "MIB compiler". There are at least two
1728
types of tool that are commonly referred to by this name.
1729
1730
The first is a tool to check MIB files for validity. With the Net-SNMP
1731
software, this functionality is mostly integrated within the MIB parser,
1732
and hence included in all the applications. The tool 'snmptranslate' is
1733
probably the most appropriate for this purpose.
1734
1735
Note that the parser is fairly forgiving (see 'What ASN.1 parser is used'
1736
below), so this should not be regarded as a stamp of approval. For a
1737
more rigourous validation, use a tool such as 'smilint', or the on-line
1738
interface at http://wwwsnmp.cs.utwente.nl/ietf/mibs/validate/
1739
1740
The second type of "MIB compiler" is one to turn a MIB specification
1741
into C code, specifically one designed to aid agent implementation. The
1742
command 'mib2c' is an example of such a tool for the Net-SNMP agent.
1743
See the CODING section for more information.
1744
1745
1746
1747
Why aren't my MIB files being read in?
1748
-------------------------------------
1749
1750
There are two basic likely causes - either the library isn't attemping to
1751
load these particular MIB files, or it's trying to load them but can't
1752
locate them.
1753
1754
By default, the Net-SNMP library loads a specific subset of MIB files.
1755
This list is set when the suite is first configured and compiled, and
1756
basically corresponds to the list of modules that the agent supports.
1757
(This is a simplification, but is a reasonable first approximation).
1758
1759
In order to load additional MIB files, it is necessary to add them to this
1760
default list. See the FAQ entry "How do I add a MIB to the tools?" for
1761
more information about how to do this.
1762
1763
1764
Alternatively, the tools may be looking in the wrong place. The directory
1765
where the library looks for MIB files is also set when the software is
1766
first configured and compiled. If you put new MIB files in the wrong
1767
location, then the library won't be able to find them (and will complain).
1768
1769
This problem may arise when switching from a vendor-supplied distribution
1770
to one compiled from source (or vice versa).
1771
See the next entry for more information.
1772
1773
1774
1775
Where should I put my MIB files?
1776
-------------------------------
1777
1778
If you've compiled the package from source (or are using binaries
1779
from the project website), then you should probably put new MIB
1780
files in the directory /usr/local/share/snmp/mibs
1781
1782
If you are using vendor-supplied binaries, then the MIB files
1783
may well be located somewhere else (e.g. /usr/share/snmp/mibs,
1784
/opt/snmp/mibs, or /etc/sma/snmp/mibs). Have a look for where
1785
existing MIB files are installed, and try adding your MIBs to
1786
the same directory.
1787
1788
If you compiled the source yourself, but specified a different
1789
--prefix value when running configure, then the location of the
1790
MIB directory will be {prefix}/share/snmp/mibs.
1791
1792
If you're still not sure where to put your MIB files, try running
1793
the command
1794
1795
snmpget -Dparse-mibs 2>&1 | grep directory
1796
1797
This will display the location(s) where the library is looking
1798
for MIB files.
1799
1800
1801
1802
What does "Cannot find module (XXX-MIB)" mean?
1803
---------------------------------------------
1804
1805
If this error is only generated for one or two modules, then it's
1806
likely that the named modules are not being found - perhaps they're
1807
not installed in the correct location, are not readable, or the
1808
name being used is incorrect. See the previous entries and the entry
1809
"How do I add a MIB to the tools?" for more details.
1810
1811
Note that the name reported is the name of the MIB *module*, which is
1812
not necessarily the same as the name of the file.
1813
1814
1815
If there are a large number of such errors, then it's more likely
1816
that either the MIB files haven't been installed at all. If you are
1817
compiling from source, then it is necessary to run "make install" in
1818
order to set up the full run-time environment.
1819
1820
Otherwise, see the previous entry to check whether the MIBs are installed
1821
in the correct location for the tools to find them.
1822
1823
1824
1825
I'm getting answers, but they're all numbers. Why?
1826
-------------------------------------------------
1827
1828
This is related to the previous questions. Remember, the results that
1829
you receive from an agent do not depend on which MIBs are loaded by the
1830
client tools - purely on how the agent was compiled and configured.
1831
1832
Because the tools don't necessarily read in every MIB file they can find
1833
(and the relevant MIB file may not be available anyway), it is quite
1834
possible for results from an agent to refer to modules that have not
1835
been loaded (particularly with GETNEXT requests, or when walking a tree).
1836
1837
The results will be reported correctly, but won't be translated to use
1838
named identifiers (or display the values in the most appropriate manner).
1839
To fix this, add the missing MIB files to the list of MIBs to be loaded.
1840
See the previous entries and the entry "How do I add a MIB to the tools?"
1841
for more information.
1842
1843
1844
1845
What does "unlinked OID" mean?
1846
-----------------------------
1847
1848
This means that the library has been able to find the MIB module,
1849
and parse the individual objects defined in it, but is having problems
1850
linking them together into a consistent tree. In particular, it
1851
can't find an object corresponding to the name within the braces
1852
(i.e. the 'xxx' in '{xxx 99}').
1853
1854
This is probably due either to a typo in this name (remember that
1855
names are case sensitive, so a reference to 'xxx' will *not* match
1856
a definition of 'Xxx'), or else the name is defined in another MIB
1857
file, and this dependency is missing from the IMPORT clause of this
1858
MIB file.
1859
1860
1861
1862
The parser doesn't handle comments properly. Why not?
1863
----------------------------------------------------
1864
1865
The way that comments are handled in a MIB file is subtly different
1866
to the equivalent syntax in most typical programming languages, and
1867
this difference can catch out the unwary. In particular, there are
1868
two common situations which can lead to problems.
1869
1870
The first scenario is where the MIB designer has attempted to "comment
1871
out" an unwanted line that already contains a comment:
1872
1873
-- broken ::= { myMIB 1 } -- This isn't working yet
1874
1875
The assumption here is that a comment continues to the end of the line.
1876
Unfortunately, this is not correct. A comment will continue either to
1877
the end of the line, *or* the next occurance of a pair of dashes.
1878
1879
Thus in this case, the definition of "broken" is commented out (as
1880
intended) but the following text ("This isn't working yet") is treated
1881
as an active part of the MIB, and will generate an error.
1882
1883
1884
The second scenario is where a line of dashes has been used to mark
1885
out separate parts of a MIB file. Depending on the exact number of
1886
dashes used, this may still result in a syntactically valid MIB file,
1887
but has a 1-in-4 possibility of triggering an error. This means that
1888
this particular situation can be particularly difficult to spot!
1889
1890
1891
Most of the Net-SNMP applications have a command-line option (-Pc) which
1892
will work around this problem by treating the whole line as a comment.
1893
But this is not strictly legal, and the offending MIB file should really
1894
be corrected.
1895
1896
1897
1898
How can I get more information about problems with MIB files?
1899
------------------------------------------------------------
1900
1901
The command 'snmptranslate' is used to translate between numeric
1902
and symbolic forms of OIDs. It uses the same MIB parsing routines
1903
as the commands that actually communicate with a network management
1904
agent, but can be used standalone. As such, it is a useful tool
1905
for identifying problems with reading in MIB files.
1906
1907
In particular, the following options may be useful in
1908
identifying problems:
1909
-Pw warns about conflicting symbols
1910
-PW prints more verbose warnings about other problems as well
1911
(in both cases, ignore the 'xmalloc' reports)
1912
-T provides sub-options for various views of these entries
1913
1914
There are other '-P' options to control various aspects of MIB parsing.
1915
See the 'snmptranslate(1)' and 'snmpcmd(1)' man pages for more details,
1916
or the tutorial at
1917
http://www.net-snmp.org/tutorial-5/commands/snmptranslate.html
1918
1919
For a more rigourous validation, use a tool such as 'smilint', or the
1920
on-line interface at http://wwwsnmp.cs.utwente.nl/ietf/mibs/validate/
1921
1922
1923
1924
What's this about "too many imported symbols"?
1925
---------------------------------------------
1926
1927
Any MIB file starts with an (optional) list of identifiers that
1928
it "imports" from other files. The parser handles this using
1929
a fixed size buffer to hold the import information.
1930
There are two circumstances in which this can result in the
1931
error message shown above.
1932
1933
Firstly, if the MIB file refers to an unusually large number
1934
of external identifiers. Handling this case requires a (trivial)
1935
patch to the parsing code. Contact the coders list for advice.
1936
(This is extremely rare - the only example that
1937
we've come across is the Cabletron Trap MIB).
1938
1939
Much more common is a syntax error in the IMPORTS clause of the
1940
MIB file in question. In particular, check that this section ends
1941
in a semicolon, before going on to the main MIB object definitions.
1942
1943
1944
1945
Do I actually need the MIB files?
1946
--------------------------------
1947
1948
Probably not.
1949
The MIB files play two main roles - they are used to translate
1950
between numeric OIDs and the corresponding textual names, and
1951
they define the structure and syntax of the relevant MIB objects.
1952
1953
This second role is perhaps best thought of in terms of a design
1954
document. It's vital while developing an application (typically
1955
the MIB module or handler within the agent), since it defines
1956
what the application (MIB) must actually do. But once the code
1957
has been written, the design document becomes redundent.
1958
The agent then has the same information hardcoded into it
1959
(literally!), and no longer needs the MIB file.
1960
1961
The translation task is not strictly necessary - SNMP will
1962
operate fine without any MIB files at all, as long as you're
1963
happy to work with numeric OIDs throughout, and know which MIB
1964
objects you're interested in. But it's much easier to work with
1965
the (hopefully) meaningful names, enumeration tags and the like,
1966
and to view the description of a particular object.
1967
This requires having the relevant MIB files installed and loaded.
1968
1969
1970
Since the agent needs MIBs the least and some systems are memory
1971
restricted, it is possible to completely disable loading these MIBs
1972
as well as remove the code that does the parsing by using the
1973
--disable-mib-loading flag to configure.
1974
1975
However, note that certain snmpd.conf tokens actually make use
1976
of mib information so they won't be as easily usable.
1977
1978
1979
1980
AGENT
1981
=====
1982
1983
What MIBs are supported?
1984
-----------------------
1985
1986
The following MIBs are supported (at least in part and on some systems):
1987
1988
- MIB-2 General network statistics
1989
(RFC 1213 and subsequent revisions)
1990
- Host Resources (RFC 1514 and 2790)
1991
- SNMPv3 framework (RFCs 2571-5, 3411-3418)
1992
(including USM, VACM, Target
1993
and Notification MIBs)
1994
- DisMan Event and Schedule MIBs
1995
- MTA-MIB (sendmail)
1996
- private UCD/Net-SNMP agent extensions
1997
(monitor specified processes and disks,
1998
memory, CPU, load average, + extending
1999
the agent using shell commands)
2000
2001
See README.agent-mibs for details.
2002
2003
Not all MIB modules are included by default on all systems. Some of
2004
these may need to be explicitly requested when the software is first
2005
configured and built, while others may not be available on all
2006
architectures.
2007
2008
There are a few other MIB implementations distributed as part of the
2009
source tarball, but these are basically unsupported and most of the
2010
core developers have little or no experience with using them.
2011
2012
2013
2014
What protocols are supported?
2015
----------------------------
2016
2017
The agent supports all three current versions of SNMP (v1, v2c and v3),
2018
over both UDP and TCP transports, as well as acting as a SMUX (RFC 1227)
2019
master agent, AgentX (RFC 2741) in both master and subagent roles, and
2020
SNMP proxying.
2021
2022
2023
2024
How do I configure the agent?
2025
----------------------------
2026
2027
That's a somewhat ambiguous question, as there are two very different
2028
stages where it is possible to "configure" the agent.
2029
2030
Firstly, you can determine what capabilities and defaults are included
2031
within the library and agent, at the time that the software is first
2032
built. This uses suitable flags to the 'configure' script, before
2033
compiling the source.
2034
As far as the agent is concerned, the most significant option is
2035
'--with-mib-modules' (or '--with-out-mib-modules') to control which
2036
MIBs will be supported by the agent. See the next few entries for
2037
details.
2038
2039
You can also control various aspects of the agent behaviour (and the
2040
information it returns) at run time, via the 'snmpd.conf' configuration
2041
file. Various aspects of this are touched on throughout this FAQ. Or
2042
see the snmpd.conf(5) manual page for full details.
2043
The "snmpconf" script can help in creating this config file.
2044
Start off with 'snmpconf -g basic_setup' to get you going.
2045
2046
2047
2048
How do I remove a MIB from the agent?
2049
------------------------------------
2050
2051
Deleting the text file for a MIB does not affect the agent (other than
2052
to prevent it from recognising MIB object names in the config files).
2053
It's necessary to tell the agent not to activate the relevant code that
2054
actually implements these objects. There are three ways to do this:
2055
2056
1) re-run 'configure' to exclude the given MIB module(s) from the
2057
build configuration, then recompile and reinstall:
2058
2059
./configure --with-out-mib-modules=path/to/unwanted ....
2060
make
2061
make install
2062
2063
This specifies the path to the module code file, relative to
2064
the 'agent/mibgroup' directory. Clearly, this approach is
2065
only possible if you are working with a source distribution.
2066
2067
2) disable the MIB at runtime
2068
2069
snmpd -I -unwanted
2070
2071
Note that this relies on knowing which modules are used to
2072
implement the relevant MIB objects. If you're not sure,
2073
you could try walking the 'nsModuleName' MIB object, which
2074
indicates the module responsible for each particular range
2075
of OIDs.
2076
You can also check which MIB modules are loaded by getting
2077
the agent to report them as they are initialised:
2078
2079
snmpd -Dmib_init -H
2080
2081
From this information, it should then be fairly obvious which
2082
modules to disable.
2083
2084
3) use access control to exclude the mib from the view used to
2085
query the agent:
2086
2087
view almostEverything included .1
2088
view almostEverything excluded unwantedMib
2089
2090
rocommunity public default -V almostEverything
2091
2092
This approach can also be used with the full com2sec/group/access
2093
configuration directives (e.g. with versions earlier than 5.3,
2094
which don't support the above mechanism).
2095
2096
2097
2098
I've installed a new MIB file. Why can't I query it?
2099
----------------------------------------------------
2100
2101
Installing a new MIB file will not magically enable the agent to know
2102
what values to report for the objects defined in that MIB. It's
2103
necessary to have some code which can provide the relevant information.
2104
The next few entries, and the CODING section address this issue in more
2105
detail.
2106
2107
2108
2109
How do I add a MIB to the agent?
2110
-------------------------------
2111
2112
Adding a MIB essentially involves writing some code to implement the
2113
objects defined in the new MIB. There are three basic approaches that
2114
can be used to do this:
2115
2116
- The agent can invoke an external command or shell script to
2117
return the necessary information. There are several possible
2118
variations on this approach - see the next entry for details.
2119
2120
- The agent can pass the request off to another (sub-)agent,
2121
which already implements the required MIB. Again, there are
2122
several ways of doing this - including AgentX, SMUX and
2123
proxied SNMP. See the next entry but one for details.
2124
2125
- You can write code to implement the new MIB objects, and
2126
include this within the agent. This is most commonly C
2127
(or C++) code, although the agent can also support MIB modules
2128
implemented in perl.
2129
See the next section (CODING) for more details.
2130
2131
Note that there is no visible difference between external commands,
2132
subagents, and modules implemented within the main agent itself.
2133
Tools querying the agent will see a single MIB structure.
2134
2135
2136
2137
What's the difference between 'exec', 'sh', 'extend' and 'pass'?
2138
---------------------------------------------------------------
2139
2140
'exec' will run the specified command and return the exit status and
2141
output. Any arguments are passed directly to the command, with no
2142
special interpretation.
2143
2144
'sh' is similar, but invokes a shell to run the command line given.
2145
This means that quoted arguments will be recognised as such, and also
2146
allows redirection, and other similar shell interpretation. The results
2147
are returned in exactly the same way.
2148
2149
'extend' is also similar, but provides a richer and more flexible MIB
2150
framework - both for configuring the exact command to be run, and for
2151
displaying the results.
2152
2153
None of these mechanisms require the command to have any knowledge of
2154
SNMP, or the fact that they are being used in this manner. But the
2155
output is returned in a fixed format, and it is up to the receiving
2156
application to interpret this appropriately.
2157
2158
2159
'pass' is a more general mechanism for implementing arbitrary MIB
2160
objects. The specified command will be invoked for any request within
2161
the named MIB subtree, and passed details of the requested OID. It
2162
should return the information relevant to the requested OID.
2163
2164
'pass-persist' is similar, but the command will continue running
2165
even after the initial request has been answered. These two mechanisms
2166
can be used to implement a particular MIB, following the correct MIB
2167
structure (as opposed to the fixed format of exec/sh/extend).
2168
2169
All of these mechanisms are described in the 'snmpd.conf(5)' man page,
2170
in the section entitled "Extending Agent Functionality".
2171
2172
2173
2174
What's the difference between AgentX, SMUX and proxied SNMP?
2175
-----------------------------------------------------------
2176
2177
All three are protocols that can be used to make two or more agents
2178
appear as one to the querying application. In each case, one agent
2179
takes the role of "master", and delegates requests to one of the others
2180
as and where this is appropriate. The differences between them mainly
2181
relate to how data is represented, and the mechanisms for communication
2182
between master and subagents.
2183
2184
SMUX and proxy SNMP both essentially use the standard SNMP packet format.
2185
The main difference is that a proxy SNMP subagent need not be aware that
2186
it is acting in such a role. It typically listens on a non-standard port,
2187
and simply receives requests as usual, forwarded from the master agent
2188
(rather than directly). The main issue to be aware of is that such requests
2189
will appear to come from the local host, and this may affect how the access
2190
control mechanisms need to be set up.
2191
2192
SMUX uses a similar packet format, but the subagent "registers" with
2193
the master agent, providing a suitable password. The Net-SNMP (and UCD)
2194
agent includes the possibility of acting as a SMUX master agent, but the
2195
suite does not include a subagent API. Note that support for SMUX is not
2196
included by default, and needs to be explicitly enabled by running:
2197
2198
--with-mib-modules=smux
2199
2200
before re-compiling the agent.
2201
See the file 'agent/mibgroup/README.smux' for details.
2202
2203
AgentX uses a more compact (and simpler) packet format, with a richer
2204
range of administrative commands, and provides a more flexible and reliable
2205
extension mechanism. The Net-SNMP agent can be used in both master and
2206
subagent roles, and the agent library can also be used to embed an AgentX
2207
subagent within another application.
2208
See the file 'README.agentx' for details.
2209
2210
AgentX support is included by default, but needs to be explicitly
2211
activated in the master agent. Do this by adding the line
2212
2213
master agentx
2214
2215
to the snmpd.conf file before starting the agent.
2216
2217
2218
2219
What is the purpose of 'dlmod'?
2220
------------------------------
2221
2222
Most of the MIB information supplied by the Net-SNMP agent is provided
2223
by C-coded implementation modules, and the choice of which modules to
2224
include is usually made when the agent is first built. Adding new
2225
MIB modules would therefore require re-compiling the agent. This is
2226
not always convenient - particularly when working with a production
2227
system, and/or pre-installed binaries.
2228
2229
Dynamically loaded modules are a means of including a MIB implementation
2230
module within the main SNMP agent (or an AgentX subagent) without needing
2231
to re-compile and re-link the agent binary. Instead, details of the
2232
module(s) to load are specified in the configuration file, and the agent
2233
locates the files listed, and merges them in at run time.
2234
2235
See http://www.net-snmp.org/tutorial-5/toolkit/dlmod/ for more information.
2236
2237
2238
2239
Which extension mechanism should I use?
2240
--------------------------------------
2241
2242
That's not easy to answer in general.
2243
2244
If there's an existing agent that already implements the desired new
2245
MIB, then it makes sense to re-use that, via whatever extension protocol
2246
that agent might support. Note that the SMUX protocol has essentially
2247
been superceded by AgentX, which provides a fuller and more reliable
2248
mechanism than either SMUX or proxied SNMP. So ideally, this would
2249
be the preferred extension approach.
2250
But if the target subagent only supports SMUX or basic SNMP, then that
2251
would dictate the extension protocol to use.
2252
2253
Implementing the module in C within the main agent (directly or via
2254
dlmod) is probably the most efficient and reliable, closely followed
2255
by embedded perl (or python) extensions. These have the advantage of
2256
minimal overheads between the code implementing the MIB module, and
2257
the agent framework, and no inter-process communication issues. But
2258
this does assume that there's a suitable mechanism for retrieving the
2259
necessary information.
2260
2261
If the new MIB is monitoring or managing some other subsystem, external
2262
to the agent, then it may be necessary to embed a subagent within the
2263
subsystem itself - particularly if there's no suitable public API to
2264
retrieve the necessary information. In this case, AgentX is probably
2265
the most appropriate way forward.
2266
Alternatively, you could implement the missing public management API
2267
for that subsystem, and develop a module within the main agent instead.
2268
2269
2270
2271
Can I use AgentX when running under Windows?
2272
-------------------------------------------
2273
2274
Yes, but there are a couple of things to be aware of.
2275
2276
Firstly, by default the AgentX master listens on the Unix domain
2277
socket '/var/agentx/master', which doesn't work under Windows.
2278
You'll need to tell it to listen on a TCP port, either by using
2279
the command-line option "-x localhost:705", or by adding the
2280
directive "agentxSocket localhost:705" to the snmpd.conf file.
2281
2282
Secondly, be aware that the security of AgentX connectivity is not
2283
particularly strong. The examples given here would allow any process
2284
running on the local machine to register as an AgentX subagent. The
2285
more obvious settings "-x 705" or "agentxSocket 705" would allow
2286
a system *anywhere* on the network (or even from remote networks) to
2287
register as an AgentX subagent. This could potentially be used to
2288
hijack the agent, or provide false information.
2289
2290
2291
2292
How can I run AgentX with a different socket address?
2293
----------------------------------------------------
2294
2295
There are two sides to an AgentX connection, and they need to
2296
agree about which socket address to use. So if you want to use
2297
a different socket, you need to configure both parties accordingly.
2298
2299
The socket that the Net-SNMP master agent uses to listen for AgentX
2300
registrations (and send appropriate requests) can be specified using
2301
the option '-x'.
2302
The command
2303
"snmpd -x tcp:localhost:705 ...."
2304
would start the agent listening on the TCP port 705 for connections
2305
from the local system.
2306
The same effect can also be obtained by adding the line
2307
agentxsocket localhost:705
2308
to the file 'snmpd.conf'.
2309
2310
The same option can be used with the Net-SNMP agent when running in
2311
This also holds when the Net-SNMP agent is running in
2312
"subagent" mode, to specify the socket to register with (and receive
2313
requests from).
2314
So a subagent might connect to the master agent above (both running
2315
on the same host), using:
2316
"snmpd -X -x tcp:localhost:705 ...."
2317
2318
A subagent running embedded within some other application will
2319
typically not understand the same command-line options, so would
2320
need to set the same configuration programmatically:
2321
2322
netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID,
2323
NETSNMP_DS_AGENT_X_SOCKET, "tcp:localhost:705");
2324
2325
With the example subagent code from the Net-SNMP tutorial, this line
2326
would be added immediately before the 'init_agent' call.
2327
2328
The same approach can also be used to listen on a different named
2329
socket, using:
2330
agentxsocket /tmp/agentx
2331
agentxperms 770 770 myuser mygroup
2332
or
2333
snmpd -x /tmp/agentx ....
2334
or
2335
netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID,
2336
NETSNMP_DS_AGENT_X_SOCKET, "/tmp/agentx");
2337
as appropriate.
2338
2339
2340
2341
How can I turn off SMUX support?
2342
-------------------------------
2343
2344
Normally, you would use the command-line option '-I -{module}' to
2345
disable the initialisation of a particular MIB module within the
2346
agent. Unfortunately, it's not currently possible to turn off SMUX
2347
support this way.
2348
2349
The safest approach is to run
2350
configure --with-out-mib-modules=smux
2351
and recompile the agent.
2352
2353
If this is not possible, an alternative workaround might be to have
2354
the agent bind the SMUX socket to an invalid IP address, using a
2355
snmpd.conf line such as:
2356
2357
smuxsocket 1.0.0.0
2358
2359
The agent may complain at startup, but it won't accept any incoming
2360
SMUX requests.
2361
2362
If the agent complains about not recognising the "smuxsocket"
2363
token, then you're out of luck. You'll either have to recompile
2364
from source, or use local firewall rules to block connections
2365
to port 199.
2366
2367
2368
2369
How can I combine two copies of the 'mib2' tree from separate subagents?
2370
-----------------------------------------------------------------------
2371
2372
This is the purpose of the SNMPv3 'context' field. Register the MIB
2373
module a second time in a non-default context (see the relevant entry
2374
in the CODING section for details), and specify this context when
2375
querying the agent. The MIB module can use this context information
2376
to determine which set of information to report.
2377
Or you could register two completely different handlers for the same
2378
OID (using different contexts), and the agent will invoke the appropriate
2379
code. This holds for both MIB modules implemented within the main agent,
2380
or AgentX subagents - the same approach will work for both.
2381
2382
Contexts can also be used with proxied SNMP requests - just specify
2383
the option '-Cn {context}' as part of the "proxy" entry. See the
2384
'snmpd.conf(5)' man page for details.
2385
2386
It's currently not possible to support parallel MIB trees when using
2387
SNMPv1 or SNMPv2c. In principle, it should be possible to use the
2388
community string in a similar way, but this has not (yet) been implemented.
2389
2390
This mechanism is only available with the v5 Net-SNMP agent. The v4
2391
UCD agent does not support contexts at all. Sorry about that.
2392
2393
Another way to handle this would be to tweak one of the subagents to
2394
use a different set of (non-standard) OID assignments - perhaps by
2395
relocating the whole of the subtree to another (private) OID. This
2396
is not ideal, but should work with all configurations.
2397
2398
2399
2400
What traps are sent by the agent?
2401
--------------------------------
2402
2403
The Net-SNMP agent sends a 'coldStart(0)' trap when it first starts up,
2404
and an enterprise-specific trap 'nsNotifyShutdown' when it stops. It
2405
generates an enterprise-specific trap 'nsNotifyRestart' (rather than
2406
the standard 'coldStart(0)' or 'warmStart(1)' traps) on receiving a HUP
2407
signal - typically after being re-configured. It can also be configured
2408
to send an 'authenticationFailure(4)' trap when it receives an SNMPv1
2409
(or SNMPv2c) request using an unknown community name.
2410
2411
The agent does not send 'linkUp' or 'linkDown' traps by default. It can
2412
be configured to do this using the directive 'linkUpDownNotifications'.
2413
See the 'snmpd.conf(5)' man page (under ACTIVE MONITORING) for details.
2414
2415
Similarly, it does not generate traps by default when one of the
2416
monitored characteristics (disk usage, running processes, etc) enters or
2417
leaves an error state. This can be configured using the 'defaultMonitors'
2418
directive (again documented under ACTIVE MONITORING).
2419
2420
2421
2422
Where are these traps sent to?
2423
-----------------------------
2424
2425
With all these alerts, the agent needs to be told where to send them,
2426
specifying the type of notification (v1 or v2 trap, or v2 inform) and
2427
the community name to use. This uses the snmpd.conf directives 'trapsink',
2428
'trap2sink' and 'informsink' for the destination type, and 'trapcommunity'
2429
for the community name. SNMPv3 destinations can be configured using the
2430
directive 'trapsess'. See the 'snmpd.conf(5)' man page for details.
2431
2432
Note that the type of trap generated is totally determined by these
2433
directives - irrespective of which API call was used to trigger sending
2434
the trap. See the trap-related entries in the CODING section for details.
2435
2436
Note also that you typically only want *one* of the settings:
2437
2438
trapsink localhost
2439
trap2sink localhost
2440
informsink localhost
2441
2442
Including two (or all three) of these lines in the snmpd.conf file will
2443
will result in multiple copies of every notifications being sent for
2444
each call to 'send_easy_trap()' (or 'send_v2trap()').
2445
This is probably not what was intended!
2446
2447
2448
2449
How can I send a particular trap to selected destinations?
2450
----------------------------------------------------------
2451
2452
This is not currently possible. All notifications will be sent to
2453
all configured destinations. The agent does not (currently) support
2454
notification filtering.
2455
2456
There is a preliminary implementation of the snmpNotifyFilterTable
2457
which is designed to allow this sort of selective trap direction.
2458
However this is not currently active. (The tables are present and
2459
can be manipulated and updated, but the information is not consulted)
2460
Documentation on how to use this mechanism will appear once the
2461
functionality is working properly.
2462
2463
2464
2465
When I run the agent it runs and then quits without staying around. Why?
2466
-----------------------------------------------------------------------
2467
2468
Firstly, are you certain that this is what is happening?
2469
2470
The normal operation of the agent is to 'fork' itself into the background,
2471
detaching itself from the controlling terminal so that it will continue
2472
running even when you log out, and freeing the command line for subsequent
2473
use. This looks at first sight as if the agent has died, but using 'ps'
2474
to show all processes should reveal that the agent is still running.
2475
2476
To prevent this behaviour (such as when attempting to debug the agent),
2477
you can start it with the '-f' flag. This suppresses the fork, and the
2478
agent will run as a 'normal' command. It's also often useful to use the
2479
'-Le' (or '-L') flag, to log messages to stderr.
2480
2481
On the other hand, if 'ps' shows that the agent is not running, then
2482
this is an error, and probably show that something went wrong in
2483
starting the agent up. Check the agent log file for any error messages,
2484
or run it with '-f -Le' and see what it reports.
2485
2486
One possible cause might be an existing agent (or some other process)
2487
that's already listening on the SNMP port. Trying to start a second
2488
agent will fail with an error about "opening the specified endpoint".
2489
2490
If you're starting the agent as a non-root user, then this may also
2491
fail with the very same error. By default, the agent (and trap handler)
2492
will attempt to listen on the standard SNMP port 161 (or 162 for the
2493
trap handler). These are defined as "privileged ports", and processes
2494
will need to be running as root in order to open them.
2495
2496
One way to tackle this is to start the agent as root, but use the -u
2497
option to switch to run as another user once the port has been opened.
2498
Alternatively, you can specify a different port to use instead.
2499
Anything greater than 1024 is available to non-root users. In this case,
2500
you'll also need to specify the same port when issuing client commands.
2501
2502
2503
2504
After a while the agent stops responding, and starts eating CPU time. Why?
2505
--------------------------------------------------------------------------
2506
2507
This is basically the same problem described in the APPLICATIONS
2508
section, in the entry
2509
The agent worked for a while, then stopped responding. Why?
2510
2511
See that entry for details.
2512
2513
2514
2515
How can I stop other people getting at my agent?
2516
-----------------------------------------------
2517
2518
Firstly, are you concerned with read access or write access?
2519
2520
As far as changing things on the agent is concerned, there is relatively
2521
little that can actually be altered (see the entry "Why can't I set
2522
any variables in the MIB?" above).
2523
2524
If you are using the example config file, this is set up to allow
2525
read access from your local network, and write access only from the
2526
system itself (accessed as 'localhost'), both using the community name
2527
specified. You will need to set appropriate values for both NETWORK
2528
and COMMUNITY in this file before using it.
2529
This mechanism can also be used to control access much more precisely.
2530
(see the next few questions for details)
2531
2532
Other options include:
2533
- Blocking access to port 161 from outside your organisation
2534
(using filters on network routers)
2535
- Using kernel-level network filtering on the system itself
2536
(such as IPTables)
2537
- Configuring TCP wrapper support ("--with-libwrap")
2538
This uses the TCP 'libwrap' library (available separately)
2539
to allow/deny access via /etc/hosts.{allow,deny}
2540
2541
For strict security you should use only SNMPv3, which is the secure
2542
form of the protocol. However, note that the agent access control
2543
mechanisms does not restrict SNMPv3 traffic by location - an SNMPv3
2544
request will be accepted or rejected based purely on the user
2545
authentication, irrespective of where it originated. Source-based
2546
restrictions on SNMPv3 requests would need to use one of the "external"
2547
mechanisms listed above.
2548
2549
2550
2551
How can I listen on just one particular interface?
2552
-------------------------------------------------
2553
2554
Normally, the agent will bind to the specified port on all interfaces
2555
on the system, and accept requests received from any of them. However,
2556
if a particular port (or ports) is specified when the agent is first
2557
started, then it will only listen for requests on these particular
2558
ports.
2559
For example:
2560
snmpd 127.0.0.1:161
2561
2562
would listen (on the standard port) on the loopback interface only, and:
2563
2564
snmpd 10.0.0.1:6161
2565
2566
would listen on port 6161, on the (internal network) interface with
2567
address 10.0.0.1. To listen on both of these interfaces (and no others)
2568
provide a list of all the desired addresses:
2569
2570
snmpd 127.0.0.1:161 127.0.0.1:6161
2571
2572
The AgentX port option ('-x') works in much the same way.
2573
2574
2575
2576
The agent is complaining about 'snmpd.conf'. Where is this?
2577
-----------------------------------------------------------
2578
2579
It doesn't exist in the distribution as shipped. You need to
2580
create it to reflect your local requirement.
2581
To get started, you can either just create this file manually,
2582
or run snmpconf to help you create one. At the very least, you
2583
will need some form of access control configuration, if the agent
2584
is to be of any use whatsoever. This can be as simple as:
2585
2586
rocommunity public
2587
2588
See the snmpd.conf(5) manual page or relevant entries in this
2589
FAQ for further details.
2590
2591
2592
2593
Why does the agent complain about 'no access control information'?
2594
------------------------------------------------------------------
2595
2596
Although an SNMP agent may support a wide range of management
2597
information, it is not necessarily appropriate to report the whole
2598
of this to every SNMP management station who asks for it. Some
2599
information may be sensitive, and should restricted to authorized
2600
administrators only. SNMP therefore includes mechanisms for
2601
controlling who has access to what information - both in terms of
2602
what can be seen, and (even more importantly) what can be changed.
2603
2604
By default, the Net-SNMP agent starts up with a completely empty
2605
access control configuration. This means that *no* SNMP request
2606
would be successful. It is necessary to explicitly configure
2607
suitable access control settings, based on who should be granted
2608
access in that particular environment.
2609
2610
If there are no access control entries configured (perhaps because
2611
no snmpd.conf configuration file has been loaded, or it contains no
2612
access control settings), then the agent will not respond to any
2613
SNMP requests whatsoever. This is almost certainly not what was
2614
intended, so the agent reports this situation.
2615
2616
See the next entry for how to configure access control settings.
2617
2618
2619
2620
How do I configure access control?
2621
---------------------------------
2622
2623
The simplest way is to use the configure directives:
2624
2625
rocommunity public (for SNMPv1/2c)
2626
rwcommunity private
2627
or
2628
rouser user1 (for SNMPv3)
2629
rwuser user2
2630
2631
These specify the community names or security names to accept for
2632
read-only and read-write access to the whole of the supported MIB tree.
2633
(Obviously you should change these names to match your requirements -
2634
which is a particularly good idea in the case of 'rwcommunity'!)
2635
2636
Note that you should *not* specify the same community name for both
2637
rocommunity and rwcommunity directives. The rwcommunity setting
2638
automatically provides read access, and having both lines (with the
2639
same community name) may result in unexpected behaviour.
2640
Only use both settings when specifying *different* community names.
2641
The same holds true for rouser and rwuser.
2642
2643
The two community directives can be restricted to only allow requests
2644
from particular sources, and all four can be restricted to a particular
2645
subtrees or (from v5.3) a named view. See 'snmpd.conf(5)' for details.
2646
2647
2648
2649
How do I configure SNMPv3 users?
2650
-------------------------------
2651
2652
There are three ways to configure SNMPv3 users:
2653
2654
1) Stop the agent, and add the line
2655
2656
createUser {myUser} MD5 {myPassword} DES
2657
2658
to the file /var/net-snmp/snmpd.conf (where {myUser} and
2659
{myPassword} are the appropriate values for username and password,
2660
_without_ the braces!). Then re-start the snmpd agent.
2661
2662
2) Stop the agent, run the command
2663
2664
net-snmp-config --create-snmpv3-user
2665
2666
and follow the prompts given. This will create an entry
2667
in the /var/net-snmp/snmpd.conf file similar to the above.
2668
Then re-start the snmpd agent.
2669
2670
3) Make sure the agent is running, and will respond to an SNMPv3
2671
request (using an existing user with the desired authentication
2672
and privacy protocols). Then use the 'snmpusm' command to clone
2673
this template user, and change the password.
2674
2675
2676
See the access control entries above and the file 'README.snmpv3'
2677
for more details about how to use SNMPv3 users,
2678
2679
Note that simply having a 'rouser' or 'rwuser' line does *not*
2680
automatically create the corresponding SNMPv3 user. You will need
2681
the above 'createUser' line (or an equivalent 'usmUser') as well.
2682
2683
2684
2685
The 'createUser' line disappears when I start the agent. Why?
2686
-------------------------------------------------------------
2687
2688
This is deliberate.
2689
2690
The agent removes the (human-readable) 'createUser' directive, and
2691
replaces it with an equivalent 'usmUser' entry. This contains the
2692
same information, but in a form that's only meaningful internally.
2693
Not only is the passphrase no longer visible in the config file, it
2694
has actually been converted to a key that is only valid on this
2695
particular system. If someone stole the configuration file, they
2696
could not use the information from the usmUser entry to access any
2697
of your other agents (even if the usernames and passwords were the same).
2698
2699
2700
2701
What's the difference between /var/net-snmp and /usr/local/share/snmp?
2702
---------------------------------------------------------------------
2703
2704
The /var/net-snmp location is primarily used for information set
2705
during the running of the agent, which needs to be persistent between
2706
one run of the agent and the next. Apart from "createUser" (see
2707
the previous entry), you shouldn't need to touch this file.
2708
2709
All other user-provided configuration should go in the traditional
2710
location (typically /usr/local/share/snmp/snmpd.conf or /etc/snmp).
2711
2712
2713
2714
My new agent is ignoring the old snmpd.conf file. Why?
2715
-----------------------------------------------------
2716
2717
The most likely explanation is that the new version of the agent is
2718
looking in a different location than the previous one. This is commonly
2719
experienced when replacing a ready-installed version (e.g. from a vendor
2720
distribution), with the current release installed from the source.
2721
2722
Try moving the old config file to the new location, and restart the agent.
2723
If you're not sure where this should go, see the next entry.
2724
2725
2726
2727
Where should the snmpd.conf file go?
2728
-----------------------------------
2729
2730
The default location for this file with the basic distribution is
2731
/usr/local/share/snmp/snmpd.conf (or PREFIX/share/snmp/snmpd.conf).
2732
Ready-installed versions often look for the file as /etc/snmpd.conf,
2733
or /etc/snmp/snmpd.conf.
2734
2735
If you are still not sure, try running the command
2736
2737
snmpd -f -Le -Dread_config 2>&1 | grep "config path"
2738
2739
The first line of output will display the list of locations where
2740
the agent is looking for configuration information.
2741
2742
2743
2744
Why am I getting "Connection refused"?
2745
-------------------------------------
2746
2747
This is actually nothing to do with the access control mechanism
2748
(though that's an understandable mistake). This is the result of
2749
the TCP wrapper mechanism using the files 'hosts.allow' and 'hosts.deny'
2750
to control access to the service. Some distributions may come with
2751
this enabled automatically - otherwise you need to explicitly activate
2752
this by running
2753
configure --with-libwrap
2754
and recompiling the agent.
2755
2756
If TCP wrappers are enabled, and both hosts.allow and hosts.deny are
2757
empty, then all requests will be rejected (with "Connection refused").
2758
The simplest way to avoid this problem and allow incoming requests is
2759
to add the line
2760
2761
snmpd: ALL
2762
2763
to the file /etc/hosts.allow. Be aware that doing this removes one
2764
level of protection and allows anyone to try and query your agent.
2765
The agent's own access control mechanisms can still be used to restrict
2766
what - if anything - they can see.
2767
2768
If you do wish to use the TCP wrappers to restrict access, it's sensible
2769
to have an explicit entry:
2770
2771
snmpd: ALL
2772
2773
in the file /etc/hosts.deny, which makes it crystal clear that access
2774
to the SNMP agent has been denied. This mechanism can also be used to
2775
restrict access to specific management hosts, using a hosts.deny entry
2776
such as:
2777
2778
snmpd: ALL EXCEPT 127.
2779
2780
which will allow connections from localhost, and nothing else.
2781
2782
Note that personal firewalls, such as the Linux iptables mechanism,
2783
may have a similar effect (though typically this won't be logged).
2784
See the earlier entry
2785
Requests always seem to timeout, and don't give me anything back. Why?
2786
2787
2788
2789
Why can't I see values in the UCDavis 'proc' or 'disk' trees?
2790
------------------------------------------------------------------
2791
2792
Both these trees are designed to report precisely those things that
2793
have been explicitly configured for monitoring. If there are no
2794
relevant configuration entries in the snmpd.conf file, then these
2795
tables will be empty. See the snmpd.conf manual page and the
2796
EXAMPLE.conf file for details on configuring the agent.
2797
2798
Optionally, run snmpconf -g monitoring to help you set up this
2799
section of the snmpd.conf file.
2800
2801
2802
2803
Why can't I see values in the UCDavis 'memory' or 'vmstat' trees?
2804
----------------------------------------------------------------
2805
2806
These trees do not need any explicit configuration, and should
2807
be present automatically.
2808
2809
However the C code necessary to implement these particular MIB
2810
modules are not supported on all operating systems. These trees
2811
will be omitted on any system for which there is no underlying
2812
code. Currently, they are only supported on Linux, HP-UX (memory
2813
only), Solaris, BSDi (vmstat on BSDi4 only), Dynix, FreeBSD, NetBSD
2814
and OpenBSD.
2815
If you want to help port it to other systems, let us know.
2816
2817
Note that these subtrees only report the current usage when
2818
explicitly queried. They do *not* automatically generate traps
2819
when the usage strays outside the configured bounds.
2820
See the earlier FAQ entry
2821
What traps are sent by the agent?
2822
or the snmpd.conf section on active monitoring, for more information.
2823
2824
2825
2826
What do the CPU statistics mean - is this the load average?
2827
----------------------------------------------------------
2828
2829
No. Unfortunately, the original definition of the various CPU
2830
statistics was a little vague. It referred to a "percentage",
2831
without specifying what period this should be calculated over.
2832
It was therefore implemented slightly differently on different
2833
architectures.
2834
2835
The 5.4 release has clarified the situation, and standardised on
2836
calculating these percentages over a minute. The relevant MIB
2837
descriptions have been updated to make the desired behaviour
2838
more explicit.
2839
2840
The Net-SNMP agent also includes "raw counters", which can be used
2841
to calculate the percentage usage over any desired period. This is
2842
the "right" way to handle things in the SNMP model. The original
2843
percentage objects have been deprecated, and may possibly be removed
2844
in a future release of the agent.
2845
2846
Note that this is different from the Unix load average, which is
2847
available via the loadTable, and is supported on all architectures.
2848
2849
2850
2851
How do I get percentage CPU utilization using ssCpuRawIdle?
2852
-----------------------------------------------------------
2853
2854
This one of the "raw counters" mentioned in the previous entry.
2855
You need to take two readings of this object and look at the
2856
difference between them. That difference divided by the total
2857
number of 'ticks' between the two readings (where one tick is
2858
probably 0.01 seconds) will give you the percentage utilization
2859
over that period.
2860
2861
2862
2863
What about multi-processor systems?
2864
----------------------------------
2865
2866
The CPU objects (both percentages and raw counters) were designed to
2867
monitor the overall CPU activity of a system, and typically reflect
2868
whatever the underlying operating system reports for the (single)
2869
CPU statistics information. How these are handled for a multi-CPU
2870
system will differ from one O/S to another, and will need
2871
to be investigated for each system individually.
2872
2873
The htProcessorTable was designed to handle monitoring multi-CPU
2874
machines, but the Net-SNMP implementation has up to now treated
2875
most systems (with the honourable exception of Solaris, and more
2876
recently Linux) as implicitly single-CPU.
2877
2878
With the 5.4 release, there is now a cleaner framework for reporting
2879
on multi-CPU equipment, and it is hoped that an increasing number
2880
of systems will be able to report suitable processor information.
2881
Also with the 5.4 release, for the first time the agent will report
2882
the hrProcessorLoad value properly, which should provide some simple
2883
per-CPU statistics.
2884
2885
2886
2887
The speed/type of my network interfaces is wrong - how can I fix it?
2888
-------------------------------------------------------------------
2889
2890
Some operating systems will provide a mechanism for determining
2891
the speed and type of network interfaces, but many do not. In such
2892
cases, the agent attempts to guess the most appropriate values,
2893
usually based on the name of the interface.
2894
2895
The snmpd.conf directive "interface" allows you to override these
2896
guessed values, and provide alternative values for the name, type
2897
and speed of a particular interface. This is particularly useful
2898
for fast-ethernet, or dial-up interfaces, where the speed cannot be
2899
guessed from the name.
2900
2901
See the snmpd.conf(5) man page for details.
2902
2903
2904
2905
The interface statistics for my subinterfaces are all zero - why?
2906
----------------------------------------------------------------
2907
2908
Unfortunately, most kernels that support multiple logical
2909
interfaces on a single physical interface, don't keep separate
2910
statistics for each of these. They simply report the overall
2911
statistics for the physical interface itself.
2912
2913
There's no easy way around this problem - the agent can only
2914
report such information as is available. If the kernel doesn't
2915
keep track of these figures, the agent can't report them.
2916
2917
Sorry!
2918
2919
2920
2921
Does the agent support the RMON-MIB?
2922
-----------------------------------
2923
2924
Not really.
2925
2926
There is an "Rmon" code module included within the agent source
2927
code tree, but this is best thought of as a template for the
2928
RMON-MIB statistics groups, rather than a full implementation.
2929
2930
With most MIBs, the hardest part of implementing the MIB is often
2931
getting hold of the data to report. This is definitely true of the
2932
RMON-MIB, which relies on gathering (and analysing) a potentially
2933
large quantity of network traffic. The Rmon code distributed with
2934
the Net-SNMP agent code avoids this problem, by using random data.
2935
2936
Some of the functionality of the RMON-MIB, such as the alarm and
2937
event groups, has since been superseded by the work of the DisMan
2938
IETF working group. The Net-SNMP agent does implement these (more
2939
general) MIB modules. But the statistics gathering aspects of
2940
the RMON-MIB are not readily available.
2941
2942
Note too that none of the core developers have any significant
2943
experience with this code, and the person who originally wrote it
2944
is no longer active on the mailing lists. So there's no point in
2945
asking on the lists whether these modules work or not. You've got
2946
the source - how badly do you need this functionality?
2947
2948
2949
2950
What does "klread: bad address" mean?
2951
-------------------------------------
2952
2953
This means that the agent was unable to extract some of the
2954
necessary information from the kernel structures. This is
2955
possibly due to:
2956
- either looking in the wrong place for kernel information
2957
(check the value of KERNEL_LOC)
2958
- an error in the implementation of part of the MIB tree
2959
for that architecture. Try and identify which
2960
OID is generating the error, and contact the
2961
list 'net-snmp-coders@lists.sourceforge.net'
2962
Remember to tell us what architecture you have!
2963
2964
2965
2966
What does "nlist err: wombat not found" (or similar) mean?
2967
----------------------------------------------------------
2968
2969
This means that the agent wasn't able to locate one of the
2970
kernel structures it was looking for. This may or may not
2971
be important - some systems provide alternative mechanisms
2972
for obtaining the necessary information - Solaris, for example,
2973
can produce a whole slew of such messages, but still provide
2974
the correct information.
2975
This error only occurs if you have used the flag
2976
'--enable-debugging' as part of the initial configuration.
2977
Reconfigure the agent with '--disable-debugging' and these
2978
messages will disappear. (It won't fix the underlying problem,
2979
but at least you won't be nagged about it).
2980
2981
2982
2983
What does "Can't open /dev/kmem" mean?
2984
-------------------------------------
2985
2986
This device is normally restricted to just being accessible by root
2987
(or possibly by a special group such as 'kmem' or 'sys'). The agent
2988
must be able to read this device to obtain the necessary information
2989
about the running system.
2990
Check that the agent was started by root, and is running with UID 0
2991
(or suitable GID if appropriate). The agent will normally continue
2992
to run without this level of access permission, but won't be able to
2993
report values for many of the variables (particularly those relating
2994
to network statistics).
2995
2996
2997
2998
The system uptime (sysUpTime) returned is wrong!
2999
-----------------------------------------------
3000
3001
Oh no it's not.
3002
The defined meaning of 'sysUpTime' is
3003
"the time ... since the *network management*
3004
portion of the system was re-initialized."
3005
3006
In other words, when the snmp agent was started, not when the
3007
system itself last booted. This latter information is available
3008
in the Host Resources MIB as "hrSystemUpTime.0"
3009
Note that even if the full Host Resources is not supported on
3010
your system, it's worth configuring in the system portion using
3011
3012
'--with-mib-modules=host/hr_system'
3013
3014
and recompiling. This particular group is reasonably likely to work,
3015
even if some of the other more architecture-specific groups don't.
3016
3017
3018
3019
Can the agent run multi-threaded?
3020
--------------------------------
3021
3022
Short answer - no.
3023
Longer answer - not easily.
3024
3025
Net-SNMP within a single thread of an threaded application is fine,
3026
as long as *all* snmp code is kept within the same thread. This lets
3027
you add SNMP support to an existing threaded application.
3028
3029
If you are concerned with the time taken for to process requests for
3030
a particular agent, object or subtree, and you want the agent to
3031
continue to respond to other requests in the meantime, there are
3032
two options.
3033
3034
The first method is using AgentX sub-agents. If you have several
3035
tables, each implemented by a separate subagent, then a single
3036
request for entries from each of the tables will be processed
3037
in parallel (and the agent will continue to respond to other
3038
requests while it waits for the subagents to return the necessary
3039
information). But a request for several objects from the same
3040
table will be passed off to the relevant subagent, where it will
3041
(normally) be processed serially.
3042
3043
The second method is to use delegated requests + IPC to another
3044
process. If takes a long time to retrieve a value for a given object,
3045
then the object handler could do whatever necessary to start or
3046
communicate with another (non-SNMP) process/thread to actually
3047
retrieve the value, and mark the request as delegated.
3048
The main agent (or subagent) can then receive and process other
3049
requests while waiting for the delegated request to finish.
3050
Dealing with resource contention is all up to you.
3051
3052
All of this only applies to the GET family of requests. A SET
3053
request will block until all pending GET requests have finished,
3054
and then will not accept new requests until the SET is complete.
3055
3056
Adding full multi-thread support directly to the agent would be
3057
nice. We just need someone with time/money to do/sponsor the work.
3058
3059
3060
3061
Can I use AgentX (or an embedded SNMP agent) in a threaded application?
3062
-----------------------------------------------------------------------
3063
3064
With care.
3065
3066
As mentioned in the earlier "thread-safe" FAQ entry, the Net-SNMP
3067
agent (including the AgentX subagent) has not been designed for
3068
threaded operation. In particular, it makes use of various global
3069
variables without attempting to protect them against simultaneous
3070
use. This means that it is *NOT* safe to have SNMP or AgentX
3071
related processing in two separate threads. This also applies to
3072
handling GET (and SET) processing in one thread, and generating traps
3073
in another. This is still vulnerable to the usual threading problems.
3074
3075
However, as long as *all* of the SNMP-related activity is limited
3076
to the one thread, then there should be no reason why this cannot
3077
safely communicate with other threads within the same application,
3078
using private (thread-safe) mechanisms.
3079
3080
But in terms of the Net-SNMP-provided code, the agent (and AgentX
3081
subagent) should *not* be regarded as thread-safe.
3082
3083
3084
3085
COMPILING
3086
=========
3087
3088
How do I control the environment used to compile the software?
3089
-------------------------------------------------------------
3090
3091
The basic mechanism for compiling the Net-SNMP project software is to
3092
run "configure", followed by "make" (to compile it), "make test" (to
3093
check that it's working properly) and then "make install" (to install
3094
the files into the correct locations - which typicalyl needs to be done
3095
as root.
3096
3097
The primary role of "configure" is to determines various aspects about
3098
the system that the software is being compiled on. However there are
3099
also a number of options to configure which can be used to control
3100
various aspects of the compilation environment.
3101
3102
The most common options are "--with-mib-modules" and "--with-out-mib-modules"
3103
which control the set of MIB module code files that are included within
3104
the agent binary. Adding or removing these modules will affect what MIB
3105
information the agent can return.
3106
See the entry "How do I add a MIB to the agent?" for more details.
3107
3108
3109
The configure script can also specify the compiler to use for compiling
3110
the source code (e.g. "configure --with-cc=cc"), the flags passed to
3111
this compiler (e.g. "configure --with-cflags=-g"), or to the linker
3112
(e.g. "configure --with-ldflags=-Bstatic"), and various other aspects of
3113
the build environment.
3114
Run "configure --help" for a full list.
3115
3116
3117
3118
How do I control the environment used to compile the software under Windows?
3119
---------------------------------------------------------------------------
3120
3121
If you are compiling the project within the MinGW or Cygwin environments,
3122
then these use the same "configure" mechanism as Unix-based systems. See
3123
the previous entry for more information.
3124
3125
If you are compiling the project from within Visual Studio, then this does
3126
not use the standard configure mechanism. Instead, there is a separate
3127
"Configure" script within the 'win32' directory. This can be used enable
3128
or disable various aspects of the build environment, such as support for
3129
encryption or IPv6.
3130
Run "Configure --help" for more information
3131
3132
Note that this script does not include an equivalent of "--with-mib-modules"
3133
for extending the MIB information supported by the agent. Instead, this
3134
needs to be done by tweaking the build environment manually. See the file
3135
README.win32 for more details of this, and various other aspects of building
3136
the project on Windows systems.
3137
3138
3139
3140
Why does the compilation complain about missing libraries?
3141
---------------------------------------------------------
3142
3143
This has been seen in a number of guises over the years - most commonly
3144
on Linux systems (although the problem may also occur elsewhere). The
3145
underlying problem is that typical installation may not always include
3146
the full set of library links required for building the Net-SNMP software.
3147
3148
This problem can usually be fixed by installing the missing packages
3149
(typically the development version of a package that is already there).
3150
3151
Examples of this that we have come across include:
3152
3153
-lelf elfutils-devel (later renamed to elfutils-libelf-devel)
3154
-lbz2 bzip2-devel
3155
-lselinux libselinux-devel
3156
-lcrypto openssl/openssl-devel
3157
-lbeecrypt libbeecrypt/beecrypt/beecrypt-devel.
3158
3159
These are the names of the RedHat/Fedora RPMs. Other distributions
3160
or O/S's may use different names, but the basic idea should be the
3161
same.
3162
3163
If the compilation is complaining about a missing .so file, then an
3164
alternative quick fix is to add the missing symbolic link, using
3165
something like:
3166
ln -s libelf.so.1 /usr/lib/libelf.so
3167
3168
giving the appropriate generic library name from the error message,
3169
and the correct number for whichever version of this library you
3170
have installed.
3171
3172
If the compilation is complaining about a .la file, then you should
3173
install the relevant development package, as listed above.
3174
3175
3176
3177
How can I reduce the memory footprint?
3178
--------------------------------------
3179
3180
In order to reduce the memory footprint (for instance, to
3181
embed the snmpd into a device), the following configure options
3182
could be used.
3183
3184
'--disable-debugging'
3185
This turns off the compilation of all debugging statements.
3186
3187
'--enable-mini-agent' '--with-out-mib-modules=examples/ucdDemoPublic'
3188
This creates an agent with just the essential MIB modules included.
3189
NOTE: If you need additional MIB modules, then simply add them
3190
using the option '--with-mib-modules=...' but this will of course
3191
increase the memory footprint.
3192
3193
'--with-transports=UDP'
3194
This option specifies the transport domains to include.
3195
For a simple standalone agent, just UDP should be sufficient.
3196
(Although the 'disman' and 'agentx' modules may require the
3197
Callback, TCP and/or Unix transport domains as well).
3198
3199
'--without-kmem-usage'
3200
This can be used in order to omit the code that operates on the
3201
/dev/kmem interface. Clearly, this option cannot be used when
3202
one of the configured MIB modules depends on it.
3203
3204
'--with-mibdirs=' and '--with-mibs='
3205
These options tell the agent not to load any MIB modules.
3206
This doesn't affect the size of libraries or application
3207
binaries, but will reduce the memory footprint during runtime.
3208
3209
'--disable-mib-loading'
3210
This can be used in order to omit the code that loads and
3211
parses the MIB files altogether. This will reduce both the
3212
runtime memory footprint, and the binary sizes.
3213
3214
Once the agent (snmpd) has been linked, you might also try running
3215
'strip snmpd' to remove un-necessary debug/symbol information.
3216
3217
3218
3219
How can I reduce the installation footprint or speed up compilation?
3220
-------------------------------------------------------------------
3221
3222
The following configure options may also be useful:
3223
3224
--disable-agent Do not build the agent (snmpd).
3225
--disable-applications Do not build the apps (snmpget, ...).
3226
--disable-manuals Do not install the manuals.
3227
--disable-scripts Do not install the scripts (mib2c, ...).
3228
--disable-mibs Do not install the mib files.
3229
--disable-mib-loading Do not include code that parses and
3230
manipulates the mib files.
3231
3232
3233
3234
How can I compile the project for use on an embedded system?
3235
-----------------------------------------------------------
3236
3237
Although this is definitely a Frequently Asked Question on the project
3238
mailing lists, it hasn't really been a Frequently _Answered_ Question.
3239
The basic problem is that none of the core development team have much
3240
involvement or experience with embedded systems. And although we have
3241
repeatedly put out a plea for implementation reports and advice, this
3242
has not so far been particularly successful. So the first thing to say
3243
is that the following suggestions should be treated with a greater than
3244
usual level of suspicion.
3245
3246
The second thing to say is that compiling the Net-SNMP project for use
3247
on an embedded system typically means compiling the *agent* (rather than
3248
the trap receiver, or command-line tools). So that is what this entry
3249
will concentrate on.
3250
3251
There are three main aspects to consider:
3252
- how to compile the code,
3253
- *what* code to compile, and
3254
- how to install the resulting agent binary.
3255
3256
The Net-SNMP project uses the standard "configure" mechanism, so the
3257
usual cross-compilation options are available - in particular "--host"
3258
and "--target". It is also possible to specify the compiler and linker
3259
to use ("--with-cc" and "--with-ld"), and any special flags to pass
3260
to them ("--with-cflags" and "--with-ldflags"). There shouldn't be
3261
anything particularly special about compiling the Net-SNMP code, so
3262
see the documentation for your target environment for more information.
3263
(And please let us know if there *is* anything special that should be
3264
mentioned here!)
3265
3266
If the aim is simply to generate an SNMP agent to run on the target
3267
system, it's probably not necessary to compile the command-line tools
3268
or trap receiver. The configure option "--disable-applications" will
3269
omit these elements. See the previous entry for other potentially
3270
relevant useful options.
3271
3272
Unfortunately, the SNMP agent (and in particular, the code for individual
3273
MIB modules) is the most system-specific part of the Net-SNMP software.
3274
It may prove necessary to disable particular MIB modules if they do not
3275
compile successfully, or attempt to use the wrong system-specific APIs.
3276
This can be done using the configure option "--with-out-mib-modules".
3277
Alternatively, the option "--enable-mini-agent" will omit all but the
3278
core MIB module code. Additional modules can then be added individually
3279
using "--with-mib-modules".
3280
3281
Further information about how to deal with problems with individual MIB
3282
modules is reliant on suitable reports being forthcoming from the wider
3283
Net-SNMP community. The ball is in your court!
3284
3285
Finally, installing the agent binary is _not_ simply a matter of copying
3286
the "snmpd" file onto the target system. The agent typically relies on
3287
a number of additional libraries (and possibly the presence of assorted
3288
MIB files, unless this has been explicitly omitted). It is normally
3289
necessary to run "make install", before copying the installed framework
3290
to the target system.
3291
3292
If the install destination needs to be different to the eventual location
3293
on the target system, this can be handled using the configure options
3294
"--prefix" (for the target location) and "--with-install-prefix" (for the
3295
temporary install location). Alternatively, this can be handled as part
3296
of the install command:
3297
make install prefix={target location} INSTALL_PREFIX={temp location}
3298
3299
Alternatively, if the agent is compiled with static linking (and no MIB
3300
files), then it may be possible to simply copy the agent binary across to
3301
the target system. See the next entry for details.
3302
3303
3304
3305
How can I compile the project to use static linking?
3306
---------------------------------------------------
3307
3308
For totally static net-snmp executables, use
3309
configure --with-ldflags=-Bstatic
3310
3311
To compile your application with static libraries (eg for easier
3312
debugging), and to link to a non-installed build directory, try the
3313
following Makefile fragment:
3314
3315
NETSNMPDIR=/usr/local/build/snmp/full-clean-cvs-V5-1-patches
3316
NETSNMPCONFIG=$(NETSNMPDIR)/net-snmp-config
3317
3318
NETSNMPBASECFLAGS := $(shell $(NETSNMPCONFIG) --base-cflags)
3319
NETSNMPINCLUDES := $(shell $(NETSNMPCONFIG) --build-includes $(NETSNMPDIR))
3320
# base flags after build/src include, in case it has /usr/local/include
3321
NETSNMPCFLAGS=$(NETSNMPINCLUDES) $(NETSNMPBASECFLAGS)
3322
3323
NETSNMPBASELIBS := $(shell $(NETSNMPCONFIG) --base-agent-libs)
3324
NETSNMPEXTLIBS := $(shell $(NETSNMPCONFIG) --external-agent-libs)
3325
NETSNMPLIBDIRS := $(shell $(NETSNMPCONFIG) --build-lib-dirs $(NETSNMPDIR))
3326
NETSNMPLIBDEPS := $(shell $(NETSNMPCONFIG) --build-lib-deps $(NETSNMPDIR))
3327
LIB_DEPS=$(NETSNMPLIBDEPS)
3328
LIBS=$(NETSNMPLIBDIRS) -Wl,-Bstatic $(NETSNMPBASELIBS) -Wl,-Bdynamic $(NETSNMPEXTLIBS)
3329
3330
STRICT_FLAGS = -Wall -Wstrict-prototypes
3331
CFLAGS=-I. $(NETSNMPCFLAGS) $(STRICT_FLAGS)
3332
3333
This replaces the standard Makefile section, which will used installed
3334
libraries:
3335
3336
NETSNMPCONFIG=net-snmp-config
3337
3338
# uncomment this if you have GNU make
3339
#NETSNMPCFLAGS := $(shell $(NETSNMPCONFIG) --base-cflags)
3340
#NETSNMPLIBS := $(shell $(NETSNMPCONFIG) --agent-libs)
3341
NETSNMPCFLAGS=`$(NETSNMPCONFIG) --base-cflags`
3342
NETSNMPLIBS=`$(NETSNMPCONFIG) --agent-libs`
3343
3344
LIBS=$(NETSNMPLIBS)
3345
3346
3347
3348
Why does 'make test' skip various tests?
3349
---------------------------------------
3350
3351
Some of the tests are only relevant to particular operating systems,
3352
or rely on specific areas of functionality. The test framework will
3353
check whether the relevant elements are available before running the
3354
relevant tests, and will skip them if these modules have been omitted
3355
from the build environment (or do not apply to the current system).
3356
3357
One example of this are the tests T053agentv1trap, T054agentv2ctrap,
3358
T055agentv1mintrap, T056agentv2cmintrap and T113agentxtrap, which
3359
rely upon functionality from the NET-SNMP-EXAMPLES-MIB implementation.
3360
This module is not included in the default agent configuration, so the
3361
test framework will skip these tests.
3362
To include them, run
3363
"configure --with-mib-modules=examples/example"
3364
and re-compile.
3365
3366
3367
3368
Why does 'make test' complain about a pid file?
3369
-----------------------------------------------
3370
3371
Typically it says something like:
3372
3373
cat: cannot open /tmp/snmp-test-1-8694/*pid*
3374
3375
It's trying to tell you the port is blocked - typically because
3376
another copy of the agent is still running, left over from from a
3377
previous testing run.
3378
3379
If you type 'ps -ef' you should notice an orphaned process like:
3380
3381
snmpd -d -r -U -P /tmp/snmp-test-5-27295/snmpd.pid...
3382
3383
Kill this process.
3384
3385
This could be happening for several reasons including:
3386
3387
1. You are trying to do concurrent runs of 'make test'.
3388
3389
2. On a slow machine, the agent might be taking too long to
3390
start up. Try changing the value of the variable SNMP_SLEEP
3391
in testing/RUNTESTS from 1 to something higher - say 3 or 5.
3392
3393
3394
3395
CODING
3396
======
3397
3398
How do I write C code to integrate with the agent?
3399
-------------------------------------------------
3400
3401
There are three main methods for integrating external C code
3402
within the agent. The code can be compiled directly into the
3403
agent itself, it can be loaded dynamically while the agent is
3404
running, or it can be compiled into a separate application
3405
(a "subagent") which communicates with the main master agent.
3406
All three approaches have been touched on elsewhere within this FAQ.
3407
3408
As far as the module code is concerned, all three mechanisms
3409
use exactly the same module API. So a module developed for use
3410
directly within the agent, could also be included within a subagent,
3411
or loaded dynamically with no (or minimal) code changes needed.
3412
3413
Most of this section is concerned with more detailed aspects
3414
of developing such code - including the 'mib2c' tool, which can
3415
handle generating a basic code framework for implementing a
3416
given set of MIB objects.
3417
3418
3419
3420
How does the agent fetch the value of a MIB variable from the system?
3421
--------------------------------------------------------------------
3422
3423
That's typically the hardest bit of implementing a new MIB module,
3424
and is the one thing that 'mib2c' can't help with. It very much
3425
depends on the MIB variable concerned (and often the underlying
3426
operating system as well).
3427
3428
Relatively few MIB modules are completely self-contained, with all
3429
the information held internally within the agent, and all updates
3430
being done via SNMP requests. Such MIB modules can be implemented
3431
fairly easily.
3432
3433
More commonly, the agent needs to provide an SNMP-based interface to
3434
information held elsewhere, perhaps in the operating system kernel or
3435
some other application. Handling this is much more complex - since
3436
a lot depends on what mechanisms are provided for retrieving (and
3437
possibly updating) this information. The mib2c tool can generate code
3438
for processing SNMP requests, based on some internal cache of management
3439
information, but it cannot help with populating this cache with the
3440
underlying data. That is up to the MIB implementer.
3441
3442
See the existing MIB modules in the Net-SNMP source tree for various
3443
examples of assorted approaches to this task.
3444
3445
3446
3447
Mib2c complains about a missing "mib reference" - what does this mean?
3448
---------------------------------------------------------------------
3449
3450
This basically means that it hasn't loaded the MIB file containing
3451
the definition of the MIB subtree you're trying to implement. This
3452
might be because it hasn't been installed, the name is wrong, or
3453
(most likely), because it isn't in the default list. See the MIBS
3454
section for more details, or the next entry for suitable invocations
3455
of 'mib2c'.
3456
3457
3458
3459
Mib2c complains about not having a "valid OID" - what does this mean?
3460
---------------------------------------------------------------------
3461
3462
This probably means that you gave it the name of a MIB file (or
3463
module), rather than the name of an object defined in that file.
3464
Mib2c expects the name of a 'root' object, and will generate a
3465
template for the sub-tree starting from there.
3466
3467
If you've got a file 'MY-MIB.txt', defining the MIB module
3468
'MY-MIB' which contains a subtree based on the object 'myMib',
3469
then you should invoke mib2c as
3470
"mib2c .... myMib"
3471
rather than
3472
"mib2c .... MY-MIB.txt"
3473
or "mib2c .... MY-MIB"
3474
3475
Note that you'll probably also have to add your MIB to the list of
3476
MIBs that are loaded automatically, in order for mib2c to recognise
3477
the name of this object. So the command would typically be
3478
"MIBS=+MY-MIB mib2c .... myMib"
3479
or "MIBS=ALL mib2c .... myMib"
3480
3481
3482
3483
Why doesn't mib2c like the MIB file I'm giving it?
3484
-------------------------------------------------
3485
3486
This is most likely the same problem as the previous entry. Mib2c
3487
takes the name of a MIB _object_, not the name of a file (or MIB
3488
module). Try using the name of the MODULE-IDENTITY definition.
3489
3490
Another possibility is that the MIB may contain syntax errors.
3491
Try running it through 'snmptranslate' or a dedicated SMI
3492
validation tool (such as 'smilint' or the on-line interface at
3493
http://wwwsnmp.cs.utwente.nl/ietf/mibs/validate/)
3494
3495
3496
3497
Mib2c ignores my MIB and generates a pair of 'mib-2' code files. Why?
3498
---------------------------------------------------------------------
3499
3500
This is usually a sign of the same problem as the previous entries,
3501
giving mib2c the name of the file containing the MIB (or of the MIB
3502
itself), rather than an object within it.
3503
3504
Earlier versions of mib2c didn't detect this situation, and merrily
3505
constructed a template for a default starting point of the mib-2 node.
3506
3507
More recent versions complain about not having a valid OID instead.
3508
3509
3510
3511
What's the difference between the various mib2c configuration files?
3512
-------------------------------------------------------------------
3513
3514
Most of the mib2c config files are concerned with implementing
3515
MIB tables, and generate various alternative code templates.
3516
These basically fall into four distinct categories.
3517
3518
'mib2c.raw-table.conf' is the lightest of the templates, and
3519
just provides a fairly basic table framework. Most of the work
3520
of implementing the table - detecting which row is required for a
3521
given request, retrieving or updating the relevant column values,
3522
and interacting with the underlying subsystem - are all left to
3523
the MIB programmer.
3524
3525
The second group of templates - 'table_data', 'container' and
3526
'tdata' - all share the same basic model (although the internal
3527
details are rather different). The MIB implementer should define a
3528
data structure to represent a row of the table, and the helper then
3529
takes care of holding the table internally, as a collection of such
3530
per-row data structures. This includes identifying which row is
3531
required for a given request. Retrieving or updating the appropriate
3532
column value is left to the MIB programmer, although the generated
3533
framework includes most of the necessary code.
3534
Allied to this is a fourth "internal data" mib2c configuration
3535
file ('create-dataset') which handles the individual columns as
3536
well. This is the closest to a Plug-and-Play configuration, and
3537
the MIB implementer only needs to be concerned with any special
3538
processing, such as linking the table with the underlying subsystem.
3539
3540
The third style of mib2c config assumes that the table data is
3541
held externally to the helper - either within the MIB module code
3542
itself, or in the external subsystem. The generated code framework
3543
includes routines to "iterate" through the rows of the table, with
3544
the iterator helper simply deciding which row is required for a
3545
particular request. Once again, the MIB programmer must handle
3546
retrieving or updating the appropriate column value, although the
3547
generated framework includes most of the necessary code.
3548
There is a variant of this config ('iterate_access') which works
3549
in basically the same way. However this tries to separate out the
3550
standard processing, from the code that needs to be amended by the
3551
programmer for retrieving and updating the individual column values.
3552
3553
This is also the idea behind the final table-oriented mib2c config
3554
template - 'mib2c.mfd.conf' (or "MIBs for Dummies"). This is a much
3555
more flexible framework, which can be used with either internally
3556
held data, or iterating through an external representation. The
3557
distinguishing feature of this framework is that it separates out
3558
standard and table-specific processing, at a much finer level of
3559
detail than the others.
3560
3561
3562
The other mib2c config templates are concerned with implementing
3563
scalar objects ('scalar', 'int_watch'), code to generating traps
3564
('notify'), and various specialised requirements. There is also a
3565
template ('old-api') to generate code suitable for the previous v4
3566
UCD agent - though this is not particularly complete or reliable.
3567
It's probably better to use a pure v4 mib2c environment (or switch
3568
wholeheartedly to the v5 style).
3569
3570
3571
3572
Which mib2c configuration file should I use?
3573
-------------------------------------------
3574
3575
The answer to that heavily depends on the characteristics of the
3576
MIB objects being implemented. Of the handler-based table frameworks,
3577
'tdata' is more appropriate for tables that can be stored (or a copy
3578
cached) within the agent itself, while 'iterate' is more relevant to
3579
reporting data from outside the agent.
3580
The raw interface is only suitable in very specific circumstances,
3581
so it's probably sensible to start with one of the other frameworks
3582
first, and only look at this if none of the alternatives seem to work.
3583
3584
The decision between the handler-based configs and MfD is more a
3585
matter of the style of programming to use. Most of the frameworks
3586
define a single handler routine to process an incoming request, so
3587
all of the code is listed together, with the MIB programmer inserting
3588
table-specific processing into this single block of code.
3589
The MfD provides a series of individual object-specific routines,
3590
each concerned with one very specific task, and hides as much as
3591
possible from the programmer.
3592
3593
If you like to understand the broad thrust of what's happening,
3594
then one of the handler-based approaches would be the best choice.
3595
If you prefer to concentrate on the nitty-gritty of a given table,
3596
and are happy to trust that the rest of the processing will work
3597
correctly, then the MfD framework would be more appropriate.
3598
3599
For implementing a group of scalar objects, then the choice is
3600
simple - use 'mib2c.scalar.conf'. Similarly, for generating traps
3601
or informs, use 'mib2c.notify.conf'. But note that this only assists
3602
with the code to actually generate the trap. It does not address the
3603
issue of _when_ to send the trap. See the FAQ entry "How can I get
3604
the agent to generate a trap?" for more information.
3605
3606
3607
3608
How can I have mib2c generate code for both scalars and tables?
3609
--------------------------------------------------------------
3610
3611
This uses a very powerful tool called a "text editor" :-)
3612
3613
The mib2c tool uses separate configuration files to generate code
3614
for scalar objects, and for tables. This means that it's not possible
3615
to automatically generate a single code file that supports both scalars
3616
and tables.
3617
3618
Instead, the two code files need to be generated separately, and
3619
then combined manually. This will typically mean copying the handler
3620
routines for the scalar object(s) into the table file, and adding the
3621
code to register these handler(s) to the table initialisation routine.
3622
3623
3624
3625
Are there any examples, or documentation for developing MIB modules?
3626
-------------------------------------------------------------------
3627
3628
Many of the MIB modules shipped with the Net-SNMP agent still
3629
use the v4 "traditional" MIB module API, but an increasing number
3630
use one of the newer v5 helper-based handlers. All of these can
3631
be found under 'agent/mibgroup'
3632
3633
The 'tdata' helper is used in the new DisMan Event, Expression
3634
and Schedule MIB modules (see 'disman/{event,expr,schedule}/*').
3635
The similar 'dataset' helper is used in the older DisMan Event
3636
MIB implementation (see 'disman/mteEvent*') and the Notification
3637
Log MIB (see 'notification-log-mib/*'), used by 'snmptrapd' to
3638
log incoming traps.
3639
3640
The basic iterator handler is used in the TCP and UDP table
3641
implementations (mibII/tcpTable & mibII/udpTable), VACM context
3642
handling (mibII/vacm_context) and various tables relating to agent
3643
internals (agent/*). These show a number of different approaches
3644
to using the iterator helper, so it's worth comparing them.
3645
3646
The two examples/netSnmpHostsTable* modules provide a contrast
3647
between the iterator and iterator_access helpers.
3648
3649
There are several examples based on the MfD framework (see
3650
'{if,ip,tcp,udp}-mib/'). Much of this code is not intended to
3651
be viewed directly, but individual files are clearly commented
3652
to distinguish between internal implementation and public code.
3653
3654
The Net-SNMP agent does not currently include any MIB modules
3655
using the array-user container-based helper. The best examples
3656
of this are to be found in the net-policy project.
3657
See http://net-policy.sourceforge.net/
3658
3659
3660
3661
Where should I put the files produced by 'mib2c'?
3662
------------------------------------------------
3663
3664
If you're using the main source tree to compile your new module, then
3665
put these two files (mymib.[ch]) in the directory 'agent/mibgroup'.
3666
You should then re-run configure to add in your new module
3667
configure --with-mib-modules=mymib
3668
and recompile.
3669
3670
If you've got a number of new modules to add, it might be
3671
sensible to put them all into a single subdirectory of 'mibgroup'.
3672
Then create a header file, listing the individual components.
3673
This might look something like:
3674
3675
config_require(mymib/myObjects)
3676
config_require(mymib/myTable)
3677
config_require(mymib/myOtherTable)
3678
3679
If this was saved as the file 'mymib.h', then the same configure
3680
line given above, would pull in all three modules. See the current
3681
contents of 'agent/mibgroup' for examples of this. Note that the
3682
MfD framework will generate a similar grouping automatically.
3683
3684
3685
3686
Why doesn't my new MIB module report anything?
3687
---------------------------------------------
3688
3689
There are probably four main reasons why a new MIB module isn't working.
3690
Either it hasn't been included in the running agent, the code is present
3691
but hasn't been initialised, the module has been initialised but the
3692
handler isn't being called, or there's a problem with the module code itself.
3693
3694
To check whether the code files are being compiled, the easiest approach is
3695
simply to look at the directory where the code is located. When the agent is
3696
compiled, this should produce .o files (and probably .lo files) corresponding
3697
to the C code files for this module. Alternatively, run 'nm' (or 'strings')
3698
on the MIB module library (libnetsnmpmibs), and look for the names of the
3699
initialisation routines or handlers (or the text of any messages displayed by
3700
the module code).
3701
3702
One other thing to check is whether you have multiple copies of the software
3703
installed on the system. This is a particular problem when compiling from
3704
source (to include your new module), without first removing any vendor-supplied
3705
version of the agent (which won't include this new code).
3706
3707
3708
Assuming that you have confirmed that the module code is present in the agent,
3709
the next step is to check whether the initialisation routine is being called
3710
to register the MIB objects. The simplest way to do this is to include a
3711
suitable debugging statement within the initialisation routine, and start
3712
the agent with the corresponding '-Dtoken'. Alternatively, try walking the
3713
nsModuleName column object, and look for mention of the new MIB module.
3714
3715
3716
Assuming the module has been registered, the next step is to check whether
3717
the handler is being called, when the agent receives a suitable SNMP request.
3718
Again, the simplest way to do this is to include debugging statements within
3719
the handler routine, and start the agent with the corresponding '-Dtoken'.
3720
Then issue an "snmpget" request for an instance within the new MIB module.
3721
(This command is preferable to the usual "snmpwalk" command, as it is more
3722
closely focused on the MIB module in question).
3723
3724
If this indicates that the handler routine isn't being called, then there are
3725
two main likely causes. Firstly, check the access control settings. If these
3726
are configured to block access to this portion of the OID tree, then the MIB
3727
handler will never be called. Secondly, several of the table helpers are
3728
designed to know which rows of the table are valid, and will call the main
3729
MIB handler with information about the relevant row. If the requested row is
3730
not valid (or the table is empty), then the handler will not be called.
3731
3732
3733
Finally, if the handler _is_ being called, but is still not returning any
3734
information, then the cause probably lies with your MIB module code. In which
3735
case, it's really up to you to find the problem and fix it! Either activate
3736
any debugging code that you have included within the handler routine, or run
3737
the agent under a source code debugger, and step through the handler processing.
3738
In either case, it's much easier to debug these problems when processing an
3739
"snmpget" request, rather than "snmpgetnext" or "snmpwalk".
3740
3741
Remember that 'mib2c' simply generates template code for your MIB module.
3742
It's up to you to fill in the details, to report the actual information from
3743
whatever underlying subsystem is being monitored. Mib2c cannot help with
3744
the semantics of the MIB module - it's purely there to provide an initial
3745
code framework, based on the _syntax_ of the MIB module objects.
3746
3747
3748
3749
Why does the iterator call my get_{first,next} routines so often?
3750
-----------------------------------------------------------------------
3751
3752
The first thing to realise is that the 'get_first' and 'get_next'
3753
hook routines are concerned with processing a single SNMP request, not
3754
with walking the whole table. A full "snmpwalk" command will typically
3755
involve a series of individual 'GetNext' requests, and every one of
3756
these will trigger a separate 'get_first/get_next/get_next/....' cycle.
3757
3758
It's usually more efficient to use 'snmptable' which will walk
3759
each column in parallel (as well as displaying the results in a
3760
more natural manner).
3761
3762
Secondly, the iterator helper was originally designed to handle
3763
unsorted data, so will look at every row of the internal table for
3764
each request. If the data is actually held in the correct order,
3765
then it's worth setting the NETSNMP_ITERATOR_FLAG_SORTED flag:
3766
iinfo = SNMP_MALLOC_TYPEDEF(netsnmp_iterator_info);
3767
iinfo->flags |= NETSNMP_ITERATOR_FLAG_SORTED;
3768
This will help the situation somewhat.
3769
3770
But the iterator helper is inherently a relatively inefficient
3771
mechanism, and it may be worth looking at one of the other helpers,
3772
particularly if the data will be held within the agent itself.
3773
3774
3775
3776
How can I get the agent to generate a trap (or inform)?
3777
------------------------------------------------------
3778
3779
There are two aspects to having the agent generate a trap -
3780
knowing *how* to do this, and knowing *when* to do so.
3781
3782
Actually generating a trap is reasonably simple - just call one
3783
of the trap API routines ('send_easy_trap()' or 'send_v2trap()')
3784
with the relevant information (generic and specific trap values,
3785
or a varbind list respectively).
3786
3787
The 'mib2c.notify.conf' configuration file can be used to
3788
construct a suitable template routine for generating a trap,
3789
including building the variable list from the MIB trap
3790
definition. These variables can then be given suitable values,
3791
before invoking the 'send_v2trap()' call to actually send the trap.
3792
See the 'snmp_trap_api(3)' man page for further details.
3793
3794
Note that these APIs are only available within the agent (or
3795
subagents), and are not available to stand-alone applications.
3796
The code for 'snmptrap' shows an approach to use in such a case.
3797
3798
3799
Determining *when* to generate the trap (either directly or
3800
via the mib2c-generated routine) is often harder. If the trap
3801
is generated in response to some action within the agent, (e.g.
3802
as the result of a SET), then this isn't too much of a problem.
3803
3804
But if the trap is intended to report on a change of status
3805
(e.g. a network interface going up or down, or a disk filling up),
3806
then actually detecting this is non-trivial. Unless the underlying
3807
system can signal this situation to the agent, then it's typically
3808
necessary to poll the value(s) on a regular basis, save the results
3809
and compare them with the new values the next time round.
3810
3811
The simplest way to handle this is via the DisMan Event MIB,
3812
which is designed for exactly this purpose. As long as you can
3813
specify a MIB object to monitor, and the value or thresholds
3814
that should trigger a notification, then this module can check
3815
these values regularly, and automatically send a suitable trap
3816
when appropriate. See the 'snmpd.conf(5)' man page (under
3817
ACTIVE MONITORING) for details.
3818
3819
Otherwise, you'd need to use the routines documented in
3820
'snmp_alarm(3)' to regularly invoke a monitoring routine. This
3821
would check the necessary conditions (which need not be MIB
3822
objects), and call the 'send_xxx_trap()' routine (as generated
3823
by 'mib2c.notify.conf') when appropriate.
3824
3825
3826
3827
How can I get an AgentX sub-agent to generate a trap (or inform)?
3828
----------------------------------------------------------------
3829
3830
This is done in exactly the same manner as with the main SNMP agent.
3831
Calling one of the routines described in 'snmp_trap_api(3)' will cause
3832
the AgentX sub-agent to send a notification to the master agent, which
3833
will then pass this on to the configured trap destination(s).
3834
3835
One of the original design aims of the Net-SNMP AgentX support was that
3836
the agent (or subagent) framework should be transparent to a MIB module
3837
implementer. The interface between the agent framework and a MIB module
3838
should be independent of the protocol used to receive the original request.
3839
So the exact same MIB module code could be used within a traditional
3840
SNMP-only agent, or an AgentX subagent, with no changes needed.
3841
3842
This also holds for sending traps.
3843
3844
3845
3846
How can I get the agent to send an SNMPv1 (or SNMPv2c) trap?
3847
-----------------------------------------------------------
3848
3849
It doesn't make any difference whether you use the v1-style
3850
API call 'send_easy_trap()' or the v2-style 'send_v2trap()'.
3851
What matters is the directive(s) in the snmpd.conf file.
3852
3853
If this file contains 'trapsink', then the agent will send
3854
an SNMPv1 trap. If this file contains 'trap2sink', then the
3855
agent will send an SNMPv2c trap. And if this file contains
3856
both, then the agent will send *two* copies of this trap.
3857
3858
See the entry
3859
Where are these traps sent to?
3860
in the AGENT section for details.
3861
3862
3863
3864
How can I get the agent to include varbinds with an SNMPv1 trap?
3865
---------------------------------------------------------------
3866
3867
There are two ways to do this. You can either use the
3868
'send_v2trap()' call and give a varbind list, starting with
3869
the v2-equivalent of the SNMPv1 trap, followed by the
3870
additional varbinds.
3871
3872
Alternatively, you can use the API call 'send_trap_vars()'
3873
which takes the same generic/specific trap values as
3874
'send_easy_trap()', plus the list of additional varbinds.
3875
3876
In either case, you also need to have 'trapsink' in the
3877
snmpd.conf file. The resulting trap will be identical,
3878
whichever approach is used.
3879
3880
3881
3882
How can I get the agent to send an SNMPv1 enterprise-specific trap?
3883
------------------------------------------------------------------
3884
3885
There are two ways to do this. You can either use the
3886
'send_v2trap()' call and give a varbind list, starting
3887
with the v2-equivalent of the SNMPv1 trap, followed by the
3888
additional varbinds.
3889
3890
Alternatively, you can use the (undocumented) API call
3891
'send_enterprise_trap_vars()' which takes the same parameters
3892
as 'send_trap_vars()', plus the enterprise OID to use (in the
3893
usual name/length form). See the code file 'agent_trap.c'
3894
3895
In either case, you also need to have 'trapsink' in the
3896
snmpd.conf file. The resulting trap will be identical,
3897
whichever approach is used.
3898
3899
3900
3901
How can I get the agent to send an SNMPv3 trap (or inform)?
3902
----------------------------------------------------------
3903
3904
It doesn't matter which API call you use to specify the
3905
trap - 'send_easy_trap()', 'send_v2trap()' or one of the other
3906
calls mentioned above. Generating an SNMPv3 notification
3907
(rather than a community-based one) is controlled by the
3908
snmpd.conf file.
3909
3910
To send an SNMPv3 trap, this file should contain a
3911
'snmpsess' directive, specifying the version, security
3912
level, user name and passphrases (if applicable), as
3913
well as the destination address. This is basically
3914
the same as the command line required for sending the
3915
trap manually, using 'snmptrap'.
3916
3917
Note that (unlike 'snmptrap') this directive does *not*
3918
read default settings from an 'snmp.conf' file, so these
3919
must be specified explicitly in the 'snmpsess' line.
3920
3921
3922
3923
Why does calling 'send_v2trap' generate an SNMPv1 trap (or vice versa)?
3924
----------------------------------------------------------------------
3925
3926
The two versions of the trap API calls are concerned with how
3927
the trap is represented when it is passed *in* to the API, not
3928
the version of the trap PDU that will actually be generated by
3929
the agent. That is determined by the configuration token used
3930
to set up the trap destination.
3931
3932
Remember that in general, all traps are sent to all destinations.
3933
This means that a trap specified using the SNMPv1 trap syntax
3934
needs to be converted to the SNMPv2 format before it can be sent
3935
to an SNMPv2 (or SNMPv3) destination. Similarly, a trap specified
3936
using the SNMPv2 syntax needs to be converted to the SNMPv1 format
3937
before it can be sent to an SNMPv1 sink.
3938
3939
Essentially, the API call to use depends on what you asking for,
3940
which is not necessarily what the recipients will actually get!
3941
See 'snmp_trap_api(3)' for a fuller explanation.
3942
3943
3944
3945
How can I register a MIB module in a different (SNMPv3) context?
3946
---------------------------------------------------------------
3947
3948
Contexts are a mechanism within SNMPv3 (and AgentX) whereby
3949
an agent can support parallel versions of the same MIB objects,
3950
referring to different underlying data sets. By default, a MIB
3951
module registrations will use the default empty context of "".
3952
But it's also possible to provide MIB information using a different
3953
(non-default) context.
3954
3955
There are three aspects involved in doing this. Firsly, it's necessary
3956
to register the MIB module in this non-default context. With the v4 API,
3957
this uses the call 'register_mib_context()' rather than the REGISTER_MIB
3958
macro. This is significantly more detailed, but most of the additional
3959
parameters can take fixed values, if all that's needed is to change the
3960
registration context.
3961
3962
Instead of the macro call:
3963
REGISTER_MIB("my_token", my_variables, variable1, my_variables_oid);
3964
use the function call:
3965
register_mib_context( "my_token",
3966
my_variables, sizeof(variable1),
3967
sizeof(my_variables)/sizeof(variable1),
3968
my_variables_oid,
3969
sizeof(my_variables_oid)/sizeof(oid),
3970
DEFAULT_MIB_PRIORITY, 0, 0, NULL,
3971
"my_context", -1, 0);
3972
3973
Things are much easier with the v5 helper-based API. Having
3974
created the registration structure, this just requires setting the
3975
'contextName' field before actually registering the MIB module:
3976
netsnmp_handler_registration *reg;
3977
reg = netsnmp_create_handler_registration(.....);
3978
reg->contextName = strdup("my_context");
3979
netsnmp_register_handler(reg);
3980
3981
3982
Secondly, it is necessary to configure the access control settings to allow
3983
access to information in the new context. This is handled automatically
3984
when using the simple "rouser" or "rwuser" directives. But if access control
3985
is configured using the fuller com2sec/group/view/access mechanism, then the
3986
"access" line must specify the appropriate context(s), either explicitly:
3987
3988
access {group} "my_context" any noauth exact ......
3989
3990
or using a single entry to cover all possible contexts:
3991
3992
access {group} "" any noauth prefix ......
3993
3994
3995
Finally, the SNMP request used to retrieve (or update) the information
3996
must also specify the required context. With SNMPv3 requests, the context
3997
is part of the protocol, so this can be done using a command-line option:
3998
3999
snmpwalk -v 3 -n my_context .....
4000
4001
With community-based requests (SNMPv1 and SNMPv2c), things aren't so simple.
4002
Although the "rocommunity" and "rwcommunity" settings also configure access
4003
for all possible contexts, there's no way to specify a non-default context
4004
as part of the request.
4005
4006
The only way to handle non-default contexts with community-based SNMP requests
4007
is to set up a mapping from the community string to the desired context. This
4008
uses the "com2sec" directive, with an additional "-Cn" parameter. Note that
4009
this also means that the access control must be configured using the full
4010
com2sec/group/view/access mechanism. The short-form access control directives
4011
do not handle the mapping of community strings to non-default contexts.
4012
4013
4014
4015
MISC
4016
======
4017
4018
What ASN.1 parser is used?
4019
-------------------------
4020
4021
The parser used by both the agent and client programs is coded by hand.
4022
This parser has recently been re-vamped to allow control of which of
4023
the available MIBs should be included, and to handle duplicate object
4024
subidentifiers.
4025
The source code can be found in the snmplib directory (in 'parse.c'),
4026
and the parser is usually bundled into the library 'libnetsnmp.a'
4027
4028
Note that the parser attempts to be fairly forgiving of some common
4029
errors and incompatibilities in MIB files. The Net-SNMP tools accepting
4030
a MIB file without complaint does *not* imply that the MIB is strictly
4031
correct.
4032
Certain MIBs may need some amendments to allow them to be read
4033
correctly by the parser. Contact the coders' list for advice.
4034
4035
4036
4037
What is the Official Slogan of the net-snmp-coders list?
4038
-------------------------------------------------------
4039
4040
"The current implementation is non-obvious and may need to be improved."
4041
(with thanks to Rohit Dube)
4042
4043
And an alternate, added 26-Apr-2000:
4044
4045
"In theory, it shouldn't be that hard, but it just needs to be done."
4046
4047
4048
Loggerhead is a web-based interface for Breezy
Version: 2.0.1