Frequently Asked Questions (FAQ) for the UCD SNMP package ========================================================= FAQ Author: Dave Shield ucd-snmp Project Author: Wes Hardaker Email: ucd-snmp-coders@ece.ucdavis.edu TABLE OF CONTENTS ================= TABLE OF CONTENTS GENERAL What is it? Where can I get it? What documentation is available? Are there binaries available? What operating systems does it run on? What happens if mine isn't listed? 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? What's the difference between SNMPv1 and SNMPv2? What are all these different SNMPv2's anyway? Which versions of SNMP are supported in this package? Where can I find more information? AGENT What MIBs are supported? How do I add a MIB? How do I add a MIB to the tools? How do I add a MIB to the agent? How do I add functionality? What traps are sent by the agent? When I run the agent it runs and then quits without staying around. Why? TECHNICAL How do I write C code to integrate with the agent? What ASN.1 parser is used? How does the agent fetch the value of a variable from the system? What is the Official Slogan of the ucd-snmp-coders list? PROBLEMS How come ever since version 3.2 my mib files are no longer read? What's this about a "party database", when I try to send a query? Why can't I see values in the UCDavis 'extensible' tree? Why can't I see values in the tree? I've done that, and I still can't see the values. Why not? I've done that, and I'm *still* not getting anything back. Why not? I've done that, but I'm *still* getting "sub-identifier not found:" Grrr! The agent is complaining about 'snmpd.conf'. Where is this? What does "klread: bad address" mean? What does "nlist err: wombat not found" (or similar) mean? How about "Can't open /dev/kmem"? Or "sendto: permission denied" ? I'm using the Perl SNMP module, and get something about "bad free"? 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? How do I compile with 'gcc' instead of 'cc'? But gcc doesn't compile it successfully on my new Solaris system. Why not? I cannot set any variables in the MIB. Sometimes I seem to get the wrong answers. Why? 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 This package is originally based on the Carnegie Mellon University SNMP implementation (version 2.1.2.1) Where can I get it? ------------------ - ftp://ftp.ece.ucdavis.edu/pub/snmp/ucd-snmp.tar.gz - ftp://sunsite.cnlab-switch.ch/mirror/ucd-snmp/ucd-snmp.tar.gz - ftp://ftp.win.or.jp/pub/network/snmp/ucd-snmp/ucd-snmp.tar.gz What documentation is available? ------------------------------- This FAQ (!) README INSTALL PORTING EXAMPLE.conf man pages for the individual tools, files and the API Most of this documentation is also available on our web page, as well as mailing list acrchives: http://www.ece.ucdavis.edu/ucd-snmp Are there binaries available? ---------------------------- - Nope, sorry. The distribution ought to compile cleanly and run on a range of systems (see the next answer). See the file INSTALL for more details. What operating systems does it run on? ------------------------------------- * HP-UX 9.07, 9.05, 9.03, 9.01 on HPPA 1.1 systems * HP-UX 10.20, 10.10, 10.01 on HPPA 1.1 systems * Ultrix 4.5, 4.4, 4.3, 4.2 on DEC MIPS systems * Solaris 2.6, 2.5.1, 2.5, 2.4, 2.3 on Sun SPARC systems * Solaris 2.5 on x86 systems * SunOS 4.1.4, 4.1.3, 4.1.3, 4.1.2 on Sun SPARC systems * OSF 4.0, 3.2 on DEC Alpha systems * NetBSD 1.3alpha, 1.2.1, 1.2, 1.1, 1.0 on all? systems * FreeBSD 3.0, 2.2.2, 2.2 on all? systems * BSDi 2.1 on all? systems * Linux 2.1, 2.0, 1.3 on all? systems * AIX 4.1.5, 3.2.5 on all? systems The applications (though not necessarily the agent) run on the following systems: * Irix 6.2 * Windows95 * Windows NT What happens if mine isn't listed? --------------------------------- It's worth trying anyway, particularly if the system is based around the BSD kernel. If it seems to work correctly, let us know so that we can update the list above. If it doesn't work, let us know and we'll try to help. If the agent almost compiles, but certain files in the agents/mibgroup directory fail, you can try omitting those modules by re-running configure with the flag --with-out-mib-modules="list" You'll then need to re-compile. Either way, try it and let us know how you get on (see below for how). How do I find out about new releases? ------------------------------------ There is a mailing list for these announcements ucd-snmp-announce@ece.ucdavis.edu To be added to (or removed from) this list, send a message to the address 'ucd-snmp-announce-request@ece.ucdavis.edu' 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. How can I find out what other people are doing? ---------------------------------------------- There is a general purpose discussion list ucd-snmp@ece.ucdavis.edu To be added to (or removed from) this list, send a message to the address 'ucd-snmp-request@ece.ucdavis.edu' with a subject line of 'subscribe' (or 'unsubscribe' as appropriate). There's not a great deal of traffic at the moment, but you can always try to do something about that! How do I submit a patch or bug report? ------------------------------------- There is a script that you can use to submit a bug report. This allow you to describe the problem you're having, and includes various pieces of information about your system that are useful in trying to track down the problem. Alternatively, you can send a message to 'ucd-snmp-coders@ece.ucdavis.edu' containing a description of the problem, and as much other relevant details as you can. Useful information includes 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. We can't promise to be able to solve the problem, but we'll certainly try and help. If you're trying to port the package to a new system, the output of the command 'make -k' is a good starting indicator of where the bulk of the work is likely to be needed. If you're reporting success 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! What's the difference between SNMPv1 and SNMPv2? ----------------------------------------------- What are all these different SNMPv2's anyway? -------------------------------------------- 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 with this showed up various problems and deficiencies wih this, and a revised framework was developed to try and address these. This was described in RFCs 1441-1452, and is known as "SNMPv2 classic". The changes proposed include: * new ways of defining information (MIB structure) (SMI, Textual conventions, conformance statements) * new protocol packet types and transport mappings * new mechanisms for administration and security * mechanisms for remote configuration Unfortunately, while many of these were generally accepted, there was still some disagreement in these last two areas, security/admin and remote configuration. This resulted in a number of variants and alternative proposals: SNMPv2c Contains the new protocol and MIB structure elements, using the existing SNMPv1 administration structure. This is the agreed SNMPv2 standard (described in RFCs 1901-1908), superseding SNMPv2 classic, and is known as "Community-based SNMPv2" or simply "SNMPv2". SNMPv2 usec } Alternative proposals to address the SNMPv2* } limitations of SNMPv1 administration } These are both super-sets of SNMPv2c SNMP-NG A recent attempt to reach agreement between the proponents of usec and v2star. SNMPv3 The formal successor to SNMP-NG, currently being active developed, and aiming to produce Proposed Standards for the next generation of core SNMP functions in the very near future. Which versions of SNMP are supported in this package? ---------------------------------------------------- This package currently supports the original SNMPv1, SNMPv2 classic (i.e. RFCs 1441-1452, and referred to as "SNMPv2 historic)), and Community-based SNMPv2 (i.e. RFCs 1901-1908). 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. The group is not currently tracking the SNMPv3 development (as far as I know). When these standards emerge, it is likely that we will seek to implement them as soon as possible. Where can I find more information? --------------------------------- There are a number of sites with network management information on the World Wide Web. Two of the most useful are http://netman.cit.buffalo.edu/index.html http://wwwsnmp.cs.utwente.nl/ 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 either of the two Web sites above. AGENT ===== What MIBs are supported? ----------------------- The following MIBs are supported (at least in part): - MIB-2 General network statistics (RFC 1213) - UCD agent extensions (processes, disks, memory, load average, shell commands, error handling) - SNMPv2 Party MIB (RFC 1447 - now 'historic') - SNMPv2 Manager-to-Manager MIB (RFC 1451 - now 'historic') - SMUX implementation (RFC 1227) for communicating with 'gated' (plus routing protocols BGP, OPSF & RIP2 - RFCs 1657, 1724 & 1850) - Host Resources (RFC 1514) skeleton implementation 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 two questions. How do I add a MIB to the tools? ------------------------------- The tools only really use the MIB files for translating between numeric and textual forms for queries and responses. They will operate quite happily without any MIB files at all, as long as you are prepared to work with numeric OIDs throughout. The tools look in a predefined directory (usually PREFIX/lib/snmp/mibs) and regard any file held there as defining a MIB module or modules. Adding translation ability for a new MIB moule is simply a matter of placing a file defining the MIB in this directory, and defining a suitable environment to tell the tools about it. (See the first question under 'PROBLEMS' for more details). The tools can then be used to communicate with any agent that implements the relevant MIB modules. The UCD agent, however, does not use these MIB text files at all, and will work quite happily without them. (Actually it needs to find the main MIB file, though it doesn't do anything with it!). The values returned by the agent are simple numeric (or string) responses, and the syntax and scope of the variables supported are hard-coded into the implementation. The MIB text files are only used to translate these responses into more meaningful terms. How do I add a MIB to the agent? ------------------------------- How do I add functionality? -------------------------- Unfortunately, adding a file to the MIB directory does not automatically extend the functionality of the agent to include this MIB. (Would that life were 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 iplementation of the agent. There are three ways to add funcionality 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" 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. See the third question under PROBLEMS for more details of how to access these. Secondly, it is possible for the agent to run commands or shell scripts in response to queries. These can optain and report the necessary information, or perform actions as required. Detailed information and examples are provided in the snmpd(1) and snmpd.conf(5) manual pages, and the EXAMPLE.conf file. Thirdly, the agent itself can be extended to support additional MIB groups, by writing the necessary C code. This is covered further in the 'TECHNICAL' section below. Note that there is effectively no difference between 'pass-through' MIB support, and modules implemented within the agent itself. Tools querying the agent will see a single MIB structure. What traps are sent by the agent? -------------------------------- The agent can be configured to send a 'coldStart(0)' trap when it first starts up. The destination to send the trap to, and the community name to use, are set in the snmpd.conf file ('trapsink' and 'trapcommunity' respectively - note both are required) The agent can also be configured to send 'authenticationFailure(4)' traps when it receives SNMPv1 requests using a community name that is not recognised. This is done with the snmpd.conf entry 'authtrapsenable 1'. When I run the agent it runs and then quits without staying around. Why? ----------------------------------------------------------------------- The first question is, 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. 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. See under 'PROBLEMS' for more advice. TECHNICAL ========= How do I write C code to integrate with the agent? ------------------------------------------------- At the moment, the only technique for integrating external C code with the agent (as opposed to using the 'pass-through' shell extensibility mentioned above) is to implement it within the agent itself. The implementation of the agent has recently been re-organised to make it easier to incorporate new MIB groups. The relevant code is held in the directory 'agent/mibgroup', with one file (plus header) per group in most cases. The README file in that directory gives more information as to the structure of these files, and how to add a new group. Contact the list 'ucd-snmp-coders@ece.ucdavis.edu' for further advice. It is hoped to implement some form of proxy mechanism (such as the agentx protocols) once the specification for these have settled, and someone gets around to writing the necessary code. 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' How does the agent fetch the value of a variable from the system? ---------------------------------------------------------------- Much of the information is extracted from kernel memory - usually by seeking to the appropriate location and reading the 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 and these mechanisms are usually used in preference. What is the Official Slogan of the ucd-snmp-coders list? ------------------------------------------------------- "The current implementation is non-obvious and may need to be improved." (with thanks to Rohit Dube) PROBLEMS ======== Why aren't my mib files read in any more? ----------------------------------------- As from version 3.2, the parser has been re-written. One effect of this is that only a specified set of MIB modules are read in by the tools by default. This list can be set in a number of ways: The tools have a default list compiled in, which can be set using the configure option --with-mibs="list" and recompiling the tools. The environmental variable 'MIBS' will be taken as a list of module names (separated by colons) to be read in, instead of (or as well as) the default list. Note that any modules these rely on will be read in automatically, without needing to be listed explicitly. The environment variable 'MIBFILES' will be taken as a list of filenames, containing MIB modules to be read in (in addition to those included by 'MIBS' and/or the default list). Again, any modules these rely on will also be loaded in automatically. The names listed in this variable can be anywhere in the filesystem, though any implicitly loaded modules must be present in the standard location(s). Finally, if the environmental variable 'MIBS' has the special value "ALL", then the tools will load in every module present in the module directory (or directories). The location where the tools look for MIB module files is compiled into the tools. This can also be set using the environmental variable 'MIBDIRS', being a (colon-seperated) list of directories containing MIB files. See the 'mib_api(3)' man page for more details. I'm getting answers, but they're all numbers. Why? ------------------------------------------------- This is actually the same as the previous question. Because the tools no longer 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 to read in the relevant module files. This does assume you have these files installed properly. There's not a great deal we can do if you haven't. What's this about a "party database", when I try to send a query? ---------------------------------------------------------------- Previous releases of these tools sent SNMPv2 (classic) queries, which relied on party configuration information being available. With the current release, by default queries now use SNMPv2c, which does not need any such party configuration. In either case, it is possible to specify the use of SNMPv1 instead, by giving the application the option "-v 1". Why can't I see values in the UCDavis 'extensible' tree? ------------------------------------------------------- The extensible tree is 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 no configuring the agent. Why can't I see values in the tree? ----------------------------------------------------------- Normally, the tools assume that any object ID specified is a full path, starting from the 'mib-2' node of the overall MIB tree. So if you perform an 'snmpwalk' on an agent, without specifying a starting point, it will return just the values in the 'mib-2' tree. If you wsh to examine anything under the 'private.enterprises' branch (or anywhere else in the MIB structure) you will need to inform the tools appropriately. There are two ways to do this: First, you can give the full specification, starting from the root of the tree - e.g: .iso.org.dod.internet.private.enterprises.ucdavis Note the initial dot - this is important! Alternatively, you can define the environmental variable PREFIX, to specify where to start looking for ( non-fully specified) objects. This can be done by the command (C shell family) setenv PREFIX .iso.org.dod.internet.private.enterprises.ucdavis or (Bourne shell family) PREFIX=.iso.org.dod.internet.private.enterprises.ucdavis export PREFIX after which, the following example should work: snmpwalk -v 1 localhost public processes I've done that, and I still can't see the values. Why not? --------------------------------------------------------- Another possibility is that there is a clash of names somewhere within the MIB tree. Try running the command 'snmptranslate -x zzz' which will inform you of any duplicates, or other similar problem. This should be less of a problem with the new parser, which now handles duplicate identifier names, though inconsistent case in labels for the same node still confuse the poor darling. I've done that, and I'm *still* not getting anything back. Why not? ------------------------------------------------------------------ Another possibility is that the agent you are querying is simply not responding. Try contacting it with a "reliable" query. A good test is to do an 'snmpwalk' on the 'system' sub-tree. Or it may be that the agent just doesn't implement the MIB module that you're interested in. Or it does, but is falling over (software with bugs in - shock horror!) Try doing an 'snmpwalk' starting somewhere above the offending bit of the MIB tree, and seeing how far it gets. I've done that, but I'm *still* getting "sub-identifier not found:" Grrr! ------------------------------------------------------------------------ If a "general" snmpwalk shows the entry, but asking for it more specifically gives a "sub-identifier not found:" error, then that's a slightly different problem. The tools assume that the object ID they are given is a full path starting from 'mib-2' (or wherever you have set PREFIX to). You can't simply give the final sub-identifier, and expect the tools to find the relevant node. (Well, you can, but you'll be disappointed). You need to specify the intermediate sub-identifiers as well. For example snmpget myhost public sysUpTime.0 will fail, while snmpget myhost public system.sysUpTime.0 will work. There are plans to include this "random access" feature (for unique names at least), but this is not yet available. 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 try copying the EXAMPLE.conf file which will use some of the UCD extensions. See the snmpd.conf(5) manual page for further details. 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 'ucd-snmp-coders@ece.ucdavis.edu' 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. 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) Or "sendto: permission denied"? ------------------------------ This was due to a minor problem in setting network addresses, which has now been fixed. If you are seeing this error, please install the most recent version of the UCD snmp tools. I'm using the Perl SNMP module, and get something about "bad free"? ------------------------------------------------------------------ This problem has also been fixed in the most recent release of the UCD SNMP tools. In general, if you experience any problem like this, try checking to see if there's a newer release first. In particular, the recent changes in the way MIB files are parsed requires Perl SNMP-1.6 or later. 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). How do I compile with 'gcc' instead of 'cc'? ------------------------------------------- Set the environmental variable 'CC' to have the value 'gcc' before running the configure script. 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 I cannot set any variables in the MIB. ------------------------------------- There are three possible reasons for this: The majority of MIB variables are "read-only" and cannot be changed. Of those that can in principle be changed, only a few have been implemented as such in this agent. Currently, most (if not all) of these are contained within the 'system' sub-tree, relating to general contact information. With the distribution as shipped, the community name "private" must be used to set these values. This can be changed by setting the second community string (via the snmpd.conf entry "community 2 newstring"). Note that the (first) community string "public" can *not* be used to set variables. Sometimes I seem to get the wrong answers. Why? ----------------------------------------------- Many of the variables in the basic MIB-2 tree require information that is not easily available in the common Unix kernels. In the absence of anything better, the agent returns hardwired 'null' values. The items affected are: interface.ifType other(1) interface.ifSpeed 1 interface.ifLastChange 0 interface.ifInNUCastPkts 0 interface.ifInDiscards 0 interface.ifInUnknownProtos 0 interface.ifOutNUCastPkts 0 interface.ifSpecific Null OID ip.ipInUnknownProtos 0 ip.ipInDiscards 0 ip.ipOutRequests 0 ip.ipOutDiscards 0 ip.ipFragOKs 0 ip.ipFragFails 0 ip.ipFragCreates 0 ip.ipRouteDiscards 0 ipAddrEntry.ipAdEntReasmMaxSize -1 ipRouteEntry.ipRouteAge 0 tcp.tcpMaxConn -1 tcp.tcpOutRsts 0 udp.udpInDatagrams 0 udp.udpNoPorts 0 udp.udpOutDatagrams 0 The following variables have 'likely guess' values, that are not necessarily strictly accurate. The SNMP protocol standards (RFCs 1157 and 1905) could actually be taken to imply that the agent should return a 'genErr' in these cases. interface.ifInOctets guess based on # of packets interface.ifInUCastPkts includes non-unicast packets interface.ifOutOctets guess based on # of packets interface.ifOutUCastPkts includes non-unicast packets ip.ipInDelivers Doesn't handle fragments properly ip.ipReasmOKs Assumes fragments are complete datagrams ipRouteEntry.ipRouteProto local(2) or icmp(4) tcp.tcpRtoAlgorithm vanJ(4) (probably correct!) The following variables are simply not implemented according to specification tcp.tcpAttemptFails } actually counting tcp.tcpEstabResets } something different tcp.tcpOutResets } Some systems may return the correct information for these values. Systems that are believed to have corrected some of these are as follows: * FreeBSD & BSDi provide correct interface statistics * Solaris, Linux & HP-UX provide correct statistics throughout (though Solaris may need a kernel patch to support interface octet counts).