Server : Apache
System : Linux server1.cgrithy.com 3.10.0-1160.95.1.el7.x86_64 #1 SMP Mon Jul 24 13:59:37 UTC 2023 x86_64
User : nobody ( 99)
PHP Version : 8.1.23
Disable Function : NONE
Directory : /usr/share/doc/net-snmp-libs-5.7.2/
|
Server : Apache System : Linux server1.cgrithy.com 3.10.0-1160.95.1.el7.x86_64 #1 SMP Mon Jul 24 13:59:37 UTC 2023 x86_64 User : nobody ( 99) PHP Version : 8.1.23 Disable Function : NONE Directory : /usr/share/doc/net-snmp-libs-5.7.2/ |
Frequently Asked Questions (FAQ) for the UCD/Net-SNMP package
=============================================================
FAQ Author: Dave Shield
Net-SNMP Version: 5.7.2
Net-SNMP/UCD-SNMP Project Leader: Wes Hardaker
Email: net-snmp-coders@lists.sourceforge.net
TABLE OF CONTENTS
=================
TABLE OF CONTENTS
GENERAL
What is it?
Where can I get it?
What documentation is available?
Are there binaries available?
What's the difference between UCD-SNMP and Net-SNMP?
What operating systems does it run on?
What happens if mine isn't listed?
Does it run on Windows?
How do I find out about new releases?
How can I find out what other people are doing?
How do I submit a patch or bug report?
Can I reuse the code in my commercial application?
What's the difference between SNMPv1, SNMPv2 and SNMPv3?
What's the difference between SNMPv2 and SNMPv2c?
Which versions of SNMP are supported in this package?
Can I use SNMPv1 requests with an SNMPv2 MIB (or vice versa)?
How can I monitor my system with SNMP?
Where can I find more information about network management?
What ports does SNMP use?
Is Net-SNMP thread safe?
APPLICATIONS
How do I add a MIB?
How do I add a MIB to the tools?
Why can't I see anything from the agent?
Why doesn't the agent respond?
I can see the system group, but nothing else. Why?
Why can't I see values in the <ENTERPRISE> tree?
The agent worked for a while, then stopped responding. Why?
Requesting an object fails with "Unknown Object Identifier" Why?
Why do I get "noSuchName" when asking for "sysUpTime" (or similar)?
Why do I sometimes get "End of MIB" when walking a tree, and sometimes not?
How do I use SNMPv3?
Why can't I set any variables in the MIB?
Variables seem to disappear when I try to set them. Why?
Why can't I change sysLocation (or sysContact)?
I get an error when trying to set a negative value - why?
I get an error when trying to query a string-indexed table value - why?
How should I specify string-indexed table values?
How do I send traps and notifications?
How do I receive traps and notifications?
How do I receive SNMPv1 traps?
Why don't I receive incoming traps?
My traphandler script doesn't work when run like this - why not?
How can the agent receive traps and notifications?
How big can an SNMP request (or reply) be?
How can I monitor my systems (disk, memory, etc)?
Applications complain about entries in your example 'snmp.conf' file. Why?
OK, what should I put in snmp.conf?
How do I specify IPv6 addresses in tools command line arguments?
PERL
What is the purpose of the Perl SNMP module?
Where can I get the Perl SNMP package?
How do I install the Perl SNMP modules?
But compiling this fails! Why?
Compiling the Perl module works OK, but 'make test' fails. Why?
Why can't mib2c (or tkmib) locate SNMP.pm?
Why can't mib2c (or tkmib) load SNMP.so?
Why can't tkmib locate Tk.pm?
Why does your RPM complain about missing Perl modules?
I've got a problem with the Net-SNMP module. Can you help?
MIBS
Where can I find a MIB compiler?
Why aren't my MIB files being read in?
Where should I put my MIB files?
What does "Cannot find module (XXX-MIB)" mean?
I'm getting answers, but they're all numbers. Why?
What does "unlinked OID" mean?
The parser doesn't handle comments properly. Why not?
How can I get more information about problems with MIB files?
What's this about "too many imported symbols"?
Do I actually need the MIB files?
AGENT
What MIBs are supported?
What protocols are supported?
How do I configure the agent?
How do I remove a MIB from the agent?
I've installed a new MIB file. Why can't I query it?
How do I add a MIB to the agent?
What's the difference between 'exec', 'sh', 'extend' and 'pass'?
What's the difference between AgentX, SMUX and proxied SNMP?
What is the purpose of 'dlmod'?
Which should I use?
Can I use AgentX when running under Windows?
How can I run AgentX with a different socket address?
How can I turn off SMUX support?
How can I combine two copies of the 'mib2' tree from separate subagents?
What traps are sent by the agent?
Where are these traps sent to?
How can I send a particular trap to selected destinations?
When I run the agent it runs and then quits without staying around. Why?
After a while the agent stops responding, and starts eating CPU time. Why?
How can I stop other people getting at my agent?
How can I listen on just one particular interface?
The agent is complaining about 'snmpd.conf'. Where is this?
Why does the agent complain about 'no access control information'?
How do I configure access control?
How do I configure SNMPv3 users?
The 'createUser' line disappears when I start the agent. Why?
What's the difference between /var/net-snmp and /usr/local/share/snmp?
My new agent is ignoring the old snmpd.conf file. Why?
Where should the snmpd.conf file go?
Why am I getting "Connection refused"?
Why can't I see values in the UCDavis 'extensible' or 'disk' trees?
Why can't I see values in the UCDavis 'memory' or 'vmstat' tree?
What do the CPU statistics mean - is this the load average?
How do I get percentage CPU utilization using ssCpuRawIdle?
What about multi-processor systems?
The speed/type of my network interfaces is wrong - how can I fix it?
The interface statistics for my subinterfaces are all zero - why?
Does the agent support the RMON-MIB?
What does "klread: bad address" mean?
What does "nlist err: wombat not found" (or similar) mean?
What does "Can't open /dev/kmem" mean?
The system uptime (sysUpTime) returned is wrong!
Can the agent run multi-threaded?
Can I use AgentX (or an embedded SNMP agent) in a threaded application?
COMPILING
How do I control the environment used to compile the software?
How do I control the environment used to compile the software under Windows?
Why does the compilation complain about missing libraries?
How can I reduce the memory footprint?
How can I reduce the installation footprint or speed up compilation?
How can I compile the project for use on an embedded system?
How can I compile the project to use static linking?
Why does 'make test' skip various tests?
Why does 'make test' complain about a pid file?
CODING
How do I write C code to integrate with the agent?
How does the agent fetch the value of a MIB variable from the system?
Mib2c complains about a missing "mib reference" - what does this mean?
Mib2c complains about not having a "valid OID" - what does this mean?
Why doesn't mib2c like the MIB file I'm giving it?
Mib2c ignores my MIB and generates a pair of 'mib-2' code files. Why?
What's the difference between the various mib2c configuration files?
Which mib2c configuration file should I use?
How can I have mib2c generate code for both scalars and tables?
Are there any examples, or documentation for developing MIB modules?
Where should I put the files produced by 'mib2c'?
Why doesn't my new MIB module report anything?
Why does the iterator call my get_{first,next} routines so often?
How can I get the agent to generate a trap (or inform)?
How can I get an AgentX sub-agent to generate a trap (or inform)?
How can I get the agent to send an SNMPv1 (or SNMPv2c) trap?
How can I get the agent to include varbinds with an SNMPv1 trap?
How can I get the agent to send an SNMPv1 enterprise-specific trap?
How can I get the agent to send an SNMPv3 trap (or inform)?
Why does calling 'send_v2trap' generate an SNMPv1 trap (or vice versa)?
How can I register a MIB module in a different (SNMPv3) context?
MISC
What ASN.1 parser is used?
What is the Official Slogan of the net-snmp-coders list?
GENERAL
=======
What is it?
----------
- Various tools relating to the Simple Network Management Protocol
including:
* An extensible agent
* An SNMP library
* tools to request or set information from SNMP agents
* tools to generate and handle SNMP traps
* a version of the unix 'netstat' command using SNMP
* a graphical Perl/Tk/SNMP based mib browser
This package is originally based on the Carnegie Mellon University
SNMP implementation (version 2.1.2.1), but has developed significantly
since then.
Where can I get it?
------------------
Download:
- http://www.net-snmp.org/download/
- ftp://ftp.net-snmp.org/pub/sourceforge/net-snmp/
Web page:
- http://www.net-snmp.org/
Sourceforge Project page:
- http://www.net-snmp.org/project/
Mirrors (note that sourceforge download servers are mirrored themselves):
- US: ftp://ftp.freesnmp.com/mirrors/net-snmp/
- Greece: ftp://ftp.ntua.gr/pub/net/snmp/net-snmp/
What documentation is available?
-------------------------------
This FAQ (!)
README and individual READMEs for various platforms
README.thread (discusses threading issues)
INSTALL
PORTING
EXAMPLE.conf
man pages for the individual tools, files and the API
A guide for extending the agent
Tutorials for both ucd-snmp v4 and net-snmp v5
at http://www.net-snmp.org/tutorial/
and http://www.net-snmp.org/tutorial-5/ respectively
Most of this documentation (plus archives of the mailing lists)
is also available on our web page:
http://www.net-snmp.org/
There is also a Wiki (including a community-maintained version
of this FAQ) at
http://www.net-snmp.org/wiki/
Are there binaries available?
----------------------------
There are binaries for some versions/systems available under
the "net-snmp binaries" package on the SourceForge "Files"
page, which is linked to from the main project download web
page at http://www.net-snmp.org/download.html.
These binaries are also available on the project FTP site,
with a link on the same web page.
There is also a mirror at ftp://ftp.freesnmp.org/mirrors/net-snmp/
What's the difference between UCD-SNMP and Net-SNMP?
---------------------------------------------------
Not a great deal, really.
Although the project originally started at UC Davis (hence the name),
and it has always been based there, most of the contributors have had
little or no connection with this institution.
The move to SourceForge was intended to provide a more flexible
environment for the project, and to distribute the administrative
workload more evenly. The change of name simply reflects this move,
which was the last remaining link with UC Davis.
The 4.2.x line saw the last releases made using the ucd-snmp name,
and all releases on this line have been been bug-fixes only. Release
5.0 was the first version released under the Net-SNMP name, and all
further development is being done on the 5.x code base. The 4.2.x
code line is now effectively closed down, as are the older 5.x branches.
Much of the work done for the various 5.x releases has involved
some fairly significant changes to the code - in particular the
architecture of the agent. However attempts have been made to retain
backwards compatibility as much as possible, and most code written
for earlier releases should continue to work. The most visible
change from the 4.2.x UCD suite to the 5.x Net-SNMP releases was a
restructuring of the header file organisation - not least a change
from <ucd-snmp/xxx.h> to <net-snmp/yyy.h>.
But given the maturity of the Net-SNMP code, this should be less
of a consideration for most current SNMP development projects.
What operating systems does it run on?
-------------------------------------
Both the applications and the agent have been reported as running
(at least in part) on the following operating systems:
* Linux (kernels 2.6 to 1.3)
* Solaris/SPARC (11 to 2.3), Solaris/Intel (10, 9) -- see
README.solaris
* HP-UX (11.31 to 9.01) -- see README.hpux11
* Mac OS X (10.5 to 10.1) -- see README.osX
* NetBSD (2.0 to 1.0)
* FreeBSD (7.0 to 2.2)
* OpenBSD (4.0 to 2.6)
* BSDi (4.0.1 to 2.1)
* AIX (6.1, 5.3, 5.2, 5.1, 4.3.3, 4.1.5, 3.2.5) -- see README.aix
* IRIX (6.5 to 5.1)
* OSF (4.0, 3.2 and Tru64 Unix 5.1B) -- see README.tru64
* SunOS 4 (4.1.4 to 4.1.2)
* Ultrix (4.5 to 4.2)
* Dynix/PTX 4.4
* QNX 6.2.1A
We have also been informed about a port to the Stratus VOS.
See http://ftp.stratus.com/vos/network/network.html for details.
See the next question but one for the status of Windows support.
Certain systems fail to compile particular portions of the agent.
These can usually be persuaded to compile (at the loss of some
functionality) by omitting the modules affected.
See the next question for more details.
Also note that the presence of a particular configuration in this
list does not imply a perfect or complete implementation. This
is simply what various people have reported as seeming to work.
(Or more frequently, the configurations where people have reported
problems that we think we've subsequently fixed!)
What happens if mine isn't listed?
---------------------------------
It's probably worth trying to compile it anyway. Unless your
system is significantly different to the supported configurations,
most of the code (library, applications and the agent infrastructure)
should probably compile with little or no difficulty. The most
likely source of problems will be MIB modules within the agent,
as this tends to be where the most system-specific code is found.
If only a few modules fail to compile, try removing them from
the agent by running "configure --with-out-mib-module=xxx,yyy",
and re-compiling. If a large number of modules fail, then it
might be easier to start from a relatively bare system, using
"configure --enable-mini-agent --with-defaults". Then if this
minimal agent compiles and runs successfully, try adding each of
the missing mibgroups individually using the configure option
'--with-mib-module'.
If configure fails with "invalid configuration" messages, or
you get completely stuck, contact the coders list for advice.
Similarly, if you manage to get this working on a new system,
please let us know of any code changes that you needed to make,
together with details of the hardware you're using, and what
versions of the operating system you've tried it on. The entry
'host' in the file 'config.status' should show this information.
Oh, and congratulations!
Does it run on Windows?
----------------------
The suite should compile and run on Win32 platforms, including
the library, command-line tools and the basic agent framework.
Note that the agent now includes support for the MIB-II module,
but this requires Microsoft's Core Platform SDK. Instructions
for how to install this are given in README.win32.
Pre-compiled binaries are available from the project web site.
As of v5.4, the Net-SNMP agent is able to load the Windows SNMP
service extension DLLs by using the Net-SNMP winExtDLL extension.
Some other Net-SNMP MIB modules, including the UCD pass-through
extensions, do not currently work under Windows. Volunteers to assist
with these missing modules are likely to welcomed with open arms :-)
Further details of Windows support (currently Visual C++, MinGW
and Cygnus cygwin32) is available in the file README.win32.
How do I find out about new releases?
------------------------------------
There is a mailing list for these announcements
net-snmp-announce@lists.sourceforge.net
To be added to (or removed from) this list, visit
http://www.net-snmp.org/lists/net-snmp-announce/
Or you can send a message to the address
net-snmp-announce-request@lists.sourceforge.net
with a subject line of 'subscribe' (or 'unsubscribe' as appropriate).
Advance notice of upcoming releases are also made on the
net-snmp-users list (for "release candidates") for a week
or two before the full release, and on the net-snmp-coders
list (for "pre-releases") during the period prior to this.
Major code revisions may be announced more widely, but these
lists are the most reliable way to keep in touch with the
status of the package.
Patches to fix known problems are also made available via the web site:
http://www.net-snmp.org/patches/
How can I find out what other people are doing?
----------------------------------------------
There is a general purpose discussion list
net-snmp-users@lists.sourceforge.net
To be added to (or removed from) this list, visit
http://www.net-snmp.org/lists/net-snmp-users/
Or you can send a message to the address
net-snmp-users-request@lists.sourceforge.net
with a subject line of 'subscribe' (or 'unsubscribe' as appropriate).
To find out what the developers are doing, and to help them
out, please read the PORTING file enclosed with the package.
There is also a #net-snmp IRC channel set up on the freenode.net
chat system. You can connect to this via chat.freenode.net.
See http://www.freenode.net/ for more information on getting
started with IRC.
Several core developers hang out on this channel on a fairly
regular basis.
How do I submit a patch or bug report?
-------------------------------------
The best way to submit a bug report is via the bug database through
the interface found at
http://www.net-snmp.org/bugs/
Be sure to include the version of the package that you've been working
with, the output of the command 'uname -a', the precise configuration
or command that triggers the problem and a copy of any output produced.
Questions about using the package should be directed at the
net-snmp-users@lists.sourceforge.net mailing list. Note that this
mailing list is relatively busy, and the people answering these
questions are doing so out of the goodness of their hearts, and in
addition to their main employment. Please note the following:
- use plain text mail, rather than HTML
- don't resend questions more than once
(even if no-one answered immediately)
- include full details of exact commands and error messages
("I've tried everything, and it doesn't work" isn't much use!)
- do *NOT* send messages to -users and -coders mailing lists
(most developers read both anyway)
- don't mail the developers privately - keep everything on the list
We can't promise to be able to solve all problems, but we'll
certainly try and help. But remember that this is basically an
unsupported package. It's Open Source, so if you need something
fixing badly enough, fundamentally it's up to you to do the work.
All patches should be submitted to the patch manager at
http://www.net-snmp.org/patches/
If possible, submit a bug report describing the patch as well
(referencing it by its patch number) since the patch manager
doesn't contain a decent description field.
The best way to submit patch (diff) information is by checking out
the current code from the development git trunk, making your changes
and then running "git diff" or "git format-patch" after you're done.
(Please see http://www.net-snmp.org/wiki/index.php/Git for further
information on using git with the Net-SNMP project)
If you're working from a source code distribution, and comparing old
and new versions of a code file, use "diff -u OLDFILE NEWFILE"
Can I reuse the code in my commercial application?
-------------------------------------------------
The details of the COPYRIGHTs on the package can be found in the COPYING
file. You should have your lawyer read this file if you wish to use the
code in your commercial application. We will not summarize here what is
in the file, as we're not lawyers and are unqualified to do so.
What's the difference between SNMPv1, SNMPv2 and SNMPv3?
-------------------------------------------------------
What's the difference between SNMPv2 and SNMPv2c?
------------------------------------------------
A full description is probably beyond the scope of this FAQ.
Very briefly, the original protocol and admin framework was
described in RFCs 1155-1157, and is now known as SNMPv1.
Practical experience showed up various problems and deficiencies
with this, and a number of revised frameworks were developed to try
and address these problems. Unfortunately, it proved difficult to
achieve any sort of agreement - particularly over the details of
the administrative framework to use.
There was less disagreement over the proposed changes to the
protocol operations. These included:
* increasing the range of errors that could be reported
* introducing "exception values"
(so a single missing value didn't affect
the other varbinds in the same request)
* a new GETBULK operation
(a supercharged GETNEXT)
* new notification PDUs
(closer in structure to the other request PDUs)
Strictly speaking, it's this revised protocol (originally defined
in RFC 1905, and most recently in RFC 3416) that is "SNMPv2".
The only framework based on this protocol that saw a significant
level of use was "Community-based SNMPv2" or "SNMPv2c" (defined
in RFC 1901). This retained the same administrative framework
as SNMPv1 (with all of the accompanying limitations), but using
the new protocol operations.
More recently, a new administrative framework has been developed,
building on the various competing SNMPv2 proposals, and using the
same SNMPv2 protocol operations. This is SNMPv3, which is defined
in RFCs 3411-3418. It addresses some of the deficiencies of the
community-based versions, including significant improvements to
the security of SNMP requests (like it finally has some!).
SNMPv3 is now a full IETF standard protocol.
Strictly speaking, SNMPv3 just defines a fairly abstract framework,
based around the idea of "Security Models" and "Access Control Models".
It's this combination of SNMPv3 plus accompanying models that actually
provides a working SNMP system.
However, the only models in common use are the "User-based Security
Model" (RFC 3414) and the "View-based Access Control Model" (RFC 3415).
So "SNMPv3" is frequently used to mean the combination of the basic
SNMPv3 framework with these two particular models.
This is also sometimes described as "SNMPv3/USM".
So in brief:
- SNMPv2c updated the protocol operations
but left the administrative framework unchanged.
- SNMPv3 updated the administrative framework
but left the protocol operations unchanged.
Which versions of SNMP are supported in this package?
----------------------------------------------------
This package currently supports the original SNMPv1 (RFC 1157),
Community-based SNMPv2 (RFCs 1901-1908), and SNMPv3 (RFCs 3411-3418).
The agent will respond to requests using any of these protocols,
and all the tools take a command-line option to determine which
version to use.
Support for SNMPv2 classic (a.k.a. "SNMPv2 historic" - RFCs 1441-1452)
was dropped with the 4.0 release of the UCD-snmp package.
Can I use SNMPv1 requests with an SNMPv2 MIB (or vice versa)?
------------------------------------------------------------
Yes.
The syntax used to specify a MIB file (better referred
to as SMIv1 or SMIv2) is purely concerned with how to define
the characteristics of various management objects. This is
(almost) completely unrelated to the versions of the protocol
used to operate on these values. So it is quite reasonable to
use SNMPv1 requests on objects defined using SMIv2, or SNMPv2
(or SNMPv3) requests on objects defined using SMIv1.
The one exception is objects of syntax Counter64, which are
only accessible using SNMPv2 or higher. SNMPv1 requests will
either treat such objects as an error, or skip them completely.
Note that SMIv1 is effectively obsolete, and all new MIBs
should be written using SMIv2.
How can I monitor my system with SNMP?
-------------------------------------
There are two main methods of using SNMP for monitoring. One is to regularly
query the SNMP agent for information of interest, graphing these values and/or
saving them for later analysis. That's not really the focus of the Net-SNMP
project - our tools are more low-level, single-shot commands. For this sort
of high-level management, you're really looking at a management console
application (such as Nagios or OpenNMS), or a data logging application
(such as RRDtool, or one of its front-ends - MRTG, Cacti, etc).
The other approach is to configure the SNMP agent to monitor the relevant
information itself, and issue an alert when the values pass suitable limits.
See the section ACTIVE MONITORING in the snmpd.conf(5) man page for details.
Note that this entry makes no reference as to _what_ you should monitor, or
what values might be significant. That's because it is impossible to provide
a universal answer to these questions. The information to monitor, and the
normal operating values will ultimately depend on your local environment.
SNMP is simply a tool to _help_ you manage your systems - it isn't a magic
panacea - you still have to think for yourself!
Where can I find more information about network management?
----------------------------------------------------------
There are a number of sites with network management information on
the World Wide Web. Some of the most useful are
http://www.simpleweb.org/
http://www.snmplink.org/
http://www.mibdepot.com/
The SNMP Usenet newsgroup is now mostly defunct, but although the
FAQ hasn't been updated for a while, it still contains a large
amount of useful information relating to SNMP, including books,
software, other sites, how to get an enterprise number, etc, etc.
This is available from
ftp://rtfm.mit.edu/pub/usenet/comp.protocols.snmp/
or via any of the Web sites above.
What ports does SNMP use?
------------------------
There are three main network ports (and one named socket), which are
typically used by SNMP. These are:
- UDP port 161 - SNMP requests (GET* and SET)
- UDP port 162 - SNMP notifications (Traps/Informs)
- TCP port 705 - AgentX
- /var/agentx/master - AgentX
However, these are simply the default "well-known" ports for these purposes,
and it is perfectly possible to accept requests on other ports.
Is Net-SNMP thread safe?
-----------------------
Strictly speaking, no. However, it is possible to use the library within
a multi-threaded management application. This is covered in detail in
the file README.thread (shipped with the standard distribution), but can
be summarised as follows:
- Call 'snmp_sess_init()' prior to activating any threads.
This reads in and parses MIB information (which isn't thread-safe)
as well as preparing a session structure for subsequent use.
- Open an SNMP session using 'snmp_sess_open()' which returns an
opaque session handle, which is essentially independent of any
other sessions (regardless of thread).
- Resource locking is not handled within the library, and is the
responsibility of the main application.
The Net-SNMP agent has not been designed for multi-threaded use. It
should be safe to use the agent library to embed a subagent within a
threaded application as long as *all* SNMP-related activity (including
generating traps, and parsing MIBs) is handled within a single thread.
The command-line tools shipped as part of the Net-SNMP distribution
are simple single-threaded applications, and are not designed for
multi-threaded use. Adapting these to a threaded model is left as
an exercise for the student.
The same holds true for the notification receiver (snmptrapd).
Unfortunately, the SNMPv3 support was added about the same time as
the thread support and since they occurred in parallel the SNMPv3
support was never checked for multi-threading correctness. It is
most likely that it is not thread-safe at this time.
APPLICATIONS
============
How do I add a MIB?
------------------
This is actually two separate questions, depending on whether you
are referring to the tools, or the agent (or both).
See the next question or the next section respectively.
How do I add a MIB to the tools?
-------------------------------
Adding a MIB to the client-side tools has two main effects:
- it allows you to refer to MIB objects by name
(rather than having to use the numeric OIDs)
- it allows the results to be displayed in a more immediately
meaningful fashion. Not just giving the object names, but
also showing named enumeration values, and interpreting table
indexes properly (particularly for string and OID index values).
There are two steps required to add a new MIB file to the tools.
Firstly, copy the MIB file into the appropriate location:
cp MY-MIB.txt /usr/local/share/snmp/mibs
(which makes it available to everyone on the system)
or
mkdir $HOME/.snmp
mkdir $HOME/.snmp/mibs
cp MY-MIB.txt $HOME/.snmp/mibs
(which makes it available to you only)
Note that the location of the shared MIB directory may be different
from that given here - see the FAQ entry "Where should I put my MIB
files?" for more information.
Secondly, tell the tools to load this MIB:
snmpwalk -m +MY-MIB .....
(load it for this command only)
or
export MIBS=+MY-MIB
(load it for this session only)
or
echo "mibs +MY-MIB" >> $HOME/.snmp/snmp.conf
(load it every time)
Note that the value for this variable is the name of the MIB
module, *not* the name of the MIB file. These are typically the
same (apart from the .txt suffix), but if in doubt, check the contents
of the file. The value to use is the token immediately before the
word DEFINITIONS at the start of the file.
Or use the special value "all" to have the tools load all available
MIBs (which may slow them down, particularly if you have a large
number of MIB files.
Note that you need *both* steps.
Adding a MIB in this way does *not* mean that the agent will
automatically return values from this MIB. The agent needs to be
explicitly extended to support the new MIB objects, which typically
involves writing new code.
See the AGENT section for details.
Most of the tools (apart from 'snmptable') will work quite happily
without any MIB files at all - although the results won't be displayed
in quite the same way. Similarly, the agent doesn't need MIB files
either (other than to handle MIB object names in the configuration file).
Why can't I see anything from the agent?
---------------------------------------
Fundamentally, there are two basic reasons why a request may go
unanswered. Either the management application does not like the
request (so never sends it), or the agent does not like the request
(so never responds). The simplest way to distinguish between the
two is to run the command with the command-line option '-d'.
If this doesn't display a hex dump of the raw outgoing packet, then
it's the client side which is dropping the request. Hopefully you
should also see an error message, to help identify what's wrong.
If this displays one or more outgoing dumps (but nothing coming back),
then the request is failing at the agent end. See the next entry for
more details.
There are three further possibilities to consider:
One is that the agent may return a response to the original query,
but the management application may not like this response, and refuse
to display it. This is relatively unusual, and typically indicates
a flaw with the remote agent. (I hope you're not contemplating the
suggestion that the Net-SNMP command-line tools might contain bugs!)
The typical symptoms of this would be that the '-d' option would
display a sequence of sending and received packet dumps, with the
same contents each time. Ask on the mailing list for advice.
Alternatively, the agent may simply not support the MIB objects being
requested. This is most commonly seen when using the "snmpwalk" tool
(particularly with SNMPv1).
The symptoms here would be that '-d' would show two pairs of raw
packet dumps - one a GETNEXT request (A1 in the sending packet),
followed by a GET request (A0). Repeating the same request with the
"snmpgetnext" command-line tool should show the information (if any)
that the agent returned, which was then discarded by snmpwalk as
irrelevant.
Note that this is how snmpwalk was designed to work. It is not an error.
Finally, it may be that the agent is simply taking too long to respond.
The easiest way to test for this is to add the command-line options
"-t 60 -r 0", which will send a single request (with no repetitions)
and wait for a minute before giving up. This ought to be long enough
for all but the most-overloaded agent, or inefficient MIB module!
If this turns out to be the cause, then ask on the mailing list for
advice on options for improving the performance.
Why doesn't the agent respond?
-----------------------------
Assuming that the tests outlined in the previous entry indicate that
the problem lies with the agent not responding, the obvious question
is "why not".
Again, there are two basic possibilities - either the agent never
sees the request, or it receives it but is unwilling (or unable) to
process it. If the remote system is running the Net-SNMP agent,
then the easiest way to distinguish between these two cases is to
shut down the agent, and re-start it manually using the options
-f -Le -d
Then send the same query as before. This should display raw dumps of
packets seen (or sent) by the agent, just as with the client side in
the previous entry.
If the agent does not display anything, then it is simply not receiving
the requests. This may be because they are being blocked by network
or local firewall settings ('iptables -L'), or the agent may not be
listening on the expected interfaces ('netstat -a').
This is most commonly encountered when running queries from a remote
host, particularly if the same request succeeds when run on the same
system as the agent itself.
If the agent displays a dump of the incoming request, but nothing going
out, then the most likely cause is access control settings. See the
relevant entries in the AGENT section for details. Note that if the agent
receives an SNMPv1 or SNMPv2c request with a unknown community string,
then it will not return an error response - the request is simply discarded.
Another possibility is that the request may be rejected by settings in
/etc/hosts.{allow,deny}. Again, '-d' will display an incoming packet
dump but no corresponding outgoing response. However in this situation,
the agent should also log a message that the request is being refused.
Running the agent with '-d' can also help identify situations where the
agent *is* responding to the request, but only after a long delay. This
would be indicated by a series of incoming packet dumps (showing various
retries from the client side), followed by several outgoing dumps - possibly
long after the client tool has given up in disgust.
See the entry
The agent worked for a while, then stopped responding. Why?
later in this section.
I can see the system group, but nothing else. Why?
--------------------------------------------------
This is almost definitely due to the access configuration of the agent.
Many pre-configured systems (such as most Linux distributions) will only
allow access to the system group by default, and need to be configured
to enable more general access.
The easiest way to test this is to try a GETNEXT request on one of
the other standard groups
e.g.
snmpgetnext ..... interfaces
If the agent responds with "hrSystemUptime.0" or "end of MIB", then it
is clearly configured in this way. See the entries on access control
in the AGENT section for more information.
Why can't I see values in the <ENTERPRISE> tree?
-----------------------------------------------
If you can see most of the standard information (not just the system and
hrSystem groups), but not in the vendor-specific 'enterprises' tree, then
once again there are several possible causes.
Firstly, it's possible that the agent does not implement this particular
enterprise tree. Remember that adding a MIB to the client tools does
*not* automatically add support for these object to the agent. See the
AGENT section for more information.
Alternatively, it may be that the agent does implement some or all of this
enterprise tree, but the access control settings are configured to block
access to it.
The simplest way to checks whether the agent implements a given portion
of the OID tree is to run
snmpwalk .... nsModuleName
and look for index values that fall in the area of interest.
(Always assuming that you have access to this particular section
of the Net-SNMP enterprise tree, of course!)
Checking the access control settings can be done by examining the tables
vacmAccessTable and vacmViewTreeFamilyTable. Note that these are used
to configure access control for *all* versions of SNMP - not just SNMPv3.
The third possibility is that simply isn't any information in the specified
tree. For example, several of the tables in the UCDavis enterprise tree
(such as prTable, extTable, dskTable and fileTable) require explicit
configuration in the snmpd.conf file. If you query this particular tables
without the necessary configuration entries, then they will be empty.
Finally, if you can't see anything from *any* enterprise-specific tree,
then this may be down to how you are asking for the information. By
default, if "snmpwalk" is run without an explicitly starting OID, then
it will display the contents of the 'mib-2' tree, containing most of the
IETF-standard management information supported by the agent.
When the agent reaches the end of this tree, it will return the first
enterprise-specific value, 'snmpwalk' will recognise that this marks the
end of the (implicit) requested tree, and stop. No enterprise-specific
information will be displayed.
To walk the whole tree, and see *all* the information that the
agent supports, specify a starting point of '.iso' or '.1'.
To walk a specific enterprise subtree, specify the root of this tree
as the starting point - e.g:
snmpwalk -v1 -c public localhost UCD-SNMP-MIB::ucdavis
There is more information about particular UCD-specific subtrees in
the AGENT section.
The agent worked for a while, then stopped responding. Why?
-----------------------------------------------------------
There are three basic possibilities:
- the agent has crashed
- it is hanging
- it is temporarily overloaded
Detecting whether the agent has crashed should be fairly straighforward.
If you can reliably reproduce this crash (e.g. by sending a particular
SNMP request), then contact the coders list for advice.
It's the other two cases that are probably more significant.
To tell the difference between these two, try leaving the agent
undisturbed for a while, and then probe it using a single 'snmpget'
request, specifying a longer timeout (e.g. '-t 120'). If it now
responds, then something was probably sending requests (including
duplicate retries) faster than the agent could process them, and it
was building up a backlog. Try adjusting the timeout period and retry
frequency of these client requests, or look at improving the efficiency
of the implementation of the relevant MIB objects.
If the agent remains unresponsive (particularly if the load on the
system is steadily climbing), then it's probably hanging, and all
you can really do is restart the agent. If you can identify what
causes this to happen, then contact the coders list for advice.
Requesting an object fails with "Unknown Object Identifier" Why?
----------------------------------------------------------------
If a general snmpwalk shows a particular entry, but asking for it more
specifically gives a "sub-identifier not found:" or "Unknown Object
Identifier" error, then that's a problem with the tool, rather than
the agent.
Firstly, make sure that you're asking for the object by the right name.
Object descriptors are case-sensitive, so asking for 'sysuptime' will
not be recognised, but 'sysUpTime' will.
Alternatively, the object may be defined in a MIB that hasn't been
loaded. Try loading in all the MIB files:
snmpget -m ALL -v1 -c public localhost sysUpTime.0
or specify the name of the appropriate MIB explicitly:
snmpget -v1 -c public myhost SNMPv2-MIB::sysUpTime.0
Note that this uses the name of the *module*, not the name of the file.
However, if 'snmpwalk' displays the object by name, this is unlikely to
be the cause, and you should look closely at the exact object name you
are using. In particular, see the next entry.
Why do I get "noSuchName" when asking for "sysUpTime" (or similar)?
------------------------------------------------------------------
Assuming that you do have access to this object, the most likely cause
is forgetting the instance subidentifier.
If you try walking the 'system' group (or any other part of the MIB tree),
you should notice that all of the results have a number after the object
name. This is the "instance subidentifier" of that particular MIB instance.
For values in tables (such as the sysORTable), this acts as an index into
the table - a very familiar concept. But *all* SNMP values will display an
instance number, whether or not they are part of a table. For non-table
objects ("scalars"), this instance subidentifier will always be '0',
and it *must* be included when making a GET request.
Compare the following:
$ snmpget -v1 -c public localhost sysUpTime
Error in packet
Reason: (noSuchName) There is no such variable name in this MIB.
This name doesn't exist: system.sysUpTime
$ snmpget -v1 -c public localhost sysUpTime.0
system.sysUpTime.0 = Timeticks: (69189271) 8 days, 0:11:32.71
This is a little less obscure when using SNMPv2c or v3 requests:
$ snmpget -v 2c -c public localhost sysUpTime
system.sysUpTime = No Such Instance currently exists
Why do I sometimes get "End of MIB" when walking a tree, and sometimes not?
--------------------------------------------------------------------------
This depends on which MIB modules are supported by the agent you are
querying and exactly what you're asking for.
Note that a tree is walked by repeatedly asking for "the next entry" until
all the values under that tree have been retrieved. However, the agent has
no idea that this is what's happening - all it sees is a request for "the
next entry after X".
If the object X happens to be the last entry in a sub-tree, the agent will
provide the next object supported (as requested) even though this will be
in a different subtree. It's up to the querying tool to recognise that
this last result lies outside the area of interest, and simply discard it.
If the object X happens to be the last entry supported by the agent, it
doesn't have another object to provide, so returns an "end of MIB"
indication. The Net-SNMP tools report this with the message above.
But in either case, the actual information provided will be the same.
How do I use SNMPv3?
-------------------
The simplest form of SNMPv3 request is unauthenticated and unencrypted
(noAuthNoPriv). It simply requires a user name, and would look something
like:
snmpget -v 3 -l noAuthNoPriv -u dave localhost sysUpTime.0
However this approach foregoes the security protection which is the
main advantage of using SNMPv3 (and the agent must also be explicitly
configured to allow unauthenticated requests from that user).
The most common form of SNMPv3 request is authenticated but not encrypted
(authNoPriv). This specifies the pass phrase to authenticate with:
snmpget -v 3 -l authNoPriv -u dave -A "Open the Door"
localhost sysUpTime.0
A fully secure (i.e. encrypted) request (authPriv) would also specify
the privacy pass phrase:
snmpget -v 3 -l authPriv -u dave -A "Open the Door"
-X "Bet you can't see me" localhost sysUpTime.0
In practise, most of these would probably be set via configuration
directives in a personal $HOME/.snmp/snmp.conf file (note, *not* the
agent's snmpd.conf file).
The equivalent settings for the third example would be:
defSecurityName dave
defSecurityLevel authPriv
defAuthPassphrase "Open the Door"
defPrivPassphrase "Bet you can't see me"
If the AuthPassphrase and the PrivPassphrase are the same, then you
can use the single setting
defPassphrase "Open the Door and see me"
instead.
See the AGENT section for how to configure the agent for SNMPv3 access.
Why can't I set any variables in the MIB?
----------------------------------------
There are three possible reasons for this:
Many MIB objects are defined as "read-only" and inherently cannot be
changed via SET requests. Attempts to do so will typically be rejected
by the 'snmpset' command without ever being sent to the agent.
Of those objects that can in principle be changed, the agent may not
include the code necessary to support SET requests. (GET and GETNEXT
are much easier to handle - particularly for objects relating to the
internals of the underlying operating system).
Even if SET support has been implemented, the agent may not be configured
to allow write access to this object.
Ready-installed distributions (such as those shipped with Linux) tend
to be configured with read-only access to part of the mib tree (typically
just the system group) and no write access at all.
To change this, you will need to set up the agent's access control
configuration. See the AGENT section for more details.
Note that neither the community string "public" nor "private" can be
used to set variables in a typical default configuration.
Variables seem to disappear when I try to set them. Why?
--------------------------------------------------------
This is actually the same as the previous question - it just isn't
particularly obvious, particularly when using SNMPv1. A typical
example of this effect would be
$ snmpget -v1 -c public localhost sysLocation.0
sysLocation.0 = somewhere nearby
$ snmpset -v1 -c public localhost sysLocation.0 s "right here"
Error in packet.
Reason: (noSuchName) There is no such variable name in this MIB.
This name doesn't exist: sysLocation.0
Trying the same request using SNMPv2 or above is somewhat more informative:
$ snmpset -v 2c -c public localhost sysLocation.0 s "right here"
Error in packet.
Reason: notWritable
The SNMPv1 error 'noSuchName' actually means:
"You can't do that to this variable"
rather than "this variable doesn't exist".
It may be the case that it doesn't exist at all. It may exist but you
don't have access to it (although different administrative credentials
might be accepted). Or it may exist, but you simply can't perform that
particular operation (e.g. changing it).
Similarly, the SNMPv2 error 'notWritable' means "not writable in this
particular case" rather than "not writable under any circumstances".
If you are sure that the object is both defined as writable, and has been
implemented as such, then you probably need to look at the agent access
control. See the AGENT section for more details.
But see the next entry first.
Why can't I change sysLocation (or sysContact)?
----------------------------------------------
There is one final possibility to consider for why a SET request might
be rejected.
The values for certain MIB objects (including 'sysLocation' and 'sysContact')
can be configured via the snmpd.conf file. If this is done, then these
particular objects become read-only, and cannot be updated via SET commands,
even if the access control settings would otherwise allow it.
This may seem perverse, but there is good reason for it. If there is a
configuration setting for one of these objects, then that value will be
used whenever the agent re-starts. If the object was allowed to be updated
using SET, this new value would be forgotten the next time the agent was
re-started.
Hence the Net-SNMP agent rejects such requests if there's a value configured
via the 'snmpd.conf' file. If there isn't such a config setting, then the
write request will succeed (assuming suitable access control settings), and
the new value will be retained the next time the agent restarts.
I get an error when trying to set a negative value - why?
--------------------------------------------------------
This is a different problem. What's happening here is that the
routine that parses the arguments to the 'snmpset' command is seeing
the '-' of the new value, and treating it as a command-line option.
This normally generates an error (since digits typically aren't valid
command line options).
The easiest way to solve this is include the "end-of-option"
indicator '--' in the command line, somewhere before the new value
(but after all of the options, obviously). For example:
snmpset -v 2c -c public localhost -- versionRestartAgent.0 i -1
(This command will still fail, since -1 isn't an acceptable value for
this particular object, but that's not the point here!)
I get an error when trying to query a string-indexed table value - why?
----------------------------------------------------------------------
The Net-SNMP library will normally try to interpret string-based
index values, and display them in a meaningful manner:
$ snmpgetnext .... vacmGroupName
vacmGroupName.3."dave" = theWorkers
The command-line tools will also accept string-valued indexes within
an OID, and convert them into the appropriate numeric form before
sending an SNMP request. However the Unix shell will typically
swallow the quotes around the string index value, before the SNMP
tools can get a chance to interpret them.
The answer is to escape the quotes, to protect them from the shell,
and allow them to be passed through to the OID parser:
snmpget .... vacmGroupName.3.\"dave\"
or
snmpget .... 'vacmGroupName.3."dave"'
Another alternative is to avoid trying to specify the index value as
a string, and provide the numeric subidentifiers directly:
snmpget .... vacmGroupName.3.4.100.97.118.101
(where '3' indicates SNMPv3, '4' is the length of the string index,
followed by the ASCII values of the individual characters).
The command-line option '-Ob' will display the results of querying
a string-indexed table in this format:
$ snmpgetnext -Ob .... vacmGroupName
vacmGroupName.3.4.100.97.118.101 = theWorkers
How should I specify string-indexed table values?
------------------------------------------------
There's one other aspect of string-indexed tables that can cause
problems - the difference between implicit- and explicit-length
strings, and how to represent these when making an SNMP query.
The most common style of string index uses an explicit length,
followed by the individual ASCII character values:
"dave" = 4.'d'.'a'.'v'.'e'
(as shown in the previous entry).
However if the string index is defined in the MIB file as IMPLIED
(or if it has a fixed length, such as a physical ethernet address),
then the length subidentifier is omitted, and the index simply
consists of the character values:
"dave" = 'd'.'a'.'v'.'e'
Note that IMPLIED index objects can only appear as the *last* index
for a table.
The Net-SNMP library uses double quotes (i.e. "dave) to indicate an
explicit length string index value, and single quotes (i.e. 'dave')
to indicate an implicit length one. If you use the wrong style of
quotes, then the resulting OID will be incorrect, and you'll get
confusing results to your query.
How do I send traps and notifications?
---------------------------------------
Traps and notifications can be sent using the command 'snmptrap'.
The following examples generate the generic trap 'warmStart(1)' and a
(dummy) enterprise specific trap '99' respectively:
snmptrap -v 1 -c public localhost "" "" 1 0 ""
snmptrap -v 1 -c public localhost "" "" 6 99 ""
The empty parameters "" will use suitable defaults for the relevant
values (enterprise OID, address of sender and current sysUptime).
An SNMPv2 or SNMPv3 notification (either trap or inform) takes
the OID of the trap to send:
snmptrap -v 2c -c public localhost "" UCD-SNMP-MIB::ucdStart
snmptrap -v 2c -c public localhost "" .1.3.6.1.4.1.2021.251.1
(These two are equivalent ways of specifying the same trap). Again,
the empty parameter "" will use a suitable default for the relevant
value (sysUptime).
Any of these commands can be followed by one or more varbinds,
using the same (OID/type/value) syntax as for 'snmpset':
snmptrap -v 2c -c public localhost "" ucdStart sysContact.0 s "Dave"
Generating traps from within the agent, or other applications, is
covered in the AGENT and CODING sections.
You should also read the snmptrap tutorial at
http://www.net-snmp.org/wiki/index.php/TUT:snmptrap
which will help you understand everything you need to know about traps.
How do I receive traps and notifications?
----------------------------------------
Handling incoming traps is the job of a "notification receiver".
The Net-SNMP suite include the tool 'snmptrapd' to act in this role.
This can log traps to a file or via the syslog mechanism, forward them
to another notification receiver and/or invoke a specified command
whenever a particular notification is received.
Logging notifications would be done by starting snmptrapd as:
snmptrapd -Ls 7 (log to syslog using 'LOCAL7')
or
snmptrapd -f -Lo (log to standard output)
Invoking a command to process a received notification uses one or
more 'traphandle' directives in the configuration file 'snmptrapd.conf'.
A typical configuration might look something like:
traphandle .1.3.6.1.6.3.1.5.1 /path/to/page_me up
traphandle .1.3.6.1.4.1.2021.251.1 /path/to/page_me up
traphandle .1.3.6.1.4.1.2021.251.2 /path/to/page_me down
traphandle default /path/to/log_it
where 'page_me' and 'log_it' are the commands to be run.
Forwarding notifications to another receiver would be done using
similar 'snmptrapd.conf' directives:
forward .1.3.6.1.4.1.8072.4.0.3 10.0.0.1
forward default 10.0.0.2
There's a tutorial with more details on the web site at
http://www.net-snmp.org/wiki/index.php/TUT:snmptrap
How do I receive SNMPv1 traps?
-----------------------------
Directives in the 'snmptrapd.conf' file use the (SNMPv2) snmpTrapOID
value to identify individual notifications. This applies to *all*
versions of SNMP - including SNMPv1 traps. See the co-existence spec
(RFC 2576) for details of mapping SNMPv1 traps to SNMPv2 OIDs.
Note that the first traphandle directive in the previous entry uses
the OID corresponding to the SNMPv1 'coldStart' trap.
Why don't I receive incoming traps?
----------------------------------
Starting with net-snmp 5.3, snmptrapd will no longer automatically
accept all incoming traps. It must be configured with authorized
SNMPv1/v2c community strings and/or SNMPv3 users. Non-authorized
traps/informs will be dropped.
Please refer to the snmptrapd.conf(5) manual page for details.
My traphandler script doesn't work when run like this - why not?
---------------------------------------------------------------
If a traphandler script works fine when run manually from the
command line, but fails or generates an error when triggered by
an incoming notification, then there are two likely causes.
Firstly, the interactive shell environment may not be precisely
the same as that for programs executed by the snmptrapd daemon.
In particular, it's quite possible that the PATH environmental
variable may not include all the additional directories that are
commonly set up for a personal login configuration. To avoid this
problem (particularly for traphandler shell scripts), it's worth
giving the full path to all programs used within the script.
Secondly, the snmptrapd daemon may not always recognise the
appropriate interpreter to use for a particular trap handler.
If this is the case, then you can specify this interpreter
explicitly as part of the trap handle directive:
traphandle default /usr/bin/perl /usr/local/bin/log_it
In this case, it's almost certain that you'll also
need to give the full path to the traphandle script (as shown)
How can the agent receive traps and notifications?
-------------------------------------------------
It can't.
The primary purpose of an SNMP agent is to handle requests for
information from management applications. In SNMP terminology,
it acts as a "command responder".
It may also issue traps to report significant events or conditions
("notification generator"). But responding to such notifications
is a significantly different role, and this is handled by a separate
application ('snmptrapd'). Note that it is perfectly possible (even
normal) for both agent and trap receiver to run on the same host.
How big can an SNMP request (or reply) be?
-----------------------------------------
The protocol definition specifies a "minimum maximum" packet size
(484 bytes for UDP), which all systems must support, but does not
attempt to define an upper bound for this maximum size. This is left
to each individual implementation.
The UCD software used a fixed size buffer of 1472 bytes to hold the
encoded packet, so all requests and responses had to fit within this.
The Net-SNMP releases handle packet buffers rather differently, and
are not subject to the same fixed restrictions.
How can I monitor my systems (disk, memory, etc)?
------------------------------------------------
In general, the Net-SNMP suite consists of relatively low-level
tools, and there is nothing included that is designed for high-level,
long-term monitoring of trends in network traffic, disk or memory
usage, etc.
There are a number of packages available that are designed for this
purpose. Two of the most widely used are MRTG (http://www.mrtg.org/)
and RRDtool (http://oss.oetiker.ch/rrdtool/). There are also several
frontends built on top of RRDtool, including Cacti (http://www.cacti.net/)
and Cricket (http://cricket.sourceforge.net/). There are details of
how to set up Cricket to monitor some of the UCD extensions at
http://www.afn.org/~jam/software/cricket/
We have also set up a page that describes in detail how MRTG
can be set up to monitor disk, memory and cpu activity at
http://www.net-snmp.org/tutorial-5/mrtg/index.html
There is also a web-based network configuration system "Net-Policy",
based upon SNMP. This is not strictly connected to the Net-SNMP project,
but a number of the core developers are also involved with that system.
See http://net-policy.sourceforge.net for more details.
Applications complain about entries in your example 'snmp.conf' file. Why?
--------------------------------------------------------------------------
There *is* no example 'snmp.conf' shipped with the standard distribution.
The configuration file 'EXAMPLE.conf' is designed as a config for
the agent, and should be installed as 'snmpd.conf' (note the 'd').
The file 'snmp.conf' is intended for general configuration options,
applicable to all applications (via the SNMP library).
Rename (or merge) the 'snmp.conf' file to 'snmpd.conf', and this
should fix the problem.
See the AGENT section or the 'snmpd.conf(5)' man page for more information
about what should go in this file.
OK, what should I put in snmp.conf?
----------------------------------
This is used to set common configuration values for most of the
applications, to avoid having to specify them every time. Examples
are the SNMPv3 settings mentioned above, defaults for which MIBs to
load and where from (see the second entry in this section),
and the default SNMP version, port and (if appropriate) community
string to use.
Some of these (such as MIB information), might be best put in a
shared snmp.conf file (typically /usr/local/share/snmp/snmp.conf or
/etc/snmp/snmp.conf) to apply to all users of the system. Others
(particularly the SNMPv3 security settings), are more likely to refer
to a particular user, and should probably go in a personal snmp.conf
file (typically $HOME/.snmp/snmp.conf).
See 'snmpget -H' and/or the snmp.conf(5) man page for more details.
You can also use the "snmpconf" command to help you generate your
snmp.conf configuration file (just run it and answer its questions).
How do I specify IPv6 addresses in tools command line arguments?
---------------------------------------------------------------
IPv6 addresses pose a particular problem for the Net-SNMP command
line tools, which parse host names into pieces. In particular, normally
if you specify a simple host name, it assumes you want UDP in IPv4 on
port 161. By default, these two commands are actually the same:
snmpget 127.0.0.1 sysUpTime.0
snmpget udp:127.0.0.1:161 sysUpTime.0
However, for IPv6 this causes a problem because IPv6 addresses also use
a colon to separate addressing parts. Thus you need to enclose the address
in square brackets ( [ and ] ).
Because most shells use these brackets too, you also likely need to quote it:
snmpget 'udp6:[::1]:161' sysUpTime.0
PERL
====
What is the purpose of the Perl SNMP module?
-------------------------------------------
Short, comprehensive (but ultimately unhelpful) anwer - to provide a
perl interface for SNMP operations.
Longer, incomplete (but more useful) answer - there are probably two
main uses for the Perl SNMP module. The first is for developing client
management applications, using perl to send SNMP requests, and manipulating
or displaying the results. As such, this is a straight alternative to
various other SNMP toolkits currently available (for both perl and other
programming languages).
The second is as a means for extending the functionality of the Net-SNMP
agent, by implementing new MIB modules. This is an alternative to the
other script-based extension mechanisms, but is more tightly bound to the
Net-SNMP agent (and hence more efficient), while still avoiding the need
to write C code.
It is also possible to use the perl SNMP module in the snmpd.conf file,
or to process incoming notifications, but the above are probably the
two primary uses.
Where can I get the Perl SNMP package?
-------------------------------------
Joe Marzot's excellent Perl 'SNMP' module, is included in the Net-SNMP
source releases. It can be found located in the perl/SNMP subdirectory
of the source tree. This is accompanied by a number of Perl modules
grouped together under the NetSNMP namespace.
The basic SNMP module (though not the NetSNMP additions), can also
be found at any Comprehensive Perl Archive Network (CPAN) mirror site,
under modules/by-module/SNMP. To find the CPAN site nearest you,
please see http://www.cpan.org/SITES.html.
These Perl modules need to be used in conjunction with a compatible
version of the Net-SNMP library. Consult the README file in the SNMP
Perl distribution to find out which version of the library it needs.
How do I install the Perl SNMP modules?
--------------------------------------
Assuming you have a reasonably new (and properly configured) Perl system,
this should be simply:
cd perl
perl Makefile.PL
(press RETURN when prompted for host and community)
make
make test
make install (probably as root)
It might be possible to install the basic module using
perl -MCPAN -e shell ; "install SNMP"
but this has not been reliably tested, and very much relies on
having the correct version of the Net-SNMP library.
There may also be appropriate pre-compiled versions of the Perl modules
available from the Net-SNMP project website, or your O/S vendor.
But compiling this fails! Why?
-----------------------------
The Perl module tends to delve quite deeply into the internals of the
main Net-SNMP library, and so is quite sensitive to changes within the
library. It's important to use the correct version of the module, that
corresponds to the version of the library you have installed. If you're
working with a Net-SNMP source distribution, the appropriate versions of
the Perl modules are shipped as part of the source code, but you *must*
have run "make install" on the main Net-SNMP distribution *first*.
If you're working with a ready-installed version of the library, make
sure you obtain a compatible version of the Perl module.
Note that the Perl modules will be compiled using the compiler
(and compiler settings) used for compiling the original perl binary,
*not* those used for compiling the Net-SNMP (or UCD) library.
If these are different (e.g. 'gcc' used for one and 'cc' for the other)
then this may well cause problems. It's much safer to use a consistent
environment for both. This issue is discussed in greater detail in
the README.solaris file.
Also note that the v5 Net-SNMP suite *must* be configured to provide
shared libraries in order for the Perl modules to work correctly. This
is not necessary with the v4 UCD-SNMP libraries.
Compiling the Perl module works OK, but 'make test' fails. Why?
--------------------------------------------------------------
That's difficult to answer in general.
Some of the Perl tests are rather picky, so this may simply be
some minor inconsistency between your precise setup, and the
expectations of the test environment.
Check that you are working with the Perl distribution that matches
the SNMP libraries (use the 'perl/SNMP' in preference to CPAN), and
that you have installed the main libraries successfully (uninstall
any old versions if you're having trouble).
If all this looks OK, and if most of the tests pass, then it's
probably safe to run 'make install' anyway. Probably.
Why can't mib2c (or tkmib) locate SNMP.pm?
-----------------------------------------
That's probably because the SNMP Perl module hasn't been installed.
It's not part of the standard Perl distribution, nor is it included
in the default Fedora Linux installation (for example).
You'll need to install it yourself.
See the second entry in this section.
Why can't mib2c (or tkmib) load SNMP.so?
---------------------------------------
This is probably the same problem. Either the SNMP module
hasn't been installed, or it's the wrong version. See the
previous questions.
Why can't tkmib locate Tk.pm?
----------------------------
Tk.pm is another Perl package that needs to be installed before tkmib
will run. It's also available on Perl CPAN. We suggest using version
"Tk800.011" or later. It can be installed by issuing the command:
perl -MCPAN -e shell ; "install Tk"
Why does your RPM complain about missing Perl modules?
-----------------------------------------------------
This has been particularly noted on RedHat 9, complaining about the
module "perl(Term::ReadKey)" - even if this is actually present (e.g.
having been installed directly from CPAN). In fact, this is not
specific to Perl modules - the same issue can potentially arise with
other RPM dependencies.
The problem is that the RPM mechanism keeps a local database of what
software packages have been installed, and checks this for any other
features that this RPM requires. If software is installed "manually"
rather than via rpm packages, then it will not appear in this database.
Attempting to install another RPM that rely on this functionality will
then complain about the "missing" package, because the RPM system doesn't
know that's it's actually available.
The ideal solution is to *always* install software using a consistent
mechanism (which may involve building RPMs locally, or looking for a
suitable pre-built version).
Failing this, it's possible to tell the "rpm" command to ignore such
dependencies, and install the package anyway. Try:
rpm -i --nodeps {package}
In this situation, it's then up to you to make sure that any other
necessary packages *are* actually present on the system.
I've got a problem with the Net-SNMP module. Can you help?
----------------------------------------------------------
Sorry, despite the similar-sounding name, the Net-SNMP (or Net::SNMP)
module is nothing to do with this package, or the NetSNMP modules.
Net::SNMP is a "pure-perl" implementation of SNMP support, developed
by David Town. The developers of the (C-based) Net-SNMP suite do
not have any significant experience in using this particular module,
and you'll probably be better off asking for help via CPAN or some
other perl-related forum.
MIBS
====
Where can I find a MIB compiler?
-------------------------------
That depends what you mean by a "MIB compiler". There are at least two
types of tool that are commonly referred to by this name.
The first is a tool to check MIB files for validity. With the Net-SNMP
software, this functionality is mostly integrated within the MIB parser,
and hence included in all the applications. The tool 'snmptranslate' is
probably the most appropriate for this purpose.
Note that the parser is fairly forgiving (see 'What ASN.1 parser is used'
below), so this should not be regarded as a stamp of approval. For a
more rigourous validation, use a tool such as 'smilint', or the on-line
interface at http://wwwsnmp.cs.utwente.nl/ietf/mibs/validate/
The second type of "MIB compiler" is one to turn a MIB specification
into C code, specifically one designed to aid agent implementation. The
command 'mib2c' is an example of such a tool for the Net-SNMP agent.
See the CODING section for more information.
Why aren't my MIB files being read in?
-------------------------------------
There are two basic likely causes - either the library isn't attemping to
load these particular MIB files, or it's trying to load them but can't
locate them.
By default, the Net-SNMP library loads a specific subset of MIB files.
This list is set when the suite is first configured and compiled, and
basically corresponds to the list of modules that the agent supports.
(This is a simplification, but is a reasonable first approximation).
In order to load additional MIB files, it is necessary to add them to this
default list. See the FAQ entry "How do I add a MIB to the tools?" for
more information about how to do this.
Alternatively, the tools may be looking in the wrong place. The directory
where the library looks for MIB files is also set when the software is
first configured and compiled. If you put new MIB files in the wrong
location, then the library won't be able to find them (and will complain).
This problem may arise when switching from a vendor-supplied distribution
to one compiled from source (or vice versa).
See the next entry for more information.
Where should I put my MIB files?
-------------------------------
If you've compiled the package from source (or are using binaries
from the project website), then you should probably put new MIB
files in the directory /usr/local/share/snmp/mibs
If you are using vendor-supplied binaries, then the MIB files
may well be located somewhere else (e.g. /usr/share/snmp/mibs,
/opt/snmp/mibs, or /etc/sma/snmp/mibs). Have a look for where
existing MIB files are installed, and try adding your MIBs to
the same directory.
If you compiled the source yourself, but specified a different
--prefix value when running configure, then the location of the
MIB directory will be {prefix}/share/snmp/mibs.
If you're still not sure where to put your MIB files, try running
the command
snmpget -Dparse-mibs 2>&1 | grep directory
This will display the location(s) where the library is looking
for MIB files.
What does "Cannot find module (XXX-MIB)" mean?
---------------------------------------------
If this error is only generated for one or two modules, then it's
likely that the named modules are not being found - perhaps they're
not installed in the correct location, are not readable, or the
name being used is incorrect. See the previous entries and the entry
"How do I add a MIB to the tools?" for more details.
Note that the name reported is the name of the MIB *module*, which is
not necessarily the same as the name of the file.
If there are a large number of such errors, then it's more likely
that either the MIB files haven't been installed at all. If you are
compiling from source, then it is necessary to run "make install" in
order to set up the full run-time environment.
Otherwise, see the previous entry to check whether the MIBs are installed
in the correct location for the tools to find them.
I'm getting answers, but they're all numbers. Why?
-------------------------------------------------
This is related to the previous questions. Remember, the results that
you receive from an agent do not depend on which MIBs are loaded by the
client tools - purely on how the agent was compiled and configured.
Because the tools don't necessarily read in every MIB file they can find
(and the relevant MIB file may not be available anyway), it is quite
possible for results from an agent to refer to modules that have not
been loaded (particularly with GETNEXT requests, or when walking a tree).
The results will be reported correctly, but won't be translated to use
named identifiers (or display the values in the most appropriate manner).
To fix this, add the missing MIB files to the list of MIBs to be loaded.
See the previous entries and the entry "How do I add a MIB to the tools?"
for more information.
What does "unlinked OID" mean?
-----------------------------
This means that the library has been able to find the MIB module,
and parse the individual objects defined in it, but is having problems
linking them together into a consistent tree. In particular, it
can't find an object corresponding to the name within the braces
(i.e. the 'xxx' in '{xxx 99}').
This is probably due either to a typo in this name (remember that
names are case sensitive, so a reference to 'xxx' will *not* match
a definition of 'Xxx'), or else the name is defined in another MIB
file, and this dependency is missing from the IMPORT clause of this
MIB file.
The parser doesn't handle comments properly. Why not?
----------------------------------------------------
The way that comments are handled in a MIB file is subtly different
to the equivalent syntax in most typical programming languages, and
this difference can catch out the unwary. In particular, there are
two common situations which can lead to problems.
The first scenario is where the MIB designer has attempted to "comment
out" an unwanted line that already contains a comment:
-- broken ::= { myMIB 1 } -- This isn't working yet
The assumption here is that a comment continues to the end of the line.
Unfortunately, this is not correct. A comment will continue either to
the end of the line, *or* the next occurance of a pair of dashes.
Thus in this case, the definition of "broken" is commented out (as
intended) but the following text ("This isn't working yet") is treated
as an active part of the MIB, and will generate an error.
The second scenario is where a line of dashes has been used to mark
out separate parts of a MIB file. Depending on the exact number of
dashes used, this may still result in a syntactically valid MIB file,
but has a 1-in-4 possibility of triggering an error. This means that
this particular situation can be particularly difficult to spot!
Most of the Net-SNMP applications have a command-line option (-Pc) which
will work around this problem by treating the whole line as a comment.
But this is not strictly legal, and the offending MIB file should really
be corrected.
How can I get more information about problems with MIB files?
------------------------------------------------------------
The command 'snmptranslate' is used to translate between numeric
and symbolic forms of OIDs. It uses the same MIB parsing routines
as the commands that actually communicate with a network management
agent, but can be used standalone. As such, it is a useful tool
for identifying problems with reading in MIB files.
In particular, the following options may be useful in
identifying problems:
-Pw warns about conflicting symbols
-PW prints more verbose warnings about other problems as well
(in both cases, ignore the 'xmalloc' reports)
-T provides sub-options for various views of these entries
There are other '-P' options to control various aspects of MIB parsing.
See the 'snmptranslate(1)' and 'snmpcmd(1)' man pages for more details,
or the tutorial at
http://www.net-snmp.org/tutorial-5/commands/snmptranslate.html
For a more rigourous validation, use a tool such as 'smilint', or the
on-line interface at http://wwwsnmp.cs.utwente.nl/ietf/mibs/validate/
What's this about "too many imported symbols"?
---------------------------------------------
Any MIB file starts with an (optional) list of identifiers that
it "imports" from other files. The parser handles this using
a fixed size buffer to hold the import information.
There are two circumstances in which this can result in the
error message shown above.
Firstly, if the MIB file refers to an unusually large number
of external identifiers. Handling this case requires a (trivial)
patch to the parsing code. Contact the coders list for advice.
(This is extremely rare - the only example that
we've come across is the Cabletron Trap MIB).
Much more common is a syntax error in the IMPORTS clause of the
MIB file in question. In particular, check that this section ends
in a semicolon, before going on to the main MIB object definitions.
Do I actually need the MIB files?
--------------------------------
Probably not.
The MIB files play two main roles - they are used to translate
between numeric OIDs and the corresponding textual names, and
they define the structure and syntax of the relevant MIB objects.
This second role is perhaps best thought of in terms of a design
document. It's vital while developing an application (typically
the MIB module or handler within the agent), since it defines
what the application (MIB) must actually do. But once the code
has been written, the design document becomes redundent.
The agent then has the same information hardcoded into it
(literally!), and no longer needs the MIB file.
The translation task is not strictly necessary - SNMP will
operate fine without any MIB files at all, as long as you're
happy to work with numeric OIDs throughout, and know which MIB
objects you're interested in. But it's much easier to work with
the (hopefully) meaningful names, enumeration tags and the like,
and to view the description of a particular object.
This requires having the relevant MIB files installed and loaded.
Since the agent needs MIBs the least and some systems are memory
restricted, it is possible to completely disable loading these MIBs
as well as remove the code that does the parsing by using the
--disable-mib-loading flag to configure.
However, note that certain snmpd.conf tokens actually make use
of mib information so they won't be as easily usable.
AGENT
=====
What MIBs are supported?
-----------------------
The following MIBs are supported (at least in part and on some systems):
- MIB-2 General network statistics
(RFC 1213 and subsequent revisions)
- Host Resources (RFC 1514 and 2790)
- SNMPv3 framework (RFCs 2571-5, 3411-3418)
(including USM, VACM, Target
and Notification MIBs)
- DisMan Event and Schedule MIBs
- MTA-MIB (sendmail)
- private UCD/Net-SNMP agent extensions
(monitor specified processes and disks,
memory, CPU, load average, + extending
the agent using shell commands)
See README.agent-mibs for details.
Not all MIB modules are included by default on all systems. Some of
these may need to be explicitly requested when the software is first
configured and built, while others may not be available on all
architectures.
There are a few other MIB implementations distributed as part of the
source tarball, but these are basically unsupported and most of the
core developers have little or no experience with using them.
What protocols are supported?
----------------------------
The agent supports all three current versions of SNMP (v1, v2c and v3),
over both UDP and TCP transports, as well as acting as a SMUX (RFC 1227)
master agent, AgentX (RFC 2741) in both master and subagent roles, and
SNMP proxying.
How do I configure the agent?
----------------------------
That's a somewhat ambiguous question, as there are two very different
stages where it is possible to "configure" the agent.
Firstly, you can determine what capabilities and defaults are included
within the library and agent, at the time that the software is first
built. This uses suitable flags to the 'configure' script, before
compiling the source.
As far as the agent is concerned, the most significant option is
'--with-mib-modules' (or '--with-out-mib-modules') to control which
MIBs will be supported by the agent. See the next few entries for
details.
You can also control various aspects of the agent behaviour (and the
information it returns) at run time, via the 'snmpd.conf' configuration
file. Various aspects of this are touched on throughout this FAQ. Or
see the snmpd.conf(5) manual page for full details.
The "snmpconf" script can help in creating this config file.
Start off with 'snmpconf -g basic_setup' to get you going.
How do I remove a MIB from the agent?
------------------------------------
Deleting the text file for a MIB does not affect the agent (other than
to prevent it from recognising MIB object names in the config files).
It's necessary to tell the agent not to activate the relevant code that
actually implements these objects. There are three ways to do this:
1) re-run 'configure' to exclude the given MIB module(s) from the
build configuration, then recompile and reinstall:
./configure --with-out-mib-modules=path/to/unwanted ....
make
make install
This specifies the path to the module code file, relative to
the 'agent/mibgroup' directory. Clearly, this approach is
only possible if you are working with a source distribution.
2) disable the MIB at runtime
snmpd -I -unwanted
Note that this relies on knowing which modules are used to
implement the relevant MIB objects. If you're not sure,
you could try walking the 'nsModuleName' MIB object, which
indicates the module responsible for each particular range
of OIDs.
You can also check which MIB modules are loaded by getting
the agent to report them as they are initialised:
snmpd -Dmib_init -H
From this information, it should then be fairly obvious which
modules to disable.
3) use access control to exclude the mib from the view used to
query the agent:
view almostEverything included .1
view almostEverything excluded unwantedMib
rocommunity public default -V almostEverything
This approach can also be used with the full com2sec/group/access
configuration directives (e.g. with versions earlier than 5.3,
which don't support the above mechanism).
I've installed a new MIB file. Why can't I query it?
----------------------------------------------------
Installing a new MIB file will not magically enable the agent to know
what values to report for the objects defined in that MIB. It's
necessary to have some code which can provide the relevant information.
The next few entries, and the CODING section address this issue in more
detail.
How do I add a MIB to the agent?
-------------------------------
Adding a MIB essentially involves writing some code to implement the
objects defined in the new MIB. There are three basic approaches that
can be used to do this:
- The agent can invoke an external command or shell script to
return the necessary information. There are several possible
variations on this approach - see the next entry for details.
- The agent can pass the request off to another (sub-)agent,
which already implements the required MIB. Again, there are
several ways of doing this - including AgentX, SMUX and
proxied SNMP. See the next entry but one for details.
- You can write code to implement the new MIB objects, and
include this within the agent. This is most commonly C
(or C++) code, although the agent can also support MIB modules
implemented in perl.
See the next section (CODING) for more details.
Note that there is no visible difference between external commands,
subagents, and modules implemented within the main agent itself.
Tools querying the agent will see a single MIB structure.
What's the difference between 'exec', 'sh', 'extend' and 'pass'?
---------------------------------------------------------------
'exec' will run the specified command and return the exit status and
output. Any arguments are passed directly to the command, with no
special interpretation.
'sh' is similar, but invokes a shell to run the command line given.
This means that quoted arguments will be recognised as such, and also
allows redirection, and other similar shell interpretation. The results
are returned in exactly the same way.
'extend' is also similar, but provides a richer and more flexible MIB
framework - both for configuring the exact command to be run, and for
displaying the results.
None of these mechanisms require the command to have any knowledge of
SNMP, or the fact that they are being used in this manner. But the
output is returned in a fixed format, and it is up to the receiving
application to interpret this appropriately.
Note that the "relocatable" form of the 'exec' directive ('exec OID ....')
produces MIB output that is not strictly valid. For this reason, support
for this has been deprecated in favour of 'extend OID ...', which produces
well-formed MIB results (as well as providing fuller functionality).
The most recent releases of the agent don't include support for "relocatable
exec" by default. This needs to be explicitly included when the agent is
first compiled, by including the module 'ucd-snmp/extensible' instead of
'agent/extend'.
'pass' is a more general mechanism for implementing arbitrary MIB
objects. The specified command will be invoked for any request within
the named MIB subtree, and passed details of the requested OID. It
should return the information relevant to the requested OID.
'pass-persist' is similar, but the command will continue running
even after the initial request has been answered. These two mechanisms
can be used to implement a particular MIB, following the correct MIB
structure (as opposed to the fixed format of exec/sh/extend).
All of these mechanisms are described in the 'snmpd.conf(5)' man page,
in the section entitled "Extending Agent Functionality".
What's the difference between AgentX, SMUX and proxied SNMP?
-----------------------------------------------------------
All three are protocols that can be used to make two or more agents
appear as one to the querying application. In each case, one agent
takes the role of "master", and delegates requests to one of the others
as and where this is appropriate. The differences between them mainly
relate to how data is represented, and the mechanisms for communication
between master and subagents.
SMUX and proxy SNMP both essentially use the standard SNMP packet format.
The main difference is that a proxy SNMP subagent need not be aware that
it is acting in such a role. It typically listens on a non-standard port,
and simply receives requests as usual, forwarded from the master agent
(rather than directly). The main issue to be aware of is that such requests
will appear to come from the local host, and this may affect how the access
control mechanisms need to be set up.
SMUX uses a similar packet format, but the subagent "registers" with
the master agent, providing a suitable password. The Net-SNMP (and UCD)
agent includes the possibility of acting as a SMUX master agent, but the
suite does not include a subagent API. Note that support for SMUX is not
included by default, and needs to be explicitly enabled by running:
--with-mib-modules=smux
before re-compiling the agent.
See the file 'agent/mibgroup/README.smux' for details.
AgentX uses a more compact (and simpler) packet format, with a richer
range of administrative commands, and provides a more flexible and reliable
extension mechanism. The Net-SNMP agent can be used in both master and
subagent roles, and the agent library can also be used to embed an AgentX
subagent within another application.
See the file 'README.agentx' for details.
AgentX support is included by default, but needs to be explicitly
activated in the master agent. Do this by adding the line
master agentx
to the snmpd.conf file before starting the agent.
What is the purpose of 'dlmod'?
------------------------------
Most of the MIB information supplied by the Net-SNMP agent is provided
by C-coded implementation modules, and the choice of which modules to
include is usually made when the agent is first built. Adding new
MIB modules would therefore require re-compiling the agent. This is
not always convenient - particularly when working with a production
system, and/or pre-installed binaries.
Dynamically loaded modules are a means of including a MIB implementation
module within the main SNMP agent (or an AgentX subagent) without needing
to re-compile and re-link the agent binary. Instead, details of the
module(s) to load are specified in the configuration file, and the agent
locates the files listed, and merges them in at run time.
See http://www.net-snmp.org/tutorial-5/toolkit/dlmod/ for more information.
Which extension mechanism should I use?
--------------------------------------
That's not easy to answer in general.
If there's an existing agent that already implements the desired new
MIB, then it makes sense to re-use that, via whatever extension protocol
that agent might support. Note that the SMUX protocol has essentially
been superceded by AgentX, which provides a fuller and more reliable
mechanism than either SMUX or proxied SNMP. So ideally, this would
be the preferred extension approach.
But if the target subagent only supports SMUX or basic SNMP, then that
would dictate the extension protocol to use.
Implementing the module in C within the main agent (directly or via
dlmod) is probably the most efficient and reliable, closely followed
by embedded perl (or python) extensions. These have the advantage of
minimal overheads between the code implementing the MIB module, and
the agent framework, and no inter-process communication issues. But
this does assume that there's a suitable mechanism for retrieving the
necessary information.
If the new MIB is monitoring or managing some other subsystem, external
to the agent, then it may be necessary to embed a subagent within the
subsystem itself - particularly if there's no suitable public API to
retrieve the necessary information. In this case, AgentX is probably
the most appropriate way forward.
Alternatively, you could implement the missing public management API
for that subsystem, and develop a module within the main agent instead.
Can I use AgentX when running under Windows?
-------------------------------------------
Yes, but there are a couple of things to be aware of.
Firstly, by default the AgentX master listens on the Unix domain
socket '/var/agentx/master', which doesn't work under Windows.
You'll need to tell it to listen on a TCP port, either by using
the command-line option "-x localhost:705", or by adding the
directive "agentxSocket localhost:705" to the snmpd.conf file.
Secondly, be aware that the security of AgentX connectivity is not
particularly strong. The examples given here would allow any process
running on the local machine to register as an AgentX subagent. The
more obvious settings "-x 705" or "agentxSocket 705" would allow
a system *anywhere* on the network (or even from remote networks) to
register as an AgentX subagent. This could potentially be used to
hijack the agent, or provide false information.
How can I run AgentX with a different socket address?
----------------------------------------------------
There are two sides to an AgentX connection, and they need to
agree about which socket address to use. So if you want to use
a different socket, you need to configure both parties accordingly.
The socket that the Net-SNMP master agent uses to listen for AgentX
registrations (and send appropriate requests) can be specified using
the option '-x'.
The command
"snmpd -x tcp:localhost:705 ...."
would start the agent listening on the TCP port 705 for connections
from the local system.
The same effect can also be obtained by adding the line
agentxsocket localhost:705
to the file 'snmpd.conf'.
The same option can be used with the Net-SNMP agent when running in
This also holds when the Net-SNMP agent is running in
"subagent" mode, to specify the socket to register with (and receive
requests from).
So a subagent might connect to the master agent above (both running
on the same host), using:
"snmpd -X -x tcp:localhost:705 ...."
A subagent running embedded within some other application will
typically not understand the same command-line options, so would
need to set the same configuration programmatically:
netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID,
NETSNMP_DS_AGENT_X_SOCKET, "tcp:localhost:705");
With the example subagent code from the Net-SNMP tutorial, this line
would be added immediately before the 'init_agent' call.
The same approach can also be used to listen on a different named
socket, using:
agentxsocket /tmp/agentx
agentxperms 770 770 myuser mygroup
or
snmpd -x /tmp/agentx ....
or
netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID,
NETSNMP_DS_AGENT_X_SOCKET, "/tmp/agentx");
as appropriate.
How can I turn off SMUX support?
-------------------------------
Normally, you would use the command-line option '-I -{module}' to
disable the initialisation of a particular MIB module within the
agent. Unfortunately, it's not currently possible to turn off SMUX
support this way.
The safest approach is to run
configure --with-out-mib-modules=smux
and recompile the agent.
If this is not possible, an alternative workaround might be to have
the agent bind the SMUX socket to an invalid IP address, using a
snmpd.conf line such as:
smuxsocket 1.0.0.0
The agent may complain at startup, but it won't accept any incoming
SMUX requests.
If the agent complains about not recognising the "smuxsocket"
token, then you're out of luck. You'll either have to recompile
from source, or use local firewall rules to block connections
to port 199.
How can I combine two copies of the 'mib2' tree from separate subagents?
-----------------------------------------------------------------------
This is the purpose of the SNMPv3 'context' field. Register the MIB
module a second time in a non-default context (see the relevant entry
in the CODING section for details), and specify this context when
querying the agent. The MIB module can use this context information
to determine which set of information to report.
Or you could register two completely different handlers for the same
OID (using different contexts), and the agent will invoke the appropriate
code. This holds for both MIB modules implemented within the main agent,
or AgentX subagents - the same approach will work for both.
Contexts can also be used with proxied SNMP requests - just specify
the option '-Cn {context}' as part of the "proxy" entry. See the
'snmpd.conf(5)' man page for details.
It's currently not possible to support parallel MIB trees when using
SNMPv1 or SNMPv2c. In principle, it should be possible to use the
community string in a similar way, but this has not (yet) been implemented.
This mechanism is only available with the v5 Net-SNMP agent. The v4
UCD agent does not support contexts at all. Sorry about that.
Another way to handle this would be to tweak one of the subagents to
use a different set of (non-standard) OID assignments - perhaps by
relocating the whole of the subtree to another (private) OID. This
is not ideal, but should work with all configurations.
What traps are sent by the agent?
--------------------------------
The Net-SNMP agent sends a 'coldStart(0)' trap when it first starts up,
and an enterprise-specific trap 'nsNotifyShutdown' when it stops. It
generates an enterprise-specific trap 'nsNotifyRestart' (rather than
the standard 'coldStart(0)' or 'warmStart(1)' traps) on receiving a HUP
signal - typically after being re-configured. It can also be configured
to send an 'authenticationFailure(4)' trap when it receives an SNMPv1
(or SNMPv2c) request using an unknown community name.
The agent does not send 'linkUp' or 'linkDown' traps by default. It can
be configured to do this using the directive 'linkUpDownNotifications'.
See the 'snmpd.conf(5)' man page (under ACTIVE MONITORING) for details.
Similarly, it does not generate traps by default when one of the
monitored characteristics (disk usage, running processes, etc) enters or
leaves an error state. This can be configured using the 'defaultMonitors'
directive (again documented under ACTIVE MONITORING).
Where are these traps sent to?
-----------------------------
With all these alerts, the agent needs to be told where to send them,
specifying the type of notification (v1 or v2 trap, or v2 inform) and
the community name to use. This uses the snmpd.conf directives 'trapsink',
'trap2sink' and 'informsink' for the destination type, and 'trapcommunity'
for the community name. SNMPv3 destinations can be configured using the
directive 'trapsess'. See the 'snmpd.conf(5)' man page for details.
Note that the type of trap generated is totally determined by these
directives - irrespective of which API call was used to trigger sending
the trap. See the trap-related entries in the CODING section for details.
Note also that you typically only want *one* of the settings:
trapsink localhost
trap2sink localhost
informsink localhost
Including two (or all three) of these lines in the snmpd.conf file will
will result in multiple copies of every notifications being sent for
each call to 'send_easy_trap()' (or 'send_v2trap()').
This is probably not what was intended!
How can I send a particular trap to selected destinations?
----------------------------------------------------------
This is not currently possible. All notifications will be sent to
all configured destinations. The agent does not (currently) support
notification filtering.
There is a preliminary implementation of the snmpNotifyFilterTable
which is designed to allow this sort of selective trap direction.
However this is not currently active. (The tables are present and
can be manipulated and updated, but the information is not consulted)
Documentation on how to use this mechanism will appear once the
functionality is working properly.
When I run the agent it runs and then quits without staying around. Why?
-----------------------------------------------------------------------
Firstly, are you certain that this is what is happening?
The normal operation of the agent is to 'fork' itself into the background,
detaching itself from the controlling terminal so that it will continue
running even when you log out, and freeing the command line for subsequent
use. This looks at first sight as if the agent has died, but using 'ps'
to show all processes should reveal that the agent is still running.
To prevent this behaviour (such as when attempting to debug the agent),
you can start it with the '-f' flag. This suppresses the fork, and the
agent will run as a 'normal' command. It's also often useful to use the
'-Le' (or '-L') flag, to log messages to stderr.
On the other hand, if 'ps' shows that the agent is not running, then
this is an error, and probably show that something went wrong in
starting the agent up. Check the agent log file for any error messages,
or run it with '-f -Le' and see what it reports.
One possible cause might be an existing agent (or some other process)
that's already listening on the SNMP port. Trying to start a second
agent will fail with an error about "opening the specified endpoint".
If you're starting the agent as a non-root user, then this may also
fail with the very same error. By default, the agent (and trap handler)
will attempt to listen on the standard SNMP port 161 (or 162 for the
trap handler). These are defined as "privileged ports", and processes
will need to be running as root in order to open them.
One way to tackle this is to start the agent as root, but use the -u
option to switch to run as another user once the port has been opened.
Alternatively, you can specify a different port to use instead.
Anything greater than 1024 is available to non-root users. In this case,
you'll also need to specify the same port when issuing client commands.
After a while the agent stops responding, and starts eating CPU time. Why?
--------------------------------------------------------------------------
This is basically the same problem described in the APPLICATIONS
section, in the entry
The agent worked for a while, then stopped responding. Why?
See that entry for details.
How can I stop other people getting at my agent?
-----------------------------------------------
Firstly, are you concerned with read access or write access?
As far as changing things on the agent is concerned, there is relatively
little that can actually be altered (see the entry "Why can't I set
any variables in the MIB?" above).
If you are using the example config file, this is set up to allow
read access from your local network, and write access only from the
system itself (accessed as 'localhost'), both using the community name
specified. You will need to set appropriate values for both NETWORK
and COMMUNITY in this file before using it.
This mechanism can also be used to control access much more precisely.
(see the next few questions for details)
Other options include:
- Blocking access to port 161 from outside your organisation
(using filters on network routers)
- Using kernel-level network filtering on the system itself
(such as IPTables)
- Configuring TCP wrapper support ("--with-libwrap")
This uses the TCP 'libwrap' library (available separately)
to allow/deny access via /etc/hosts.{allow,deny}
For strict security you should use only SNMPv3, which is the secure
form of the protocol. However, note that the agent access control
mechanisms does not restrict SNMPv3 traffic by location - an SNMPv3
request will be accepted or rejected based purely on the user
authentication, irrespective of where it originated. Source-based
restrictions on SNMPv3 requests would need to use one of the "external"
mechanisms listed above.
How can I listen on just one particular interface?
-------------------------------------------------
Normally, the agent will bind to the specified port on all interfaces
on the system, and accept requests received from any of them. However,
if a particular port (or ports) is specified when the agent is first
started, then it will only listen for requests on these particular
ports.
For example:
snmpd 127.0.0.1:161
would listen (on the standard port) on the loopback interface only, and:
snmpd 10.0.0.1:6161
would listen on port 6161, on the (internal network) interface with
address 10.0.0.1. To listen on both of these interfaces (and no others)
provide a list of all the desired addresses:
snmpd 127.0.0.1:161 127.0.0.1:6161
The AgentX port option ('-x') works in much the same way.
The agent is complaining about 'snmpd.conf'. Where is this?
-----------------------------------------------------------
It doesn't exist in the distribution as shipped. You need to
create it to reflect your local requirement.
To get started, you can either just create this file manually,
or run snmpconf to help you create one. At the very least, you
will need some form of access control configuration, if the agent
is to be of any use whatsoever. This can be as simple as:
rocommunity public
See the snmpd.conf(5) manual page or relevant entries in this
FAQ for further details.
Why does the agent complain about 'no access control information'?
-----------------------------------------------------------------
Although an SNMP agent may support a wide range of management
information, it is not necessarily appropriate to report the whole
of this to every SNMP management station who asks for it. Some
information may be sensitive, and should restricted to authorized
administrators only. SNMP therefore includes mechanisms for
controlling who has access to what information - both in terms of
what can be seen, and (even more importantly) what can be changed.
By default, the Net-SNMP agent starts up with a completely empty
access control configuration. This means that *no* SNMP request
would be successful. It is necessary to explicitly configure
suitable access control settings, based on who should be granted
access in that particular environment.
If there are no access control entries configured (perhaps because
no snmpd.conf configuration file has been loaded, or it contains no
access control settings), then the agent will not respond to any
SNMP requests whatsoever. This is almost certainly not what was
intended, so the agent reports this situation.
See the next entry for how to configure access control settings.
How do I configure access control?
---------------------------------
The simplest way is to use the configure directives:
rocommunity public (for SNMPv1/2c)
rwcommunity private
or
rouser user1 (for SNMPv3)
rwuser user2
These specify the community names or security names to accept for
read-only and read-write access to the whole of the supported MIB tree.
(Obviously you should change these names to match your requirements -
which is a particularly good idea in the case of 'rwcommunity'!)
Note that you should *not* specify the same community name for both
rocommunity and rwcommunity directives. The rwcommunity setting
automatically provides read access, and having both lines (with the
same community name) may result in unexpected behaviour.
Only use both settings when specifying *different* community names.
The same holds true for rouser and rwuser.
The two community directives can be restricted to only allow requests
from particular sources, and all four can be restricted to a particular
subtrees or (from v5.3) a named view. See 'snmpd.conf(5)' for details.
How do I configure SNMPv3 users?
-------------------------------
There are three ways to configure SNMPv3 users:
1) Stop the agent, and add the line
createUser {myUser} MD5 {myPassword} DES
to the file /var/net-snmp/snmpd.conf (where {myUser} and
{myPassword} are the appropriate values for username and password,
_without_ the braces!). Then re-start the snmpd agent.
2) Stop the agent, run the command
net-snmp-config --create-snmpv3-user
and follow the prompts given. This will create an entry
in the /var/net-snmp/snmpd.conf file similar to the above.
Then re-start the snmpd agent.
3) Make sure the agent is running, and will respond to an SNMPv3
request (using an existing user with the desired authentication
and privacy protocols). Then use the 'snmpusm' command to clone
this template user, and change the password.
See the access control entries above and the file 'README.snmpv3'
for more details about how to use SNMPv3 users,
Note that simply having a 'rouser' or 'rwuser' line does *not*
automatically create the corresponding SNMPv3 user. You will need
the above 'createUser' line (or an equivalent 'usmUser') as well.
The 'createUser' line disappears when I start the agent. Why?
-------------------------------------------------------------
This is deliberate.
The agent removes the (human-readable) 'createUser' directive, and
replaces it with an equivalent 'usmUser' entry. This contains the
same information, but in a form that's only meaningful internally.
Not only is the passphrase no longer visible in the config file, it
has actually been converted to a key that is only valid on this
particular system. If someone stole the configuration file, they
could not use the information from the usmUser entry to access any
of your other agents (even if the usernames and passwords were the same).
What's the difference between /var/net-snmp and /usr/local/share/snmp?
---------------------------------------------------------------------
The /var/net-snmp location is primarily used for information set
during the running of the agent, which needs to be persistent between
one run of the agent and the next. Apart from "createUser" (see
the previous entry), you shouldn't need to touch this file.
All other user-provided configuration should go in the traditional
location (typically /usr/local/share/snmp/snmpd.conf or /etc/snmp).
My new agent is ignoring the old snmpd.conf file. Why?
-----------------------------------------------------
The most likely explanation is that the new version of the agent is
looking in a different location than the previous one. This is commonly
experienced when replacing a ready-installed version (e.g. from a vendor
distribution), with the current release installed from the source.
Try moving the old config file to the new location, and restart the agent.
If you're not sure where this should go, see the next entry.
Where should the snmpd.conf file go?
-----------------------------------
The default location for this file with the basic distribution is
/usr/local/share/snmp/snmpd.conf (or PREFIX/share/snmp/snmpd.conf).
Ready-installed versions often look for the file as /etc/snmpd.conf,
or /etc/snmp/snmpd.conf.
If you are still not sure, try running the command
snmpd -f -Le -Dread_config 2>&1 | grep "config path"
The first line of output will display the list of locations where
the agent is looking for configuration information.
Why am I getting "Connection refused"?
-------------------------------------
This is actually nothing to do with the access control mechanism
(though that's an understandable mistake). This is the result of
the TCP wrapper mechanism using the files 'hosts.allow' and 'hosts.deny'
to control access to the service. Some distributions may come with
this enabled automatically - otherwise you need to explicitly activate
this by running
configure --with-libwrap
and recompiling the agent.
If TCP wrappers are enabled, and both hosts.allow and hosts.deny are
empty, then all requests will be rejected (with "Connection refused").
The simplest way to avoid this problem and allow incoming requests is
to add the line
snmpd: ALL
to the file /etc/hosts.allow. Be aware that doing this removes one
level of protection and allows anyone to try and query your agent.
The agent's own access control mechanisms can still be used to restrict
what - if anything - they can see.
If you do wish to use the TCP wrappers to restrict access, it's sensible
to have an explicit entry:
snmpd: ALL
in the file /etc/hosts.deny, which makes it crystal clear that access
to the SNMP agent has been denied. This mechanism can also be used to
restrict access to specific management hosts, using a hosts.deny entry
such as:
snmpd: ALL EXCEPT 127.
which will allow connections from localhost, and nothing else.
Note that personal firewalls, such as the Linux iptables mechanism,
may have a similar effect (though typically this won't be logged).
See the earlier entry
Requests always seem to timeout, and don't give me anything back. Why?
Why can't I see values in the UCDavis 'proc' or 'disk' trees?
------------------------------------------------------------------
Both these trees are designed to report precisely those things that
have been explicitly configured for monitoring. If there are no
relevant configuration entries in the snmpd.conf file, then these
tables will be empty. See the snmpd.conf manual page and the
EXAMPLE.conf file for details on configuring the agent.
Optionally, run snmpconf -g monitoring to help you set up this
section of the snmpd.conf file.
Why can't I see values in the UCDavis 'memory' or 'vmstat' trees?
----------------------------------------------------------------
These trees do not need any explicit configuration, and should
be present automatically.
However the C code necessary to implement these particular MIB
modules are not supported on all operating systems. These trees
will be omitted on any system for which there is no underlying
code. Currently, they are only supported on Linux, HP-UX (memory
only), Solaris, BSDi (vmstat on BSDi4 only), Dynix, FreeBSD, NetBSD
and OpenBSD.
If you want to help port it to other systems, let us know.
Note that these subtrees only report the current usage when
explicitly queried. They do *not* automatically generate traps
when the usage strays outside the configured bounds.
See the earlier FAQ entry
What traps are sent by the agent?
or the snmpd.conf section on active monitoring, for more information.
What do the CPU statistics mean - is this the load average?
----------------------------------------------------------
No. Unfortunately, the original definition of the various CPU
statistics was a little vague. It referred to a "percentage",
without specifying what period this should be calculated over.
It was therefore implemented slightly differently on different
architectures.
The 5.4 release has clarified the situation, and standardised on
calculating these percentages over a minute. The relevant MIB
descriptions have been updated to make the desired behaviour
more explicit.
The Net-SNMP agent also includes "raw counters", which can be used
to calculate the percentage usage over any desired period. This is
the "right" way to handle things in the SNMP model. The original
percentage objects have been deprecated, and may possibly be removed
in a future release of the agent.
Note that this is different from the Unix load average, which is
available via the loadTable, and is supported on all architectures.
How do I get percentage CPU utilization using ssCpuRawIdle?
-----------------------------------------------------------
This one of the "raw counters" mentioned in the previous entry.
You need to take two readings of this object and look at the
difference between them. That difference divided by the total
number of 'ticks' between the two readings (where one tick is
probably 0.01 seconds) will give you the percentage utilization
over that period.
What about multi-processor systems?
----------------------------------
The CPU objects (both percentages and raw counters) were designed to
monitor the overall CPU activity of a system, and typically reflect
whatever the underlying operating system reports for the (single)
CPU statistics information. How these are handled for a multi-CPU
system will differ from one O/S to another, and will need
to be investigated for each system individually.
The htProcessorTable was designed to handle monitoring multi-CPU
machines, but the Net-SNMP implementation has up to now treated
most systems (with the honourable exception of Solaris, and more
recently Linux) as implicitly single-CPU.
With the 5.4 release, there is now a cleaner framework for reporting
on multi-CPU equipment, and it is hoped that an increasing number
of systems will be able to report suitable processor information.
Also with the 5.4 release, for the first time the agent will report
the hrProcessorLoad value properly, which should provide some simple
per-CPU statistics.
The speed/type of my network interfaces is wrong - how can I fix it?
-------------------------------------------------------------------
Some operating systems will provide a mechanism for determining
the speed and type of network interfaces, but many do not. In such
cases, the agent attempts to guess the most appropriate values,
usually based on the name of the interface.
The snmpd.conf directive "interface" allows you to override these
guessed values, and provide alternative values for the name, type
and speed of a particular interface. This is particularly useful
for fast-ethernet, or dial-up interfaces, where the speed cannot be
guessed from the name.
See the snmpd.conf(5) man page for details.
The interface statistics for my subinterfaces are all zero - why?
----------------------------------------------------------------
Unfortunately, most kernels that support multiple logical
interfaces on a single physical interface, don't keep separate
statistics for each of these. They simply report the overall
statistics for the physical interface itself.
There's no easy way around this problem - the agent can only
report such information as is available. If the kernel doesn't
keep track of these figures, the agent can't report them.
Sorry!
Does the agent support the RMON-MIB?
-----------------------------------
Not really.
There is an "Rmon" code module included within the agent source
code tree, but this is best thought of as a template for the
RMON-MIB statistics groups, rather than a full implementation.
With most MIBs, the hardest part of implementing the MIB is often
getting hold of the data to report. This is definitely true of the
RMON-MIB, which relies on gathering (and analysing) a potentially
large quantity of network traffic. The Rmon code distributed with
the Net-SNMP agent code avoids this problem, by using random data.
Some of the functionality of the RMON-MIB, such as the alarm and
event groups, has since been superseded by the work of the DisMan
IETF working group. The Net-SNMP agent does implement these (more
general) MIB modules. But the statistics gathering aspects of
the RMON-MIB are not readily available.
Note too that none of the core developers have any significant
experience with this code, and the person who originally wrote it
is no longer active on the mailing lists. So there's no point in
asking on the lists whether these modules work or not. You've got
the source - how badly do you need this functionality?
What does "klread: bad address" mean?
-------------------------------------
This means that the agent was unable to extract some of the
necessary information from the kernel structures. This is
possibly due to:
- either looking in the wrong place for kernel information
(check the value of KERNEL_LOC)
- an error in the implementation of part of the MIB tree
for that architecture. Try and identify which
OID is generating the error, and contact the
list 'net-snmp-coders@lists.sourceforge.net'
Remember to tell us what architecture you have!
What does "nlist err: wombat not found" (or similar) mean?
----------------------------------------------------------
This means that the agent wasn't able to locate one of the
kernel structures it was looking for. This may or may not
be important - some systems provide alternative mechanisms
for obtaining the necessary information - Solaris, for example,
can produce a whole slew of such messages, but still provide
the correct information.
This error only occurs if you have used the flag
'--enable-debugging' as part of the initial configuration.
Reconfigure the agent with '--disable-debugging' and these
messages will disappear. (It won't fix the underlying problem,
but at least you won't be nagged about it).
What does "Can't open /dev/kmem" mean?
-------------------------------------
This device is normally restricted to just being accessible by root
(or possibly by a special group such as 'kmem' or 'sys'). The agent
must be able to read this device to obtain the necessary information
about the running system.
Check that the agent was started by root, and is running with UID 0
(or suitable GID if appropriate). The agent will normally continue
to run without this level of access permission, but won't be able to
report values for many of the variables (particularly those relating
to network statistics).
The system uptime (sysUpTime) returned is wrong!
-----------------------------------------------
Oh no it's not.
The defined meaning of 'sysUpTime' is
"the time ... since the *network management*
portion of the system was re-initialized."
In other words, when the snmp agent was started, not when the
system itself last booted. This latter information is available
in the Host Resources MIB as "hrSystemUpTime.0"
Note that even if the full Host Resources is not supported on
your system, it's worth configuring in the system portion using
'--with-mib-modules=host/hr_system'
and recompiling. This particular group is reasonably likely to work,
even if some of the other more architecture-specific groups don't.
Can the agent run multi-threaded?
--------------------------------
Short answer - no.
Longer answer - not easily.
Net-SNMP within a single thread of an threaded application is fine,
as long as *all* snmp code is kept within the same thread. This lets
you add SNMP support to an existing threaded application.
If you are concerned with the time taken for to process requests for
a particular agent, object or subtree, and you want the agent to
continue to respond to other requests in the meantime, there are
two options.
The first method is using AgentX sub-agents. If you have several
tables, each implemented by a separate subagent, then a single
request for entries from each of the tables will be processed
in parallel (and the agent will continue to respond to other
requests while it waits for the subagents to return the necessary
information). But a request for several objects from the same
table will be passed off to the relevant subagent, where it will
(normally) be processed serially.
The second method is to use delegated requests + IPC to another
process. If takes a long time to retrieve a value for a given object,
then the object handler could do whatever necessary to start or
communicate with another (non-SNMP) process/thread to actually
retrieve the value, and mark the request as delegated.
The main agent (or subagent) can then receive and process other
requests while waiting for the delegated request to finish.
Dealing with resource contention is all up to you.
All of this only applies to the GET family of requests. A SET
request will block until all pending GET requests have finished,
and then will not accept new requests until the SET is complete.
Adding full multi-thread support directly to the agent would be
nice. We just need someone with time/money to do/sponsor the work.
Can I use AgentX (or an embedded SNMP agent) in a threaded application?
-----------------------------------------------------------------------
With care.
As mentioned in the earlier "thread-safe" FAQ entry, the Net-SNMP
agent (including the AgentX subagent) has not been designed for
threaded operation. In particular, it makes use of various global
variables without attempting to protect them against simultaneous
use. This means that it is *NOT* safe to have SNMP or AgentX
related processing in two separate threads. This also applies to
handling GET (and SET) processing in one thread, and generating traps
in another. This is still vulnerable to the usual threading problems.
However, as long as *all* of the SNMP-related activity is limited
to the one thread, then there should be no reason why this cannot
safely communicate with other threads within the same application,
using private (thread-safe) mechanisms.
But in terms of the Net-SNMP-provided code, the agent (and AgentX
subagent) should *not* be regarded as thread-safe.
COMPILING
=========
How do I control the environment used to compile the software?
-------------------------------------------------------------
The basic mechanism for compiling the Net-SNMP project software is to
run "configure", followed by "make" (to compile it), "make test" (to
check that it's working properly) and then "make install" (to install
the files into the correct locations - which typicalyl needs to be done
as root.
The primary role of "configure" is to determines various aspects about
the system that the software is being compiled on. However there are
also a number of options to configure which can be used to control
various aspects of the compilation environment.
The most common options are "--with-mib-modules" and "--with-out-mib-modules"
which control the set of MIB module code files that are included within
the agent binary. Adding or removing these modules will affect what MIB
information the agent can return.
See the entry "How do I add a MIB to the agent?" for more details.
The configure script can also specify the compiler to use for compiling
the source code (e.g. "configure --with-cc=cc"), the flags passed to
this compiler (e.g. "configure --with-cflags=-g"), or to the linker
(e.g. "configure --with-ldflags=-Bstatic"), and various other aspects of
the build environment.
Run "configure --help" for a full list.
How do I control the environment used to compile the software under Windows?
---------------------------------------------------------------------------
If you are compiling the project within the MinGW or Cygwin environments,
then these use the same "configure" mechanism as Unix-based systems. See
the previous entry for more information.
If you are compiling the project from within Visual Studio, then this does
not use the standard configure mechanism. Instead, there is a separate
"Configure" script within the 'win32' directory. This can be used enable
or disable various aspects of the build environment, such as support for
encryption or IPv6.
Run "Configure --help" for more information
Note that this script does not include an equivalent of "--with-mib-modules"
for extending the MIB information supported by the agent. Instead, this
needs to be done by tweaking the build environment manually. See the file
README.win32 for more details of this, and various other aspects of building
the project on Windows systems.
Why does the compilation complain about missing libraries?
---------------------------------------------------------
This has been seen in a number of guises over the years - most commonly
on Linux systems (although the problem may also occur elsewhere). The
underlying problem is that typical installation may not always include
the full set of library links required for building the Net-SNMP software.
This problem can usually be fixed by installing the missing packages
(typically the development version of a package that is already there).
Examples of this that we have come across include:
-lelf elfutils-devel (later renamed to elfutils-libelf-devel)
-lbz2 bzip2-devel
-lselinux libselinux-devel
-lcrypto openssl/openssl-devel
-lbeecrypt libbeecrypt/beecrypt/beecrypt-devel.
These are the names of the RedHat/Fedora RPMs. Other distributions
or O/S's may use different names, but the basic idea should be the
same.
If the compilation is complaining about a missing .so file, then an
alternative quick fix is to add the missing symbolic link, using
something like:
ln -s libelf.so.1 /usr/lib/libelf.so
giving the appropriate generic library name from the error message,
and the correct number for whichever version of this library you
have installed.
If the compilation is complaining about a .la file, then you should
install the relevant development package, as listed above.
How can I reduce the memory footprint?
--------------------------------------
In order to reduce the memory footprint (for instance, to
embed the snmpd into a device), the following configure options
could be used.
'--disable-debugging'
This turns off the compilation of all debugging statements.
'--enable-mini-agent' '--with-out-mib-modules=examples/ucdDemoPublic'
This creates an agent with just the essential MIB modules included.
NOTE: If you need additional MIB modules, then simply add them
using the option '--with-mib-modules=...' but this will of course
increase the memory footprint.
'--with-transports=UDP'
This option specifies the transport domains to include.
For a simple standalone agent, just UDP should be sufficient.
(Although the 'disman' and 'agentx' modules may require the
Callback, TCP and/or Unix transport domains as well).
'--without-kmem-usage'
This can be used in order to omit the code that operates on the
/dev/kmem interface. Clearly, this option cannot be used when
one of the configured MIB modules depends on it.
'--with-mibdirs=' and '--with-mibs='
These options tell the agent not to load any MIB modules.
This doesn't affect the size of libraries or application
binaries, but will reduce the memory footprint during runtime.
'--disable-mib-loading'
This can be used in order to omit the code that loads and
parses the MIB files altogether. This will reduce both the
runtime memory footprint, and the binary sizes.
Once the agent (snmpd) has been linked, you might also try running
'strip snmpd' to remove un-necessary debug/symbol information.
How can I reduce the installation footprint or speed up compilation?
-------------------------------------------------------------------
The following configure options may also be useful:
--disable-agent Do not build the agent (snmpd).
--disable-applications Do not build the apps (snmpget, ...).
--disable-manuals Do not install the manuals.
--disable-scripts Do not install the scripts (mib2c, ...).
--disable-mibs Do not install the mib files.
--disable-mib-loading Do not include code that parses and
manipulates the mib files.
How can I compile the project for use on an embedded system?
-----------------------------------------------------------
Although this is definitely a Frequently Asked Question on the project
mailing lists, it hasn't really been a Frequently _Answered_ Question.
The basic problem is that none of the core development team have much
involvement or experience with embedded systems. And although we have
repeatedly put out a plea for implementation reports and advice, this
has not so far been particularly successful. So the first thing to say
is that the following suggestions should be treated with a greater than
usual level of suspicion.
The second thing to say is that compiling the Net-SNMP project for use
on an embedded system typically means compiling the *agent* (rather than
the trap receiver, or command-line tools). So that is what this entry
will concentrate on.
There are three main aspects to consider:
- how to compile the code,
- *what* code to compile, and
- how to install the resulting agent binary.
The Net-SNMP project uses the standard "configure" mechanism, so the
usual cross-compilation options are available - in particular "--host"
and "--target". It is also possible to specify the compiler and linker
to use ("--with-cc" and "--with-ld"), and any special flags to pass
to them ("--with-cflags" and "--with-ldflags"). There shouldn't be
anything particularly special about compiling the Net-SNMP code, so
see the documentation for your target environment for more information.
(And please let us know if there *is* anything special that should be
mentioned here!)
If the aim is simply to generate an SNMP agent to run on the target
system, it's probably not necessary to compile the command-line tools
or trap receiver. The configure option "--disable-applications" will
omit these elements. See the previous entry for other potentially
relevant useful options.
Unfortunately, the SNMP agent (and in particular, the code for individual
MIB modules) is the most system-specific part of the Net-SNMP software.
It may prove necessary to disable particular MIB modules if they do not
compile successfully, or attempt to use the wrong system-specific APIs.
This can be done using the configure option "--with-out-mib-modules".
Alternatively, the option "--enable-mini-agent" will omit all but the
core MIB module code. Additional modules can then be added individually
using "--with-mib-modules".
Further information about how to deal with problems with individual MIB
modules is reliant on suitable reports being forthcoming from the wider
Net-SNMP community. The ball is in your court!
Finally, installing the agent binary is _not_ simply a matter of copying
the "snmpd" file onto the target system. The agent typically relies on
a number of additional libraries (and possibly the presence of assorted
MIB files, unless this has been explicitly omitted). It is normally
necessary to run "make install", before copying the installed framework
to the target system.
If the install destination needs to be different to the eventual location
on the target system, this can be handled using the configure options
"--prefix" (for the target location) and "--with-install-prefix" (for the
temporary install location). Alternatively, this can be handled as part
of the install command:
make install prefix={target location} INSTALL_PREFIX={temp location}
Alternatively, if the agent is compiled with static linking (and no MIB
files), then it may be possible to simply copy the agent binary across to
the target system. See the next entry for details.
How can I compile the project to use static linking?
---------------------------------------------------
For totally static net-snmp executables, use
configure --with-ldflags=-Bstatic
To compile your application with static libraries (eg for easier
debugging), and to link to a non-installed build directory, try the
following Makefile fragment:
NETSNMPDIR=/usr/local/build/snmp/full-clean-cvs-V5-1-patches
NETSNMPCONFIG=$(NETSNMPDIR)/net-snmp-config
NETSNMPBASECFLAGS := $(shell $(NETSNMPCONFIG) --base-cflags)
NETSNMPINCLUDES := $(shell $(NETSNMPCONFIG) --build-includes $(NETSNMPDIR))
# base flags after build/src include, in case it has /usr/local/include
NETSNMPCFLAGS=$(NETSNMPINCLUDES) $(NETSNMPBASECFLAGS)
NETSNMPBASELIBS := $(shell $(NETSNMPCONFIG) --base-agent-libs)
NETSNMPEXTLIBS := $(shell $(NETSNMPCONFIG) --external-agent-libs)
NETSNMPLIBDIRS := $(shell $(NETSNMPCONFIG) --build-lib-dirs $(NETSNMPDIR))
NETSNMPLIBDEPS := $(shell $(NETSNMPCONFIG) --build-lib-deps $(NETSNMPDIR))
LIB_DEPS=$(NETSNMPLIBDEPS)
LIBS=$(NETSNMPLIBDIRS) -Wl,-Bstatic $(NETSNMPBASELIBS) -Wl,-Bdynamic $(NETSNMPEXTLIBS)
STRICT_FLAGS = -Wall -Wstrict-prototypes
CFLAGS=-I. $(NETSNMPCFLAGS) $(STRICT_FLAGS)
This replaces the standard Makefile section, which will used installed
libraries:
NETSNMPCONFIG=net-snmp-config
# uncomment this if you have GNU make
#NETSNMPCFLAGS := $(shell $(NETSNMPCONFIG) --base-cflags)
#NETSNMPLIBS := $(shell $(NETSNMPCONFIG) --agent-libs)
NETSNMPCFLAGS=`$(NETSNMPCONFIG) --base-cflags`
NETSNMPLIBS=`$(NETSNMPCONFIG) --agent-libs`
LIBS=$(NETSNMPLIBS)
Why does 'make test' skip various tests?
---------------------------------------
Some of the tests are only relevant to particular operating systems,
or rely on specific areas of functionality. The test framework will
check whether the relevant elements are available before running the
relevant tests, and will skip them if these modules have been omitted
from the build environment (or do not apply to the current system).
One example of this are the tests T053agentv1trap, T054agentv2ctrap,
T055agentv1mintrap, T056agentv2cmintrap and T113agentxtrap, which
rely upon functionality from the NET-SNMP-EXAMPLES-MIB implementation.
This module is not included in the default agent configuration, so the
test framework will skip these tests.
To include them, run
"configure --with-mib-modules=examples/example"
and re-compile.
Why does 'make test' complain about a pid file?
-----------------------------------------------
Typically it says something like:
cat: cannot open /tmp/snmp-test-1-8694/*pid*
It's trying to tell you the port is blocked - typically because
another copy of the agent is still running, left over from from a
previous testing run.
If you type 'ps -ef' you should notice an orphaned process like:
snmpd -d -r -U -P /tmp/snmp-test-5-27295/snmpd.pid...
Kill this process.
This could be happening for several reasons including:
1. You are trying to do concurrent runs of 'make test'.
2. On a slow machine, the agent might be taking too long to
start up. Try changing the value of the variable SNMP_SLEEP
in testing/RUNTESTS from 1 to something higher - say 3 or 5.
CODING
======
How do I write C code to integrate with the agent?
-------------------------------------------------
There are three main methods for integrating external C code
within the agent. The code can be compiled directly into the
agent itself, it can be loaded dynamically while the agent is
running, or it can be compiled into a separate application
(a "subagent") which communicates with the main master agent.
All three approaches have been touched on elsewhere within this FAQ.
As far as the module code is concerned, all three mechanisms
use exactly the same module API. So a module developed for use
directly within the agent, could also be included within a subagent,
or loaded dynamically with no (or minimal) code changes needed.
Most of this section is concerned with more detailed aspects
of developing such code - including the 'mib2c' tool, which can
handle generating a basic code framework for implementing a
given set of MIB objects.
How does the agent fetch the value of a MIB variable from the system?
--------------------------------------------------------------------
That's typically the hardest bit of implementing a new MIB module,
and is the one thing that 'mib2c' can't help with. It very much
depends on the MIB variable concerned (and often the underlying
operating system as well).
Relatively few MIB modules are completely self-contained, with all
the information held internally within the agent, and all updates
being done via SNMP requests. Such MIB modules can be implemented
fairly easily.
More commonly, the agent needs to provide an SNMP-based interface to
information held elsewhere, perhaps in the operating system kernel or
some other application. Handling this is much more complex - since
a lot depends on what mechanisms are provided for retrieving (and
possibly updating) this information. The mib2c tool can generate code
for processing SNMP requests, based on some internal cache of management
information, but it cannot help with populating this cache with the
underlying data. That is up to the MIB implementer.
See the existing MIB modules in the Net-SNMP source tree for various
examples of assorted approaches to this task.
Mib2c complains about a missing "mib reference" - what does this mean?
---------------------------------------------------------------------
This basically means that it hasn't loaded the MIB file containing
the definition of the MIB subtree you're trying to implement. This
might be because it hasn't been installed, the name is wrong, or
(most likely), because it isn't in the default list. See the MIBS
section for more details, or the next entry for suitable invocations
of 'mib2c'.
Mib2c complains about not having a "valid OID" - what does this mean?
---------------------------------------------------------------------
This probably means that you gave it the name of a MIB file (or
module), rather than the name of an object defined in that file.
Mib2c expects the name of a 'root' object, and will generate a
template for the sub-tree starting from there.
If you've got a file 'MY-MIB.txt', defining the MIB module
'MY-MIB' which contains a subtree based on the object 'myMib',
then you should invoke mib2c as
"mib2c .... myMib"
rather than
"mib2c .... MY-MIB.txt"
or "mib2c .... MY-MIB"
Note that you'll probably also have to add your MIB to the list of
MIBs that are loaded automatically, in order for mib2c to recognise
the name of this object. So the command would typically be
"MIBS=+MY-MIB mib2c .... myMib"
or "MIBS=ALL mib2c .... myMib"
Why doesn't mib2c like the MIB file I'm giving it?
-------------------------------------------------
This is most likely the same problem as the previous entry. Mib2c
takes the name of a MIB _object_, not the name of a file (or MIB
module). Try using the name of the MODULE-IDENTITY definition.
Another possibility is that the MIB may contain syntax errors.
Try running it through 'snmptranslate' or a dedicated SMI
validation tool (such as 'smilint' or the on-line interface at
http://wwwsnmp.cs.utwente.nl/ietf/mibs/validate/)
Mib2c ignores my MIB and generates a pair of 'mib-2' code files. Why?
---------------------------------------------------------------------
This is usually a sign of the same problem as the previous entries,
giving mib2c the name of the file containing the MIB (or of the MIB
itself), rather than an object within it.
Earlier versions of mib2c didn't detect this situation, and merrily
constructed a template for a default starting point of the mib-2 node.
More recent versions complain about not having a valid OID instead.
What's the difference between the various mib2c configuration files?
-------------------------------------------------------------------
Most of the mib2c config files are concerned with implementing
MIB tables, and generate various alternative code templates.
These basically fall into four distinct categories.
'mib2c.raw-table.conf' is the lightest of the templates, and
just provides a fairly basic table framework. Most of the work
of implementing the table - detecting which row is required for a
given request, retrieving or updating the relevant column values,
and interacting with the underlying subsystem - are all left to
the MIB programmer.
The second group of templates - 'table_data', 'container' and
'tdata' - all share the same basic model (although the internal
details are rather different). The MIB implementer should define a
data structure to represent a row of the table, and the helper then
takes care of holding the table internally, as a collection of such
per-row data structures. This includes identifying which row is
required for a given request. Retrieving or updating the appropriate
column value is left to the MIB programmer, although the generated
framework includes most of the necessary code.
Allied to this is a fourth "internal data" mib2c configuration
file ('create-dataset') which handles the individual columns as
well. This is the closest to a Plug-and-Play configuration, and
the MIB implementer only needs to be concerned with any special
processing, such as linking the table with the underlying subsystem.
The third style of mib2c config assumes that the table data is
held externally to the helper - either within the MIB module code
itself, or in the external subsystem. The generated code framework
includes routines to "iterate" through the rows of the table, with
the iterator helper simply deciding which row is required for a
particular request. Once again, the MIB programmer must handle
retrieving or updating the appropriate column value, although the
generated framework includes most of the necessary code.
There is a variant of this config ('iterate_access') which works
in basically the same way. However this tries to separate out the
standard processing, from the code that needs to be amended by the
programmer for retrieving and updating the individual column values.
This is also the idea behind the final table-oriented mib2c config
template - 'mib2c.mfd.conf' (or "MIBs for Dummies"). This is a much
more flexible framework, which can be used with either internally
held data, or iterating through an external representation. The
distinguishing feature of this framework is that it separates out
standard and table-specific processing, at a much finer level of
detail than the others.
The other mib2c config templates are concerned with implementing
scalar objects ('scalar', 'int_watch'), code to generating traps
('notify'), and various specialised requirements. There is also a
template ('old-api') to generate code suitable for the previous v4
UCD agent - though this is not particularly complete or reliable.
It's probably better to use a pure v4 mib2c environment (or switch
wholeheartedly to the v5 style).
Which mib2c configuration file should I use?
-------------------------------------------
The answer to that heavily depends on the characteristics of the
MIB objects being implemented. Of the handler-based table frameworks,
'tdata' is more appropriate for tables that can be stored (or a copy
cached) within the agent itself, while 'iterate' is more relevant to
reporting data from outside the agent.
The raw interface is only suitable in very specific circumstances,
so it's probably sensible to start with one of the other frameworks
first, and only look at this if none of the alternatives seem to work.
The decision between the handler-based configs and MfD is more a
matter of the style of programming to use. Most of the frameworks
define a single handler routine to process an incoming request, so
all of the code is listed together, with the MIB programmer inserting
table-specific processing into this single block of code.
The MfD provides a series of individual object-specific routines,
each concerned with one very specific task, and hides as much as
possible from the programmer.
If you like to understand the broad thrust of what's happening,
then one of the handler-based approaches would be the best choice.
If you prefer to concentrate on the nitty-gritty of a given table,
and are happy to trust that the rest of the processing will work
correctly, then the MfD framework would be more appropriate.
For implementing a group of scalar objects, then the choice is
simple - use 'mib2c.scalar.conf'. Similarly, for generating traps
or informs, use 'mib2c.notify.conf'. But note that this only assists
with the code to actually generate the trap. It does not address the
issue of _when_ to send the trap. See the FAQ entry "How can I get
the agent to generate a trap?" for more information.
How can I have mib2c generate code for both scalars and tables?
--------------------------------------------------------------
This uses a very powerful tool called a "text editor" :-)
The mib2c tool uses separate configuration files to generate code
for scalar objects, and for tables. This means that it's not possible
to automatically generate a single code file that supports both scalars
and tables.
Instead, the two code files need to be generated separately, and
then combined manually. This will typically mean copying the handler
routines for the scalar object(s) into the table file, and adding the
code to register these handler(s) to the table initialisation routine.
Are there any examples, or documentation for developing MIB modules?
-------------------------------------------------------------------
Many of the MIB modules shipped with the Net-SNMP agent still
use the v4 "traditional" MIB module API, but an increasing number
use one of the newer v5 helper-based handlers. All of these can
be found under 'agent/mibgroup'
The 'tdata' helper is used in the new DisMan Event, Expression
and Schedule MIB modules (see 'disman/{event,expr,schedule}/*').
The similar 'dataset' helper is used in the older DisMan Event
MIB implementation (see 'disman/mteEvent*') and the Notification
Log MIB (see 'notification-log-mib/*'), used by 'snmptrapd' to
log incoming traps.
The basic iterator handler is used in the TCP and UDP table
implementations (mibII/tcpTable & mibII/udpTable), VACM context
handling (mibII/vacm_context) and various tables relating to agent
internals (agent/*). These show a number of different approaches
to using the iterator helper, so it's worth comparing them.
The two examples/netSnmpHostsTable* modules provide a contrast
between the iterator and iterator_access helpers.
There are several examples based on the MfD framework (see
'{if,ip,tcp,udp}-mib/'). Much of this code is not intended to
be viewed directly, but individual files are clearly commented
to distinguish between internal implementation and public code.
The Net-SNMP agent does not currently include any MIB modules
using the array-user container-based helper. The best examples
of this are to be found in the net-policy project.
See http://net-policy.sourceforge.net/
Where should I put the files produced by 'mib2c'?
------------------------------------------------
If you're using the main source tree to compile your new module, then
put these two files (mymib.[ch]) in the directory 'agent/mibgroup'.
You should then re-run configure to add in your new module
configure --with-mib-modules=mymib
and recompile.
If you've got a number of new modules to add, it might be
sensible to put them all into a single subdirectory of 'mibgroup'.
Then create a header file, listing the individual components.
This might look something like:
config_require(mymib/myObjects)
config_require(mymib/myTable)
config_require(mymib/myOtherTable)
If this was saved as the file 'mymib.h', then the same configure
line given above, would pull in all three modules. See the current
contents of 'agent/mibgroup' for examples of this. Note that the
MfD framework will generate a similar grouping automatically.
Why doesn't my new MIB module report anything?
---------------------------------------------
There are probably four main reasons why a new MIB module isn't working.
Either it hasn't been included in the running agent, the code is present
but hasn't been initialised, the module has been initialised but the
handler isn't being called, or there's a problem with the module code itself.
To check whether the code files are being compiled, the easiest approach is
simply to look at the directory where the code is located. When the agent is
compiled, this should produce .o files (and probably .lo files) corresponding
to the C code files for this module. Alternatively, run 'nm' (or 'strings')
on the MIB module library (libnetsnmpmibs), and look for the names of the
initialisation routines or handlers (or the text of any messages displayed by
the module code).
One other thing to check is whether you have multiple copies of the software
installed on the system. This is a particular problem when compiling from
source (to include your new module), without first removing any vendor-supplied
version of the agent (which won't include this new code).
Assuming that you have confirmed that the module code is present in the agent,
the next step is to check whether the initialisation routine is being called
to register the MIB objects. The simplest way to do this is to include a
suitable debugging statement within the initialisation routine, and start
the agent with the corresponding '-Dtoken'. Alternatively, try walking the
nsModuleName column object, and look for mention of the new MIB module.
Assuming the module has been registered, the next step is to check whether
the handler is being called, when the agent receives a suitable SNMP request.
Again, the simplest way to do this is to include debugging statements within
the handler routine, and start the agent with the corresponding '-Dtoken'.
Then issue an "snmpget" request for an instance within the new MIB module.
(This command is preferable to the usual "snmpwalk" command, as it is more
closely focused on the MIB module in question).
If this indicates that the handler routine isn't being called, then there are
two main likely causes. Firstly, check the access control settings. If these
are configured to block access to this portion of the OID tree, then the MIB
handler will never be called. Secondly, several of the table helpers are
designed to know which rows of the table are valid, and will call the main
MIB handler with information about the relevant row. If the requested row is
not valid (or the table is empty), then the handler will not be called.
Finally, if the handler _is_ being called, but is still not returning any
information, then the cause probably lies with your MIB module code. In which
case, it's really up to you to find the problem and fix it! Either activate
any debugging code that you have included within the handler routine, or run
the agent under a source code debugger, and step through the handler processing.
In either case, it's much easier to debug these problems when processing an
"snmpget" request, rather than "snmpgetnext" or "snmpwalk".
Remember that 'mib2c' simply generates template code for your MIB module.
It's up to you to fill in the details, to report the actual information from
whatever underlying subsystem is being monitored. Mib2c cannot help with
the semantics of the MIB module - it's purely there to provide an initial
code framework, based on the _syntax_ of the MIB module objects.
Why does the iterator call my get_{first,next} routines so often?
-----------------------------------------------------------------------
The first thing to realise is that the 'get_first' and 'get_next'
hook routines are concerned with processing a single SNMP request, not
with walking the whole table. A full "snmpwalk" command will typically
involve a series of individual 'GetNext' requests, and every one of
these will trigger a separate 'get_first/get_next/get_next/....' cycle.
It's usually more efficient to use 'snmptable' which will walk
each column in parallel (as well as displaying the results in a
more natural manner).
Secondly, the iterator helper was originally designed to handle
unsorted data, so will look at every row of the internal table for
each request. If the data is actually held in the correct order,
then it's worth setting the NETSNMP_ITERATOR_FLAG_SORTED flag:
iinfo = SNMP_MALLOC_TYPEDEF(netsnmp_iterator_info);
iinfo->flags |= NETSNMP_ITERATOR_FLAG_SORTED;
This will help the situation somewhat.
But the iterator helper is inherently a relatively inefficient
mechanism, and it may be worth looking at one of the other helpers,
particularly if the data will be held within the agent itself.
How can I get the agent to generate a trap (or inform)?
------------------------------------------------------
There are two aspects to having the agent generate a trap -
knowing *how* to do this, and knowing *when* to do so.
Actually generating a trap is reasonably simple - just call one
of the trap API routines ('send_easy_trap()' or 'send_v2trap()')
with the relevant information (generic and specific trap values,
or a varbind list respectively).
The 'mib2c.notify.conf' configuration file can be used to
construct a suitable template routine for generating a trap,
including building the variable list from the MIB trap
definition. These variables can then be given suitable values,
before invoking the 'send_v2trap()' call to actually send the trap.
See the 'snmp_trap_api(3)' man page for further details.
Note that these APIs are only available within the agent (or
subagents), and are not available to stand-alone applications.
The code for 'snmptrap' shows an approach to use in such a case.
Determining *when* to generate the trap (either directly or
via the mib2c-generated routine) is often harder. If the trap
is generated in response to some action within the agent, (e.g.
as the result of a SET), then this isn't too much of a problem.
But if the trap is intended to report on a change of status
(e.g. a network interface going up or down, or a disk filling up),
then actually detecting this is non-trivial. Unless the underlying
system can signal this situation to the agent, then it's typically
necessary to poll the value(s) on a regular basis, save the results
and compare them with the new values the next time round.
The simplest way to handle this is via the DisMan Event MIB,
which is designed for exactly this purpose. As long as you can
specify a MIB object to monitor, and the value or thresholds
that should trigger a notification, then this module can check
these values regularly, and automatically send a suitable trap
when appropriate. See the 'snmpd.conf(5)' man page (under
ACTIVE MONITORING) for details.
Otherwise, you'd need to use the routines documented in
'snmp_alarm(3)' to regularly invoke a monitoring routine. This
would check the necessary conditions (which need not be MIB
objects), and call the 'send_xxx_trap()' routine (as generated
by 'mib2c.notify.conf') when appropriate.
How can I get an AgentX sub-agent to generate a trap (or inform)?
----------------------------------------------------------------
This is done in exactly the same manner as with the main SNMP agent.
Calling one of the routines described in 'snmp_trap_api(3)' will cause
the AgentX sub-agent to send a notification to the master agent, which
will then pass this on to the configured trap destination(s).
One of the original design aims of the Net-SNMP AgentX support was that
the agent (or subagent) framework should be transparent to a MIB module
implementer. The interface between the agent framework and a MIB module
should be independent of the protocol used to receive the original request.
So the exact same MIB module code could be used within a traditional
SNMP-only agent, or an AgentX subagent, with no changes needed.
This also holds for sending traps.
How can I get the agent to send an SNMPv1 (or SNMPv2c) trap?
-----------------------------------------------------------
It doesn't make any difference whether you use the v1-style
API call 'send_easy_trap()' or the v2-style 'send_v2trap()'.
What matters is the directive(s) in the snmpd.conf file.
If this file contains 'trapsink', then the agent will send
an SNMPv1 trap. If this file contains 'trap2sink', then the
agent will send an SNMPv2c trap. And if this file contains
both, then the agent will send *two* copies of this trap.
See the entry
Where are these traps sent to?
in the AGENT section for details.
How can I get the agent to include varbinds with an SNMPv1 trap?
---------------------------------------------------------------
There are two ways to do this. You can either use the
'send_v2trap()' call and give a varbind list, starting with
the v2-equivalent of the SNMPv1 trap, followed by the
additional varbinds.
Alternatively, you can use the API call 'send_trap_vars()'
which takes the same generic/specific trap values as
'send_easy_trap()', plus the list of additional varbinds.
In either case, you also need to have 'trapsink' in the
snmpd.conf file. The resulting trap will be identical,
whichever approach is used.
How can I get the agent to send an SNMPv1 enterprise-specific trap?
------------------------------------------------------------------
There are two ways to do this. You can either use the
'send_v2trap()' call and give a varbind list, starting
with the v2-equivalent of the SNMPv1 trap, followed by the
additional varbinds.
Alternatively, you can use the (undocumented) API call
'send_enterprise_trap_vars()' which takes the same parameters
as 'send_trap_vars()', plus the enterprise OID to use (in the
usual name/length form). See the code file 'agent_trap.c'
In either case, you also need to have 'trapsink' in the
snmpd.conf file. The resulting trap will be identical,
whichever approach is used.
How can I get the agent to send an SNMPv3 trap (or inform)?
----------------------------------------------------------
It doesn't matter which API call you use to specify the
trap - 'send_easy_trap()', 'send_v2trap()' or one of the other
calls mentioned above. Generating an SNMPv3 notification
(rather than a community-based one) is controlled by the
snmpd.conf file.
To send an SNMPv3 trap, this file should contain a
'snmpsess' directive, specifying the version, security
level, user name and passphrases (if applicable), as
well as the destination address. This is basically
the same as the command line required for sending the
trap manually, using 'snmptrap'.
Note that (unlike 'snmptrap') this directive does *not*
read default settings from an 'snmp.conf' file, so these
must be specified explicitly in the 'snmpsess' line.
Why does calling 'send_v2trap' generate an SNMPv1 trap (or vice versa)?
----------------------------------------------------------------------
The two versions of the trap API calls are concerned with how
the trap is represented when it is passed *in* to the API, not
the version of the trap PDU that will actually be generated by
the agent. That is determined by the configuration token used
to set up the trap destination.
Remember that in general, all traps are sent to all destinations.
This means that a trap specified using the SNMPv1 trap syntax
needs to be converted to the SNMPv2 format before it can be sent
to an SNMPv2 (or SNMPv3) destination. Similarly, a trap specified
using the SNMPv2 syntax needs to be converted to the SNMPv1 format
before it can be sent to an SNMPv1 sink.
Essentially, the API call to use depends on what you asking for,
which is not necessarily what the recipients will actually get!
See 'snmp_trap_api(3)' for a fuller explanation.
How can I register a MIB module in a different (SNMPv3) context?
---------------------------------------------------------------
Contexts are a mechanism within SNMPv3 (and AgentX) whereby
an agent can support parallel versions of the same MIB objects,
referring to different underlying data sets. By default, a MIB
module registrations will use the default empty context of "".
But it's also possible to provide MIB information using a different
(non-default) context.
There are three aspects involved in doing this. Firsly, it's necessary
to register the MIB module in this non-default context. With the v4 API,
this uses the call 'register_mib_context()' rather than the REGISTER_MIB
macro. This is significantly more detailed, but most of the additional
parameters can take fixed values, if all that's needed is to change the
registration context.
Instead of the macro call:
REGISTER_MIB("my_token", my_variables, variable1, my_variables_oid);
use the function call:
register_mib_context( "my_token",
my_variables, sizeof(variable1),
sizeof(my_variables)/sizeof(variable1),
my_variables_oid,
sizeof(my_variables_oid)/sizeof(oid),
DEFAULT_MIB_PRIORITY, 0, 0, NULL,
"my_context", -1, 0);
Things are much easier with the v5 helper-based API. Having
created the registration structure, this just requires setting the
'contextName' field before actually registering the MIB module:
netsnmp_handler_registration *reg;
reg = netsnmp_create_handler_registration(.....);
reg->contextName = strdup("my_context");
netsnmp_register_handler(reg);
Secondly, it is necessary to configure the access control settings to allow
access to information in the new context. This is handled automatically
when using the simple "rouser" or "rwuser" directives. But if access control
is configured using the fuller com2sec/group/view/access mechanism, then the
"access" line must specify the appropriate context(s), either explicitly:
access {group} "my_context" any noauth exact ......
or using a single entry to cover all possible contexts:
access {group} "" any noauth prefix ......
Finally, the SNMP request used to retrieve (or update) the information
must also specify the required context. With SNMPv3 requests, the context
is part of the protocol, so this can be done using a command-line option:
snmpwalk -v 3 -n my_context .....
With community-based requests (SNMPv1 and SNMPv2c), things aren't so simple.
Although the "rocommunity" and "rwcommunity" settings also configure access
for all possible contexts, there's no way to specify a non-default context
as part of the request.
The only way to handle non-default contexts with community-based SNMP requests
is to set up a mapping from the community string to the desired context. This
uses the "com2sec" directive, with an additional "-Cn" parameter. Note that
this also means that the access control must be configured using the full
com2sec/group/view/access mechanism. The short-form access control directives
do not handle the mapping of community strings to non-default contexts.
MISC
======
What ASN.1 parser is used?
-------------------------
The parser used by both the agent and client programs is coded by hand.
This parser has recently been re-vamped to allow control of which of
the available MIBs should be included, and to handle duplicate object
subidentifiers.
The source code can be found in the snmplib directory (in 'parse.c'),
and the parser is usually bundled into the library 'libnetsnmp.a'
Note that the parser attempts to be fairly forgiving of some common
errors and incompatibilities in MIB files. The Net-SNMP tools accepting
a MIB file without complaint does *not* imply that the MIB is strictly
correct.
Certain MIBs may need some amendments to allow them to be read
correctly by the parser. Contact the coders' list for advice.
What is the Official Slogan of the net-snmp-coders list?
-------------------------------------------------------
"The current implementation is non-obvious and may need to be improved."
(with thanks to Rohit Dube)
And an alternate, added 26-Apr-2000:
"In theory, it shouldn't be that hard, but it just needs to be done."