| Frequently Asked Questions (FAQ) for the UCD/Net-SNMP package |
| ============================================================= |
| FAQ Author: Dave Shield |
| net-snmp Version: 5.4.1.pre3 CVS 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 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 doesn't the agent respond? |
| I can see the system group, but nothing else. Why? |
| Why can't I see values in the <INSERT ENTERPRISE HERE> tree? |
| The agent worked for a while, then stopped responding. Why? |
| Requesting an object fails with "Unknown Object Identifier" Why? |
| Why do I get "noSuchName" when asking for "sysUpTime" (or similar)? |
| Why do I sometimes get "End of MIB" when walking a tree, and sometimes not? |
| How do I use SNMPv3? |
| I cannot set any variables in the MIB. |
| Variables seem to disappear when I try to set them. Why? |
| Why can't I change sysLocation (or sysContact)? |
| I get an error when trying to set a negative value - why? |
| I get an error when trying to 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? |
| 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? |
| 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? |
| 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 can I get more information about problems with MIB files? |
| What's this about "too many imported symbols"? |
| Do I actually need the MIB files? |
| AGENT |
| What MIBs are supported? |
| What protocols are supported? |
| How do I configure the agent? |
| How do I remove a MIB from the agent? |
| I've installed a new MIB file. Why can't I query it? |
| How do I add a MIB to the agent? |
| What's the difference between 'exec', 'sh', 'extend' and 'pass'? |
| What's the difference between AgentX, SMUX and proxied SNMP? |
| What 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/net-snmp and /usr/local/share/snmp? |
| My new agent is ignoring the old snmpd.conf file. Why? |
| Why am I getting "Connection refused"? |
| Why can't I see values in the UCDavis 'extensible' or 'disk' trees? |
| Why can't I see values in the UCDavis 'memory' or 'vmstat' tree? |
| What do the CPU statistics mean - is this the load average? |
| How do I get percentage CPU utilization using ssCpuRawIdle? |
| What about multi-processor systems? |
| The speed/type of my network interfaces is wrong - how can I fix it? |
| The interface statistics for my subinterfaces are all zero - why? |
| Does the agent support the RMON-MIB? |
| What does "klread: bad address" mean? |
| What does "nlist err: wombat not found" (or similar) mean? |
| 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'? |
| The compilation is complaining about missing libraries. Why? |
| 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? |
| 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? |
| Why does the iterator call my get_{first,next} routines so often? |
| How can I get the agent to generate a trap (or inform)? |
| How can I get 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 |
| What ASN.1 parser is used? |
| What is the Official Slogan of the net-snmp-coders list? |
| |
| |
| GENERAL |
| ======= |
| |
| What is it? |
| ---------- |
| |
| - Various tools relating to the Simple Network Management Protocol |
| including: |
| |
| * An extensible agent |
| * An SNMP library |
| * tools to request or set information from SNMP agents |
| * tools to generate and handle SNMP traps |
| * a version of the unix 'netstat' command using SNMP |
| * a graphical Perl/Tk/SNMP based mib browser |
| |
| This package is originally based on the Carnegie Mellon University |
| SNMP implementation (version 2.1.2.1), but has developed significantly |
| since then. |
| |
| |
| |
| Where can I get it? |
| ------------------ |
| |
| Download: |
| - http://www.net-snmp.org/download/ |
| - ftp://ftp.net-snmp.org/pub/sourceforge/net-snmp/ |
| Web page: |
| - http://www.net-snmp.org/ |
| Sourceforge Project page: |
| - http://www.net-snmp.org/project/ |
| Mirrors (note that sourceforge download servers are mirrored themselves): |
| - US: ftp://ftp.freesnmp.com/mirrors/net-snmp/ |
| - Greece: ftp://ftp.ntua.gr/pub/net/snmp/net-snmp/ |
| |
| |
| What documentation is available? |
| ------------------------------- |
| |
| This FAQ (!) |
| README and individual READMEs for various platforms |
| README.thread (discusses threading issues) |
| INSTALL |
| PORTING |
| EXAMPLE.conf |
| man pages for the individual tools, files and the API |
| A guide for extending the agent |
| Tutorials for both ucd-snmp v4 and net-snmp v5 |
| at http://www.net-snmp.org/tutorial/ |
| and http://www.net-snmp.org/tutorial-5/ respectively |
| |
| Most of this documentation (plus archives of the mailing lists) |
| is also available on our web page: |
| |
| http://www.net-snmp.org/ |
| |
| There is also a Wiki (including a community-maintained version |
| of this FAQ) at |
| |
| http://www.net-snmp.org/wiki/ |
| |
| |
| |
| Are there binaries available? |
| ---------------------------- |
| |
| There are binaries for some versions/systems available under |
| the "net-snmp binaries" package on the project download 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 saw the last releases made using the ucd-snmp name, |
| and all releases on this line have been been bug-fixes only. Release |
| 5.0 was the first version released under the Net-SNMP name, and all |
| further development is being done on the 5.x code base. The 4.2.x |
| code line is now almost completely dormant, and is due to be closed |
| down altogether. |
| |
| Much of the work done for the various 5.x releases has involved |
| some fairly significant changes to the code - in particular the |
| architecture of the agent. However attempts have been made to retain |
| backwards compatibility as much as possible, and most code written |
| for earlier releases should continue to work. The most significant |
| change from the 4.2.x ucd suite to the 5.x Net-SNMP releases was a |
| restructuring of the header file organisation - not least a change |
| from <ucd-snmp/xxx.h> to <net-snmp/yyy.h>. |
| |
| But given the maturity of the Net-SNMP code, this should be less |
| of a consideration for most current SNMP development projects. |
| |
| |
| |
| What operating systems does it run on? |
| ------------------------------------- |
| |
| Both the applications and the agent have been reported as running |
| (at least in part) on the following operating systems: |
| |
| * Linux (kernels 2.6 to 1.3) |
| * Solaris/SPARC (11 to 2.3), Solaris/Intel (10, 9) -- see |
| README.solaris |
| * HP-UX (10.20 to 9.01 and 11.23 to 11.0 -- see README.hpux11) |
| * Mac OS X (10.4 to 10.1) -- see README.osX |
| * NetBSD (2.0 to 1.0) |
| * FreeBSD (6.1 to 2.2) |
| * OpenBSD (4.0 to 2.6) |
| * BSDi (4.0.1 to 2.1) |
| * AIX (5.3, 5.2, 5.1, 4.3.3, 4.1.5, 3.2.5) -- see README.aix |
| * IRIX (6.5 to 5.1) |
| * OSF (4.0, 3.2 and Tru64 Unix 5.1B -- see README.tru64) |
| * SunOS 4 (4.1.4 to 4.1.2) |
| * Ultrix (4.5 to 4.2) |
| * Dynix/PTX 4.4 |
| * QNX 6.2.1A |
| |
| We have also been informed about a port to the Stratus VOS. |
| See http://ftp.stratus.com/vos/network/network.html for details. |
| |
| See the next question 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 which |
| that we think we've fixed!) |
| |
| |
| |
| What happens if mine isn't listed? |
| --------------------------------- |
| |
| It's probably worth trying to compile it anyway. Unless your |
| system is significantly different to the supported configurations, |
| most of the code (library, applications and the agent infrastructure) |
| should probably compile with little or no difficulty. The most |
| likely source of problems will be MIB modules within the agent, |
| as this tends to be where the most system-specific code is found. |
| |
| If only a few modules fail to compile, try removing them from |
| the agent by running "configure --with-out-mib-module=xxx,yyy", |
| and re-compiling. If a large number of modules fail, then it |
| might be easier to start from a relatively bare system, using |
| "configure --enable-mini-agent --with-defaults". Then if this |
| minimal agent compiles and runs successfully, try adding each of |
| the missing mibgroups individually using the configure option |
| '--with-mib-module'. |
| |
| If configure fails with "invalid configuration" messages, or |
| you get completely stuck, contact the coders list for advice. |
| Similarly, if you manage to get this working on a new system, |
| please let us know of any code changes that you needed to make, |
| together with details of the hardware you're using, and what |
| versions of the operating system you've tried it on. The entry |
| 'host' in the file 'config.status' should show this information. |
| Oh, and congratulations! |
| |
| |
| |
| Does it run on Windows? |
| ---------------------- |
| |
| The suite will compile and run on Win32 platforms, including |
| the library, command-line tools and the basic agent framework. |
| Note that the agent now includes support for the MIB-II module, |
| but this requires Microsoft's Core Platform SDK. Instructions |
| for how to install this are given in README.win32. |
| |
| Pre-compiled binaries are available from the Net-SNMP web site. |
| |
| As of Net-SNMP 5.4, the Net-SNMP agent is able to load the Windows |
| SNMP service extension DLLs by using the Net-SNMP winExtDLL extension. |
| |
| Some Net-SNMP 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). Several |
| core developers hang out there on a regular basis. |
| |
| |
| |
| How do I submit a patch or bug report? |
| ------------------------------------- |
| |
| The best way to submit a bug report is via the bug database through |
| the interface found at http://www.net-snmp.org/bugs/. Be sure to |
| include the version of the package that you've been working with, |
| the output of the command 'uname -a', the precise configuration or |
| command that triggers the problem and a copy of any output produced. |
| |
| 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 admin framework was |
| described in RFCs 1155-1157, and is now known as SNMPv1. |
| |
| Practical experience showed up various problems and deficiencies |
| with this, and a number of revised frameworks were developed to try |
| and address these problems. Unfortunately, it proved difficult to |
| achieve any sort of agreement - particularly over the details of |
| the administrative framework to use. |
| |
| There was less disagreement over the proposed changes to the |
| protocol operations. These included: |
| * increasing the range of errors that could be reported |
| * introducing "exception values" |
| (so a single missing value didn't affect |
| the other varbinds in the same request) |
| * a new GETBULK operation |
| (a supercharged GETNEXT) |
| * new notification PDUs |
| (closer in structure to the other request PDUs) |
| |
| Strictly speaking, it's this revised protocol (originally defined |
| in RFC 1905, and most recently in RFC 3416) that is "SNMPv2". |
| |
| The only framework based on this protocol that saw a significant |
| level of use was "Community-based SNMPv2" or "SNMPv2c" (defined in |
| RFCs 1901-1908). This retained the same administrative framework |
| as SNMPv1 (with all of the accompanying limitations), but using |
| the new protocol operations. |
| |
| More recently, a new administrative framework has been developed, |
| building on the various competing SNMPv2 proposals, and using the |
| same SNMPv2 protocol operations. This is SNMPv3, which is defined |
| in RFCs 3411-3418. It addresses some of the deficiencies of the |
| community-based versions, including significant improvements to |
| the security of SNMP requests (like it finally has some!). |
| SNMPv3 is now a full IETF standard protocol. |
| |
| Strictly speaking, SNMPv3 just defines a fairly abstract framework, |
| based around the idea of "Security Models" and "Access Control Models". |
| It's this combination of SNMPv3 plus accompanying models that actually |
| provides a working SNMP system. |
| However, the only models in common use are the "User-based Security |
| Model" (RFC 3414) and the "View-based Access Control Model" (RFC 3415). |
| So "SNMPv3" is frequently used to mean the combination of the basic |
| SNMPv3 framework with these two particular models. |
| This is also sometimes described as "SNMPv3/USM". |
| |
| |
| So in brief: |
| - SNMPv2c updated the protocol operations |
| but left the administrative framework unchanged. |
| - SNMPv3 updated the administrative framework |
| but left the protocol operations unchanged. |
| |
| |
| |
| Which versions of SNMP are supported in this package? |
| ---------------------------------------------------- |
| |
| This package currently supports the original SNMPv1, 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 syntax used to specify a MIB file (better referred |
| to as SMIv1 or SMIv2) is purely concerned with how to define |
| the characteristics of various management objects. This is |
| (almost) completely unrelated to the versions of the protocol |
| used to operate on these values. So it is quite reasonable to |
| use SNMPv1 requests on objects defined using SMIv2, or SNMPv2 |
| (or SNMPv3) requests on objects defined using SMIv1. |
| |
| The one exception is objects of syntax Counter64, which are |
| only accessible using SNMPv2 or higher. SNMPv1 requests will |
| either treat such objects as an error, or skip them completely. |
| |
| |
| |
| Where can I find more information about network management? |
| ---------------------------------------------------------- |
| |
| There are a number of sites with network management information on |
| the World Wide Web. A couple of the most useful are |
| |
| http://www.simpleweb.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? |
| ------------------------------- |
| |
| Adding a MIB to the client-side tools has two main effects: |
| |
| - it allows you to refer to MIB objects by name |
| (rather than having to use the numeric OIDs) |
| - it allows the results to be displayed in a more immediately |
| meaningful fashion. Not just giving the object names, but |
| also showing named enumeration values, and interpreting table |
| indexes properly (particularly for string and OID index values). |
| |
| Most of the tools (apart from 'snmptable') will work quite happily |
| without any MIB files at all - although the results won't be displayed |
| in quite the same way. |
| The same holds true for the agent - see the AGENT section for details. |
| |
| |
| There are two steps required to add a new MIB file to the tools. |
| Firstly, copy the MIB file into the appropiate location: |
| |
| cp MY-MIB.txt /usr/local/share/snmp/mibs |
| (which makes it available to everyone on the system) |
| |
| or |
| |
| mkdir $HOME/.snmp |
| mkdir $HOME/.snmp/mibs |
| cp MY-MIB.txt $HOME/.snmp/mibs |
| (which makes it available to you only) |
| |
| Note that the location of the shared MIB directory may be different |
| from that given here - particularly if you're working with a vendor |
| supplied distribution. See where the MIBs are currently installed, |
| and copy the new MIB to the same place. |
| |
| |
| Secondly, tell the tools to load this MIB: |
| |
| export MIBS=+MY-MIB |
| (load it for this session only) |
| |
| or |
| |
| echo "mibs +MY-MIB" >> $HOME/.snmp/snmp.conf |
| (load it every time) |
| |
| This will add the new MIB to the list of MIBs loaded by default. |
| Omitting the '+' will *replace* the list of MIBs to be loaded by |
| the specified (colon-separated) list - together with any MIBs that |
| they explicitly rely on. |
| 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. |
| |
| If you prefer to have the tools load all available MIBs (which |
| may slow them down), then set the MIBS environmental variable |
| (or the snmp.conf token "mibs") to the special value "ALL". |
| |
| Note that you need *both* steps. |
| |
| |
| |
| Why can't I see anything from the agent? |
| --------------------------------------- |
| |
| There are two main general causes of problems retrieving information |
| from the agent. Either the client tool may not like the request (and |
| refuse to send it at all), or the agent may not respond with anything |
| useful. The simplest way to distinguish between the two is to run the |
| command with the command-line option '-d'. |
| |
| If this doesn't display a hex dump of the raw outgoing packet, then |
| it's the client side which is dropping the request. Hopefully you |
| should see some form of error message, to help identify what's wrong. |
| |
| If this displays one or more outgoing dumps (but nothing coming back), |
| then the request is failing at the agent end. See the next entry for |
| more details. |
| |
| If you see dumps of both the outgoing request, and a response, but |
| no results are displayed, then either there may be a problem with |
| decoding the response (in which case you should see an error message), |
| or the agent may simply not support the requested information (and the |
| response is being discarded as irrelevant). |
| |
| |
| |
| Why doesn't the agent respond? |
| ----------------------------- |
| |
| Assuming that the agent is actually sending the request (see the |
| previous entry), there are two main likely causes for the agent not |
| to respond. Either it doesn't receive the request (e.g. it's being |
| blocked by a firewall or packet filtering), or it receives it, but |
| is unwilling (or unable) to process it. |
| |
| If the remote system is running the Net-SNMP agent, then the easiest |
| way to check what's going wrong is to shut down the agent, and re-start |
| it using the options: |
| -f -Le -d |
| This will display raw dumps of packets seen (or sent) by the agent, |
| just as the '-d' flag did for the client side in the previous entry. |
| |
| Restart the agent with these flags, and send the same query as before. |
| If the agent doesn't display anything in response to this request, then |
| it's probably some form of firewall settings, which are preventing the |
| agent from ever seeing the request. |
| |
| If the agent displays a dump of the incoming request, but nothing going |
| out, then the most likely cause is access control settings. See the |
| relevant entries in the AGENT section for details. |
| |
| A third possibility is that the agent *is* responding to the request, |
| but only after a long delay. This would be indicated by a series of |
| incoming packet dumps (showing various retries from the client side), |
| followed by several outgoing dumps - possibly long after the client |
| tool has given up in disgust. |
| See the entry |
| The agent worked for a while, then stopped responding. Why? |
| later in this section. |
| |
| The same basic causes could also affect other vendors' SNMP agents. |
| Please consult the relevant documentation for how to investigate and |
| address such problems. |
| |
| |
| |
| 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 UCD-SNMP-MIB::versionTag |
| instead of |
| snmpget -v1 -c public localhost UCD-SNMP-MIB::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. |
| |
| |
| |
| Why can't I see values in the <INSERT ENTERPRISE HERE> tree? |
| ----------------------------------------------------------- |
| |
| If you're walking a specific tree, but failing to see anything in |
| it, then the most likely cause is that the agent simply does not |
| implement those particular MIB objects. Or if it does, that the |
| access control or other configuration settings mean that there's |
| nothing for you to see there. |
| |
| However, if you're trying a basic "snmpwalk" with no explicit OID |
| specified, then this would also explain why you're not seeing any |
| enterprise-specific results. |
| |
| By default, unless given an explicit starting OID, then the 'snmpwalk' |
| command will display the contents of the 'mib-2' tree, containing most |
| of the IETF-standard management information supported by the agent. |
| When the agent reaches the end of this tree, it will return the first |
| enterprise-specific value, and 'snmpwalk' will recognise that this |
| marks the end of the (implicitly) request tree, and stop. No |
| enterprise-specific information will be displayed. |
| |
| To walk the whole tree, and see *all* the information that the |
| agent supports, specify a starting point of '.iso' or '.1'. |
| To walk a specific enterprise subtree, specify the root of this tree |
| as the starting point - e.g: |
| |
| snmpwalk -v1 -c public localhost UCD-SNMP-MIB::ucdavis |
| |
| There is more information about particular UCD-specific subtrees in |
| the AGENT section. |
| |
| |
| |
| The agent worked for a while, then stopped responding. Why? |
| ----------------------------------------------------------- |
| |
| There are three basic possibilities: |
| - the agent has crashed |
| - it is hanging |
| - it is temporarily overloaded |
| |
| Detecting whether the agent has crashed should be fairly straighforward. |
| If you can reliably reproduce this crash (e.g. by sending a particular |
| SNMP request), then contact the coders list for advice. |
| It's the other two cases that are probably more significant. |
| |
| To tell the difference between these two, try leaving the agent |
| undisturbed for a while, and then probe it using a single 'snmpget' |
| request, specifying a longer timeout (e.g. '-t 120'). If it now |
| responds, then something was probably sending requests (including |
| duplicate retries) faster than the agent could process them, and it |
| was building up a backlog. Try adjusting the timeout period and retry |
| frequency of these client requests, or look at improving the efficiency |
| of the implementation of the relevant MIB objects. |
| |
| If the agent remains unresponsive (particularly if the load on the |
| system is steadily climbing), then it's probably hanging, and all |
| you can really do is restart the agent. If you can identify what |
| causes this to happen, then contact the coders list for advice. |
| |
| |
| |
| Requesting an object fails with "Unknown Object Identifier" Why? |
| ---------------------------------------------------------------- |
| |
| If a general snmpwalk shows a particular entry, but asking for it more |
| specifically gives a "sub-identifier not found:" or "Unknown Object |
| Identifier" error, then that's a problem with the tool, rather than |
| the agent. |
| |
| Firstly, make sure that you're asking for the object by the right name. |
| Object descriptors are case-sensitive, so asking for 'sysuptime' will |
| not be recognised, but 'sysUpTime' will. |
| |
| Alternatively, the object may be defined in a MIB that hasn't been |
| loaded. Try loading in all the MIB files: |
| |
| snmpget -m ALL -v1 -c public localhost sysUpTime.0 |
| |
| or specify the name of the appropriate MIB explicitly: |
| |
| snmpget -v1 -c public myhost SNMPv2-MIB::sysUpTime.0 |
| |
| Note that this uses the name of the *module*, not the name of the file. |
| See the second entry in this section for the distinction. However, |
| if 'snmpwalk' displays the object by name, this is unlikely to be the |
| cause, and you should look closely at the exact object name you are using. |
| |
| |
| |
| Why do I get "noSuchName" when asking for "sysUpTime" (or similar)? |
| ------------------------------------------------------------------ |
| |
| Assuming that you do have access to this object, the most likely |
| cause is forgetting the "instance subidentifier". |
| |
| If you try walking the 'system' group, you should notice that all |
| of the results have a number after the MIB object name. This is |
| the "instance subidentifier" of that particular MIB instance. |
| |
| For values from the sysORTable, this basically provides an index into |
| the table, and should be very familiar. But the other values in the |
| system group also have an instance number displayed. For non-table |
| objects ("scalars"), this instance subidentifier will always be '0', |
| and it *must* be included when making a GET request. |
| |
| Compare the following: |
| |
| $ snmpget -v1 -c public localhost sysUpTime |
| Error in packet |
| Reason: (noSuchName) There is no such variable name in this MIB. |
| This name doesn't exist: system.sysUpTime |
| $ snmpget -v1 -c public localhost sysUpTime.0 |
| system.sysUpTime.0 = Timeticks: (69189271) 8 days, 0:11:32.71 |
| |
| This is a little less obscure when using SNMPv2c or v3 requests: |
| |
| $ snmpget -v 2c -c public localhost sysUpTime |
| system.sysUpTime = No Such Instance currently exists |
| |
| |
| |
| Why do I sometimes get "End of MIB" when walking a tree, and sometimes not? |
| -------------------------------------------------------------------------- |
| |
| This depends on which MIB modules are supported by the agent you are |
| querying and exactly what you're asking for. |
| |
| Note that a tree is walked by repeatedly asking for "the next entry" until |
| all the values under that tree have been retrieved. However, the agent has |
| no idea that this is what's happening - all it sees is a request for "the |
| next entry after X". |
| |
| If the object X happens to be the last entry in a sub-tree, the agent will |
| provide the next object supported (as requested) even though this will be |
| in a different subtree. It's up to the querying tool to recognise that |
| this last result lies outside the area of interest, and simply discard it. |
| |
| If the object X happens to be the last entry supported by the agent, it |
| doesn't have another object to provide, so returns an "end of MIB" |
| indication. The Net-SNMP tools report this with the message above. |
| |
| But in either case, the actual information provided will be the same. |
| |
| |
| |
| How do I use SNMPv3? |
| ------------------- |
| |
| The simplest form of SNMPv3 request (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 single setting |
| defPassphrase "Open the Door and see me" |
| instead. |
| |
| See the AGENT section for how to configure the agent for SNMPv3 access. |
| |
| |
| |
| I cannot set any variables in the MIB. |
| ------------------------------------- |
| |
| There are three possible reasons for this: |
| |
| Many MIB objects are defined as "read-only" and inherently cannot be |
| changed via SET requests. Attempts to do so will typically be dropped |
| by the 'snmpset' command without ever being sent to the agent. |
| |
| Of those objects that can in principle be changed, the agent may not |
| include the code necessary to support SET requests. (GET and GETNEXT |
| are much easier to handle - particularly for objects relating to the |
| internals of the underlying operating system). |
| |
| Even if SET support has been implemented, the agent may not be configured |
| to allow write access to this object. |
| |
| Ready-installed distributions (such as those shipped with Linux) tend |
| to be configured with read-only access to part of the mib tree (typically |
| just the system group) and no write access at all. |
| |
| To change this, you will need to set up the agent's access control |
| configuration. See the AGENT section for more details. |
| |
| Note that neither the community string "public" nor "private" can be |
| used to set variables in a typical default configuration. |
| |
| |
| |
| Variables seem to disappear when I try to set them. Why? |
| -------------------------------------------------------- |
| |
| This is actually the same as the previous question - it just isn't |
| particularly obvious, particularly when using SNMPv1. A typical |
| example of this effect would be |
| |
| $ snmpget -v1 -c public localhost 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" |
| |
| rather than "this variable doesn't exist". It may be the case that it |
| doesn't exist at all. It may exist but you don't have access to it |
| (although someone else with different administrative credentials might do). |
| Or it may exist, but you simply can't perform that particular operation |
| (e.g. changing it). |
| Similarly, the SNMPv2 error 'notWritable' means "not writable in |
| this particular case" rather than "not writable under any circumstances". |
| |
| If you are sure that the object is 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. |
| |
| |
| |
| Why can't I change sysLocation (or sysContact)? |
| ---------------------------------------------- |
| |
| Assuming that the access control settings should allow this, another |
| 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 Net-SNMP 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 configured via the 'snmpd.conf' file. |
| If there isn't such a config setting, then the write request will succeed |
| (assuming suitable access control settings), and the new value will be |
| retained the next time the agent restarts. |
| |
| |
| |
| I get an error when trying to set a negative value - why? |
| -------------------------------------------------------- |
| |
| This is a different problem. What's happening here is that the |
| routine that parses the arguments to the 'snmpset' command is seeing |
| the '-' of the new value, and treating it as a command-line option. |
| This normally generates an error (since digits typically aren't valid |
| command line options). |
| |
| The easiest way to solve this is include the "end-of-option" |
| indicator '--' in the command line, somewhere before the new value |
| (but after all of the options, obviously). For example: |
| |
| snmpset -v 2c -c public localhost -- versionRestartAgent.0 i -1 |
| |
| (This will also fail, since -1 isn't an acceptable value for this |
| particular object, but that's not the point here!) |
| |
| |
| |
| I get an error when trying to 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 ..... vacmGroupName.3.\"wes\" |
| or snmpget ..... 'vacmGroupName.3."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 automatically |
| accept all incoming traps. It must be configured with authorized |
| SNMPv1/v2c community strings and/or SNMPv3 users. Non-authorized |
| traps/informs will be dropped. |
| Please refer to the snmptrapd.conf(5) manual page for details. |
| |
| 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 fails or generates an error when triggered by |
| an incoming notification, then there are two likely causes. |
| |
| Firstly, the interactive shell environment may not be precisely |
| the same as that for programs executed by the snmptrapd daemon. |
| In particular, it's quite possible that the PATH environmental |
| variable may not include all the additional directories that are |
| commonly set up for a personal login configuration. To avoid this |
| problem (particularly for traphandler shell scripts), it's worth |
| giving the full path to all programs used within the script. |
| |
| Secondly, the snmptrapd daemon may not always recognise the |
| appropriate interpreter to use for a particular trap handler. |
| If this is the case, then you can specify this interpreter |
| explicitly as part of the trap handle directive: |
| |
| traphandle default /usr/bin/perl /usr/local/bin/log_it |
| |
| In this case, it's almost certain that you'll also |
| need to give the full path to the traphandle script (as shown) |
| |
| |
| |
| How big can an SNMP request (or reply) be? |
| ----------------------------------------- |
| |
| The protocol definition specifies a "minimum maximum" packet size |
| (484 bytes for UDP), which all systems must support, but does not |
| attempt to define an upper bound for this maximum size. This is left |
| to each individual implementation. |
| |
| The UCD software used a fixed size buffer of 1472 bytes to hold the |
| encoded packet, so all requests and responses had to fit within this. |
| The Net-SNMP releases handle packet buffers rather differently, and |
| are not subject to the same fixed restrictions. |
| |
| |
| |
| How can I monitor my systems (disk, memory, etc)? |
| ------------------------------------------------ |
| |
| In general, the Net-SNMP suite consists of relatively low-level |
| tools, and there is nothing included that is designed for high-level, |
| long-term monitoring of trends in network traffic, disk or memory |
| usage, etc. |
| |
| There are a number of packages available that are designed for this |
| purpose. Two of the most widely used are MRTG (http://www.mrtg.org/) |
| and RRDtool (http://oss.oetiker.ch/rrdtool/). There are also several |
| frontends built on top of RRDtool, including Cacti (http://www.cacti.net/) |
| and Cricket (http://cricket.sourceforge.net/). There are details of |
| how to set up Cricket to monitor some of the UCD extensions at |
| http://www.afn.org/~jam/software/cricket/ |
| |
| We have also set up a page that describes in detail how MRTG |
| can be set up to monitor disk, memory and cpu activity at |
| http://www.net-snmp.org/tutorial-5/mrtg/index.html |
| |
| There is also a web-based network configuration system "Net-Policy", |
| based upon SNMP. This is not strictly connected to the Net-SNMP project, |
| but a number of the core developers are also involved with that system. |
| See http://net-policy.sourceforge.net for more details. |
| |
| |
| |
| Applications complain about entries in your example 'snmp.conf' file. Why? |
| -------------------------------------------------------------------------- |
| |
| There *is* no example 'snmp.conf' shipped with the standard distribution. |
| |
| The configuration file 'EXAMPLE.conf' is designed as a config for |
| the agent, and should be installed as 'snmpd.conf' (note the 'd'). |
| The file 'snmp.conf' is intended for general configuration options, |
| applicable to all applications (via the SNMP library). |
| Rename (or merge) the 'snmp.conf' file to 'snmpd.conf', and this |
| should fix the problem. |
| |
| |
| |
| OK, what should I put in snmp.conf? |
| ---------------------------------- |
| |
| This is used to set common configuration values for most of the |
| applications, to avoid having to specify them every time. Examples |
| are the SNMPv3 settings mentioned above, defaults for which MIBs to |
| load and where from (see the second entry in the APPLICATIONS section), |
| and the default SNMP version, port and (if appropriate) community |
| string to use. |
| |
| Some of these (such as the MIB file location), might be best put in |
| a shared snmp.conf file (typically /usr/local/share/snmp/snmp.conf or |
| /etc/snmp/snmp.conf) to apply to all users of the system. Others |
| (particularly the SNMPv3 security settings), are more likely to refer |
| to a particular user, and should go in a personal snmp.conf file |
| (typically $HOME/.snmp/snmp.conf). |
| |
| See 'snmpget -H' and/or the snmp.conf(5) man page for more details. |
| |
| You can also use the "snmpconf" command to help you generate your |
| snmp.conf configuration file (just run it and answer its questions). |
| |
| |
| |
| PERL |
| ==== |
| |
| Where can I get the Perl SNMP package? |
| ------------------------------------- |
| |
| Joe Marzot's excellent Perl 'SNMP' module, is included in the Net-SNMP |
| source releases. It can be found located in the perl/SNMP subdirectory |
| of the source tree. This is accompanied by a number of Perl modules |
| grouped together under the NetSNMP namespace. |
| |
| The basic SNMP module (though not the NetSNMP additions), can also |
| be found at any Comprehensive Perl Archive Network (CPAN) mirror site, |
| under modules/by-module/SNMP. To find the CPAN site nearest you, |
| please see http://www.cpan.org/SITES.html. |
| |
| These Perl modules need to be used in conjunction with a compatible |
| version of the Net-SNMP library. Consult the README file in the SNMP |
| Perl distribution to find out which version of the library it needs. |
| |
| |
| |
| How do I install the Perl SNMP modules? |
| -------------------------------------- |
| |
| Assuming you have a reasonably new (and properly configured) Perl system, |
| this should be simply: |
| |
| cd perl |
| perl Makefile.PL |
| (press RETURN when prompted for host and community) |
| make |
| make test |
| make install (probably as root) |
| |
| |
| It might be possible to install the basic module using |
| |
| perl -MCPAN -e shell ; "install SNMP" |
| |
| but this has not been reliably tested, and very much relies on |
| having the correct version of the Net-SNMP library. |
| |
| There may also be appropriate pre-compiled versions of the Perl modules |
| available from the Net-SNMP project website, or your O/S vendor. |
| |
| |
| |
| But compiling this fails! Why? |
| ----------------------------- |
| |
| The Perl module tends to delve quite deeply into the internals of the |
| main Net-SNMP library, and so is quite sensitive to changes within the |
| library. It's important to use the correct version of the module, that |
| corresponds to the version of the library you have installed. If you're |
| working with a Net-SNMP source distribution, the appropriate version of |
| the Perl modules are shipped as part of the source code, but you *must* |
| have run "make install" on the main Net-SNMP distribution *first*. |
| |
| If you're working with a ready-installed version of the library, make |
| sure you obtain a compatible version of the Perl module. |
| |
| Note that the Perl modules will be compiled using the compiler |
| (and compiler settings) used for compiling the original perl binary, |
| *not* those used for compiling the Net-SNMP (or UCD) library. |
| If these are different (e.g. 'gcc' used for one and 'cc' for the other) |
| then this may well cause problems. It's much safer to use a consistent |
| environment for both. This issue is discussed in greater detail in |
| the README.solaris file. |
| |
| Also note that the v5 Net-SNMP suite *must* be configured to provide |
| shared libraries in order for the Perl modules to work correctly. This |
| is not necessary with the v4 UCD-SNMP libraries. |
| |
| |
| |
| Compiling the Perl module works OK, but 'make test' fails. Why? |
| -------------------------------------------------------------- |
| |
| That's difficult to answer in general. |
| Some of the Perl tests are rather picky, so this may simply be |
| some minor inconsistency between your precise setup, and the |
| expectations of the test environment. |
| |
| Check that you are working with the Perl distribution that matches |
| the SNMP libraries (use the 'perl/SNMP' in preference to CPAN), and |
| that you have installed the main libraries successfully (uninstall |
| any old versions if you're having trouble). |
| |
| If all this looks OK, and if most of the tests pass, then it's |
| probably safe to run 'make install' anyway. Probably. |
| |
| |
| |
| 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 many vendor distributions. |
| You'll need to install it. See the previous 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 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. |
| |
| |
| |
| Why aren't my mib files being read in? |
| ------------------------------------- |
| |
| The Net-SNMP library only loads a specific 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 working |
| with a fresh installation. |
| |
| |
| |
| I'm getting answers, but they're all numbers. Why? |
| ------------------------------------------------- |
| |
| This is related to the previous question. The results that you |
| receive do not depend on which MIBs are loaded - just on how the |
| agent was compiled and configured. |
| |
| Because the tools don't read in every MIB module they can find (and |
| the relevant MIB file may not be installed anyway), it is quite possible |
| for results from an agent to refer to modules that have not been loaded |
| (particularly with GETNEXT requests, or when walking a tree). |
| |
| The results will be reported quite correctly, but won't be translated |
| to use named identifiers or enumerations. To fix this, use the |
| environmental variables MIBS or MIBFILES (or the '-m' and '-M' flags) |
| to read in the relevant module files (assuming these are available). |
| |
| |
| |
| What does "Cannot find module (XXX-MIB)" mean? |
| --------------------------------------------- |
| |
| If this error is only generated for one or two modules, then it's |
| likely that the named modules are not being found - perhaps they're |
| not installed in the correct location, are not readable, or the |
| name being used is incorrect. 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 there are a large number of such errors, then it's more likely |
| that either the MIB files haven't been installed at all, or the |
| library is looking in the wrong place for them. |
| Try running "snmptranslate -Dparse-mibs" to see where the MIB files |
| are expected to be found. |
| |
| |
| |
| 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 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 an active 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 can I get more information about problems with MIB files? |
| ------------------------------------------------------------ |
| |
| The command 'snmptranslate' is used to translate between numeric |
| and symbolic forms of OIDs. It uses the same MIB parsing routines |
| as the commands that actually communicate with a network management |
| agent, but can be used standalone. As such, it is a useful tool |
| for identifying problems with reading in MIB files. |
| |
| In particular, the following options may be useful in |
| identifying problems: |
| -Pw warns about conflicting symbols |
| -PW prints more verbose warnings about other problems as well |
| (in both cases, ignore the 'xmalloc' reports) |
| -T provides sub-options for various views of these entries |
| |
| There are other '-P' options to control various aspects of MIB parsing. |
| See the 'snmptranslate(1)' and 'snmpcmd(1)' man pages for more details, |
| or the tutorial at |
| http://www.net-snmp.org/tutorial-5/commands/snmptranslate.html |
| |
| |
| |
| What's this about "too many imported symbols"? |
| --------------------------------------------- |
| |
| Any MIB file starts with an (optional) list of identifiers that |
| it "imports" from other files. The parser handles this using |
| a fixed size buffer to hold the import information. |
| There are two circumstances in which this can result in the |
| error message shown above. |
| |
| Firstly, if the MIB file refers to an unusually large number |
| of external identifiers. Handling this case requires a (trivial) |
| patch to the parsing code. Contact the coders list for advice. |
| (This is extremely rare - the only example that |
| we've come across is the Cabletron Trap MIB). |
| |
| Much more common is a syntax error in the IMPORTS clause of the |
| MIB file in question. In particular, check that this section ends |
| in a semicolon, before going on to the main MIB object definitions. |
| |
| |
| |
| Do I actually need the MIB files? |
| -------------------------------- |
| |
| Probably not. |
| The MIB files play two main roles - they are used to translate |
| between numeric OIDs and the corresponding textual names, and |
| they define the structure and syntax of the relevant MIB objects. |
| |
| This second role is perhaps best thought of in terms of a design |
| document. It's vital while developing an application (typically |
| the MIB module or handler within the agent), since it defines |
| what the application (MIB) must actually do. But once the code |
| has been written, the design document becomes redundent. |
| The agent then has the same information hardcoded into it |
| (literally!), and no longer needs the MIB file. |
| |
| The translation task is not strictly necessary - SNMP will |
| operate fine without any MIB files at all, as long as you're |
| happy to work with numeric OIDs throughout, and know which MIB |
| objects you're interested in. But it's much easier to work with |
| the (hopefully) meaningful names, enumeration tags and the like, |
| and to view the description of a particular object. |
| This requires having the relevant MIB files installed and loaded. |
| |
| |
| |
| AGENT |
| ===== |
| |
| What MIBs are supported? |
| ----------------------- |
| |
| The following MIBs are supported (at least in part and on some systems): |
| |
| - MIB-2 General network statistics |
| (RFC 1213 and subsequent revisions) |
| - Host Resources (RFC 1514 and 2790) |
| - SNMPv3 framework (RFCs 2571-5, 3411-3418) |
| (including USM, VACM, Target |
| and Notification MIBs) |
| - DisMan Event and Schedule MIBs |
| - MTA-MIB (sendmail) |
| - private UCD/Net-SNMP agent extensions |
| (monitor specified processes and disks, |
| memory, CPU, load average, plus extend |
| the agent using shell commands) |
| |
| See README.agent-mibs for details. |
| |
| Not all MIB modules are included by default on all systems, and some of |
| these may need to be explicitly requested when the software is first |
| configured and built. From Net-SNMP 5.3 and above, this primarily |
| applies to the MTA-MIB of those listed above. |
| |
| There are a few other MIB implementations distributed as part of the |
| source tarball, but these are basically unsupported and most of the |
| core developers have little or no experience with using them. |
| |
| |
| |
| What protocols are supported? |
| ---------------------------- |
| |
| The agent supports all three current versions of SNMP (v1, v2c and v3), |
| over both UDP and TCP transports, as well as acting as a SMUX (RFC 1227) |
| master agent, AgentX (RFC 2741) in both master and subagent roles, and |
| SNMP proxying. |
| |
| |
| |
| How do I configure the agent? |
| ---------------------------- |
| |
| That depends on what you want it to do, and what stage of the process |
| you have in mind. There are actually two very distinct ways you can |
| configure the agent. |
| |
| Firstly, you can determine what capabilities and defaults are included |
| within the library and agent, at the time that the software is first |
| built. This uses suitable flags to the 'configure' script, before |
| compiling the source. |
| As far as the agent is concerned, the most significant option is |
| '--with-mib-modules' (or '--with-out-mib-modules') to control which |
| MIBs will be supported by the agent. See the next few entries for |
| details. |
| |
| You can also control various aspects of the agent behaviour (and the |
| information it returns) at run time, via the 'snmpd.conf' configuration |
| file. Various aspects of this are touched on throughout this FAQ. Or |
| see the snmpd.conf(5) manual page for full details. |
| The "snmpconf" script can help in creating this config file. |
| Start off with 'snmpconf -g basic_setup' to get you going. |
| |
| |
| |
| How do I remove a MIB from the agent? |
| ------------------------------------ |
| |
| Deleting the text file for a MIB does not affect the agent (other than |
| to prevent it from recognising MIB object names in the config files). |
| It's necessary to tell the agent not to activate the relevant code that |
| actually implements these objects. There are three ways to do this: |
| |
| 1) re-run 'configure' to exclude the given MIB module(s) from the |
| build configuration, recompile, and reinstall: |
| |
| ./configure --with-out-mib-modules=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 |
| |
| With v5.3 and above, this can also be done by supplying the |
| relevant view name to the "rocommunity" or similar directive: |
| |
| rocommunity public default -V ourmib |
| |
| 3) disable the MIB at runtime |
| |
| snmpd -I -hr_system,hr_storage,hr_device,hr_other,.... |
| |
| Note that this relies on knowing which modules are used to |
| implement the relevant MIB objects. If you're not sure, |
| you can check which MIB modules are loaded by getting the |
| agent to report them as they are initialised: |
| |
| snmpd -Dmib_init -H |
| |
| Hopefully it should then be fairly obvious which ones to turn off. |
| |
| |
| |
| |
| I've installed a new MIB file. Why can't I query it? |
| ---------------------------------------------------- |
| |
| Similarly, installing a new MIB file isn't sufficient for the |
| agent to automatically support this MIB. It's necessary to have |
| some form of code which can provide the corresponding information. |
| The next few entries, and the following section (CODING) address |
| this issue in some detail. |
| |
| |
| |
| How do I add a MIB to the agent? |
| ------------------------------- |
| |
| As indicated above, this basically involves writing some code to |
| implement the objects defined in the new MIB. There are three basic |
| approaches that can be used to do this: |
| |
| - The agent can invoke an external command or shell script to |
| return the necessary information. There are several possible |
| variations on this approach - see the next entry for details. |
| |
| - The agent can pass the request off to another (sub-)agent, |
| which already implements the required MIB. Again, there are |
| several ways of doing this - including AgentX, SMUX and |
| proxied SNMP. See the next entry but one for details. |
| |
| - You can write code to implement the new MIB objects, and |
| include this within the agent. This is most commonly C |
| (or C++) code, although the agent can also support MIB modules |
| implemented in perl or (from 5.4) python. |
| See the next section (CODING) for more details. |
| |
| Note that there is no visible difference between external commands, |
| subagents, and modules implemented within the main agent itself. |
| Tools querying the agent will see a single MIB structure. |
| |
| |
| |
| What's the difference between 'exec', 'sh', 'extend' and 'pass'? |
| --------------------------------------------------------------- |
| |
| 'exec' will fork off the specified command and return the exit status |
| and/or the output. Any 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. The results |
| are returned in exactly the same way. |
| |
| 'extend' is also similar, but provides a richer and more flexible MIB |
| framework - both for configuring the exact command to be run, and for |
| displaying the results. |
| |
| None of these mechanisms require the command to have any knowledge of |
| 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. |
| |
| |
| 'pass' is a more general mechanism for implementing arbitrary MIB |
| objects. The specified command will be invoked for any request within |
| the named MIB subtree, and should return the information relevant to |
| the requested OID. |
| |
| 'pass-persist' is similar, but the command will continue running |
| even after the initial request has been answered. |
| |
| All of these mechanisms are described in the 'snmpd.conf(5)' man page, |
| in the section entitled "Extending Agent Functionality". |
| |
| |
| |
| What's the difference between AgentX, SMUX and proxied SNMP? |
| ----------------------------------------------------------- |
| |
| All three are protocols that can be used to make two or more agents |
| appear as one to the querying application. In each case, one agent |
| takes the role of "master", and delegates requests to one of the others |
| as and where this is appropriate. The differences between them mainly |
| relate to how data is represented, and the mechanisms for communication |
| between master and subagents. |
| |
| SMUX and proxy SNMP both essentially use the standard SNMP packet format. |
| The main difference is that a proxy SNMP subagent need not be aware that |
| it is acting in such a role. It typically listens on a non-standard port, |
| and simply receives requests as usual, forwarded from the master agent. |
| The main issue to be aware of is that such requests will appear to come |
| from the local host, and this may affect how the access control mechanisms |
| need to be set up. |
| |
| SMUX uses a similar packet format, but the subagent "registers" with |
| the master agent, providing a suitable password. The Net-SNMP (and UCD) |
| agent includes the possibility of acting as a SMUX master agent, but the |
| suite does not include a subagent API. Note that 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 |
| |
| AgentX support is included by default, but needs to be explicitly |
| activated in the master agent. Do this by adding the line |
| |
| master agentx |
| |
| to the snmpd.conf file before starting the agent. |
| |
| |
| |
| What about 'dlmod' - what's that about? |
| -------------------------------------- |
| |
| The choice of which C-coded modules to include within an agent (or |
| subagent) is usually made when the agent is first built. Adding new |
| MIB modules would therefore require re-compiling the agent. This is |
| not always convenient - particularly when working with a production |
| system, and/or pre-installed binaries. |
| |
| Dynamically loaded modules are a means of including a MIB implementation |
| module within the main SNMP agent (or an AgentX subagent) without needing |
| to re-compile and re-link the agent binary. Instead, details of the |
| module(s) to load are specified in the configuration file, and the agent |
| locates the files listed, and merges them in at run time. |
| |
| See http://www.net-snmp.org/tutorial-5/toolkit/dlmod/ for more information. |
| |
| |
| |
| Which should I use? |
| ------------------ |
| |
| That's not easy to answer in general. |
| |
| If there's an existing agent that already implements the desired new |
| MIB, then it makes sense to re-use that, via whatever extension protocol |
| it might support. Ideally, this would be an AgentX sub-agent, since the |
| AgentX protocol is deliberately designed for this purpose, and provides |
| a fuller and more reliable mechanism than either SMUX or proxied SNMP. |
| But if the target subagent only supports SMUX or basic SNMP, then that |
| would dictate the extension protocol to use. |
| |
| Implementing the module directly within the main agent (or via dlmod) |
| is probably the most efficient and reliable (since there's minimal |
| overheads between the code implementing the MIB module, and the agent |
| framework). But it does assume that there's a suitable mechanism for |
| retrieving the necessary information. |
| |
| If the new MIB is monitoring or managing some other subsystem, external |
| to the agent, then it may be necessary to embed a subagent within the |
| subsystem itself - particularly if there's no suitable public API to |
| retrieve the necessary information. In this case, AgentX is probably |
| the most appropriate way forward. |
| Unless you prefer to implement the missing public management API, |
| and develop a module within the main agent instead. |
| |
| |
| In terms of writing C code for the Net-SNMP agent, the way that the |
| (sub-)agent receives the request is more or less irrelevant. The |
| MIB module API was deliberately designed to be independent of any |
| extension mechanism being used - so the exact same module code could |
| be included as part of a pure-SNMP master agent, or an AgentX subagent, |
| either compiled in or dynamically loaded. No modifications should be |
| needed to the MIB module code itself - just to how it's compiled into |
| the appropriate application. |
| |
| |
| |
| 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 parties accordingly. |
| |
| The socket that the Net-SNMP master agent uses to listen for AgentX |
| registrations (and send appropriate requests) can be specified using |
| the option '-x'. |
| The command |
| "snmpd -x localhost:705 ...." |
| would start the agent listening on the TCP port 705 for connections |
| from the local system. |
| The same effect can also be obtained by adding the line |
| agentxsocket localhost:705 |
| to the file 'snmpd.conf'. |
| |
| The same option can be used with the Net-SNMP agent when running in |
| "subagent" mode, to specify the socket to register with (and receive |
| requests from). |
| So a subagent might connect to the master agent above (both running |
| on the same host), using: |
| "snmpd -X -x localhost:705 ...." |
| |
| A subagent running embedded within some other application will |
| typically not understand the same command-line options, so would |
| need to set the same configuration programmatically: |
| |
| netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID, |
| NETSNMP_DS_AGENT_X_SOCKET, "localhost:705"); |
| |
| With the example subagent code from the Net-SNMP tutorial, this line |
| would be added immediately before the 'init_agent' call. |
| |
| The same approach can also be used to listen on a different named |
| socket, using: |
| agentxsocket /tmp/agentx |
| agentxperms 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 earlier entry. |
| |
| |
| |
| How can I turn off SMUX support? |
| ------------------------------- |
| |
| Normally, you would use the command-line option '-I -{module}' to |
| disable the initialisation of a particular MIB module within the |
| agent. Unfortunately, it's not currently possible to turn off SMUX |
| support this way. |
| |
| The safest approach is to re-run configure with the option |
| "--with-out-mib-modules=smux", and recompile the agent. If this |
| is not possible, an alternative workaround might be to have the |
| agent 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? |
| ----------------------------------------------------------------------- |
| |
| This is the purpose of the SNMPv3 'context' field. Register the MIB |
| module a second time in a non-default context (see the relevant entry |
| in the CODING section for details), and specify this context when |
| querying the agent. The MIB module can use this context information |
| to determine which set of information to report. |
| Or you could register two completely different handlers for the same |
| OID (using different contexts), and the agent will invoke the appropriate |
| code. This holds for both MIB modules implemented within the main agent, |
| or AgentX subagents - the same approach will work for both. |
| |
| Contexts can also be used with proxied SNMP requests - just specify |
| the option '-Cn {context}' as part of the "proxy" entry. See the |
| 'snmpd.conf(5)' man page for details. |
| |
| It's currently not possible to support parallel MIB trees when using |
| SNMPv1 or SNMPv2c. In principle, it should be possible to use the |
| community string in a similar way, but this has not (yet) been implemented. |
| |
| This mechanism is only available with the v5 Net-SNMP agent. The v4 |
| UCD agent does not support contexts at all. Sorry about that. |
| |
| Another way to handle this would be to tweak one of the subagents to |
| use a different set of (non-standard) OID assignments - perhaps by |
| relocating the whole of the subtree to another (private) OID. This |
| is not ideal, but should work with all configurations. |
| |
| |
| |
| What traps are sent by the agent? |
| -------------------------------- |
| |
| The 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 config directive |
| 'linkUpDownNotifications'. See the 'snmpd.conf(5)' man page (under |
| ACTIVE MONITORING) for details. |
| |
| Similarly, it does not generate traps by default when one of the |
| monitored characteristics (disk usage, running processes, etc) enters or |
| leaves an error state. This can be configured using the 'defaultMonitors' |
| config directive (also documented under ACTIVE MONITORING). |
| |
| 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 needs to be told where to send them, |
| specifying the type of notification (v1 or v2 trap, or v2 inform) and |
| the community name to use. This uses the snmpd.conf directives 'trapsink', |
| 'trap2sink' and 'informsink' for the destination type, and 'trapcommunity' |
| for the community name. SNMPv3 destinations can be configured using the |
| directive 'trapsess'. See the 'snmpd.conf(5)' man page for details. |
| |
| Note that the type of trap generated is totally determined by these |
| directives - irrespective of which API call was used to trigger sending |
| the trap. See the trap-related entries in the CODING section for details. |
| |
| 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'). Probably not what was wanted! |
| |
| |
| |
| How can I send a particular trap to selected destinations? |
| ---------------------------------------------------------- |
| |
| This is not currently possible. All notifications will be sent to |
| all configured destinations. The agent does not (currently) support |
| notification filtering. |
| |
| There is a preliminary implementation of the snmpNotifyFilterTable |
| which is designed to allow this sort of selective trap direction. |
| However this is not currently active. (The tables are present and |
| can be manipulated and updated, but the information is not consulted) |
| Documentation on how to use this 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 '-Le' (or '-L') flag, to log messages to stderr. |
| |
| On the other hand, if 'ps' shows that the agent is not running, then |
| this is an error, and probably show that something went wrong in |
| starting the agent up. Check the agent log file for any error messages, |
| or run it with '-f -Le' and see what it reports. |
| |
| 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 basically the same problem described in the APPLICATIONS |
| section, in the entry |
| The agent worked for a while, then stopped responding. Why? |
| |
| See that entry for details. |
| |
| |
| |
| How can I stop other people getting at my agent? |
| ----------------------------------------------- |
| |
| Firstly, are you concerned with read access or write access? |
| |
| As far as changing things on the agent is concerned, there is relatively |
| little that can actually be altered (see the 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. Source-based |
| restrictions on SNMPv3 requests would need to use one of the "external" |
| mechanisms listed above. |
| |
| |
| |
| How can I listen on just one particular interface? |
| ------------------------------------------------- |
| |
| Normally, the agent will bind to the specified port on all interfaces |
| on the system, and accept requests received from any of them. However, |
| if a particular port (or ports) is specified when the agent is first |
| started, then it will only listen for requests on these particular |
| ports. |
| For example: |
| snmpd 127.0.0.1:161 |
| |
| would listen (on the standard port) on the loopback interface only, and: |
| |
| snmpd 10.0.0.1:6161 |
| |
| will listen on port 6161, on the (internal network) interface with |
| address 10.0.0.1. To listen on both of these interfaces (and no others) |
| provide a list of all the desired addresses: |
| |
| snmpd 127.0.0.1:161 127.0.0.1:6161 |
| |
| The AgentX port option ('-x') works in much the same way. |
| |
| |
| |
| How do I configure access control? |
| --------------------------------- |
| |
| The simplest way is to use the configure directives: |
| |
| rocommunity public (for SNMPv1/2c) |
| rwcommunity private |
| or |
| rouser user1 (for SNMPv3) |
| rwuser user2 |
| |
| These specify the community names or security names to accept for |
| read-only and read-write access to the whole of the supported MIB tree. |
| (Obviously you should change these names to match your requirements - |
| which is a particularly good idea in the case of 'rwcommunity'!) |
| |
| Note that you should *not* specify the same community name for both |
| rocommunity and rwcommunity directives. The rwcommunity setting |
| automatically provides read access, and having both lines (with the |
| same community name) may result in unexpected behaviour. |
| Only use both settings when specifying *different* community names. |
| The same holds true for rouser and rwuser. |
| |
| The two community directives can be restricted to allow requests |
| from particular sources, and all four can be restricted to a particular |
| subtrees or (from v5.3) a named view. See 'snmpd.conf(5)' for details. |
| |
| 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. |
| |
| |
| |
| 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 |
| specific 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 fields 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. |
| This is most relevant when defining "unusual" views, such as a single |
| row of a table. In most cases, this field should be omitted. |
| |
| The third field can be used to include or exclude particular portions |
| of the MIB from the named view. A single view can be built up using |
| several 'view' lines (with the same view name), including or excluding |
| OID subtrees as appropriate. |
| |
| 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 (or |
| near enough), 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/net-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/net-snmp/snmpd.conf file similar to the above. |
| Then re-start the snmpd agent. |
| |
| 3) Make sure the agent is running, and will respond to 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' entry. This contains the |
| same information, but in a form that's only meaningful internally. |
| Not only is the passphrase no longer visible in the config file, it |
| has actually been converted to a key that is only valid on the local |
| machine. If someone stole the new usmUser line from this system, |
| they could not use that information to access any of your other agents |
| (even if the usernames and passwords were the same). |
| |
| |
| |
| What's the difference between /var/net-snmp and /usr/local/share/snmp? |
| --------------------------------------------------------------------- |
| |
| The /var/net-snmp location is primarily used for information set |
| during the running of the agent, which needs to be persistent between |
| one run of the agent and the next. Apart from "createUser" (see |
| the previous entry), you shouldn't need to touch this file. |
| |
| All other user-provided configuration should go in the traditional |
| location (typically /usr/local/share/snmp/snmpd.conf or /etc/snmp). |
| |
| |
| |
| My new agent is ignoring the old snmpd.conf file. Why? |
| ----------------------------------------------------- |
| |
| The most likely explanation is that the new version of the agent is |
| looking in a different location than the previous one. This is commonly |
| experienced when replacing a ready-installed version (e.g. from a vendor |
| distribution), with the current release installed from the source. |
| |
| 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? |
| |
| |
| |
| 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* automatically generate traps |
| when the usage strays outside the configured bounds. |
| See the earlier FAQ entry |
| What traps are sent by the agent? |
| for more information. |
| |
| |
| |
| What do the CPU statistics mean - is this the load average? |
| ---------------------------------------------------------- |
| |
| No. Unfortunately, the original definition of the various CPU |
| statistics was a little vague. It referred to a "percentage", |
| without specifying what period this should be calculated over. |
| It was therefore implemented slightly differently on different |
| architectures. |
| |
| The 5.4 release has clarified the situation, and standardised on |
| calculating these percentages over a minute. The relevant MIB |
| descriptions have been updated to make the desired behaviour |
| more explicit. |
| |
| The Net-SNMP agent also includes "raw counters", which can be used |
| to calculate the percentage usage over any desired period. This is |
| the "right" way to handle things in the SNMP model. The original |
| percentage objects have been deprecated, and may possibly be removed |
| in a future release of the agent. |
| |
| Note that this is different from the Unix load average, which is |
| available via the loadTable, and is supported on all architectures. |
| |
| |
| |
| How do I get percentage CPU utilization using ssCpuRawIdle? |
| ----------------------------------------------------------- |
| |
| This one of the "raw counters" mentioned in the previous entry. |
| You need to take two readings of this object and look at the |
| difference between them. That difference divided by the total |
| number of 'ticks' between the two readings (where one tick is |
| probably 0.01 seconds) will give you the percentage utilization |
| over that period. |
| |
| |
| |
| What about multi-processor systems? |
| ---------------------------------- |
| |
| The CPU objects (both percentages and raw counters) were designed to |
| monitor the overall CPU activity of a system, and typically reflect |
| whatever the underlying operating system reports for the (single) |
| CPU statistics information. How these are handled for a multi-CPU |
| system will probably differ from one O/S to another, and will need |
| to be investigated for each system individually. |
| |
| The htProcessorTable was designed to handle monitoring multi-CPU |
| machines, but the Net-SNMP implementation has up to now treated |
| most systems (with the honourable exception of Solaris, and more |
| recently Linux) as implicitly single-CPU. |
| |
| With the 5.4 release, there is now a cleaner framework for reporting |
| on multi-CPU equipment, and it is hoped that an increasing number |
| of systems will be able to report suitable processor information. |
| Also with the 5.4 release, for the first time the agent will report |
| the hrProcessorLoad value properly, which should provide some simple |
| per-CPU statistics. |
| |
| |
| |
| The speed/type of my network interfaces is wrong - how can I fix it? |
| ------------------------------------------------------------------- |
| |
| Some operating systems will provide a mechanism for determining |
| the speed and type of network interfaces, but many do not. In such |
| cases, the agent attempts to guess the most appropriate values, |
| usually based on the name of the interface. |
| |
| The snmpd.conf directive "interface" allows you to override these |
| guessed values, and provide alternative values for the name, type |
| and speed of a particular interface. This is particularly useful |
| for fast-ethernet, or dial-up interfaces, where the speed cannot be |
| guessed from the name. |
| |
| See the snmpd.conf(5) man page for details. |
| |
| |
| |
| The interface statistics for my subinterfaces are all zero - why? |
| ---------------------------------------------------------------- |
| |
| Unfortunately, most kernels that support multiple logical |
| interfaces on a single physical interface, don't keep separate |
| statistics for each of these. They simply report the overall |
| statistics for the physical interface itself. |
| |
| There's no easy way around this problem - the agent can only |
| report such 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 file manually, |
| or run snmpconf to help you create one. At the very least, you |
| will need some form of access control configuration, if the agent |
| is to be of any use whatsoever. This can be as simple as: |
| |
| rocommunity public |
| |
| See the snmpd.conf(5) manual page or relevant entries in this |
| FAQ for further details. |
| |
| |
| |
| The system uptime (sysUpTime) returned is wrong! |
| ----------------------------------------------- |
| |
| Oh no it's not. |
| The defined meaning of 'sysUpTime' is |
| "the time ... since the *network management* |
| portion of the system was re-initialized." |
| |
| In other words, when the snmp agent was started, not when the |
| system itself last booted. This latter information is available |
| in the Host Resources MIB as "hrSystemUpTime.0" |
| Note that even if the full Host Resources is not supported on |
| your system, it's worth configuring in the system portion using |
| |
| '--with-mib-modules=host/hr_system' |
| |
| and recompiling. This particular group is reasonably likely to |
| work, even if some of the other more 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. |
| |
| |
| |
| The compilation is complaining about missing libraries. Why? |
| ----------------------------------------------------------- |
| |
| This has been seen in a number of guises over the years - most |
| commonly on Linux systems (although the problem may also occur |
| elsewhere). A typical installation may not always include the full |
| set of library links required for building the Net-SNMP software. |
| |
| This problem can usually be fixed by installing the missing packages |
| (typically the development version of a package that is already there). |
| |
| Examples of this that we have come across include: |
| |
| -lelf elfutils-devel |
| -lbz2 bzip2-devel |
| -lselinux libselinux-devel |
| -lcrypto openssl/openssl-devel |
| -lbeecrypt libbeecrypt/beecrypt/beecrypt-devel. |
| |
| These are the names of the RedHat/Fedora RPMs. Other distributions |
| or O/S's may use different names, but the basic idea should be the |
| same. |
| |
| A alternative quick fix is to add the missing symbolic link, using |
| something like: |
| ln -s libelf.so.1 /usr/lib/libelf.so |
| |
| giving the appropriate generic library name from the error message, |
| and the correct number for whichever version of this library you |
| have installed. |
| |
| |
| |
| 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? |
| ------------------------------------------------- |
| |
| There are three main methods for integrating external C code |
| within the agent. |
| |
| The code can be compiled directly into the agent itself, it |
| can be loaded dynamically while the agent is running, or it can |
| be compiled into a separate application (a "subagent") which |
| communicates with the main master agent. All three approaches |
| have been touched on elsewhere within this FAQ. |
| |
| As far as the module code is concerned, all three mechanisms |
| use exactly the same module API. So a module developed for use |
| directly within the agent, could also be included within a subagent, |
| or loaded dynamically with no (or minimal) code changes needed. |
| |
| Most of this section is concerned with more detailed aspects |
| of developing such code - including the 'mib2c' tool, which can |
| handle generating a basic code framework for implementing a |
| given set of MIB objects. |
| |
| |
| |
| How does the agent fetch the value of a MIB variable from the system? |
| -------------------------------------------------------------------- |
| |
| That's typically the hardest bit of implementing a new MIB module, |
| and is the one thing that 'mib2c' can't help with. It very much |
| depends on the MIB variable concerned (and often the underlying |
| operating system as well). |
| |
| Relatively few MIB modules are completely self-contained, with all |
| the information held internally within the agent, and all updates |
| being done via SNMP requests. Such MIB modules can be implemented |
| fairly easily. |
| |
| More commonly, the agent needs to provide an SNMP-based interface to |
| information held elsewhere, perhaps in the operating system kernel or |
| some other application. Handling this is much more complex - since |
| a lot depends on what mechanisms are provided for retrieving (and |
| possibly updating) this information. |
| |
| See the existing MIB modules in the Net-SNMP source tree for various |
| examples of assorted approaches to this task. |
| |
| |
| |
| Mib2c complains about a missing "mib reference" - what does this mean? |
| --------------------------------------------------------------------- |
| |
| This basically means that it hasn't loaded the MIB file containing |
| the definition of the MIB subtree you're trying to implement. This |
| might be because it hasn't been installed, the name is wrong, or |
| (most likely), because it isn't in the default list. See the MIBS |
| section for more details. |
| |
| |
| |
| 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. |
| |
| |
| |
| What's the difference between the various mib2c configuration files? |
| ------------------------------------------------------------------- |
| |
| Most of the mib2c config files are concerned with implementing |
| MIB tables, and generate various alternative code templates. |
| These basically fall into four distinct categories. |
| |
| 'mib2c.raw-table.conf' is the lightest of the templates, and |
| just provides a fairly basic table framework. Most of the work |
| of implementing the table - detecting which row is required for a |
| given request, retrieving or updating the relevant column values, |
| and interacting with the underlying subsystem - are all left to |
| the MIB programmer. |
| |
| The second group of templates - 'table_data', 'container' and |
| 'tdata' - all share the same basic model (although the internal |
| details are rather different). The MIB implementer should define a |
| data structure to represent a row of the table, and the helper then |
| takes care of holding the table internally, as a collection of such |
| per-row data structures. This includes identifying which row is |
| required for a given request. Retrieving or updating the appropriate |
| column value is left to the MIB programmer, although the generated |
| framework includes most of the necessary code. |
| Allied to this is a fourth "internal data" mib2c configuration |
| file ('create-dataset') which handles the individual columns as |
| well. This is the closest to a Plug-and-Play configuration, and |
| the MIB implementer only needs to be concerned with any special |
| processing, such as linking the table with the underlying subsystem. |
| |
| The third style of mib2c config assumes that the table data is |
| held externally to the helper - either within the MIB module code |
| itself, or in the external subsystem. The generated code framework |
| includes routines to "iterate" through the rows of the table, with |
| the iterator helper simply deciding which row is required for a |
| particular request. Once again, the MIB programmer must handle |
| retrieving or updating the appropriate column value, although the |
| generated framework includes most of the necessary code. |
| There is a variant of this config ('iterate_access') which works |
| in basically the same way. However this tries to separate out the |
| standard processing, from the code that needs to be amended by the |
| programmer for retrieving and updating the individual column values. |
| |
| This is also the idea behind the final table-oriented mib2c config |
| template - 'mib2c.mfd.conf' (or "MIBs for Dummies"). This is a much |
| more flexible framework, which can be used with either internally |
| held data, or iterating through an external representation. The |
| distinguishing feature of this framework is that it separates out |
| standard and table-specific processing, at a much finer level of |
| detail than the others. |
| |
| |
| The other mib2c config templates are concerned with implementing |
| scalar objects ('scalar', 'int_watch'), code to generating traps |
| ('notify'), and various specialised requirements. There is also a |
| template ('old-api') to generate code suitable for the previous v4 |
| UCD agent - though this is not particularly complete or reliable. |
| It's probably better to use a pure v4 mib2c environment (or switch |
| wholeheartedly to the v5 style). |
| |
| |
| |
| Which mib2c configuration file should I use? |
| ------------------------------------------- |
| |
| The answer to that heavily depends on the characteristics of the |
| MIB objects being implemented. Of the handler-based table frameworks, |
| 'tdata' is more appropriate for tables that can be stored (or a copy |
| cached) within the agent itself, while 'iterate' is more relevant to |
| reporting data from outside the agent. |
| The raw interface is only suitable in very specific circumstances, |
| so it's probably sensible to start with one of the other frameworks |
| first, and only look at this if none of the alternatives seem to work. |
| |
| The decision between the handler-based configs and MfD is more a |
| matter of the style of programming to use. Most of the frameworks |
| define a single handler routine to process an incoming request, so |
| all of the code is listed together, with the MIB programmer inserting |
| table-specific processing into this single block of code. |
| The MfD provides a series of individual object-specific routines, |
| each concerned with one very specific task, and hides as much as |
| possible from the programmer. |
| |
| If you like to understand the broad thrust of what's happening, |
| then one of the handler-based approaches would be the best choice. |
| If you prefer to concentrate on the nitty-gritty of a given table, |
| and are happy to trust that the rest of the processing will work |
| correctly, then the MfD framework would be more appropriate. |
| |
| For implementing a group of scalar objects, then the choice is |
| simple - use 'mib2c.scalar.conf'. Similarly, for generating traps |
| or informs, use 'mib2c.notify.conf'. |
| |
| |
| |
| 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? |
| ------------------------------------------- |
| |
| Many of the MIB modules shipped with the Net-SNMP agent still |
| use the v4 "traditional" MIB module API, but an increasing number |
| use one of the newer v5 helper-based handlers. All of these can |
| be found under 'agent/mibgroup' |
| |
| The 'tdata' helper is used in the new DisMan Event, Expression |
| and Schedule MIB modules (see 'disman/{event,expr,schedule}/*'). |
| The similar 'dataset' helper is used in the older DisMan Event |
| MIB implementation (see 'disman/mteEvent*') and the Notification |
| Log MIB (see 'notification-log-mib/*'), used by 'snmptrapd' to |
| log incoming traps. |
| |
| The basic iterator handler is used in a number of modules, such |
| as the TCP and UDP table implementations (mibII/tcpTable & |
| mibII/udpTable), VACM context handling (mibII/vacm_context) and |
| various tables relating to agent internals (agent/*). These show |
| a number of different approaches to using the iterator helper, so |
| it's worth comparing them. |
| |
| The two examples/netSnmpHostsTable* modules provide a contrast |
| between the iterator and iterator_access helpers. |
| |
| There are an ever-increasing number of examples based on the |
| MfD framework (see '{if,ip,tcp,udp}-mib/'). Much of this code |
| is not intended to be viewed directly, but these individual files |
| are clearly commented to distinguish between internal implementation |
| and public code. |
| |
| The Net-SNMP agent does not currently include any MIB modules |
| using the array-user container-based helper. The best examples |
| of this are to be found in the net-policy project. |
| See http://net-policy.sourceforge.net/ |
| |
| |
| |
| Where should I put the files produced by 'mib2c'? |
| ------------------------------------------------ |
| |
| If you're using the main source tree to compile your new module, then |
| put these two files (mymib.[ch]) in the directory 'agent/mibgroup'. |
| You should then re-run configure to add in your new module |
| ("configure --with-mib-modules=mymib") and recompile. |
| |
| If you've got a number of new modules to add, it might be |
| sensible to put them all into a single subdirectory of 'mibgroup'. |
| Then create a header file, listing the individual components. |
| This might look something like: |
| |
| config_require(mymib/myObjects) |
| config_require(mymib/myTable) |
| config_require(mymib/myOtherTable) |
| |
| If this was saved as the file 'mymib.h', then the same configure |
| line given above, would pull in all three modules. See the |
| current contents of 'agent/mibgroup' for examples of this. |
| |
| |
| |
| 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. |
| |
| |
| |
| 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 get the agent to generate a trap (or inform)? |
| ------------------------------------------------------ |
| |
| There are two aspects to generating a trap - knowing *how* to |
| do this, and knowing *when* to do so. |
| |
| How to generate a trap is reasonably simple - just call one of |
| the trap API routines ('send_easy_trap()' or 'send_v2trap') with |
| the relevant information (generic and specific trap values, or a |
| varbind list respectively). |
| |
| The 'mib2c.notify.conf' configuration file can be used to |
| construct a suitable template routine for generating a trap, |
| including building the variable list from the MIB trap |
| definition. These variables can then be given suitable values, |
| before invoking the 'send_v2trap' call to actually send the trap. |
| See the 'snmp_trap_api(3)' man page for further details. |
| |
| Note that these APIs are only available within the agent (or |
| subagents), and are not available to stand-alone applications. |
| The code for 'snmptrap' shows an approach to use in such a case. |
| |
| |
| Determining *when* to generate the trap (either directly or |
| via the mib2c-generated routine) is often harder. If the trap |
| is generated in response to some action within the agent, (e.g. |
| as the result of a SET), then this isn't too much of a problem. |
| |
| But if the trap is intended to report on a change of status |
| (e.g. a network interface going up or down, or a disk filling up), |
| then actually detecting this is non-trivial. 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. |
| |
| The simplest way to handle this is via the DisMan Event MIB, |
| which is designed for exactly this purpose. As long as you can |
| specify MIB object(s) to monitor, and the values or thresholds |
| that should trigger a notification, then this module can check |
| these values regularly, and automatically send a suitable trap |
| when appropriate. See the 'snmpd.conf(5)' man page (under |
| ACTIVE MONITORING) for details. |
| |
| Otherwise, you'd need to use the routines documented in |
| 'snmp_alarm(3)' to regularly invoke a monitoring routine. This |
| could check the necessary conditions (which need not be MIB |
| objects), and call the 'send_xxx_trap()' routine when appropriate. |
| |
| |
| |
| How can I get the agent to send an SNMPv1 (or SNMPv2c) trap? |
| ----------------------------------------------------------- |
| |
| It doesn't make any difference whether you use the v1-style |
| API call 'send_easy_trap' or the v2-style 'send_v2trap' - what |
| matters is the directive(s) in the snmpd.conf file. |
| |
| If this file contains 'trapsink', then the agent will send |
| an SNMPv1 trap. If this file contains 'trap2sink', then the |
| agent will send an SNMPv2c trap. And if this file contains |
| both, then the agent will send *two* copies of this trap. |
| |
| See the entry |
| Where are these traps sent to? |
| in the AGENT section for details. |
| |
| |
| |
| How can I get the agent to include varbinds with an SNMPv1 trap? |
| --------------------------------------------------------------- |
| |
| There are two ways to do this. You can either use the |
| 'send_v2trap' call and give a varbind list, starting with |
| the v2-equivalent of the SNMPv1 trap, followed by the |
| additional varbinds. |
| |
| Alternatively, you can use the API call 'send_trap_vars' |
| which takes the same generic/specific trap values as |
| 'send_easy_trap', plus the list of additional varbinds. |
| |
| In either case, you also need to have 'trapsink' in the |
| snmpd.conf file. The resulting trap will be identical, |
| whichever approach is used. |
| |
| |
| |
| How can I get the agent to send an SNMPv1 enterprise-specific trap? |
| ------------------------------------------------------------------ |
| |
| There are two ways to do this. You can either use the |
| 'send_v2trap' call and give a varbind list, starting with |
| the v2-equivalent of the SNMPv1 trap, followed by the |
| additional varbinds. |
| |
| Alternatively, you can use the (undocumented) API call |
| 'send_enterprise_trap_vars' which takes the same parameters |
| as 'send_trap_vars', plus the enterprise OID to use (in the |
| usual name/length form). See the code file 'agent_trap.c' |
| |
| In either case, you also need to have 'trapsink' in the |
| snmpd.conf file. The resulting trap will be identical, |
| whichever approach is used. |
| |
| |
| |
| How can I get the agent to send an SNMPv3 trap (or inform)? |
| ---------------------------------------------------------- |
| |
| It doesn't matter which API call you use to specify the |
| trap - 'send_easy_trap', 'send_v2trap' or one of the other |
| calls mentioned above. Generating an SNMPv3 notification |
| (rather than a community-based one) is controlled by the |
| snmpd.conf file. |
| |
| To send an SNMPv3 trap, this file should contain a |
| 'snmpsess' directive, specifying the version, security |
| level, user name and passphrases (if applicable), as |
| well as the destination address. This is basically |
| the same as the command line required for sending the |
| trap manually, using 'snmptrap'. |
| |
| Note that (unlike 'snmptrap') this directive does *not* |
| read default settings from an 'snmp.conf' file, so these |
| must be specified explicitly in the 'snmpsess' line. |
| |
| |
| |
| Why does calling 'send_v2trap' generate an SNMPv1 trap (or vice versa)? |
| ---------------------------------------------------------------------- |
| |
| The two versions of the trap API calls are concerned with how |
| the trap is represented when it is passed *in* to the API, not |
| the version of the trap PDU that will actually be generated by |
| the agent. That is determined by the configuration token used |
| to set up the trap destination. |
| |
| Remember that in general, all traps are sent to all destinations. |
| This means that a trap specified using the SNMPv1 trap syntax |
| needs to be converted to the SNMPv2 format before it can be sent |
| to an SNMPv2 (or SNMPv3) destination. Similarly, a trap specified |
| using the SNMPv2 syntax needs to be converted to the SNMPv1 format |
| before it can be sent to an SNMPv1 sink. |
| |
| Essentially, the API call to use depends on what you asking for, |
| which is not necessarily what the recipients will actually get! |
| See 'snmp_trap_api(3)' for a fuller explanation. |
| |
| |
| |
| 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 |
| ====== |
| |
| 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." |
| |
| |
| |
