Tryag File Manager
Home
-
Turbo Force
Current Path :
/
proc
/
self
/
root
/
usr
/
share
/
doc
/
net-snmp-5.3.2.2
/
Upload File :
New :
File
Dir
//proc/self/root/usr/share/doc/net-snmp-5.3.2.2/FAQ
Frequently Asked Questions (FAQ) for the UCD/Net-SNMP package ============================================================= FAQ Author: Dave Shield net-snmp Version: 5.3.2.2 SVN branch 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)? Where can I find more information about network management? 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 can't I see values in the <INSERT ENTERPRISE HERE> tree? Requests always seem to timeout, and don't give me anything back. Why? I can see the system group, but nothing else. Why? 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? I cannot set any variables in the MIB. Variables seem to disappear when I try to set them. Why? I still can't change sysLocation, though the access settings allow it. Why not? I get an error when trying to set a negative value - why? I get an error when trying to get a string-indexed table value - why? How do I send traps and notifications? How do I handle traps and notifications? My traphandler script doesn't work when run like this - why not? The ucdShutdown trap OID received by my manager is wrong. Why? Why does snmptrapd complain about AgentX? How do I use SNMPv3? 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? PERL 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? The perl 'make test' fails on the OID tests. Is it safe to continue? I'm trying to use mib2c (or tkmib) and it can't locate SNMP.pm? I'm trying to use mib2c (or tkmib) and it can't load SNMP.so? I'm trying to use tkmib and it can't locate Tk.pm? I'm trying to install your RPM, but it complains about missing perl modules. Why? I've got a problem with the Net-SNMP module. Can you help? MIBS Where can I find a MIB compiler? I can't load any of the mib files, and they seem to be missing the first two characters of the filename. What's happening? Why aren't my mib files being read in? I'm getting answers, but they're all numbers. Why? What does "Cannot find module (XXX-MIB)" mean? What about "unlinked OID"? The parser doesn't handle comments properly. Why not? How do I replace MIB values with new ones? How can I get more information about these MIB file problems? 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 add a MIB to the agent? How do I remove a MIB from the agent? I've installed a new MIB file. Why can't I query it? What's the difference between 'exec', 'sh' and 'pass'? What's the difference between AgentX, SMUX and proxied SNMP? What about 'dlmod' - what's that about? Which should I use? Can I use AgentX when running under Windows? Can I use AgentX (or an embedded SNMP agent) in a threaded application? 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? How do I configure access control? I don't understand the new access control stuff - what does it mean? How do I configure SNMPv3 users? The 'createUser' line disappears when I start the agent. Why? What's the difference between /var/ucd-snmp and /usr/local/share/snmp? My new agent is ignoring the old snmpd.conf file. Why? Why am I getting "Connection refused"? I'm getting errors about "bad security model" - why? I'm getting errors about "bad prefix match parameter" - why? 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? How about "Can't open /dev/kmem"? The agent is complaining about 'snmpd.conf'. Where is this? The system uptime (sysUpTime) returned is wrong! Can the agent run multi-threaded? COMPILING How do I compile with 'cc' instead of 'gcc'? But gcc doesn't compile it successfully on my new Solaris system. Why not? On RedHat 8.0 or up I get "/usr/bin/ld: cannot find -lelf". Why? What about '-lbz2' or '-lselinux' errors? What about a failed dependency on 'libcrypto'? Where can I get that? I'm getting an error "autoheader: not found" - what's wrong? How can I reduce the memory footprint? How can I reduce the installation footprint or speed up compilation? How can I compile the project to use static linking? Why is the project workspace empty under Visual C++? Why does 'make test' skip five 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? Mib2c complains about "configuration files". What's this for? 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? Where should I put the files produced by 'mib2c'? I've created a new module with 'mib2c' but it doesn't work. Why not? I've added my code to this template and it still doesn't work. Why not? Mib2c only handles a single table in my MIB. How can I fix this? Why does the iterator call my get_{first,next} routines so often? How can I support a large table, with more than 256 column objects? How can I get the 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)? What if I'm using an AgentX sub-agent instead? How can I register a MIB module in a different (SNMPv3) context? MISC Why are packets requesting the same information larger with UC-Davis SNMP? 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/ Are there binaries available? ---------------------------- - There are binaries for some systems available in the binaries directory on the ftp site. 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 is the last release line that uses the ucd-snmp name, and all releases under this banner will be bug-fixes only. Release 5.0 is the first version using the net-snmp name, and all new features and significant development will be released under this name. (Though the dividing line between a bug-fix and a new feature is something of a vague one, so some changes in the 4.2.x line may be relatively non-trivial!) Starting with the 5.0 release, we are also trying to review and rework the underlying code base to improve the readability and maintainability of the package. The 5.0 changes have mostly concentrated on the agent architecture, though there have been some significant changes to the library as well. Future releases may include further restructuring of the library. This process will probably result in some changes to the API, though we will attempt to retain some form of backwards compatibility as far as possible, and clearly mark anything that has changed. The most significant change with the 5.0 release is a restructuring of the header file organisation - not least a change from <ucd-snmp/xxx.h> to <net-snmp/yyy.h>. 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 (10.20 to 9.01 and 11.11 to 11.0 -- see README.hpux11) * Mac OS X (10.4 to 10.1) -- see README.osX * NetBSD (2.0 to 1.0) * FreeBSD (5.3 to 2.2) * OpenBSD (3.7, 2.8, 2.6) * BSDi (4.0.1 to 2.1) * AIX (5.2, 5.1, 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 people have reported problems with that we think we've fixed!) What happens if mine isn't listed? --------------------------------- It's probably worth trying to compile it anyway. If your system is reasonably similar to another supported configuration, it may well 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 the missing mibgroups 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 both 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' will 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. Some other MIB modules, including the UCD pass-through extensions, do not currently work under Windows. Volunteers to assist in 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). Major code revisions may be announced more widely (e.g. on the SNMP mailing lists, or comp.protocols.snmp) but this list is the most reliable way to keep in touch with the status of this 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 an net-snmp IRC channel set up on the freenode.net IRC chat servers (you can use irc.freenode.net to connect and/or see http://www.freenode.net/ for getting started with irc). Multiple core developers hang out there on a regular basis. How do I submit a patch or bug report? ------------------------------------- All bug reports should be submitted to 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 command that triggers the problem and a copy of the output it produces. 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. 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 Remember that this is basically an unsupported package. Fundamentally it's Open Source, so you have the source code. If you need something fixing badly enough, it's up to you to do the work. 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. 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 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 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 RFCs 1901-1908). This retained the same administrative framework as SNMPv1 (with all of the accompanying deficiencies), 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, Community-based SNMPv2 (i.e. RFCs 1901-1908), and SNMPv3 (i.e. 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 version of the syntax used to define a MIB file is better referred to as SMIv1 or SMIv2, and is purely concerned with defining the characteristics of the various management objects. This is (almost) completely unrelated to the versions of the protocol operations. 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 over them completely. Where can I find more information about network management? ---------------------------------------------------------- There are a number of sites with network management information on the World Wide Web. Three of the most useful are http://www.snmpweb.org/ http://www.snmplink.org/ http://www.mibdepot.com/ There are two Usenet newsgroups which are relevant. 'comp.dcom.net-management' which discusses general issues relating to network management 'comp.protocols.snmp' which is specifically concerned with use of SNMP in particular (though there is a large overlap between these two groups). The SNMP group also has an FAQ (split into two parts) which discusses more general issues related 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. Is Net-SNMP thread safe? ----------------------- Strictly speaking, no. However, it should be possible to use the library in a thread-safe manner. 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 applications and the agent have not been designed for 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. 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? ------------------------------- Firstly, cp MY-MIB.txt /usr/local/share/snmp/mibs or mkdir $HOME/.snmp mkdir $HOME/.snmp/mibs cp MY-MIB.txt $HOME/.snmp/mibs And then, export MIBS=+MY-MIB or alternatively: echo "mibs +MY-MIB" >> $HOME/.snmp/snmp.conf Note that you need *both* steps. The first command copies the file defining the new MIB to a expected location for MIB files. This defaults to /usr/local/share/snmp/mibs (or PREFIX/share/snmp/mibs if the the suite was installed into a different base location). Some ready-packaged distributions (such as Linux RPM packages) may look for MIB files in a different location, such as /etc/snmp/mibs - put the new file in this directory instead. This makes it available for everyone on the system. The tools will also look for mibs in your personal $HOME/.snmp/mibs directory, but this will only work for you. The second command tells the tools to load in this new MIB file as well as the default set. Note that the tools do *not* load every MIB found in the directory - this is to avoid slowing them down excessively when there is a large collection of MIB files. If you do want the tools to load all the MIB files, set the environmental variable MIBS to the special value "ALL". 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. Of course, if you load 'ALL' mibs, then this distinction is irrelevant. Most of the tools (apart from 'snmptable') will work quite happily without any MIB files at all, as long as you are prepared to work with numeric OIDs throughout. The MIB files are only used for translating between numeric and textual forms for queries and responses. The same holds true for the agent - see the AGENT section for details. Why can't I see anything from the agent? --------------------------------------- There are two main general causes of problems retrieving information from the agent. Firstly, the variable (or variables) specified may not be recognised by the tools as valid names. In this case, the tools will typically reject the request without ever contacting the remote agent. Alternatively, the tool may be happy with the request, but the agent does not return the corresponding value(s). It may return an explicit error message instead, or the request may time out without any response being sent back at all. The next few entries look at these in more detail. A simple way to tell which is the case would be to run the command with the command-line option '-d'. If this displays a dump of the packet, then the request is failing at the agent end. If not, then it's the client-side which is dropping the request. Why can't I see values in the <INSERT ENTERPRISE HERE> tree? ----------------------------------------------------------- Having said that there are two main reasons for not getting a response, the most likely cause of this problem is actually something else again. The 'snmpwalk' command takes a point in the overall MIB tree, and tries to display all the values that lie within this subtree. However, it actually does this by issuing a series of "getnext" requests, until the variable returned lies outside the subtree of interest. If the very first request returns such an undesired value, then the command will terminate, without having displayed anything at all. If an expicit starting point is given to 'snmpwalk', then it is reasonably clear what is happening, and that there is simply nothing in the subtree specified. However, if 'snmpwalk' is called without giving an explicit starting point, then it will display the contents of the 'mib-2' subtree. It will not attempt to traverse any 'private.enterprise' subtree, such as the UCD-specific objects (including any local extensions). To walk the whole tree, specify a starting point of '.iso' To walk a specific enterprise subtree, specify the root of this as the starting point - e.g: snmpwalk -v1 -c public localhost ucdavis Or, of course, you can walk a selected portion of an enterprise subtree by specifying the appropriate starting point - e.g: snmpwalk -v1 -c public localhost ucdavis.version If you still can't see any information, keep reading. The next few questions will probably help you. Requests always seem to timeout, and don't give me anything back. Why? ---------------------------------------------------------------------- There are a number of possible causes of this. The most likely are the agent access control settings (who is allowed access by the agent itself), or firewall/packet filtering settings (who is allowed access by the underlying operating system). A fuller list of possible causes (with indications of how to check for each) is as follows: - is the machine you are querying up and running? (Does it respond to 'ping' or similar requests?) - is there an SNMP agent running on it? (Run 'ps -ef | grep snmp' or 'netstat -an | grep 161') - are the requests arriving, or being blocked (e.g. by a firewall)? (Restart the agent using 'snmpd -f -Le -d' and see if it shows the incoming packet dumps) - is the agent simply taking a long time to respond? (The 'snmpd -f -Le -d' command should show a series of incoming PDUs, followed eventually by the outgoing PDUs. Try the request again with a long timeout value, e.g. 'snmpcmd -t 120 ....') - do the agent's control settings allow this request? (The 'snmpd -f -Le -d' command will show a series of incoming PDUs with *no* corresponding outgoing PDUs) If the agent is not configured to allow access for a particular community, then no error response will be returned. The Net-SNMP tools will retry the request a number of times, before reporting a timeout error. If the agent is configured to allow partial access for a given community, then requests that fall outside this authorised access *will* result in an error response. (SNMP agents can be very fussy over who they talk to!) See the entries on access control in the AGENT section for how to configure the Net-SNMP agent to allow suitable access. For other vendors' agents, you will need to consult the relevant documentation. 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 that ought to return the entry of interest. e.g. snmpgetnext -v1 -c public localhost ucdavis.version.versionTag instead of snmpget -v1 -c public localhost ucdavis.version.versionTag.0 If the agent responds with "end of MIB" or a different object, then either the agent doesn't implement that particular object at all, or the access control won't allow you access to it. See the entries on access control in the AGENT section for how to configure the Net-SNMP agent, or consult the agent's own documentation. The agent worked for a while, then stopped responding. Why? ----------------------------------------------------------- Assuming that the agent hasn't crashed completely, the most likely explanation is that it's simply overloaded, and is taking longer to respond than the querying tool is waiting. Since the agent handles each request in turn, without regard to earlier activity, and most tools will retry a request when it times out, the list of outstanding requests can grow longer and longer. To determine whether this is the cause, try leaving the agent undisturbed for a while, and then probe it using a single 'snmpget' or 'snmpgetnext' request, specifying a longer timeout (e.g. '-t 120'). This should give the agent time to handle the request first time round, and avoids overloading it with duplicate requests. This is not a full solution, of course, but at least it should allow you to isolate the offending portion of the tree. The developers may then be able to offer a more long-term solution. Requesting an object fails with "Unknown Object Identifier" Why? ---------------------------------------------------------------- If a general snmpwalk shows the 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. Secondly, 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 (though if snmpwalk displays the object by name, this is unlikely to be the cause). Thirdly, earlier versions of the UCD software expected "full" paths for object names, either based at the root of the whole MIB tree (".iso.org.dod.internet.mgmt.mib-2.system.sysUpTime") or the 'mib-2' subtree ("system.sysUpTime"). Try: snmpget -v1 -c public myhost system.sysUpTime.0 These earlier versions of the tools may take a command-line option '-R' or '-IR' (depending on vintage) to invoke this "random-access" mode. Note that snmptranslate still requires "random-access" to be specified explicitly - all other command tools now use this mode by defaults. All versions of the UCD and Net-SNMP tools accept the syntax snmpget -v1 -c public myhost RFC1213-MIB:sysUpTime.0 to denote a particular object in a specific MIB module. Note that this uses the name of the *module*, not the name of the file. See the second question in this section for the distinction. Why do I get "noSuchName" when asking for "sysUpTime" (or similar)? ------------------------------------------------------------------ There are a number of possible causes of this (scattered throughout this FAQ, so keep reading!). But one of the most likely snares for the unwary is forgetting the instance subidentifier for 'non-table' objects. If you walk the 'system' tree, you'll notice that all the results (apart from the sysORTable), have a '.0' at the end of the OID. This is the "instance sub-identifier" - which *must* be included for 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 what you're asking for. Recall 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. I cannot set any variables in the MIB. ------------------------------------- There are three possible reasons for this: The majority of MIB objects are defined as "read-only" and inherently cannot be changed via SET requests. Of those that can in principle be changed, not all have been implemented as such in this agent. Even if SET support has been implemented, the agent may not be configured to allow write access to this object. The example configuration file shipped with the basic distribution only allows write access for the local host itself (and a suitable community name must be configured first). 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 system.sysLocation.0 system.sysLocation.0 = somewhere nearby $ snmpset -v1 -c public localhost system.sysLocation.0 s "right here" Error in packet. Reason: (noSuchName) There is no such variable name in this MIB. This name doesn't exist: system.sysLocation.0 Trying the same request using SNMPv2 or above is somewhat more informative: $ snmpset -v 2c -c public localhost system.sysLocation.0 s "right here" Error in packet. Reason: notWritable The SNMPv1 error 'noSuchName' actually means: "You can't do that to this variable" This might be because the variable doesn't exist, it does exist but you don't have access to it (but someone else may do), or it exists but you can't perform that particular operation (i.e. 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 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. I still can't change sysLocation, though the access settings allow it. Why not? ------------------------------------------------------------------------------- One other possibility for the 'sysLocation' and 'sysContact' objects, is that you've got a configuration option in the 'snmpd.conf' file which already sets the corresponding value there. Earlier versions of the agent would allow you to write to these objects, but the new value would be forgotten the next time the agent was re-started. More recent versions of the agent reject such write requests if there's a value set via the config file. If there isn't such a config setting, then the write request will succeed (assuming the access settings allow it), 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 probably aren't valid command line option). 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 will also fail, since -1 isn't an acceptable value for this object, but it will be rejected by the agent, rather than confusing the snmpset command!) I get an error when trying to get a string-indexed table value - why? -------------------------------------------------------------------- This is probably due to the shell swallowing the quotes, before they ever get to the SNMP command's OID parser. Try escaping them: snmpget ..... vacmSecurityModel.0.\"wes\" or snmpget ..... 'vacmSecurityModel.0."wes"' How do I send traps and notifications? --------------------------------------- Traps and notifications can be sent using the command 'snmptrap'. The following examples generate the generic trap 'coldStart' and a (dummy) enterprise specific trap '99' respectively: snmptrap -v 1 -c public localhost "" "" 0 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). 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 is covered in the AGENT and CODING sections. You should also read the snmptrap tutorial at http://www.net-snmp.org/tutorial-5/commands/snmptrap.html which will help you understand everything you need to know about traps. How do I handle traps and notifications? --------------------------------------- Handling received traps is done using the tool 'snmptrapd'. This can log these traps via the syslog mechanism: snmptrapd -Ls 7 (log to 'LOCAL7') printed to standard output snmptrapd -f -Lo or pass them to an external command. This last approach uses a 'traphandle' directive in the configuration file 'snmptrapd.conf'. A typical file might look something like: traphandle .1.3.6.1.6.3.1.5.1 page_me up traphandle .1.3.6.1.4.1.2021.251.1 page_me up traphandle .1.3.6.1.4.1.2021.251.2 page_me down traphandle default log_it where 'page_me' and 'log_it' are the command to be run. (You probably need to specify full pathnames, to ensure that the commands will be found. They're just short here for readability). Note that the first entry uses the OID corresponding to the SNMPv1 'coldStart' trap. See the co-existence RFC (RFC 2576) for details of mapping SNMPv1 traps to SNMPv2 OIDs. Starting with net-snmp 5.3, snmptrapd will no longer accept all traps by default. 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. There's a tutorial with more details on the web site at http://www.net-snmp.org/tutorial-5/commands/snmptrap.html 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 generates an error when triggered by an incoming notification, then this is probably down to one of 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 Note that in this case, it's almost certain that you'll also need to give the full path to the traphandle script (as shown) The ucdShutdown trap OID received by my manager is wrong. Why? ------------------------------------------------------------- This is due to the way that traps are converted between SNMPv1 and SNMPv2 formats. The algorithm used for converting from an SNMPv1 enterprise-specific trap number, to an SNMPv2 trap OID results in a penultimate '0' subidentifier, before the trap number itself. The definition of the trap objects in the UCD-SNMP-MIB file does not include this subidentifier. In due course, the intention is to define a new set of MIB objects, under the 'net-snmp' enterprise tree. This will include new trap OIDs, which will be designed such that this problem does not arise in the future. Why does snmptrapd complain about AgentX? ---------------------------------------- Starting from the v5 release, the trap handling daemon has implemented the notification logging aspects of the NOTIFICATION-MIB (RFC 3014). This is handled by the trap handler daemon registering as an AgentX subagent, to supply this statistical information. If there is no AgentX master agent available, this registration fails, generating the warning about "failed to connect to the agentx master". This warning only appears between version 5.0 and 5.0.4 (in 5.0.4 and after the warning was silenced). This failure does not affect the main operation of the trap handler. It simply means that the nsmLog information won't be available for query via SNMP. Basically, this is a warning that can safely be ignored. How do I use SNMPv3? ------------------- The simplest form of SNMPv3 request (unauthenticated, unencrypted) would be something like: snmpget -v 3 -l noAuthNoPriv localhost sysUpTime.0 An authenticated request would specify a username and pass phrase: snmpget -v 3 -l authNoPriv -u dave -A "Open the Door" localhost sysUpTime.0 A fully secure request 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 setting defPassphrase "Open the Door and see me" instead. See the AGENT section for how to configure the agent to respond to SNMPv3 requests. 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 uses a fixed size buffer of 1472 bytes to hold the encoded packet, so all requests and responses must fit within this. Unfortunately, it's not possible to predict how many varbinds this corresponds to, since it depends on the type and actual values being sent, as well as the corresponding OIDs. As a rule of thumb, sending 400 integer-valued varbinds seems to work OK, while 300 string-valued varbinds triggers an overrun. 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 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? -------------------------------------------------------------------------- The example 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. Note that there is no example snmp.conf shipped with the standard distribution. 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 include the SNMPv3 settings mentioned above, defaults for which MIBs to load and where from, and the default SNMP version, port and (if appropriate) the community string to use. Some of these (such as the MIB file location), might belong 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 go in a personal snmp.conf file (typically $HOME/.snmp/snmp.conf). Note that the Net-SNMP package does not come with an example snmp.conf file. 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). PERL ==== Where can I get the perl SNMP package? ------------------------------------- Joe Marzot's excellent perl SNMP module, which requires the ucd-snmp library, is now included in the ucd-snmp source release. It's located in the perl/SNMP subdirectory of the ucd-snmp source tree. It can also be found at any Comprehensive Perl Archive Network (CPAN) site mirror in modules/by-module/SNMP. To find the CPAN site nearest you, please see http://www.cpan.org/SITES.html. With the v5 release of the Net-SNMP suite, this is now accompanied by a number of perl modules grouped together under the NetSNMP namespace. Consult the README file in the SNMP perl module distribution to find out what version of the ucd-snmp library it needs to be linked against. 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 (for 5.0.x) or cd perl/SNMP (for 4.2.x) perl Makefile.PL (press RETURN when prompted for host and community) make make test make install (probably as root) Note that with the 5.0 release line, there are additional SNMP-related perl modules that should probably be installed as well. These can also be found under the 'perl' subdirectory. At the very least, install the 'default_store' module. This is not necessary with the 4.2.x releases. 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 the main Net-SNMP distribution, the appropriate version of the perl module is shipped as part of this, 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. The perl 'make test' fails on the OID tests. Is it safe to continue? ------------------------------------------------------------------- No. Almost certainly not. If the "perl/OID" tests fail the first four tests, and then crashes out complaining about a "netsnmp_oidPtr", then this is a sign of a more fundamental problem. The 4.2.x line perl support was a single module, so was independent of the way that the C library was configured. In contrast to this, the 5.0.x perl support consist of a number of inter-cooperating modules, which rely on sharing a consistent C library environment. In practise, this means that the perl modules *MUST* be configured and compiled using a shared version of the C library. Unfortunately, the default for most early versions of the Net-SNMP suite was to compile using static libraries unless explicitly configured to use shared libraries. The default should be to use shared libraries from 5.0.7 onwards. The error "oid1 is not of type netsnmp_oidPtr" is a fairly sure indication that the C library was compiled statically. You'll need to re-configure the main Net-SNMP package using the "--enable-shared" configure flag. Then re-install the C library before re-configuring and re-compiling the perl module support. Note that this problem does not arise when using the 4.2.x version of perl support. I'm trying to use mib2c (or tkmib) and it can't 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 installed by default in RedHat Linux (for example). You'll need to install it. See the previous two questions. I'm trying to use mib2c (or tkmib) and it can't 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 two questions. I'm trying to use tkmib and it can't 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" I'm trying to install your RPM, but it complains about missing perl modules. Why? -------------------------------------------------------------------------------- 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. This functionality is mostly integrated within the MIB parser (part of the Net-SNMP library) 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. The second type of tool 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. I can't load any of the mib files, and they seem to be missing the first two characters of the filename. What's happening? ----------------------------------------------------------- This is a problem experienced with Sun systems when the tools have been compiled with a mixture of BSD and Solaris environments. You'll need to re-configure and compile the tools, making sure that '/usr/ucb' is not in your PATH (or at least comes at the end). Why aren't my mib files being read in? ------------------------------------- The Net-SNMP library only loads a subset of MIB files by default. This list is set at 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). You can override this by using the command-line option '-m', the environmental variable 'MIBS' or the snmp.conf directive 'mibs'. Each of these take a (colon-separated) list of MIB module names to load. Starting the list with a '+' character will add them to the default list - otherwise it replaces the defaults. Using the special value 'ALL' will load all the MIB files that the library can find. Alternatively, the tools may be looking in the wrong place. The default location for the mib files is /usr/local/share/snmp/mibs. Again, this is set when the suite is first configured and compiled. This can be changed using the environmental variable 'MIBDIRS' or the snmp.conf directive 'mibdirs'. Note that this may very well affect you if you've installed a new version of the suite manually, replacing one provided by the supplier (which typically would use a more 'central' location). Finally, are you sure that you've installed the MIB files? If you've compiled the suite from scratch, you need to run "make install" at least once, before the tools will be able to find the MIB files. This is unlikely to be a problem if you've been working with the tools for a while, but can bite those coming fresh to the SNMP world. I'm getting answers, but they're all numbers. Why? ------------------------------------------------- This is actually the same as the previous question. Because the tools don't read in every MIB module they can find, 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 tools will report the answer quite correctly, but won't translate identifiers and enumerations into readable strings. To fix this, use the environmental variables MIBS or MIBFILES (or the '-m' and '-M' flags) to read in the relevant module files. What does "Cannot find module (XXX-MIB)" mean? --------------------------------------------- This is similar to the previous questions. In this case, it's stating that it can't find the specified module - either because it's not installed properly, or the name used is subtly wrong. If it's just one or two modules that are not being found, check that the files are in the expected location, are readable, and the name being used is correct. Note that the name reported is the name of the MIB module, which is not necessarily the same as the name of the file. See the question 'How do I add a MIB to the tools?' for more details on this. If the tool is generating a whole slew of errors, then it's likely that either the MIB files haven't been installed at all, or the library is looking in the wrong place. See the previous two questions. What about "unlinked OID"? ------------------------- 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 most likely reason is that the line in question contains two (or more) sequences of pairs of dashes. This is often used to try and "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 assumption 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 is treated as part of the MIB, and will generate an error. A similar effect can be obtained when a line of dashes has been used to try and mark separate parts of a MIB file. Most of the 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 do I replace MIB values with new ones? ----------------------------------------- The Net-SNMP parser generally takes the first definition it sees for each object in the MIB hierarchy. Even if you specify your file to be read first, if the IMPORTS clauses reference a MIB with competing objects, those objects will be parsed first. When specifying the Replace MIB command-line option (-PR), the parser will use definitions sourced from the most recent MIB file. The parser will replace MIB objects when the sub-identifier and name match. Caution: Using Replace MIB, there is NO guarantee that the resulting MIB tree will be correct. Other MIB objects matching the name but not the sub-identifier will persist. Sub-hierarchies may be reparented. In particular, random access searching [see man 1 snmpcmd] may give unexpected result. The Replace MIB option is experimental, buyer beware, carpe diem, etc. Here are a few considerations to help you obtain good results. These hold true even if you never use the Replace MIB feature. Your suggestions for improvement are welcomed. 1. The parser searches the specified directories and attempt to parse every file whose path does not begin with "." (period). Remove (or rename) older MIB files from these directories. Rename "README" to ".README" , etc. 2. Hint: the parser's module list is in LIFO order. You may see better results if the directory with the most correct MIB files is specified last in the MIBDIRS environment. 3. Constrain the parser to not read in default MIB files by setting the MIBS environmental variable to the appropriate separator character (semi-colon on win32, colon everywhere else). Setting this to "" may also have the same effect. 4. The MIBFILES environment can specify the path of the new MIB file. Within a program, the call: /* 4.2.x */ ds_set_boolean(DS_LIBRARY_ID, DS_LIB_MIB_REPLACE, 1 | 0); or, if using the 5.0.x series code: /* 5.0.x */ netsnmp_ds_set_boolean(NETSNMP_DS_LIBRARY_ID, NETSNMP_DS_LIB_MIB_REPLACE, 1 | 0); will enable or disable the Replace MIB feature respectively. If you're having problems loading a particular MIB file, this call can be used to disable this feature, before using read_mib() to load the required file, and then re-enabling the Replace MIB feature. (or vice versa, as appropriate). How can I get more information about these MIB file problems? ------------------------------------------------------------ The command 'snmptranslate' is used to translate between numeric and symbolic forms of OIDs. It uses the same routines as the 'active' commands, but does not rely on communicating successfully with a network management agent. 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 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 implements 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 ends in a semicolon, before going on to the main definition section. 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. 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) - Host Resources (RFC 1514 and 2790) - SNMPv3 MIBS (RFCs 2571-5, 3411-3418) (including USM, VACM, Target and Notification MIBs) - DisMan Event MIB - DisMan Schedule MIB - MTA-MIB (sendmail) - private agent extensions (monitor specified processes and disks, memory, CPU, load average, plus extend the agent using shell commands) See README.agent-mibs for details. The Host Resources MIB, the DisMan MIBs and the MTA MIB are not included by default, and need to be explicitly requested when the suite is first configured and built. Starting with net-snmp 5.3, the DisMan Event MIB is included by default on all platforms, and the Host Resources MIB is included by default on the major supported platforms. 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 a SMUX (RFC 1227) master agent, AgentX (RFC 2257 ) in both master and subagent roles, and SNMP proxying. How do I configure the agent? ---------------------------- That depends on what you want it to do. See the snmpd.conf(5) manual page for the possibilities. You can also run the "snmpconf" perl script to help you create this file. Start off with 'snmpconf -g basic_setup' to get you going. How do I add a MIB to the agent? ------------------------------- How do I add functionality? -------------------------- While simply adding a file to the MIB directory (and possibly tweaking the list of MIBs to load) is sufficient for the tools, unfortunately extending the functionality of the agent to include this is not so simple. In fact, the agent makes little or no use of these files, and will work quite happily without them. All the information about the syntax and scope of the variables supported is hardwired into the implementation of the agent. There are a number of alternative ways to add functionality for a new MIB to the agent. Firstly, it is possible that the agent distribution already includes the desired functionality, but this has simply not been configured in to the running version. This is done using the configure option --with-mib-modules="list" (where "list" is a space-separated list of modules to include) then recompiling the agent. Note that some functionality concerned with monitoring and managing unix hosts is included in the UCD extension modules, which are located within the 'private' branch of the MIB tree. This is covered in a later question in this FAQ. Secondly, it is possible for the agent to run commands or shell scripts in response to queries. These can obtain and report the necessary information, or perform actions as required. Detailed information and examples are provided in the snmpd(8) and snmpd.conf(5) manual pages, and the EXAMPLE.conf file. This is known as "pass-through" support. Thirdly, it may be possible to link another agent (which already supports the desired MIB), as a "subagent" of the Net-SNMP master (or vice versa). The possibilities here are SMUX, AgentX or proxied SNMP (see the next question but one). Finally, the agent itself can be extended to support additional MIB groups, by writing the necessary C code, and including this within the main agent - either statically compiled in, or dynamically loaded. This is covered further in the next section. Note that there is no visible difference between 'pass-through' MIB support, subagents, and modules implemented within the main agent itself. Tools querying the agent will see a single MIB structure. 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 textual names instead of raw OIDs in the config files. There are three options to prevent the agent returning information from a particular MIB: 1) re-run configure to exclude the given MIB module, rebuild, and reinstall: ./configure --with-out-mib-module=host .... make make install 2) use access control to exclude the mib from the view used to query the agent: com2sec public default public group public v1 public group public v2c public view ourmib included system view ourmib included printmib view ourmib excluded host view ourmib included privatemib access public "" any noauth exact ourmib none none 3) disable the MIB at runtime First you need to figure out which MIB modules are being loaded by getting the agent to report them as they are initialised: snmpd -Dmib_init -H Then turn off the ones you don't want: snmpd -I -hr_system,hr_storage,hr_device,hr_other,.... I've installed a new MIB file. Why can't I query it? ---------------------------------------------------- Unfortunately, simply installing the MIB file isn't enough for the agent to automatically provide the corresponding information. This typically requires writing some code. See the section CODING, and the on-line documentation. It may sometimes be possible to achieve the same effect using the various extension directives, but this typically still involves providing a suitable script or command. The agent isn't magic and doesn't know how to locate the MIB information. Somebody has to tell it. What's the difference between 'exec', 'sh' and 'pass'? ----------------------------------------------------- 'exec' will fork off the specified command and return the exit status and/or the output. Arguments are passed directly to the command. '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. Neither of these mechanisms require the command to have any knowledge of 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 with the 4.2.x and 5.0.x lines, return values are cached within the agent for 30 seconds, rather than invoking the command for every request. This does not hold for the 5.1.x agent. 'pass' is a more general mechanism for extending the agent, and the command given will be invoked for any request within the specific MIB subtree. Details of precisely how this command will be called in various circumstances is given in the 'snmpd.conf(5)' man page. 'pass-persist' is similar, but the command will continue running even once the initial request has been answered. See 'snmpd.conf(5)' for more details. 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. The main issue to be aware of is that such requests will usually 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 the SMUX protocol has essentially been superceded by AgentX, but is still provided in order to support existing SMUX subagents. However the core developers have little experience (and even less interest!) in this code, so assistance with SMUX-related problems is likely to be somewhat limited. 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. Note that support for SMUX is not configured in by default. You will need to run configure with the option --with-mib-modules=smux Starting from release 4.2.1, AgentX support is now 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. Note that there are a number of known problems with the AgentX support in the 4.x line, and this should not be used on production systems. The 5.0 AgentX support has been significantly improved, and production use is less foolhardy. See README.agentx for details. What about 'dlmod' - what's that about? -------------------------------------- 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 should I use? ------------------ That's a difficult question. Comparing the three protocols, SNMP was not originally designed as an internal subagent-communication protocol, and there are certain architectural limitations to SMUX, which were addressed as part of the design of AgentX. These include such aspects as reliable handling of SET requests (particularly in the face of failures), a common value for sysUpTime, and a mechanism for sharing tables across multiple subagents. So from a purely functional point of view, AgentX is the most appropriate choice for subagent communication. In terms of implementation, SMUX is the most mature of the three, but is no longer being actively maintained. The original author has moved on, and the current developers don't use this facility. It also only includes master agent support - the package does not provide a SMUX sub-agent API. The AgentX support in the 4.x line has a number of known problems, and is not suitable for use in front-line situations (though it's probably sufficiently stable and functional for simple day-to-day use). The 5.0 agent has seen a significant amount of development, and is a much more reliable beast. Bear in mind that the AgentX and proxy SNMP implementations are relatively new code, so have not received the same level of active service that the core agent has. But with that caveat, either of these options should be suitable for most use. This decision will probably be dictated by external considerations (i.e. the other agents you need to combine with). Ideally, you should be looking towards AgentX, but this is not always possible. Dynamically loaded modules serve a somewhat different purpose, and are purely concerned with how the individual MIB implementation modules are located. These can be combined with either a "pure SNMP" model, an AgentX subagent or a proxied SNMP agent. They will involve a slightly greater load on agent start-up (plus an extra level of complexity if things go wrong) - balanced against the ability to avoid re-compiling and re-linking a working binary. Note that as far as individual MIB modules are concerned, the protocol used to transport the request is more or less irrelevant. The same information is being requested (or set) each time, so a MIB module ought to be protocol-independent. This was one of the design aims of the AgentX support, and the exact same module code can be included as part of a pure-SNMP master agent, or an AgentX subagent, either compiled in or dynamically loaded with no modifications needed to the MIB module code itself. 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. 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. 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 sides accordingly. For the Net-SNMP master agent, this is done using the command-line option '-x'. The command "snmpd -x localhost:705 ...." would start the agent listening on the TCP port 705 for connections from the local system. Or the same effect can be obtained by adding the line agentxsocket localhost:705 to the file snmpd.conf The main Net-SNMP agent can also be run in a "subagent" mode, and this uses the same command-line option to specify a different AgentX socket. So "snmpd -X -x localhost:705 ...." would start it as a subagent, and connect to the master agent listening on TCP port 705 on the same system. A subagent running embedded within some other application will typically not understand the same command-line options. This will need to set the same configuration programmatically. For example, the example subagent driving code from the Net-SNMP "subagent program" tutorial (on the project web pages) could be made to connect to the same TCP port by adding the line netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID, NETSNMP_DS_AGENT_X_SOCKET, "localhost:705"); before the 'init_agent' call. The same approach can also be used to listen on a different named socket, using: agentxsocket /tmp/agentx agentxperms 777 777 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. But also see the mention of AgentX security (or the lack of it!) in the previous entry. How can I turn off SMUX support? ------------------------------- Unfortunately, it's not currently possible to disable the SMUX initialisation using '-I'. If it's not possible to recompile from source (having reconfigured without SMUX), the simplest way to disable this functionality is to get the agent to bind to an invalid IP address. If you put a line such as smuxsocket 1.0.0.0 in the snmpd.conf file, the agent will whinge at startup, but 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? ----------------------------------------------------------------------- With the 4.x line agent, you can't. Sorry about that. With the 5.0 agent, this is possible by using the SNMPv3 context string to distinguish between parallel MIB trees. This can be set up for an individual MIB implementation module when it registers itself with the main agent framework (either directly, or via AgentX). It can also be set up for a proxied subagent as part of the proxy configuration entry (see 'snmpd.conf(5)'). This facility is not currently available for SNMPv1 or SNMPv2c requests (although it ought to be possible to use the community string in a similar way). 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 agent sends a 'coldStart(0)' trap when it first starts up, and an enterprise-specific trap 'nsNotifyShutdown' (or 'ucdShutdown') when it stops. It can also be configured to send an 'authenticationFailure(4)' trap when it receives an SNMPv1 request using an unknown community name. The Net-SNMP agent 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. The agent does not send 'linkUp' or 'linkDown' traps by default. The Net-SNMP agent can be configured to do this using the 'monitor' config directive. See the 'snmpd.conf(5)' man page (under DISMAN-EVENT-MIB) for details (including the need for an 'agentSecName' setting). 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' config directive (also documented under DISMAN-EVENT-MIB). Note that these facilities are only available with the v5 Net-SNMP agent, and are not supported by the v4 UCD agent. Where are these traps sent to? ----------------------------- With all these alerts, the agent also needs to be configured with (one or more) destinations to send them to, 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 these directives control the type of notification that is generated. This is completely separate from the style of API used to request that the notification should be sent. If a module invokes the v1-style API 'send_easy_trap', this will still send SNMPv2 notifications to destinations configured using 'trap2sink' or 'informsink' (and vice versa). A configuration block such as trapsink localhost trap2sink localhost informsink localhost will result in *three* notifications being sent for each call to 'send_easy_trap' (or 'send_v2trap'). See 'snmp_trap_api(3)' for details. Note that all notifications will be sent to all destinations. The agent does not (currently) support notification filtering. How can I send a particular trap to selected destinations? ---------------------------------------------------------- With the v4 UCD agent, this isn't possible (or at least not easily). When you request the agent to generate a trap (using either 'send_v2trap' or 'send_easy_trap'), this will be sent to *all* the known destinations. The v5 Net-SNMP agent introduced preliminary support for the snmpNotifyFilterTable which is designed to allow this sort of selective trap direction, though this is not currently active. (The tables are present, but the information is not consulted) Documentation on how to use this facility 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 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 '-L' (or '-Le') flag, to log messages to stdout. 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 known example of this is the 'ucd-snmp' RPM distributed by RedHat. This agent crashes if there is a 'disk' configuration entry in the snmpd.conf file. It is not currently known what causes this, as this setting works correctly if the agent is compiled from source. Another 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 most commonly seen when performing an "snmpwalk" on an agent that's either using a default "vendor provided" configuration (typically access to the 'system' group only), or which is trying to restrict access for individual users or communities to a subset of the whole OID tree. The agent implementation of "GetNext" processing is relatively inefficient when dealing with inaccessible objects, and it is quite easy for the clients to time-out and retry a request, while the agent is still trying to process the original. If this happens continually (as is typically the case with an snmpwalk), the agent can get swamped by this backlog. The 5.0.x line has now addressed this, starting with the 5.0.7 release. The 4.2.x line still suffers from this problem, and it is unlikely that this will be fixed. (The 5.0.7 approach relies on some of the new features in the 5.0.x line, and it has not proved possible to apply this to the 4.2.x code base). 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 answer to " I cannot 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. 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 request received from any of them. With version 4.2, the '-p' option can be used to listen on individual interfaces. For example, snmpd -p 161@127.0.0.1 will listen (on the standard port) on the loopback interface only, and snmpd -p 6161@10.0.0.1 will listen on port 6161, on the (internal network) interface with address 10.0.0.1. If you want to listen on multiple interfaces (but not all), then simply repeat this option for each one: snmpd -p 161@127.0.0.1 -p 6161@10.0.0.1 The v5 Net-SNMP agent has a similar facility, but does not use the '-p' command line option flag. Instead, the ports and/or interfaces to listen on are simply listed on the command line, following any other options. Also, the syntax of port and interface is slightly different (interface:port). So the three examples above would be snmpd 127.0.0.1:161 snmpd 127.0.0.1:6161 snmpd 127.0.0.1:161 127.0.0.1:6161 The AgentX port option ('-x') works in much the same way, using the "host:port" syntax (in both 4.2 and 5.0 lines - and yes, this *is* an inconsistency in 4.2!) 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 it is *not* necessary (and not advisible) to specify the same community name for both rocommunity and rwcommunity directives. The rwcommunity setting automatically includes rocommunity access, and having both lines (with the same community name) may result in apparently inconsistent behaviour. Only use both settings when specifying *different* community names. The same holds true for rouser and rwuser. All four of these settings can can also be restricted to particular subtrees, and/or request sources. See 'snmpd.conf(5)' for details. These directives are effectively wrappers round the core access control mechanism, which uses the four directives 'com2sec', 'group', 'view' and 'access' to provide a more efficient and flexible control over who can access which portions of the tree. See the next question for the gory details, and the entry after that for setting up SNMPv3 users. I don't understand the new access control stuff - what does it mean? ------------------------------------------------------------------- The idea behind the new access control model is to give a more flexible way of specifying who can see and do what within the MIB tree. It's more complicated to understand than the simple example above, but that's because it can do a whole lot more. There are four configuration keywords in the new scheme: 'com2sec', 'group', 'view', and 'access' We'll consider these one at a time, starting with 'access'. (Because I feel like starting with the last one, that's why - OK?) The "access" keyword has the job of specifying who has access to which bits of the MIB tree. This has eight parameters, so can look rather offputting. Most of these can be safely left with default values in most cases (so don't you worry your pretty little head about them). The syntax is access {group} "" any noauth exact {read-tree} {write-tree} {notify-tree} where the entries in braces need to be defined elsewhere (I'm coming to that - be patient!), and the rest can be left as shown here. [ If you really want to know, the 'sec.model' field can be used to have an access line that's only relevant to particular versions of SNMP (such v1 or v2c) rather than "any" version, and the 'sec.level' field to ensure that the request must be authenticated or encrypted. The context and prefix fields can be used to distinguish between parallel versions of the same overall OID tree ] The "view" keyword is used to define particular bits of the MIB tree, for use in the last three field of the access entry. This has the syntax view {name} included/excluded {subtree} {mask} where {name} is the identifier to be used for this view (i.e. what should appear in the access entry), and {subtree} is the portion of the MIB tree that this name refers to (in either numeric or named form). Note that the name of the view does not have to have anything to do with the MIB sub-identifier names - it's purely an identifying tag for use within the config file (though choosing a meaningful name is, as always, a very good idea). The {mask} field can be used to control which elements of the OID subtree should be regarded as relevant when determining which view an OID is in. Normally, the whole of the OID should be included, and in this case the mask field can be omitted. See snmpd.conf for a description of how this might be used. The third field can be used to include or exclude particular portions of the MIB from the view, and different lines can use the same view name to build up a more complicated view, if that's what's needed. The three view fields in the access line are used to control which portions of the MIB tree a particular {group} can see (GET et al), alter (SET), or request NOTIFYs on. That's dealt with the "what" - now for the "who". This is the role of the "group" and "com2sec" entries. The "group" keyword gives general control, by mapping between a "security name" (for a particular protocol version), and the internal name used in the access line. Note that the token "any" is no longer acceptable for the security model - the original support for this was due due to a misreading of the RFC. You should replace any such line with separate versions for each of the desired security models ('v1', 'v2c' & 'usm'). For SNMPv1 and SNMPv2c, the group line is just an intermediate step between the "access" line and the "com2sec" line, which is the last bit of the jigsaw. The "com2sec" entry is used to determine a "security name" from the traditional community string, taking into account where the request has come from. Thus the same community string can give access to different portions of the tree, depending on where the request is sent from. For example, in an earlier version of the example config file, there were two com2sec lines with the community string "public" - one was valid from anywhere (with the security name "public") and one was only valid from the local network (using the security name "mynet"). The group lines converted these security names into the groups "public" and "mygroup" respectively, and the access lines gave these two groups the ability to GET values in the 'system' sub-tree (from anywhere) or the 'mib-2' sub-tree (from the local network). Neither of these could SET any values though, (since the write-tree was "none" in both cases). Someone on the local machine, using the community string "private", had the security name "local" and the group name "local", and hence had full access (both GET and SET, as well as NOTIFY) to the whole of the MIB tree (or at least everything under .1, which covers most things!) Note that the three occurrences of "public", as community string, security name and group name, were three totally separate things. You can't use a community string in a security name field, or either of these as a group name (or vice versa), unless you set up suitable entries to map one name onto the other. With SNMPv3, the security name is part of the basic protocol, and can be used directly in a group definition. And here concludes our tour of the view-based access control mechanism. Phew! How do I configure SNMPv3 users? ------------------------------- There are three ways to configure SNMPv3 users: 1) Stop the agent, and create a file /var/ucd-snmp/snmpd.conf, containing the line createUser {myUser} MD5 {myPassword} DES (where {myUser} and {myPassword} are the appropriate values, _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 instructions. This will create an entry in the /var/ucd-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 a suitable existing SNMPv3 user (with the same Authentication and Encryption protocols as required for the new user). 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 user. You will need the above 'createUser' line (or an equivalent 'usmUser') as well. The 'createUser' line disappears when I start the agent. Why? ------------------------------------------------------------- That's deliberate. The agent removes the (human-readable) 'createUser' directive, and replaces it with an equivalent 'usmUser'. This contains the same information, but in a form that's only meaningful internally. This means that the password is not longer stored in a human-readable form. Additionally, the password has been converted to a key that can only be used to access the local machine. If someone stole the new usmUser line on this machine, they could not use that information to access any of your other agents. What's the difference between /var/ucd-snmp and /usr/local/share/snmp? --------------------------------------------------------------------- Most "static" agent configuration should go in the traditional location (typically /usr/local/share/snmp/snmpd.conf or /etc/snmp). The /var/ucd-snmp (or /var/net-snmp) location is used for information set during the running of the agent, which needs to be persistent between one run of the agent and the next. Putting the 'createUser' line in this persistent file is an exception, for security reasons (see above). In general you shouldn't need to put anything else here. 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. 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. Try moving the old config file to the new location, and restart the agent. With release 5.0, the name of the package changed from "ucd-snmp" to "net-snmp", and this change was reflected in the name of the persistent /var directory. So a v5 Net-SNMP agent will not look in /var/ucd-snmp/snmpd.conf for settings from a v4 UCD agent. 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 configuring using '--with-libwrap'. 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 (or wherever this file is on your system). Though be aware that doing this removes one level of protection and allows anyone to try and query your agent (though 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 Linux' ipchains or 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? I'm getting errors about "bad security model" - why? ---------------------------------------------------- Until release 4.2, the access control handling accepted the token "any" to cover all of the recognised security models. This is explicitly forbidden in the relevant RFC, so support for this is being withdrawn. As an interim measure, it is currently accepted (with the warning you see), but this will not be the case in future releases of the agent. You should replace the token 'any' with 'v1', 'v2c' or 'usm' as appropriate. If you want to support all three of these security models, you'll need to use three distinct group lines, one for each. See the example snmpd.conf file for details. I'm getting errors about "bad prefix match parameter" - why? ------------------------------------------------------------ This is similar to the previous question. With 4.2, the syntax of the 'access' configure line has changed, and a value of '0' is no longer acceptable for the sixth field. Simply replace this with the word 'exact'. Why can't I see values in the UCDavis 'extensible' or 'disk' trees? ------------------------------------------------------------------ Both these trees are designed to report things you ask it to report on. If you don't declare anything in the snmpd.conf file for it to monitor, it will not report anything. 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 mib modules are not supported on all operating systems, and will not be included on any other system. 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* generate traps when the usage strays outside the configured bounds. See the earlier FAQ entry What traps are sent by the agent? 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. Recent releases 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 flawed percentage objects should not be used, and will 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? ---------------------------------- Sorry - the CPU statistics (both original percentages, and the newer raw statistics) both refer to the system as a whole. There is currently no way to access individual statistics for a particular processor (except on Solaris systems - see below). Note that although the Host Resources table includes a hrProcessorTable, the current implementation suffers from two major flaws. Firstly, it doesn't currently recognise the presence of multiple processors, and simply assumes that all systems have precisely one CPU. Secondly, it doesn't calculate the hrProcessorLoad value correctly, and either returns a dummy value (based on the load average) or nothing at all. As of net-snmp version 5.1, the Solaris operating system delivers some information about multiple CPU's such as speed and type. Other than that, to monitor a multi-processor system, you're currently out of luck. We hope to address this in a future release of the agent. But you've got the source, so you can always have a go yourself :-) 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. Version 4.2 allows you to override these guessed values, using the configuration directive 'interface', specifying 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 values as it can find out. 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 superceded 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). How about "Can't open /dev/kmem"? -------------------------------- 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 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 as an empty file, or run snmpconf to help you create one. See the snmpd.conf(5) manual page for further details. 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 "host.hrSystem.hrSystemUpTime" 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 system-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. COMPILING ========= How do I compile with 'cc' instead of 'gcc'? ------------------------------------------- Run configure with --with-cc=cc Note that if you've already run configure once, it will probably have detected the presence of 'gcc', cached this information, and may still try to use this anyway. In which case, simply remove the 'config.cache' file before re-running configure. But gcc doesn't compile it successfully on my new Solaris system. Why not? ------------------------------------------------------------------------- Whenever you upgrade the operating system under Solaris, you need to reinstall gcc, and run the 'fixincludes' script. (This is probably a sensible step to take when you upgrade any operating system). Under Solaris 2.6, there is also a bug in the gcc 'fixinc.sv4' script. This needs an additional line as follows: *** fixinc.svr4.cln Thu Jun 15 22:03:29 1995 --- fixinc.svr4 Tue Nov 25 09:47:57 1997 *************** *** 191,191 **** --- 191,192 ---- s/__STDC__ - 0 == 0/!defined (__STRICT_ANSI__)/g + s/__STDC__ - 0 == 1/defined (__STRICT_ANSI__)/g NOTE: This appears to have been resolved. On RedHat 8.0 or up I get "/usr/bin/ld: cannot find -lelf"? ---------------------------------------------------------- A typical installation of RedHat 8.0 and up doesn't always include the full set of 'libelf' library links. In order to build Net-SNMP you may need to install the 'elfutils-devel' RPM. A alternative quick fix is to add the missing symbolic link, using: ln -s libelf.so.1 /usr/lib/libelf.so (or whatever the correct library is on your system). This is typically only needed when you've configured the agent to include the Host Resources MIB support ('--with-mib-modules=host'). What about '-lbz2' or '-lselinux' errors? ---------------------------------------- This is the same basic problem - the relevant development RPMs have not been installed. You should either install them (bzip2-devel and libselinux-devel respectively), or create any missing symbolic links by hand: (cd /usr/lib ; ls -s libbz2* libselinux*) ln -s libbz2.so.1 /usr/lib/libbz2.so ln -s libselinux.so.1 /usr/lib/libselinux.so What about a failed dependency on 'libcrypto'? Where can I get that? -------------------------------------------------------------------- This is typically encountered when installing a Linux RPM of the ucd-snmp package. This library is part of the 'openssl' suite, so simply install that RPM first, or download the source from ftp://ftp.openssl.org and compile and install that. When compiling {UCD,Net}-SNMP from source, the configure script should detect that this library is not present, and use alternative arrangements for MD5-based authentication. If encryption (or SHA1-based authentication) is required, then this typically requires compiling from source. Under Linux, both the 'openssl' and 'openssl-devel' RPMs should be installed, and the 'config.cache' file removed before running "configure --with-openssl" and re-compiling. I'm getting an error "autoheader: not found" - what's wrong? ----------------------------------------------------------- This usually appears when compiling the current development source version, obtained via CVS. Unfortunately, the timestamps on some of the configure files are such that make assumes (mistakenly) that the configure script needs to be re-generated. A similar problem may arise relating to 'autoconf'. In both cases, this can be corrected by running the command "make -k touchit" before attempting to make the main package. 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? ------------------------------------------------------------------- If you are using net-snmp v5.1 or above, then the following configure options may be useful to you: --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 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 is the project workspace empty under Visual C++? --------------------------------------------------- This is probably due to the different ways that Unix and Windows handle text file line termination. Older versions of WinZip don't handle this properly, and Visual C++ gets confused (poor dear!). The latest version of WinZip is reported to unpack this correctly. Why does 'make test' skip five tests? ----------------------------------- You mean T053agentv1trap, T054agentv2ctrap, T055agentv1mintrap, T056agentv2cmintrap and T113agentxtrap? These tests rely upon functionality in the NET-SNMP-EXAMPLES-MIB which is not implemented in the default agent configuration. To include these tests, invoke the `configure` script to include '--with-mib-modules="examples/example". 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? ------------------------------------------------- At the moment, there are three methods for integrating external C code within the agent. The code can be included within the agent itself, statically configured and linked in when the agent is compiled. Alternatively, with the 4.2 release of the agent, it's possible to dynamically load MIB modules once the agent is running. Finally, the agent can be configured to pass certain portions of the MIB tree off to one or more subagents. See the earlier question on AgentX, SMUX and proxied SNMP for more details. All three mechanisms use the same module API. This is described (in excruciating detail) in the file AGENT.txt, shipped with the standard distribution. There is also an HTML version accessible via the project web page. This task can be aided using the tool 'mib2c' which generates most of the necessary skeleton code from the description in the MIB file. Note that the UCD suite does not include support for SMUX subagents. How does the agent fetch the value of a MIB variable from the system? -------------------------------------------------------------------- This depends on the MIB variable (and the operating system). Much of the 'mib-2' information is extracted from kernel memory - often by seeking to the appropriate location in the kernel itself and reading the data structures directly. Some systems provide cleaner interfaces to such kernel information (it would be hard to think of a less clean interface!), via ioctl() calls or similar system routines. Such mechanisms are usually used in preference. Some other MIBs may be implemented completely within the agent itself, where the necessary information is already being held internally. This particularly holds for MIBs relating to the operation of SNMP directly. Other MIBs may involve communicating with another running process, or using a variety of other sources. There's no simple answer to this question, and obtaining the necessary information is often the hardest part of implementing a MIB. Writing the code is straightforward by comparison! 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. 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 above. Mib2c takes the name of a MIB object, not the name of a file (or a 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 above - 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 rather than report an error, it merrily constructed a template for a default starting point of the mib-2 node. More recent versions issue the error mentioned above instead. Mib2c complains about "configuration files". What's this for? ------------------------------------------------------------ You've probably upgraded to the v5 net-snmp release (from the v4 ucd-snmp release). This introduced a new approach to agent module development, including a number of different "helpers". The mib2c tool comes with configurations to generate code for many of these, but you'll need to select which is most convenient for your particular case. What's the difference between the various mib2c configuration files? ------------------------------------------------------------------- There are various alternative configuration templates for mib2c, mostly concerned with implementing MIB tables. 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 one 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'. How can I have mib2c generate code for both scalars and tables? -------------------------------------------------------------- This uses a very powerful tool called a "text editor" :-) The v5 Net-SNMP 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. The handler and supporting routines from one file can simply be included in the other with no changes needed. The corresponding registration of these handlers can then be copied from the first initialisation routine into the second. Are there any examples, or documentation? ------------------------------------------- Most of the MIB modules shipped with the Net-SNMP agent still use the v4 "traditional" MIB module API, but a few use one of the newer v5 helper-based handlers. The dataset handler is used in the two DISMAN-EVENT-MIB modules (disman/mteEventTable and disman/mteEventNotificationTable), as well as the 'snmptrapd' implementation of logging incoming traps (apps/notification_log) The basic iterator handler is used in a number of modules, such as the latest 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. 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. I've created a new module with 'mib2c' but it doesn't work. Why not? -------------------------------------------------------------------- Remember that 'mib2c' generates a template for the MIB implementation. It doesn't fill in all the details for you. In particular, it cannot know how to obtain the information needed to answer particular queries. That's the job of the MIB module programmer (you!) - See the previous question for how to proceed. Essentially mib2c handles the syntax of the MIB implementation, leaving you to concentrate on the semantics. I've added my code to this template and it still doesn't work. Why not? ----------------------------------------------------------------------- It's difficult to provide a definitive answer to that. The best we can do is suggest a checklist that might help pinpoint the source of the problem. Try looking at the following: - Is the new module being compiled? (Delete any .o files, and re-run 'make' Are the .o files re-created?) - Is it being included in the agent library? (Run 'nm' on the library and look for the names of the initialisation routine and variable handlers) - Is the initialisation routine being run? (Activate the debugging code that you put into this routine. You *do* include debugging code as a matter of course, don't you?) - Has the module been registered with the agent? (Try walking the NET-SNMP-MIB::nsModuleTable) This will also check whether the agent accepts requests for enterprise-specific OIDs. - Is the module handler actually being called at all? (Activate the debugging code that you put into this handler, and do a single 'snmpget' or 'snmpgetnext' for a suitable instance. You *do* include debugging code as a matter of course, don't you?) - Is it returning success or an error? (Activate the debugging code.... but you get the idea!) That won't actually solve the problem, but at least you'll have some idea where to look. Mib2c only handles a single table in my MIB. How can I fix this? --------------------------------------------------------------- This was a bug in the mib2c script, which was corrected with the 4.2 release. Earlier versions can be fixed by applying the following patch: $ diff -u mib2c.cln mib2c --- mib2c.cln Wed Nov 29 15:12:47 2000 +++ mib2c Wed Nov 29 15:13:18 2000 @@ -132,6 +132,6 @@ #============================================ foreach $vtable (@table_list) { foreach $ptable (@processtable) { - $variables{$ptable}{'processed'} = + $variables{$ptable}{'processed'} .= (eval "\"$variables{$ptable}{'code'}\"") . "\n\n"; } 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 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 support a large table, with more than 256 column objects? ------------------------------------------------------------------ This is a problem (at least apparently) with the v4 UCD module API, which uses a "magic number" to distinguish between the various column objects implemented by a common variable handling routine. Since this field is defined as an unsigned character, it can only take values 0-255. So at first sight, it would appear that the agent cannot support tables (or scalar groups) with more than 256 objects, since this would start to duplicate these magic numbers. However, the agent doesn't actually care which routine implements a given object, and magic numbers only need to be unique within a single variable handling routine. So it is actually perfectly possible to implement a larger table by splitting it between two (or more) variable handling routines. These can then re-use the magic numbers quite safely: struct variable1 [] = { {MAGIC1, ASN_INTEGER, RWRITE, var_myfirst, 1, { 1}}, {MAGIC2, ASN_INTEGER, RWRITE, var_myfirst, 1, { 2}}, : {MAGIC255, ASN_INTEGER, RWRITE, var_myfirst, 1, {255}}, {MAGIC1, ASN_INTEGER, RWRITE, var_mysecond, 1, {256}}, {MAGIC2, ASN_INTEGER, RWRITE, var_mysecond, 1, {257}}, : {MAGIC255, ASN_INTEGER, RWRITE, var_mysecond, 1, {510}} }; All that matters is that a given magic number isn't re-used within the same variable handling routine. The v5 table handlers typically use an integer variable for holding column information, so aren't subject to the same limitations. Though I'd have to question whether having such a wide table is necessarily a particularly good design strategy! How can I get the agent to generate a trap (or inform)? ------------------------------------------------------ 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). See the 'snmp_trap_api(3)' man page for details. 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. 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. It's necessary to poll the value(s) on a regular basis, save the results and compare them with the new values the next time round. With the v4 UCD agent, this would have to be done manually, using the routines documented in 'snmp_alarm(3)'. The v5 Net-SNMP agent has implemented the Distributed Management Event MIB, which provides this functionality in a flexible, standardised manner. See the 'snmpd.conf(5)' man page (under DISMAN-EVENT-MIB) for details (including the need for an 'agentSecName' setting). 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. 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. What if I'm using an AgentX sub-agent instead? --------------------------------------------- That doesn't matter - the routines described in 'snmp_trap_api(3)' can still be used, and the subagent will do the Right Thing. One of the original design aims of the AgentX support was that this should be transparent to a MIB module implementer. The agent-module interface 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. In fact, the main agent supplied as part of the package can indeed be run as an SNMP agent or an AgentX subagent, simply based on command line flags (or similar configuration options). 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 explicitly register an individual MIB module using a different 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); In either case, it will also be necessary to define suitable access control entries to cover requests using the new context. This can either list each context explicitly: access {group} "my_context" any noauth exact ...... or use a single entry to cover all possible contexts: access {group} "" any noauth prefix ...... But note that *both* steps are required. Changing the access control settings won't affect the default context used for MIB registrations, and registering a MIB in a non-default context won't automatically configure the necessary access control settings. MISC ====== Why are packets requesting the same information larger with UC-Davis SNMP? ------------------------------------------------------------------------- This shouldn't happen with version 4.2 or later, but for older version the following still applies: Some users note that UCD-SNMP applications always generate larger PDUs than other SNMP packages, even if the information requested is the same. Further, there are some agents that refuse PDUs from UCD-SNMP applications but accept PDUs from other applications. UCD-SNMP is based on the CMU code from a long time ago which encoded things using the long form of length encoding. Some agents use the short form of length encoding only, and do not understand the long form. This should not be a problem with UCD v4.2 or higher, or the Net-SNMP releases. 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 'libsnmp.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."