      Frequently Asked Questions (FAQ) for the UCD/Net SNMP package
      =============================================================
		       FAQ Author: Dave Shield
		        ucd-snmp Version: 4.2
		ucd-snmp Project Author: Wes Hardaker
		Email: net-snmp-coders@lists.sourceforge.net

TABLE OF CONTENTS
=================

 TABLE OF CONTENTS
 GENERAL
   What is it?
   Where can I get it?
   What documentation is available?
   Are there binaries available?
   What's the difference between UCD-SNMP and Net-SNMP?
   What operating systems does it run on?
   What happens if mine isn't listed?
   Does it run on Windows?
   How do I find out about new releases?
   How can I find out what other people are doing?
   How do I submit a patch or bug report?
   What's the difference between SNMPv1, SNMPv2 and SNMPv3?
   What are all these different SNMPv2's anyway?
   Which versions of SNMP are supported in this package?
   Where can I find more information about network management?
   Is ucd-snmp thread safe?
 APPLICATIONS
   How do I add a MIB?
   How do I add a MIB to the tools?
   Why can't I see values in the <INSERT ENTERPRISE HERE> tree?
   Requests always seem to timeout, and don't give me anything back.  Why?
   I can see the system group, but nothing else.  Why?
   Requesting an object fails with "sub-identifier not found"  Why?
   Why do I sometimes get "End of MIB" when walking a tree, and sometimes not?
   I cannot set any variables in the MIB.
   Variables seem to disappear when I try to set them.  Why?
   I get an error when trying to set a negative value - why?
   How do I send traps and notifications?
   How do I handle traps and notifications?
   How do I use SNMPv3?
   How big can an SNMP request (or reply) be?
   How can I monitor my systems (disk, memory, etc)?
   Applications complain about entries in your example 'snmp.conf' file.  Why?
   OK, what should I put in snmp.conf?
 MIBS
   Where can I find a MIB compiler?
   I can't load any of the mib files, and they seem to be missing
       the first two characters of the filename.  What's happening?
   Why aren't my mib files being read in?
   I'm getting answers, but they're all numbers. Why?
   The parser doesn't handle comments properly. Why not?
   How do I replace MIB values with new ones ?
   How can I get more information about these MIB file problems?
   What's this about "too many imported symbols"?
 PERL
   Where can I get the perl SNMP package?
   How do I install the Perl SNMP module?
   But compiling this 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?
 AGENT
   What MIBs are supported?
   What protocols are supported?
   How do I configure the agent?
   How do I add a MIB to the agent?
   What's the difference between 'exec', 'sh' and 'pass'?
   What's the difference between AgentX, SMUX and proxied SNMP?
   What traps are sent by the agent?
   When I run the agent it runs and then quits without staying around. Why?
   How can I stop other people getting at my agent?
   How can I listen on just one particular interface?
   How do I configure access control?
   I don't understand the new access control stuff - what does it mean?
   How do I configure SNMPv3 users?
   The 'createUser' line disappears when I start the agent.  Why?
   What's the difference between /var/ucd-snmp and /usr/local/share/snmp?
   My new version is ignoring the old snmpd.conf file. Why?
   Why am I getting "Connection refused"?
   I'm getting errors about "bad security model" - why?
   I'm getting errors about "bad prefix match parameter" - why?
   Why can't I see values in the UCDavis 'extensible' or 'disk' trees?
   Why can't I see values in the UCDavis 'memory' or 'vmstat' tree?
   What do the CPU statistics mean - is this the load average?
   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?
   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!
   The Host Resources information is wrong (and/or doesn't even compile)!
 CODING
   How do I compile with 'cc' instead of 'gcc'?
   But gcc doesn't compile it successfully on my new Solaris system. Why not?
   How do I write C code to integrate with the agent?
   How does the agent fetch the value of a variable from the system?
   I've created a new module with 'mib2c' but it doesn't work.  Why not?
   Mib2c only handles a single table in my MIB. How can I fix this?
   Mib2c complains about a missing "mib reference" - what does this mean?
   How can I get the agent to generate a trap (or inform)?
   I'm getting an error "autoheader: not found" - what's wrong?
   Why is the project workspace empty under Visual C++?
   Why are packets requesting the same information larger with UC-Davis SNMP ?
   What ASN.1 parser is used?
   What is the Official Slogan of the ucd-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?
------------------

WWW:
  Download:
    - http://download.sourceforge.net/net-snmp/
  Web page:
    - http://www.netsnmp.org/
  Project page:
    - http://sourceforge.net/projects/net-snmp/

FTP:
  - ftp://ucd-snmp.ucdavis.edu/ucd-snmp.tar.gz
  - ftp://sunsite.cnlab-switch.ch:/mirror/ucd-snmp/ucd-snmp.tar.gz
  - ftp://ftp.win.ne.jp/pub/network/snmp/ucd-snmp/ucd-snmp.tar.gz
  - ftp://ftp.chg.ru/pub/networking/management/snmp/ucd-snmp/ucd-snmp.tar.gz
  - ftp://mirror.aarnet.edu.au/pub/ucd-snmp/ucd-snmp.tar.gz
  - ftp://archive.logicnet.ro/mirrors/ucd-snmp.ucdavis.edu/


What documentation is available?
-------------------------------

	This FAQ (!)
	README
	INSTALL
	PORTING
	EXAMPLE.conf
	man pages for the individual tools, files and the API
	A guide for extending the agent
	A Tutorial at http://www.netsnmp.org/tutorial/

      Most of this documentation (plus archives of the mailing lists)
	 is also available on our web page:

        	http://www.netsnmp.org/



Are there binaries available?
----------------------------

  - There are binaries for some systems available in the binaries
    directory on the ftp site.



What's the difference between UCD-SNMP and Net-SNMP?
---------------------------------------------------

  Not a great deal, really.
  Although the project originally started at UC Davis (hence the name),
  and it has always been based there, most of the contributors have had
  little or no connection with this institution.

    The recent move to SourceForge is 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 release will be the last version under the UCD banner.
  Future releases will be made under the name 'net-snmp'.   The code
  base will remain more or less the same, though we may take advantage
  of the change of name to restructure the code somewhat.  Any changes
  in API will be clearly marked, and kept to a minimum.



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:

	* HP-UX (9.01 to 10.20)
	* Ultrix (4.2 to 4.5)
	* Solaris (2.3 to 2.8) and SunOS (4.1.2 to 4.1.4)
	* OSF (4.0, 3.2)
	* NetBSD (1.5alpha to 1.0)
	* FreeBSD (4.1 to 2.2)
	* BSDi (4.0.1 to 2.1)
	* Linux (kernels 2.2 to 1.3)
        * AIX (4.1.5, 3.2.5)
        * OpenBSD (2.8, 2.6)
        * Irix (6.5 to 5.1)

  See the next question but one for the status of Windows support.

  Certain systems (e.g. HP-UX 11, Irix?) fail to compile particular
  portions of the agent.  These can usually be persuaded to compile
  (at the loss of some functionality) by omitting the modules affected.
  See the next question for more details.

  Also note that the presence of a particular configuration in this
  list does not imply a perfect or complete implementation.  This is
  simply what various people have reported as seeming to work. (Or more
  frequently, the configurations people have reported problems with
  that we think we've fixed!)



What happens if mine isn't listed?
---------------------------------

    Try "configure --enable-mini-agent --with-defaults".
  If configure fails with "invalid configuration" messages,
  contact the coders list for advice.  Otherwise, see if this
  minimal agent compiles successfully.

    If so, try adding the missing mibgroups (either one at a
  time or en masse, depending how adventurous you're feeling),
  using the configure option '--with-mib-module'.
    If a particular module fails to compile, omit it using
  '--with-out-mib-module', and try again.

  Either way, try it and let us know how you get on (see below for how).
	


Does it run on Windows?
----------------------

  The basic suite should compile and run on Win32 platforms.
  This includes the library and command-line tools (apart perhaps
  from 'snmpdtrapd').

    The basic architecture of the agent builds, but the MIB-II
  (and other) modules do not (which rather negates the point!).
  Note that the UCD pass-through extensions do not work under Windows.

  Volunteers to assist in implementing Windows versions of these
  modules are likely to welcomed with open arms :-)

    Further details of Windows support (currently Visual C++ 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://lists.sourceforge.net/mailman/listinfo/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://sourceforge.net/patch/?group_id=12694



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://lists.sourceforge.net/mailman/listinfo/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.



How do I submit a patch or bug report?
-------------------------------------

  All bug reports should be submitted to the bug database through the
  interface found at http://sourceforge.net/bugs/?group_id=12694.  Be
  sure to include the version of the package that you've been working
  with, the output of the command 'uname -a', the precise command that
  triggers the problem and a copy of the output it produces.

    All patches should be submitted to the patch manager at
  http://sourceforge.net/patch/?group_id=12694.  If possible, submit a
  bug report describing the patch as well (referencing it by its patch
  number) since patch manager doesn't contain a decent description
  field.

    There is also a support database at
  http://sourceforge.net/patch/?group_id=12694 where "I need help
  with" questions can be submitted.  Be advised that the people
  answering these kinds of questions are doing so out of the goodness
  of their hearts, as this is an otherwise unsupported package.

    You can also mail the net-snmp-users@lists.sourceforge.net list
  with your questions and see if anyone there can help you.

    We can't promise to be able to solve the problem, but we'll
  certainly try and help.  Please *don't* mail both the coders
  and users lists - choose one or the other.  Most of the core
  contributors read both lists, and will respond as quickly and
  helpfully as we can.  Duplicated messages simply increase the
  load on these (already busy) lists, and are likely to annoy,
  rather than encourage a sympathetic response.

    If you're trying to port the package to a new system, the output
  of the command 'make -k' is a good starting indicator of where
  the bulk of the work is likely to be needed.

    If you're asking for help with a problem, please enclose the exact
  command you tried, and the output it generated.  Comments like "I did
  what it said in the man page", or "I've tried everything" aren't very
  helpful.  Exact messages, please!

   If you're reporting success on a new system, please let us know
  both details of the hardware you're using, and what versions of
  the operating system you've tried it on.  The entry 'host' in
  the file 'config.status' will show this information.
	Oh, and congratulations!



What's the difference between SNMPv1, SNMPv2 and SNMPv3?
-------------------------------------------------------
What are all these different SNMPv2's anyway?
--------------------------------------------


  A full description is probably beyond the scope of this FAQ.
  Very briefly, the original protocol and framework was described
  in RFCs 1155-1157, and is now known as SNMPv1.

    Practical experience showed up various problems and
  deficiencies with this, and a revised framework was developed to
  try and address these.  This was described in RFCs 1441-1452, and
  is known as "SNMPv2 classic".
  The changes proposed include:

	* new ways of defining information (MIB structure)
		(SMI, Textual conventions, conformance statements)
	* new protocol packet types and transport mappings
	* new mechanisms for administration and security
	* mechanisms for remote configuration

  Unfortunately, while many of these were generally accepted, there
  was some disagreement in these last two areas, security/admin
  and remote configuration.  This resulted in a number of variants and
  alternative proposals:

	SNMPv2c		Contains the new protocol and MIB structure elements,
			using the existing SNMPv1 administration structure.
			This is the agreed SNMPv2 standard (described in
			RFCs 1901-1908), superseding SNMPv2 classic, and is
			known as "Community-based SNMPv2" or simply "SNMPv2".


	SNMPv2 usec	} Alternative proposals to address the
	SNMPv2*		} limitations of SNMPv1 administration
			} These are both super-sets of SNMPv2c

			
	SNMP-NG		An attempt to reach agreement between
			the proponents of usec and v2star.

  The formal successor to the SNMP-NG work has been termed SNMPv3.
  This has now been effectively finalised, and as been published as
  Proposed Standards.  This is described in RFCs 2571-2575.



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 2271-2275).
    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)
  has now been dropped.  Those still requiring this functionality should
  continue to use the v3-line of the UCD suite.  However, please note that
  this version of the software is no longer being actively supported.



Where can I find more information about network management?
----------------------------------------------------------

  There are a number of sites with network management information on
  the World Wide Web. Two of the most useful are

      http://netman.cit.buffalo.edu/index.html
      http://wwwsnmp.cs.utwente.nl/

  There are two Usenet newsgroups which are relevant.
	'comp.dcom.net-management'
		which discusses general issues relating to network management
	'comp.protocols.snmp'
		which is specifically concerned with use of SNMP in particular

  (though there is a large overlap between these two groups).
  The SNMP group also has an FAQ (split into two parts) which discusses more
  general issues related to SNMP, including books, software, other sites,
  how to get an enterprise number, etc, etc.
  This is available from

      ftp://rtfm.mit.edu/pub/usenet/comp.protocols.snmp/

  or via either of the two Web sites above.


Is ucd-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.





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?
-------------------------------

  In essence,

	cp MY-MIB.txt /usr/local/share/snmp/mibs

          or

        mkdir $HOME/.snmp
        mkdir $HOME/.snmp/mibs
	cp MY-MIB.txt $HOME/.snmp/mibs

  And then,

	export MIBS=+MY-MIB

          or alternatively:

        echo "mibs +MY-MIB" >> $HOME/.snmp/snmp.conf

  The first command copies the file defining the new MIB to a
  expected location for MIB files.  This defaults to
  /usr/local/share/snmp/mibs (or PREFIX/share/snmp/mibs if the the
  suite was installed into a different base location).  Some
  ready-packaged distributions (such as Linux RPM packages) may look
  for MIB files in a different location, such as /etc/snmp/mibs - put
  the new file in this dirctory instead.  It will also look for mibs
  in your personal $HOME/.snmp/mibs directory.

  The second command tells the tools to load in this new MIB file as well
  as the default set.   Note that the tools do *not* load every MIB found
  in the directory - this is to avoid slowing them down excessively when
  there is a large collection of MIB files.  If you do want the tools to
  load all the MIB files, set the environmental variable MIBS to the special
  value "ALL".

     Note that the value for this variable is the name of the MIB module,
  *not* the name of the MIB file.   These are typically the same (apart
  from the .txt suffix), but if in doubt, check the contents of the file.
  The value to use is the token immediately before the word DEFINITIONS
  at the start of the file.  Of course, if you load 'ALL' mibs, then this
  distinction is irrelevant.

    Most of the tools (apart from 'snmptable') will work quite happily
  without any MIB files at all, as long as you are prepared to work with
  numeric OIDs throughout.  The MIB files are only used for translating
  between numeric and textual forms for queries and responses.
    The same holds true for the agent - see the AGENT section for details.



Why can't I see values in the <INSERT ENTERPRISE HERE> tree?
-----------------------------------------------------------

  A simply call to 'snmpwalk' (without specifying what to retrieve) will
  display the contents of the 'mib-2' subtree.  It will not attempt to
  traverse any 'private.enterprise' subtrees.  This includes the UCD
  UCD-specific objects (including any local extensions).

    To walk the whole tree, specify a starting point of '.iso'
  To walk a specific enterprise subtree, specify the root of this as
  the starting point - e.g:

	snmpwalk localhost public ucdavis
 
  Or, of course, you can walk a selected portion of an enterprise subtree
  by specifying the appropraite starting point - e.g:

	snmpwalk localhost public ucdavis.version
  
  If you still can't see any information, keep reading.  The next few
  questions will probably help you.

Requests always seem to timeout, and don't give me anything back.  Why?
----------------------------------------------------------------------

  There are a number of possible causes of this.
  Firstly, are you sure that the machine you are querying is actually up?
  Check that it responds to a 'ping' request and that that there is an
  SNMP process running on it.

  Secondly, it may simply be taking a long time to process the request.
  Try running the request with a long timeout value (e.g. '-t 120')

  If the system responds to ping, but not to a simple SNMP request
  (regardless of the timeout), then the problem may be due to the access
  configuration of the agent.  If the community string you have specified
  is not recognised, then the agent will simply not respond.
    See the next question, or the question on access control in the AGENT
  section for more details.



I can see the system group, but nothing else.  Why?
--------------------------------------------------

  This is probably the same as the previous question - a problem with
  the access configuration of the agent.   The easiest way to test this
  is to try a GETNEXT request, that ought to return the entry of interest.
  e.g.
	snmpgetnext localhost public ucdavis.version.versionTag
  instead of
	snmpget     localhost public ucdavis.version.versionTag.0

  If the agent responds with "end of MIB" or a different object, then
  either the agent doesn't implement that particular object at all, or
  the access control won't allow you access to it.

    This is frequently experienced with Linux systems, which often tend to
  come with the UCD agent configured to only allow access to the system group.

  If the agent being queried is the UCD agent, then see the entry on access
  control in the AGENT section for how to deal with this.
    If it is a different agent, you'll need to see the documentation that
  came with it.  (But of course, a non-UCD agent is unlikely to implement
  the 'ucdavis' sub-tree, so the examples above won't work anyway!)

  As a quick fix, you might create a new snmpd.conf configuration file
  that gives you the access control you need.  Run snmpconf -g
  basic_setup and follow its instructions.

Requesting an object fails with "sub-identifier not found"  Why?
---------------------------------------------------------------

  If a "general" snmpwalk shows the entry, but asking for it more
  specifically gives a "sub-identifier not found:" error, then that's
  probably a slightly different problem.

    Firstly, make sure that you're asking for the object by the right name.
  Object descriptors are case-sensitive, so asking for 'sysuptime' will
  not be recognised, but 'sysUpTime' will.

    Secondly, the object may be defined in a MIB that hasn't been loaded.
  Try loading in all the MIB files:

	snmpget -m ALL localhost public sysUpTime.0

  (though if snmpwalk translates it OK, that's less likely to be the cause).

    Thirdly, earlier versions of the UCD software expected "full" paths
  for object names, either based at the root of the whole MIB tree
  (".iso.org.dod.internet.mgmt.mib-2.system.sysUpTime") or the 'mib-2'
  subtree ("system.sysUpTime").  Try:
  
	snmpget myhost public system.sysUpTime.0

  These earler versions oF the tools may take a command-line option '-R'
  or '-IR' (depending on vintage) to invoke this "random-access" mode.
  All (reasonably-recent) versions of the tools accept the syntax

	snmpget myhost public RFC1213-MIB:sysUpTime.0

  to denote a particular object in a specific MIB module.   Note that
  this uses the name of the *module*, not the name of the file.  See
  the first question in this section for more details.



Why do I sometimes get "End of MIB" when walking a tree, and sometimes not?
--------------------------------------------------------------------------

  This depends on which MIB modules are supported by the agent you are
  querying and what you're asking for.

  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 a suitable error.
  The UCD tools report this with the message above.

  But in either case, the actual information provided will be the same.



I cannot set any variables in the MIB.
-------------------------------------

  There are three possible reasons for this:

  The majority of MIB objects are defined as "read-only" and inherently
  cannot be changed via SET requests.

  Of those that can in principle be changed, not all have been implemented
  as such in this agent.

  Even if the SET support has been provided, the agent must be configured
  to allow this level of access.  The example configuration file shipped
  with the basic distribution only allows write access for the local host
  itself (and a suitabre community name must be configured first).
    Ready-installed distributions (such as those shipped with Linux) tend
  to be configured with read-only access to a portion of the mib tree. More
  general access, including SET support, needs to be configured explicitly.
  See the access-control entries in the AGENT section for more details.

    Note that neither the community string "public" nor "private" can be
  used to set veriables 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 localhost public system.sysLocation.0
	system.sysLocation.0 = somewhere nearby

	$ snmpset localhost public 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 localhost public system.sysLocation.0 s "right here"
        Error in packet.
        Reason: notWritable

  The SNMPv1 error 'noSuchName' actually means:

	"You can't do that to this variable"

  This might be because the variable doesn't exist, it does exist but
  you don't have access to it (but someone else may do), or it exists
  but you can't perform that particular operation (i.e. changing it).
    Similarly, the SNMPv2 error 'notWritable' means "not writeable in
  this particular case" rather than "not writeable under any circumstances".
  It may be that a different invocation (such as using a different community
  name, or an authenticated SNMPv3 request) might be successful.



I get an error when trying to set a negative value - why?
--------------------------------------------------------

    This is a different problem.  What's happening here is that the
  routine that parses the arguments to the 'snmpset' command is seeing
  the '-' of the new value, and treating it as a command-line option.
  This normally generates an error (since digits probably aren't valid
  command line option).

    The easiest way to solve this is include the "end-of-option"
  indicator '--' in the command line, somewhere before the new value
  (but after all of the options, obviously).  For example:

	snmpset -v 2c localhost public -- versionRestartAgent.0 i -1

  (This will also fail, since -1 isn't an acceptable value for this
  object, but it will be rejected by the agent, rather than confusing
  the snmpset command!)



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 localhost public "" "" 0 0  ""
	snmptrap -v 1 localhost public "" "" 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 localhost public UCD-SNMP-MIB::ucdStart
	snmptrap -v 2c localhost public .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 localhost public 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.netsnmp.org/tutorial/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 -s -l7	(log to 'LOCAL7')

  printed to standard output

	snmptrapd -f -P

  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

  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.

    There's a tutorial with more details on the web site
    (http://www.netsnmp.org/tutorial/commands/snmptrap.html).
  


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"


  For how to configure the agent to respond to SNMPv3 requests, see
  the AGENT section.
 


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 much support, but does not
  attempt to define an upper bound for this maximum size.  This is left
  to each individual implementation.

    The UCD software uses a fixed size buffer of 1472 bytes to hold the
  encoded packet, so all requests and responses must fit within this.
  Unfortunately, it's not possible to predict how many varbinds this
  corresponds to, since it depends on the type and actual values being
  sent, as well as the corresponding OIDs.

    As a rule of thumb, sending 400 integer-valued varbinds seems to
  work OK, while 300 string-valued varbinds triggers the problem.



How can I monitor my systems (disk, memory, etc)?
------------------------------------------------

    In general, the UCD suite consists of relatively low-level tools,
  and there is nothing included that is designed for high-level,
  long-term monitoring of trends in network traffic, disk or memory
  usage, etc.

    There are a number of packages available that are designed for this
  purpose.  Two of the most widely used are MRTG (http://www.mrtg.org/)
  and Cricket (http://cricket.sourceforge.net/).  There are details of
  how to set up Cricket to monitor some of the UCD extensions at
  http://www.afn.org/~jam/software/cricket/   If anyone has something
  similar for MRTG, please let us know.

    The net-snmp package contains a web based manager itself that
  runs on top of a mysql database, but it is extremely beta in
  nature.  See the manager/README file for details.


Applications complain about entries in your example 'snmp.conf' file.  Why?
--------------------------------------------------------------------------

    The example configuration file 'EXAMPLE.conf' is designed as a config
  for the agent, and should be installed as 'snmpd.conf' (note the 'd').
  The file 'snmp.conf' is intended for general configuration options,
  applicable to all applications (via the SNMP library).
    Rename (or merge) the 'snmp.conf' file to 'snmpd.conf', and this should
  fix the problem.



OK, what should I put in snmp.conf?
----------------------------------

    This is used to set common configuration values for most of the
  applications, to avoid having to specify them every time.  Examples
  include the SNMPv3 settings mentioned above, defaults for which MIBs
  to load and where from, and the default SNMP version, port and
  community string to use.

    Some of these (such as the MIB file location), might belong in a
  shared snmp.conf file (typically /usr/local/share/snmp/snmp.conf) to
  apply to all users of the system.  Others (particularly the SNMPv3
  security settings), are more likely to refer to a particular user, and
  should go in a personal snmp.conf file (typically $HOME/.snmp/snmp.conf).

    Note that the UCD package does not usually come with an example
  snmp.conf file.  See 'snmpget -H' and/or the snmp.conf(5) man page
  for more details.

    You can also use the "snmpconf" command to help you generate your
  snmp.conf configuration file (just run it and answer its questions).


PERL
====

Where can I get the perl SNMP package?
-------------------------------------

  Joe Marzot's excellent perl SNMP module, which requires the ucd-snmp
  library, is now included in the ucd-snmp source release.  It's
  located in the perl/SNMP subdirectory of the ucd-snmp source tree.

  It can also be found at any Comprehensive Perl Archive Network
  (CPAN) site mirror in modules/by-module/SNMP.  To find the CPAN site
  nearest you, please see http://www.cpan.org/SITES.html.

  Consult the README file in the SNMP perl module distribution to find 
  out what version of the ucd-snmp library it needs to be linked against.



How do I install the Perl SNMP module?
-------------------------------------

  Assuming you have a reasonably new (and properly configured) perl system,
  this should be simply:

        cd perl/SNMP
	perl Makefile.PL
	    (press RETURN when prompted for host and community)
	make
	make test
	make install  (probably as root)



But compiling this fails! Why?
-----------------------------

  The perl module tends to delve quite deeply into the internals of the
  main UCD snmp library, and so is quite sensitive to changes within the
  library.  It's important to use the correct version of the module, that
  corresponds to the version of the library you have installed.  If you're
  working with the main UCD distribution, the appropriate version of the
  perl module is shipped as part of this, but you *must* have
  run "make install" on the main UCD 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.



I'm trying to use mib2c (or tkmib) and it can't locate SNMP.pm?
------------------------------------------------------------

  That's probably because the SNMP perl module hasn't been installed.
  It's not part of the standard perl distribution, nor is it installed
  by default in RedHat linux (for example).
    You'll need to install it.  See the previous two questions.



I'm trying to use mib2c (or tkmib) and it can't load SNMP.so?
------------------------------------------------------------

    This is probably the same problem.  Either the SNMP module
  hasn't been installed, or it's the wrong version.  See the
  previous two questions.



I'm trying to use tkmib and it can't locate Tk.pm?
-------------------------------------------------

  Tk.pm is another Perl package that needs to be installed before tkmib
  will run.  It's also available on Perl CPAN.  We suggest using version
  "Tk800.011" or later.  It can be installed by issuing the command:

		perl -MCPAN -e shell ; "install Tk"



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.  The functionality
  of this is mostly integrated within the MIB parser (part of the UCD 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 UCD agent.  
  See the CODING section for more information.



I can't load any of the mib files, and they seem to be missing
the first two characters of the filename.  What's happening?
-----------------------------------------------------------

  This is a problem experienced with Sun systems when the tools have
  been compiled with a mixture of BSD and Solaris environments.
  You'll need to re-configure and compile the tools, making sure that
  '/usr/ucb' is not in your PATH (or at least comes at the end).



Why aren't my mib files being read in?
-------------------------------------

    The most likely cause is that the UCD library only loads a subset
  of MIB files by default.  This list is set at when the suite is first
  configured and compiled, and basically corresponds to the list of
  modules that the agent supports.  (This is a simplification, but is
  a reasonable first approximation).

    You can override this by using the command-line option '-m', the
  environmental variable 'MIBS' or the snmp.conf directive 'mibs'.
  Each of these take a (colon-separated) list of MIB module names
  to load.   Starting the list with a '+' character will add them to
  the default list - otherwise it replaces the defaults.

    Using the special value 'ALL' will load all the MIB files that
  the library can find.


    Alternatively, the tools may be looking in the wrong place.
  The default location for the mib files is /usr/local/share/snmp/mibs.
  Again, this is set when the suite is first configured and compiled.
  This can be changed using the environmental variable 'MIBDIRS'
  or the snmp.conf directive 'mibdirs'.

    Note that this may very well affect you if you've installed a
  new version of the suite, replacing one provided by the supplier
  (which typically would use a more 'central' location).


    Finally, are you sure that you've installed the MIB files?
  If you've compiled the suite from scratch, you need to run
  "make install" at least once, before the tools will be able to
  find the MIB files.  This is unlikely to be a problem if you've
  been working with the tools for a while, but can bite those coming
  fresh to the SNMP world.



I'm getting answers, but they're all numbers. Why?
-------------------------------------------------

  This is actually the same as the previous question.  Because the tools
  don't read in every MIB module they can find, it is quite possible
  for results from an agent to refer to modules that have not been loaded
  (particularly with GETNEXT requests, or when walking a tree).
     The tools will report the answer quite correctly, but won't translate
  identifiers and enumerations into readable strings.  To fix this, use
  the environmental variables MIBS or MIBFILES (or the '-m' and '-M' flags)
  to read in the relevant module files.



What does "Cannot find module (XXX-MIB)" mean?
---------------------------------------------

    This is similar to the previous questions.   In this case, it's
  stating that it can't find the specified module - either becuase
  it's not installed properly, or the name used is subtly wrong.

    If it's just one or two modules that are not being found, check
  that the files are in the expected location, are readable, and the
  name being used is correct.  Note that the name reported is the
  name of the MIB module, which is not necessarily the same as the
  name of the file. See the question 'How do I add a MIB to the tools?'
  for more details on this.

    If the tool is generating a whole slew of errors, then it's
  likely that either the MIB files haven't been installed at all,
  or the library is looking in the wrong place.   See the previous
  two questions.



The parser doesn't handle comments properly. Why not?
------------------------------------------------------------

  The most likely reason is that the line in question contains two
  (or more) sequences of pairs of dashes.  This is often used to try
  and "comment out" an unwanted line that already contains a comment:

	--   broken ::= { myMIB 1 }   -- This isn't working yet

  The assumption here is that a comment continues to the end of the line.
  Unfortunately, this assumption is not correct.
    A comment will continue either to the end of the line, or the next
  occurance of a pair of dashes.  Thus in this case, the definition of
  "broken" is commented out (as intended) but the following text is
  treated as part of the MIB, and will generate an error.

    A similar effect can be obtained when a line of dashes has been used
  to try and mark separate parts of a MIB file.

    Most of the applications have a command-line option (-Pc) which will
  work around this problem by treating the whole line as a comment.  But
  this is not strictly legal, and the offending MIB file should really be
  corrected.


How do I replace MIB values with new ones?
-----------------------------------------

  The UCD parser generally takes the first definition it sees for each
  object in the MIB hierarchy.   Even if you specify your file to be read
  first, if the IMPORTS clauses reference a MIB with competing objects,
  those objects will be parsed first !

  When specifying the Replace MIB command-line option (-PR), the parser
  will use definitions sourced from the most recent MIB file.
  The parser will replace MIB objects when the sub-identifier and name match.

  Caution: Using Replace MIB, there is NO guarantee that the resulting
  MIB tree will be correct.  Other MIB objects matching the name but
  not the sub-identifier will persist.  Sub-hierarchies may be reparented.
  In particular, random access searching [see man 1 snmpcmd]
  may give unexpected result.
  The Replace MIB option is experimental, buyer beware, carpe diem, etc.

  Here are a few considerations to help you obtain good results.
  These hold true even if you never use the Replace MIB feature.
  Your suggestions for improvement are welcomed.

    1. The parser searches the specified directories and attempt
       to parse every file whose path does not begin with "." (period).
       Remove (or rename) older MIB files from these directories.
       Rename "README" to ".README" , etc.

    2. Hint: the parser's module list is in LIFO order. You may see better
       results if the directory with the most correct MIB files is
       specified last in the MIBDIRS environment.

    3. Constrain the parser to not read in default MIB files by setting
       the MIBS environment to the environment separator character
       [semi-colon on win32, colon everywhere else].

    4. The MIBFILES environment can specify the path of the new MIB file.

  If you grok programmer-speak, invoke :
  ds_set_boolean(DS_LIBRARY_ID, DS_LIB_MIB_REPLACE, 1 | 0)
  to enable or disable the Replace MIB feature, then invoke read_mib
  specifying the MIB file name.  Then disable Replace MIB feature.


How can I get more information about these MIB file problems?
------------------------------------------------------------

  The command 'snmptranslate' is used to translate between numeric
  and symbolic forms of OIDs.  It uses the same routines as the
  'active' commands, but does not rely on communicating successfully
  with a network management agent.  As such, it is a useful tool
  for identifying problems with reading in MIB files.

    In particular, the following options may be useful in
  identifying problems:
	-Pw  warns about conflicting symbols
	-PW  prints more verbose warnings about other problems as well
		(in both cases, ignore the 'xmalloc' reports)
	-p   prints a list of the entries that have been read in
		(including the MIBs they belong to)
	-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.

  (see the
  http://www.netsnmp.org/tutorial/commands/snmptranslate.html
  web page as well)

What's this about "too many imported symbols"?
---------------------------------------------

  Any MIB file starts with an (optional) list of identifiers that
  it "imports" from other files.  The parser implements this using
  a fixed size buffer to hold the import information.
    There are two circumstances in which this can result in the
  error message shown above.

    Firstly, if the MIB file refers to an unususally large number
  of external identifiers.  Handling this case requires a (trivial)
  patch to the parsing code.  Contact the coders list for advice.
     (This is extremely rare - the only example that
      we've come across is the Cabletron Trap MIB).

    Much more common is a syntax error in the IMPORTS clause of the
  MIB file in question.  In particular, check that this ends in a
  semicolon, before going on to the main definition section.
  


AGENT
=====

What MIBs are supported?
-----------------------

  The following MIBs are supported (at least in part):

	- MIB-2  General network statistics (RFC 1213)
	- UCD agent extensions
		(processes, disks, memory, load average,
		 shell commands, error handling)
	- Host Resources (RFC 1514) initial implementation
	- SNMPv3 MIBS (RFCs 2571-6)

  The SNMPv2 Party and Manager-to-Manager MIBs (RFCs 1447 & 1451) have been
  withdrawn.



What protocols are supported?
----------------------------

  The agent supports all three versions of SNMP (v1, v2c and v3), over both
  UDP and TCP transports, as well as a SMUX (RFC 1227) master agent, and
  AgentX (RFC 2257 ) in both master and subagent roles.
  support.


How do I configure the agent?
----------------------------

  Read the snmpd.conf manual page for full details on how to do this.

  You can also run the "snmpconf" perl script to help you create this
  file.

  You might start off with snmpconf -g basic_setup to get you going.


How do I add a MIB to the agent?
-------------------------------
How do I add functionality?
--------------------------

  Unfortunately, adding a file to the MIB directory does not automatically
  extend the functionality of the agent to include this MIB.  (Would that
  life were so simple).  In fact, the agent makes little or no use of
  these files, and will work quite happily without them.
  All the information about the syntax and scope of the variables supported
  is hardwired into the implementation of the agent.

  There are a number of alternative ways to add functionality for a new
  MIB to the agent.

  Firstly, it is possible that the agent distribution already includes
  the desired functionality, but this has simply not been configured in
  to the running version.  This is done using the configure option
		--with-mib-modules="list"
  (where "list" is a space-separated list of modules to include) then
  recompiling the agent.
  Note that some functionality concerned with monitoring and managing
  unix hosts is included in the UCD extension modules, which are located
  within the 'private' branch of the MIB tree.  This is covered in a later
  question in this FAQ.

  Secondly, it is possible for the agent to run commands or shell scripts
  in response to queries.  These can obtain and report the necessary
  information, or perform actions as required.
  Detailed information and examples are provided in the snmpd(1) and
  snmpd.conf(5) manual pages, and the EXAMPLE.conf file.
  This is known as "pass-through" support.

  Thirdly, it may be possible to link another agent (which already
  supports the desired MIB), as a "subagent" of the UCD master (or
  vice versa).  The possibilities here are SMUX, AgentX or proxied
  SNMP (see the next question but one).

  Finally, the agent itself can be extended to support additional MIB
  groups, by writing the necessary C code, and including this within
  the main agent - either statically compiled in, or dynamically loaded.
  This is covered further in the next section.

    Note that there is effectively no difference between 'pass-through'
  MIB support, subagents and modules implemented within the main agent
  itself. Tools querying the agent will see a single MIB structure.
 


What's the difference between 'exec', 'sh' and 'pass'?
-----------------------------------------------------

    'exec' will fork off the specified command and return the exit status
  and/or the output.  Arguments are passed directly to the command.

    'sh' is similar, but invokes a shell to run the command.
  This means that quoted arguments will be recognised as such, and also
  allows redirection, and other similar shell interpretation.

  Neither of these mechanisms require the command to have any knowledge
  of the fact that they are being used in this manner.  Note that return
  values are cached within the agent for 30 seconds, rather than invoking
  the command for every request.


    'pass' is a more general mechanism for extending the agent, and the
  command given will be invoked for any request within the specific MIB
  subtree.  Details of precisely how this command will be called in
  various circumstances is given in the 'snmpd.conf(8)' man page.

    'pass-persist' is similar, but the command will continue running
  even once the initial request has been answered.

  See 'snmpd.conf(5)' for more details.

  

What's the difference between AgentX, SMUX and proxied SNMP?
-----------------------------------------------------------

    All three are protocols that can be used to make two or more agents
  appear as one to the querying application.  In each case, one agent
  takes the role of "master", and delegates requests to one of the others
  as and where this is appropriate.  The differences between them mainly
  relate to how data is represented, and the mechanisms for communication
  between master and subagents.

    SMUX and proxy SNMP both essentially use the same SNMP packet format.
  The main difference is probably that a proxy SNMP subagent need not be
  aware that it is acting in such a role.  It typically listens on a
  non-standard port, and simply receives requests as usual, forwarded from
  the master agent.  The main issue to be aware of is that such requests
  will usually appear to come from the local host, and this may affect how
  the access control mechanisms need to be set up.

    SMUX uses a similar packet format, but the subagent "registers" with
  the master agent, providing a suitable password.  The 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.
    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 UCD 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 'agent/mibgroup/agentx/README' for details.

  Note that support for the SMUX and AgentX extension mechanisms are
  not configured in by default.  You will need to run configure with
  the option

		--with-mib-modules=agentx,smux

  (or whichever of these you wish to support).



What traps are sent by the agent?
--------------------------------

  The agent sends a 'coldStart(0)' trap when it first starts up, and a
  UCD-specific trap '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.  It does not currently generate
  'warmStart(1)' traps on being re-configured, though this would be fairly
  simple to add.

    The agent does not send 'linkUp' or 'linkDown' traps.  Generating such
  traps would be simple enough, but the difficulty is in recognising when
  they should be generated.  See the question on generating traps in the
  CODING section for more discussion of this.

    With all these alerts, the agent also needs to be configured with
  (one or more) destinations to send them to, specifying the type of
  notification (v1 or v2 trap, or v2 inform) and the community name to
  use.  This uses the snmpd.conf directives 'trapsink', 'trap2sink' and
  'informsink' for the destination type, and 'trapcommunity' for the
  community name.  SNMPv3 destinations can be configured using the directive
  'trapsess'.   See the snmpd.conf man page for details.

    Note that all notifications will be sent to all destinations.  The
  agent does not (currently) support notification filtering.
 


When I run the agent it runs and then quits without staying around. Why?
-----------------------------------------------------------------------

  The first question is, are you certain that this is what is happening?

  The normal operation of the agent is to 'fork' itself into the
  background, detaching itself so that it will continue running even
  when you log out, and freeing the command line for subsequent use.
  This looks at first sight as if the agent has died, but using 'ps'
  to show all processes should reveal that the agent is still running.

  To prevent this behaviour (such as when attempting to debug the
  agent), you can start it with the '-f' flag.  This suppresses the
  fork, and the agent will run as a 'normal' command.  It's also often
  useful to use the '-L' flag, to log messages to stdout.

  On the other hand, if 'ps' shows that the agent is not running, then
  this is an error, and probably show that something went wrong in
  starting the agent up.  Check the agent log file for any error messages.



How can I stop other people getting at my agent?
-----------------------------------------------

  First question - are you concerned with read access or write access?

  As far as changing things on the agent is concerned, there is very
  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 questions for details)

  Other options include:
	- Blocking access to port 161 from outside your organisation
		(using filters on network routers)
	- 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.



How can I listen on just one particular interface?
-------------------------------------------------

    Normally, the agent will bind to the specified port on all interfaces
  on the system, and accept request received from any of them.  With
  version 4.2, the '-p' option can now be used to listen on individual
  interfaces.  For example,
	
			snmpd -p 161@127.0.0.1

  will listen (on the standard port) on the loopback interface only, and

			snmpd -p 6161@10.0.0.1

  will listen on port 6161, on the (internal network) interface with address
  10.0.0.1.   If you want to listen on multiple interfaces (but not all),
  then simply repeat this option for each one:

		snmpd -p 161@127.0.0.1 -p 161@10.0.0.1

    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'
  and 'rwcommunity'.   These specify the community names to use for
  read-only and read-write access to the whole of the supported MIB
  tree (though they can also be restricted to particular subtrees,
  and/or specific request sources).
    Similarly, the configure directives 'rouser' and 'rwuser' can be
  used to allow the specified SNMPv3-authenticated users access to
  all or part of the MIB tree.

    These are effectively wrappers round the core access control
  mechanisms.  This uses four directives 'com2sec', 'group', 'view'
  and 'access',  and provides a more efficient and flexible control
  over who can access what 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 old community style, but
  that's because it can do a whole lot more.

    There are four configuration keywords in the new scheme:
	'com2sec', 'group', 'view', and 'access'

  We'll consider these one at a time, starting with 'access'.
  (Because I feel like starting with the last one, that's why - OK?)


  The "access" keyword has the job of specifying who has access to
  which bits of the MIB tree.  This has eight parameters, so can look
  rather offputting. Most of these can be safely left with default values
  in most cases (so don't you worry your pretty little head about them).
  The syntax is

	access {group} "" any noauth exact {read-tree} {write-tree} {notify-tree}

  where the entries in braces need to be defined elsewhere (I'm coming
  to that - be patient!), and the rest can be left as shown here.

	[ If you really want to know, the 'sec.model' field can be used
	  to have an access line that's only relevant to particular
	  versions of SNMP (such v1 or v2c) rather than "any" version,
	  and the 'sec.level' field can be used to ensure that the
	  request is authenticated or encrypted.
	    You'll have to ask Niels about the other two!]


  The "view" keyword is used to define particular bits of the MIB tree,
  for use in the last three field of the access entry.
  This has the syntax

	view  {name}  included/excluded  {subtree}   {mask}

  where {name} is the identifier to be used for this view (i.e. what should
  appear in the access entry), and {subtree} is the portion of the MIB tree
  that this name refers to (in either numeric or named form).
    Note that the name of the view does not have to have anything to do
  with the MIB sub-identifier names - it's purely an identifying tag for
  use within the config file (though choosing a meaningful name is, as
  always, a very good idea).
  
    The {mask} field is used to control which elements of the OID subtree
  should be regarded as relevant when determining which view an OID is in.
  Normally, the whole of the OID should be included, so you'll need a mask
  with as many bits set as there are OID elements.
    Thus, in the example config file,  ".1" (i.e. the whole dod tree) has
  one element, so the mask has one bit set (counting from the most
  significant) - i.e. '80' (in hex).
  ".iso.org.dod.internet.mgmt.mib-2" has six elements, so six bits set ('fc').
  "system" is short for ".iso.org.dod.internet.mgmt.mib-2.system", which
  has seven elements, and so seven bits in its mask (hence 'fe')
    If there are more than eight elements, you specify the longer masks
  as single octet values, separated by dots (e.g. 'ff.c0' for 10 bits)
  The third field can be used to include or exclude particular portions
  of the MIB from the view, and different lines can use the same view name
  to build up a more complicated view, if that's what's needed.

    The three view fields in the access line are used to control which
  portions of the MIB tree a particular {group} can see (GET et al),
  alter (SET), or request NOTIFYs on.



    That's dealt with the "what" - now for the "who".
  This is the role of the "group" and "com2sec" entries.

  The "group" keyword gives general control, by mapping between a "security
  name" (for a particular protocol version), and the internal name used in the
  access line.  Note that the token "any" is no longer acceptable for the
  security model - the original support for this was due due to a misreading
  of the RFC.  You should replace any such line with separate versions for
  each of the desired security models ('v1', 'v2c' & 'usm').

    For SNMPv1 and SNMPv2c, the group line is just an intermediate step
  between the "access" line and the "com2sec" line, which is the last bit
  of the jigsaw.  The "com2sec" entry is used to determine a "security name"
  from the traditional community string, taking into account where the request
  has come from.  Thus the same community string can give access to  different
  portions of the tree, depending on where the request is sent from.

     For example, in the example config file, there are two com2sec lines
  with the community string "public" - one is valid from anywhere (with
  the security name "public") and one is only valid from the local network
  (using the security name "mynet").
     The group lines convert these security names into the groups "public"
  and "mygroup" respectively, and the access lines give 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 can
  SET any values though, (since the write-tree is "none" in both cases).
    Someone on the local machine, using the community string "private",
  has the security name "local" and the group name "local", and hence has
  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, are three totally separate things.
  You can't use a community string in a security name field, or either
  of these as a group name (or vice versa), unless you set up suitable
  entries to map one name onto the other.

    With SNMPv3, the security name is part of the basic protocol, and can
  be used directly.

  And here concludes our tour of the view-based access control mechanism.
  Phew!



How do I configure SNMPv3 users?
-------------------------------

    Create a file /var/ucd-snmp/snmpd.conf file, containing the line

	createUser {myUser} MD5 {myPassword} DES

  (where {myUser} and {myPassword} are the appropriate values, _without_
  the braces).  Then start (or re-start) the snmpd agent.
  This will create the new user.  See the access control entries above
  for how to use this, and the file 'README.snmpv3' for more details.



The 'createUser' line disappears when I start the agent.  Why?
-------------------------------------------------------------

    That's deliberate.   The agent removes the (human-readable) 'createUser'
  directive, and replaces it with an equivalent 'usmUser'.  This
  contains the same information, but in a form that's only meaningful
  internally.  This means that the password is not longer available in
  a readable form.  Additionally, the password has been converted to a
  key that can only be used to access the local machine.  If someone
  stole the new usmUser line on this machine, they could not use that
  information to access any of your other agents.


What's the difference between /var/ucd-snmp and /usr/local/share/snmp?
---------------------------------------------------------------------

    Most "static" agent configuration should go in the traditional location
  (typically /usr/local/share/snmp/snmpd.conf).   The /var/ucd-snmp
  location is used for information set during the running of the agent,
  which needs to be persistent between one run of the agent and the next.

    Putting the 'createUser' line in this persistent file is an exception,
  for security reasons (see above).  In general you shouldn't need to put
  anything else here.



My new version 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 version was.  This is commonly
  experienced when replacing a ready-installed version (e.g. from a Linux
  distribution), with the current release, installed from the source.

    The default location for the snmpd.conf file with the basic distribution
  is /usr/local/share/snmp.  Ready-installed versions often look for the
  file as /etc/snmpd.conf.  Try moving the old config file to the new
  location, and restart the 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 (such as RedHat
  Linux) come with this enabled automatically - otherwise you need to
  select it explicitly by configuring using '--with-libwrap'.

    The simplest way to avoid this problem is to add the line

		snmpd: ALL

  in the file /etc/hosts.allow (or wherever this file is on your system).


 
I'm getting errors about "bad security model" - why?
----------------------------------------------------

  Until release 4.2, the access control handling accepted the token "any" 
  to cover all of the recognised security models.  This is explicitly
  forbidden in the relevant RFC, so support for this is being withdrawn.
    As an interim measure, it is currently accepted (with the warning you
  see), but this will not be the case in future releases of the agent.
 
    You should replace the token 'any' with 'v1', 'v2c' or 'usm' as
  appropriate.  If you want to support all three of these security models,
  you'll need to use three distinct group lines, one for each. See the
  example snmpd.conf file for details.

  

I'm getting errors about "bad prefix match parameter" - why?
------------------------------------------------------------

  This is similar to the previous question.  With 4.2, the syntax of the
  'access' configure line has changed, and a value of '0' is no longer
  acceptable for the sixth field.  Simply replace this with the word 'exact'.


  
Why can't I see values in the UCDavis 'extensible' or 'disk' trees?
------------------------------------------------------------------

  Both these trees are designed to report things you ask it to report
  on.  If you don't declare anything in the snmpd.conf file for it to
  monitor, it will not report anything.  See the snmpd.conf manual page
  and the EXAMPLE.conf file for details on configuring the agent.

  Optionally, run snmpconf -g monitoring to help you set up this
  section of the snmpd.conf file.


Why can't I see values in the UCDavis 'memory' or 'vmstat' trees?
----------------------------------------------------------------

  These mib modules are not supported on all operating systems, and
  will not be included on any other system.  Currently, they are only
  supported on Linux, HP-UX (memory only), Solaris, BSDi (vmstat on
  BSDi4 only), FreeBSD, NetBSD and OpenBSD.
    If you want to help port it to other systems, let us know.



What do the CPU statistics mean - is this the load average?
----------------------------------------------------------

  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 the different architectures.

    The 4.2 release 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.

    Note that this is different from the Unix load average, which is
  available via the loadTable, and is supported on all architectures.



What about multi-processor systems?
----------------------------------

    Sorry - the CPU statistics (both original percentages, and the
  newer raw statistics) both refer to the system as a whole.  There
  is currently no way to access individual statistics for a particular
  processor.

    Note that although the Host Resources table includes a hrProcessorTable,
  the current implementation suffers from two major flaws.  Firstly, it
  doesn't currently recognise the presence of multiple processors, and
  simply assumes that all systems have precisely one CPU.  Secondly, it
  doesn't calculate the hrProcessorLoad value correctly, and either returns
  a dummy value (based on the load average) or nothing at all.

    If you want to monitor a multi-processor system, you're currently
  out of luck.   But you've got the source, so you can always have a
  go yourself :-)



The speed/type of my network interfaces is wrong - how can I fix it?
-------------------------------------------------------------------

    Some operating systems will provide a mechanism for determining
  the speed and type of network interfaces, but many do not.  In this
  case, the agent attempts to guess the most appropriate values, based
  on the name of the interface.
    Version 4.2 allows you to override these guessed values, using the
  configuration directive 'interface', specifying the name, type and
  speed of a particular interface.  This is particularly useful for
  fast-ethernet, or dial-up interfaces, where the speed cannot be
  guessed from the name.
    See the snmpd.conf 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!


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'



What does "nlist err:  wombat not found" (or similar) mean?
----------------------------------------------------------

  This means that the agent wasn't able to locate one of the
  kernel structures it was looking for.  This may or may not
  be important - some systems provide alternative mechanisms
  for obtaining the necessary information - Solaris, for example,
  can produce a whole slew of such messages, but still provide
  the correct information.
    This error only occurs if you have used the flag
  '--enable-debugging' as part of the initial configuration.
  Reconfigure the agent with '--disable-debugging' and these
  messages will disappear.



How about "Can't open /dev/kmem"?
--------------------------------

  This device is normally restricted to just being accessible by root
  (or possibly by a special group such as 'kmem' or 'sys').  The agent
  must be able to read this device to obtain the necessary information
  about the running system.
    Check that the agent was started by root, and is running with UID 0
  (or suitable GID if appropriate).  The agent will normally continue
  to run without this level of access permission, but won't be able to
  report values for many of the variables (particularly those relating
  to network statistics).

 

The agent is complaining about 'snmpd.conf'.  Where is this?
-----------------------------------------------------------

  It doesn't exist in the distribution as shipped.  You need to
  create it to reflect your local requirement.
    To get started, you can either just create this as an empty file,
  or run snmpconf to help you create one.
    See the snmpd.conf(5) manual page for further details.



The system uptime (sysUpTime) returned is wrong!
-----------------------------------------------

  Oh no it's not.
  The defined meaning of 'sysUpTime' is
	"the time ... since the *network management*
	 portion of the system was re-initialized."

  In other words, when the snmp agent was started, not when the
  system itself last booted.  This latter information is available
  in the Host Resources MIB as "host.hrSystem.hrSystemUpTime"
  Note that even if the full Host Resources is not supported on
  your system, it's worth configuring in the system portion using

		'--with-mib-modules=host/hr_system'

  and recompiling.  This particular group is reasonably likely to
  work, even if some of the other more system-specific groups don't.
	(see the next question)



The Host Resources information is wrong (and/or doesn't even compile)!
---------------------------------------------------------------------

  Very likely.

  This is still a relatively immature implementation, and has only not
  received a great deal of development.  While every attempt is made
  to provide information in as general way as possible, the Host
  Resources is extremely system-specific, by its very nature.

  Basically, if the information returned is wrong on your architecture,
  tell us how to get the correct values, and we'll try and fix it.



CODING
======

How do I compile with 'cc' instead of 'gcc'?
-------------------------------------------

  Run configure with --with-cc=cc


But gcc doesn't compile it successfully on my new Solaris system. Why not?
-------------------------------------------------------------------------

  Whenever you upgrade the operating system under Solaris, you need to
  reinstall gcc, and run the 'fixincludes' script.  (This is probably
  a sensible step to take when you upgrade any operating system).
    Under Solaris 2.6, there is also a bug in the gcc 'fixinc.sv4' script.
  This needs an additional line as follows:

*** fixinc.svr4.cln     Thu Jun 15 22:03:29 1995
--- fixinc.svr4 Tue Nov 25 09:47:57 1997
***************
*** 191,191 ****
--- 191,192 ----
          s/__STDC__ - 0 == 0/!defined (__STRICT_ANSI__)/g
+         s/__STDC__ - 0 == 1/defined (__STRICT_ANSI__)/g



How do I write C code to integrate with the agent?
-------------------------------------------------

  At the moment, there are three methods for integrating external C code
  within the agent.

    The code can be included within the agent itself, statically configured
  and linked in when the agent is compiled.  Alternatively, with the 4.2
  release of the agent, it's possible to dynamically load MIB modules once
  the agent is running.  Finally, the agent can be configured to pass certain
  portions of the MIB tree off to one or more subagents.  See the earlier
  question on AgentX, SMUX and proxied SNMP for more details.

    All three mechanisms use the same module API.  This is described (in
  excruciating detail) in the file AGENT.txt, shipped with the standard
  distribution.  There is also an HTML version accessible via the project
  web page.  This task can be aided using the tool 'mib2c' which generates
  most of the necessary skeleton code from the description in the MIB file.

    Note that the UCD suite does not include support for SMUX subagents.



How does the agent fetch the value of a variable from the system?
----------------------------------------------------------------

  Much of the information is extracted from kernel memory - usually
  by seeking to the appropriate location and reading the structures
  directly.
    Some systems provide cleaner interfaces to such kernel information
  (it would be hard to think of a less clean interface!), via ioctl()
  calls or similar system routines and these mechanisms are usually used
  in preference.



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.



Mib2c only handles a single table in my MIB. How can I fix this?
---------------------------------------------------------------

    This is a bug in the mib2c script, which has been corrected with
  the 4.2 release.  Earlier versions can be fixed by applying the
  following patch:

	$ diff -u mib2c.cln mib2c
	--- mib2c.cln   Wed Nov 29 15:12:47 2000
	+++ mib2c       Wed Nov 29 15:13:18 2000
	@@ -132,6 +132,6 @@
	 #============================================
	 foreach $vtable (@table_list) {
	     foreach $ptable (@processtable) {
	-       $variables{$ptable}{'processed'} = 
	+       $variables{$ptable}{'processed'} .= 
	            (eval "\"$variables{$ptable}{'code'}\"") . "\n\n";
	     }



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.



How can I get the agent to generate a trap (or inform)?
------------------------------------------------------

    Actually generating a trap is reasonably simple - just call one
  of the utility routines 'send_easy_trap()' or 'send_v2trap' with
  the relevant information (trap values, or varbind list respectively).
  See the 'snmp_trap_api(3)' man page for details.

    Determining _when_ to generate the trap 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.
    This can be done using the routines documented in 'snmp_alarm(3)',
  though unfortunately we don't have any examples of how to do this.
  Eventually, the intention is to implement the Event MIB (from the
  Distributed Management working group), which will provide this
  functionality in a flexible, standardised manner.

    In the meantime, the simplest approach is probably to set up
  an external program, to poll the agent for the desired values,
  and generate a trap when values change.  E.g:

		old_value=`snmpget myObject.0`
		while true
		do
		    sleep 60
		    new_value=`snmpget myObject.0`
		    if [ $old_value != $new_value ]
		    then
			snmptrap .... myObject.0 i $new_value
		    fi
		    old_value=$new_value
		done

   (Obviously, this is not complete, but should give you the
   general idea).



I'm getting an error "autoheader: not found" - what's wrong?
-----------------------------------------------------------

    This usually apears 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.



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 are packets requesting the same information larger with UC-Davis SNMP ?
-------------------------------------------------------------------------

    This shouldn't happen with version 4.2 or later, but for older
  version the following still applies:

    Some users note that UCD-SNMP applications always generate larger PDUs
  than other SNMP packages, even if the information requested is the same.
  Further, there are some agents that refuse PDUs from UCD-SNMP applications
  but accept PDUs from other applications.

  UCD-SNMP is based on the CMU code from a long time ago which encoded things
  using the long form of length encoding.  Some agents use the short form
  of length encoding only, and do not understand the long form.

    Get version 4.2 or higher to user th shorter encoding lengths.

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 incompatabilities in MIB files.  The UCD tools accepting a
  MIB file without complaint does not imply that the MIB is strictly
  correct.
    Certain MIBs (most notably those from Cisco) 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 ucd-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."



