Chapter 186. SNMP for eCos

186.1. Version

This is a port of UCD-SNMP-4.1.2

Originally this document said: See http://ucd-snmp.ucdavis.edu/ for details. And send them a postcard.

The project has since been renamed “net-snmp” and re-homed at http://net-snmp.sourceforge.net/ where various new releases (of the original, not eCos ports) are available.

The original source base from which we worked to create the eCos port is available from various archive sites such as ftp://ftp.freesnmp.com/mirrors/net-snmp/ generally with this filename and details:

        ucd-snmp-4.1.2.tar.gz. . . . . . Nov  2  2000   1164k

186.2. SNMP packages in the eCos source repository

The SNMP/eCos package consists of two eCos packages; the SNMP library and the SNMP agent.

The sources are arranged this way partly for consistency with the original release from UCD, and so as to accommodate possible future use of the SNMP library without having an agent present. That could be used to build an eCos-based SNMP client application.

The library contains support code for talking SNMP over the net - the SNMP protocol itself - and a MIB file parser (ASN-1) which is not used in the agent case.

The agent contains the application specific handler files to get information about the system into the SNMP world, together with the SNMP agent thread (snmpd in UNIX terms).

186.3. MIBs supported

The standard set in MIB-II, together with the Ether-Like MIB, are supported by default. The MIB files used to compile the handlers in the agent and to “drive” the testing (snmpwalk et al under LINUX) are those acquired from that same UCD distribution.

These are the supported MIBs; all are below mib2 == 1.3.6.1.2.1:

system        { mib2 1 }
interfaces    { mib2 2 }
              [ address-translation “at” { mib2 3 } is deprecated ]
ip            { mib2 4 }
icmp          { mib2 5 }
tcp           { mib2 6 }
udp           { mib2 7 }
              [ exterior gateway protocol “egp” { mib2 8 } not supported ]
              [ cmot { mib2 9 } is “historic”, just a placeholder ]
dot3          { mib2 10 7 } == { transmission 7 } “EtherLike MIB”
snmp          { mib2 11 }

On inclusion of SNMPv3 support packages, the following MIBs are added to the default set of MIBs enumerated above :

snmpEngine    { snmpFrameworkMIBObjects 1 }  SNMP-FRAMEWORK-MIB, as described in
                                             RFC-2571 for support of SNMPv3
                                             framework.

usmStats      {           usmMIBObjects 1 }  SNMP-USER-BASED-SM-MIB, as
usmUser       {           usmMIBObjects 2 }  specified in RFC-2574 for support
                                             of user based security model in
                                             SNMPv3 management domains.
[Note]Note

Not every MIB variable is necessarily supported - some don't really apply to eCos, some are simply not yet implemented, and some would be overly complex to implement to be worth it in an embedded system. Similarly writing to some variables may be permitted by the MIB definition, but may not produce any effect. For example trying to set an interface administratively up or down with IF-MIB::ifAdminStatus at present has no effect.

186.4. Changes to eCos sources

Small changes were made in three areas to accomodate SNMP originally:

  1. Various hardware-specific ethernet drivers.
  2. The generic ethernet device driver.
  3. The OpenBSD TCP/IP networking package (Deprecated and removed from current eCosPro releases).

These changes were made in order to export information about the driver and the network that the SNMP agent must report. The changes were trivial in the case of the network stack, since it was already SNMP-friendly. The generic ethernet device driver was re-organized to have an extensive header file and to add a couple of APIs to extract statistics that the hardware-specific device drivers keep within themselves.

There may be a performance hit for recording that data; disabling a config option named something like CYGDBG_DEVS_ETH_xxxx_xxxx_KEEP_STATISTICS depending on the specific device driver will prevent that.

Not all platform ethernet device drivers export complete SNMP statistical information; if the exported information is missing, SNMP will report zero values for such data (in the dot3 MIB).

The interface chipset has an ID which is an OID; not all the latest greatest devices are listed in the available database, so new chipsets may need to be added to the client MIB, if not defined in those from UCD.

186.5. Starting the SNMP Agent

A routine to instantiate and start the SNMP agent thread in the default configuration is provided in PACKAGES/net/snmp/agent/current/src/snmptask.c

It starts the snmpd thread at priority CYGPKG_NET_THREAD_PRIORITY+1 by default, ie. one step less important than the TCP/IP stack service thread. It also statically creates and uses a very large stack of around 100 KiloBytes. To use that convenience function, this code fragment may be copied (in plain C).

#ifdef CYGPKG_SNMPAGENT
{
                extern void cyg_net_snmp_init(void);
                cyg_net_snmp_init();

}
#endif

In case you need to perform initialization, for example setting up SNMPv3 security features, when the snmp agent starts and every time it restarts, you can register a callback function by simply writing the global variable:

externC void (*snmpd_reinit_function)( void );

with a suitable function pointer.

The entry point to the SNMP agent is:

externC void snmpd( void (*initfunc)( void ) );

so you can of course easily start it in a thread of your choice at another priority instead if required, after performing whatever other initialization your SNMP MIBs need. A larger than default stacksize is required. The initfunc parameter is the callback function mentioned above — a NULL parameter there is safe and obviously means no callback is registered.

Note that if you call snmpd(); yourself and do not call cyg_net_snmp_init(); then that routine, global variable, and the default large stack will not be used. This is the recommended way control such features from your application; create and start the thread yourself at the appropriate moment.

Other APIs from the snmpd module are available, specifically:

void SnmpdShutDown(int a);

which causes the snmpd to restart itself — including the callback to your init function — as soon as possible.

The parameter a is ignored. It is there because in snmpd's “natural environment” this routine is a UNIX signal handler.

The helper functions in the network stack for managing DHCP leases will call SnmpdShutDown() when necessary, for example if network interfaces go down and/or come up again.

186.6. Configuring eCos

To use the SNMP agent, the SNMP library and agent packages must be included in your configuration. To incorporate the stack into your configuration select the SNMP library and SNMP agent packages in the eCos Configuration Tool, or at the command line type:

$ ecosconfig add snmplib snmpagent

After adding the networking, common ethernet device drivers, snmp library and snmp agent packages, there is no configuration required. However there are a number of configuration options that can be set such as some details for the System MIB, and disabling SNMPv3 support (see below).

Starting the SNMP agent is not integrated into network tests other than snmpping below, nor is it started automatically in normal eCos startup - it is up to the application to start the agent when it is ready, at least after the network interfaces are both ’up‚.

186.6.1. Version usage (v1, v2 or v3)

The default build supports all three versions of the SNMP protocol, but without any dispatcher functionality (rfc 2571, section 3.1.1.2). This has the following implications :

1. There is no community authentication for v1 and v2c.

2. Security provided by v3 can be bypassed by using v1/v2c protocol.

To provide the dispatcher with rfc 2571 type functionality, it is required to set up security models and access profiles. This can be provided in the normal Unix style by writing the required configurations in snmpd.conf file. Application code may setup profiles in snmpd.conf and optionally set the environment variable SNMPCONFPATH to point to the file if it is not in the usual location. The whole concept works in the usual way as with the standard UCD-SNMP distribution.

186.6.2. Traps

The support of the trapsink command in the snmpd.conf file is not tested and there may be problems for it working as expected. Moreover, in systems that do not have filesystem support, there is no way to configure a trap-session in the conventional way.

For reasons mentioned above, applications need to initialize their own trap sessions and pass it the details of trap-sink. The following is a small sample for initializing a v1 trap session :

typedef struct trap {
        unsigned char ip [4];
        unsigned int  port;
        unsigned char community [256];
}

trap            trapsink;
unsinged char   sink [16];

…
…

if (trapsink.ip != 0) {
        sprintf (sink, "%d.%d.%d.%d",
                 trapsink[0], trapsink[1], trapsink[2], trapsink[3]);
        if (create_trap_session (sink,
                trapsink.port,
                (char *)trapsink.community,
                SNMP_VERSION_1,
                SNMP_MSG_TRAP) == 0) {
                log_error ("Creation of trap session failed \n");
        }
}

186.6.3. snmpd.conf file

Using snmpd.conf requires the inclusion of one of the file-system packages (eg. CYGPKG_RAMFS) and CYGPKG_FILEIO. With these two packages included, the SNMP sub-system will read the snmpd.conf file from the location specified in SNMPCONFPATH, or the standard builtin locations, and use these profiles. Only the profiles specified in the ACCESS-CONTROL section of snmpd.conf file have been tested and shown to work. Other profiles which have been implemented in UCD-SNMP-4.1.2's snmpd.conf may not work because the sole purpose of adding support for the snmpd.conf file has been to set up ACCESS-CONTROL models.

At startup, the SNMP module tries to look for file snmp.conf. If this file is not available, the module successively looks for files snmpd.conf, snmp.local.conf and snmpd.local.conf at the locations pointed to by SNMPCONFPATH environment variable. In case SNMPCONFPATH is not defined, the search sequence is carried out in default directories. The default directories are :/usr/share/snmp, /usr/local/share/snmp and $(HOME)/.snmp. The configurations read from these files are used to control both, SNMP applications and the SNMP agent; in the usual UNIX fashion.

The inclusion of snmpd.conf support is enabled by default when suitable filesystems and FILEIO packages are active.

186.7. Test cases

Currently only one test program is provided which uses SNMP.

"snmpping" in the SNMP agent package runs the ping test from the TCPIP package, with the snmpd running also. This allows you to interrogate it using host tools of your choice. It supports MIBs as documented above, so eg. snmpwalk <hostname> public dot3 under Linux/UNIX should have the desired effect.

For serious testing, you should increase the length of time the test runs by setting CYGNUM_SNMPAGENT_TESTS_ITERATIONS to something big (e.g., 999999). Build the test (make -C net/snmp/agent/current tests) and run it on the target.

Then start several jobs, some for pinging the board (to make the stats change) and some for interrogating the snmpd. Set $IP to whatever IP address the board has:

# in a root shell, for flood ping
while(1)
date
ping -f -c 3001 $IP
sleep 5
ping -c 32 -s 2345 $IP
end
# have more than one of these going at once
setenv MIBS all
while (1)
snmpwalk -OS $IP  public
date
end

Leave to run for a couple of days or so to test stability.

The test program can also test snmpd.conf support. It tries to build a minimal snmpd.conf file on a RAM filesystem and passes it to the snmp sub-system. With this profile on target, the following snmp[cmd] (cmd=walk, get, set) should work :

snmp[cmd] -v1 $IP crux $OID
snmp[cmd] -v2 $IP crux $OID
snmp[cmd] -v3 $IP -u root -L noAuthNoPriv $OID
snmp[cmd] -v3 $IP -u root -L authNoPriv -A MD5 -a md5passwd $OID

The following commands would however fail since they violate the access model :

snmp[cmd] $IP public $OID
snmp[cmd] -v1 $IP public $OID
snmp[cmd] -v2c $IP public $OID
snmp[cmd] -v3 $IP -u no_user -L noAuthNoPriv $OID
snmp[cmd] -v3 $IP -u root -L authNoPriv -A MD5 -a badpasswd $OID

186.8. SNMP clients and package use

SNMP clients may use these packages, but this usage is currently untested: the reason why this port to eCos exists is to acquire the SNMP agent. The fact that that the SNMP API (for clients) exists is a side-effect. See the standard man page SNMP_API(3) for details. There are further caveats below about client-side use of the SNMP library.

All of the SNMP header files are installed beneath …/include/ucd-snmp in the install tree. The SNMP code itself assumes that directory is on its include path, so we recommend that client code does the same. Further, like the TCP/IP stack, compiling SNMP code requires definition of _KERNEL and __ECOS, and additionally IN_UCD_SNMP_SOURCE.

Therefore, add all of these to your compile lines if you wish to include SNMP header files:

-D_KERNEL
-D__ECOS
-DIN_UCD_SNMP_SOURCE=1
-I$(PREFIX)/include/ucd-snmp

186.9. Unimplemented features

Currently, the filesystem and persistent storage areas are left undone, to be implemented by the application.

The SNMP library package is intended to support client and agent code alike. It therefore contains lots of assumptions about the presence of persistent storage ie. a filesystem. Currently, by default, eCos has no such thing, so those areas have been simply commented out and made to return empty lists or say “no data here.”

Specifically the following files have omitted/unimplemented code :

PACKAGES/net/snmp/lib/current/src/parse.c

contains code to enumerate MIB files discovered in the system MIB directories (“/usr/share/snmp/mibs”), and read them all in, building data structures that are used by client programs to interrogate an agent. This is not required in an agent, so the routine which enumerates the directories returns an empty list.

PACKAGES/net/snmp/lib/current/src/read_config.c contains two systems:

The first tries to read the configuration file as described in the snmpd.conf file section and the second system contains code to record persistent data as files in a directory (typically /var/ucd-snmp) thus preserving the state permanently.

The first part is partially implemented to support multiple profiles and enables dispatcher functionality as discussed in Section 186.6.1, “Version usage (v1, v2 or v3)”. The second part is not supported at all in the default implementation. As required, a cleaner interface to permit application code to manage persistent data will be developed in consultation with customers.

186.10. MIB Compiler

In the directory /snmp/agent/current/utils/mib2c, there are the following files:

README-eCos             notes about running with a nonstandard
                        perl path.
README.mib2c            the README from UCD; full instructions on
                        using mib2c
mib2c                   the perl program
mib2c.conf              a configuration file altered to include the
                        eCos/UCD
mib2c.conf-ORIG         copyright and better #include paths; and
                        the ORIGinal.
mib2c.storage.conf      other config files, not modified.
mib2c.vartypes.conf

mib2c is provided BUT it requires the SNMP perl package SNMP-3.1.0, and that in turn requires perl nsPerl5.005_03 (part of Red Hat Linux from 6.0, April 1999).

These are available from the CPAN (“the Comprehensive Perl Archive Network”) as usual; http://www.cpan.org/ and links from there. Specifically:

(note that the .tar.gz files are not browsable)

For documentation on the files produced, see the documentation available at http://ucd-snmp.ucdavis.edu/ in general, and file AGENT.txt in particular.

It is likely that the output of mib2c will be further customized depending on eCos customer needs; it‚s easy to do this by editing the mib2c.conf file to add or remove whatever you need with the resulting C sources.

The UCD autoconf-style configuration does not apply to eCos. So if you add a completely new MIB to the agent, and support it using mib2c so that the my_new_mib.c file contains a init_my_new_mib() routine to register the MIB handler, you will also need to edit a couple of control files; these claim to be auto-generated, but in the eCos release, they‚re not, don‚t worry.

PACKAGES/net/snmp/agent/current/include/mib_module_includes.h

contains a number of lines like

#include “mibgroup/mibII/interfaces.h”

so add your new MIB thus:

#include “mibgroup/mibII/my_new_mib.h”
PACKAGES/net/snmp/agent/current/include/mib_module_inits.h 

contains a number of lines like

init_interfaces();
init_dot3(); 

and so on; add your new MIB as follows:

init_my_new_mib(); 

and this should work correctly.

186.11. snmpd.conf

SNMPD.CONF(5)                                       SNMPD.CONF(5)



NAME
       share/snmp/snmpd.conf  -  configuration  file for the ucd-
       snmp SNMP agent.

DESCRIPTION
       snmpd.conf is the configuration file which defines how the
       ucd-smnp SNMP agent operates.  These files may contain any
       of the directives found in the DIRECTIVES  section  below.
       This  file  is  not  required for the agent to operate and
       report mib entries.

PLEASE READ FIRST
       First, make sure you have read the  snmp_config(5)  manual
       page  that  describes how the ucd-snmp configuration files
       operate, where they are located  and  how  they  all  work
       together.

EXTENSIBLE-MIB
       The  ucd-snmp  SNMP  agent reports much of its information
       through queries to the 1.3.6.1.4.1.2021 section of the mib
       tree.   Every  mib in this section has the following table
       entries in it.

       .1 -- index
              This is the table's index numbers for each  of  the
              DIRECTIVES listed below.

       .2 -- name
              The  name of the given table entry.  This should be
              unique, but is not required to be.

       .100 -- errorFlag
              This is a flag returning either the integer value 1
              or  0 if an error is detected for this table entry.

       .101 -- errorMsg
              This is a DISPLAY-STRING describing any error trig-
              gering the errorFlag above.

       .102 -- errorFix
              If  this entry is SNMPset to the integer value of 1
              AND the errorFlag defined above is indeed  a  1,  a
              program  or script will get executed with the table
              entry name from above as the argument.  The program
              to  be  executed is configured in the config.h file
              at compile time.

   Directives
       proc NAME

       proc NAME MAX

       proc NAME MAX MIN

              Checks to see if the NAME'd processes  are  running
              on  the  agent's  machine.  An error flag (1) and a
              description  message  are  then   passed   to   the
              1.3.6.1.4.1.2021.2.100  and  1.3.6.1.4.1.2021.2.101
              mib tables (respectively) if the NAME'd program  is
              not  found  in  the  process  table  as reported by
              "/bin/ps -e".

              If MAX and MIN are not specified, MAX is assumed to
              be infinity and MIN is assumed to be 1.

              If  MAX  is specified but MIN is not specified, MIN
              is assumed to be 0.

       procfix NAME PROG ARGS
              This registers a command  that  knows  how  to  fix
              errors   with   the   given   process  NAME.   When
              1.3.6.1.4.1.2021.2.102 for a given NAMEd program is
              set to the integer value of 1, this command will be
              called.  It defaults to a compiled value set  using
              the PROCFIXCMD definition in the config.h file.

       exec NAME PROG ARGS

       exec MIBNUM NAME PROG ARGS

              If  MIBNUM is not specified, the agent executes the
              named PROG with arguments of ARGS and  returns  the
              exit status and the first line of the STDOUT output
              of   the   PROG   program   to   queries   of   the
              1.3.6.1.4.1.2021.8.100  and  1.3.6.1.4.1.2021.8.101
              mib  tables  (respectively).   All  STDOUT   output
              beyond the first line is silently truncated.

              If  MIBNUM  is  specified,  it  acts  as  above but
              returns the exit status  to  MIBNUM.100.0  and  the
              entire  STDOUT  output to the table MIBNUM.101 in a
              mib table.  In this case, the MIBNUM.101  mib  con-
              tains the entire STDOUT output, one mib table entry
              per line of output (ie, the first line is output as
              MIBNUM.101.1,  the second at MIBNUM.101.2, etc…).

              Note:  The MIBNUM must be specified in dotted-inte-
                     ger  notation  and  can  not be specified as
                     ".iso.org.dod.internet…"  (should  instead
                     be

              Note:  The  agent caches the exit status and STDOUT
                     of the executed program for 30 seconds after
                     the  initial  query.   This  is  to increase
                     speed and maintain consistency  of  informa-
                     tion  for  consecutive  table  queries.  The
                     cache can be flushed by a  snmp-set  request
                     of  integer(1)  to 1.3.6.1.4.1.2021.100.VER-
                     CLEARCACHE.

       execfix NAME PROG ARGS
              This registers a command  that  knows  how  to  fix
              errors  with  the  given  exec  or  sh  NAME.  When
              1.3.6.1.4.1.2021.8.102 for a given NAMEd  entry  is
              set to the integer value of 1, this command will be
              called.  It defaults to a compiled value set  using
              the EXECFIXCMD definition in the config.h file.

       disk PATH

       disk PATH [ MINSPACE | MINPERCENT% ]

              Checks  the  named disks mounted at PATH for avail-
              able disk space.  If the disk space  is  less  than
              MINSPACE  (kB) if specified or less than MINPERCENT
              (%) if a  %  sign  is  specified,  or  DEFDISKMINI-
              MUMSPACE  (kB)  if  not  specified,  the associated
              entry in the 1.3.6.1.4.1.2021.9.100 mib table  will
              be  set to (1) and a descriptive error message will
              be returned to queries of 1.3.6.1.4.1.2021.9.101.

       load MAX1

       load MAX1 MAX5

       load MAX1 MAX5 MAX15

              Checks the load average of the machine and  returns
              an error flag (1), and an text-string error message
              to   queries   of    1.3.6.1.4.1.2021.10.100    and
              1.3.6.1.4.1.2021.10.101   (respectively)  when  the
              1-minute, 5-minute, or  15-minute  averages  exceed
              the associated maximum values.  If any of the MAX1,
              MAX5, or MAX15 values are unspecified, they default
              to a value of DEFMAXLOADAVE.

       file FILE [MAXSIZE]
              Monitors  file sizes and makes sure they don't grow
              beyond a certain size.  MAXSIZE defaults  to  infi-
              nite  if  not specified, and only monitors the size
              without reporting errors about it.

   Errors
       Any errors in obtaining the above information are reported
       via    the    1.3.6.1.4.1.2021.101.100    flag   and   the
       1.3.6.1.4.1.2021.101.101 text-string description.

SMUX SUB-AGENTS
       To enable and SMUX based sub-agent, such as gated, use the
       smuxpeer configuration entry

       smuxpeer OID PASS
              For gated a sensible entry might be

       .1.3.6.1.4.1.4.1.3 secret

ACCESS CONTROL
       snmpd  supports the View-Based Access Control Model (vacm)
       as defined in RFC 2275.  To this end,  it  recognizes  the
       following  keywords  in  the  configuration file: com2sec,
       group, access, and view  as  well  as  some  easier-to-use
       wrapper   directives:  rocommunity,  rwcommunity,  rouser,
       rwuser.

       rocommunity COMMUNITY [SOURCE] [OID]

       rwcommunity COMMUNITY [SOURCE] [OID]
              These create read-only and  read-write  communities
              that  can  be used to access the agent.  They are a
              quick method of using the following com2sec, group,
              access,  and view directive lines.  They are not as
              efficient either, as groups aren't created  so  the
              tables  are possibly larger.  In other words: don't
              use these if you have complex situations to set up.

              The  format  of the SOURCE is token is described in
              the com2sec directive section below.  The OID token
              restricts  access  for that community to everything
              below that given OID.

       rouser USER [noauth|auth|priv] [OID]

       rwuser USER [noauth|auth|priv] [OID]
              Creates a  SNMPv3  USM  user  in  the  VACM  access
              configuration  tables.   Again,  its more efficient
              (and powerful) to use the combined com2sec,  group,
              access, and view directives instead.

              The minimum level of authentication and privacy the
              user must use  is  specified  by  the  first  token
              (which  defaults  to  "auth").   The  OID parameter
              restricts access for that user to everything  below
              the given OID.

       com2sec NAME SOURCE COMMUNITY
              This   directive   specifies  the  mapping  from  a
              source/community pair to a  security  name.  SOURCE
              can be a hostname, a subnet, or the word "default".
              A subnet can be specified as  IP/MASK  or  IP/BITS.
              The first source/community combination that matches
              the incoming packet is selected.

       group NAME MODEL SECURITY
              This directive defines the mapping  from  security-
              model/securityname  to  group.  MODEL is one of v1,
              v2c, or usm.

       access NAME CONTEXT MODEL LEVEL PREFX READ WRITE NOTIFY
              The  access  directive  maps  from   group/security
              model/security  level  to  a view.  MODEL is one of
              any, v1, v2c, or usm.   LEVEL  is  one  of  noauth,
              auth,  or priv.  PREFX specifies how CONTEXT should
              be matched against the context of the incoming pdu,
              either  exact  or  prefix.   READ, WRITE and NOTIFY
              specifies the view to be used for the corresponding
              access.   For  v1  or  v2c  access,  LEVEL  will be
              noauth, and CONTEXT will be empty.

       view NAME TYPE SUBTREE [MASK]
              The defines the named view. TYPE is either included
              or  excluded.   MASK is a list of hex octets, sepa-
              rated by '.' or ':'.  The MASK defaults to "ff"  if
              not specified.

              The  reason  for the mask is, that it allows you to
              control access to one row in a table,  in  a  rela-
              tively  simple  way.  As  an example, as an ISP you
              might consider giving each customer access  to  his
              or her own interface:

              view cust1 included interfaces.ifTable.ifEntry.ifIndex.1 ff.a0
              view cust2 included interfaces.ifTable.ifEntry.ifIndex.2 ff.a0

              (interfaces.ifTable.ifEntry.ifIndex.1 == .1.3.6.1.2.1.2.2.1.1.1,
              ff.a0 == 11111111.10100000. which nicely covers up and including
              the row index, but lets the user vary the field of the row)

       VACM Examples:
              #       sec.name  source          community
              com2sec local     localhost       private
              com2sec mynet     10.10.10.0/24   public
              com2sec public    default         public

              #             sec.model  sec.name
              group mygroup v1         mynet
              group mygroup v2c        mynet
              group mygroup usm        mynet
              group local   v1         local
              group local   v2c        local
              group local   usm        local
              group public  v1         public
              group public  v2c        public
              group public  usm        public

              #           incl/excl subtree                          mask
              view all    included  .1                               80
              view system included  system                           fe
              view mib2   included  .iso.org.dod.internet.mgmt.mib-2 fc

              #              context sec.model sec.level prefix read   write notify
              access mygroup ""      any       noauth    exact  mib2   none  none
              access public  ""      any       noauth    exact  system none  none
              access local   ""      any       noauth    exact  all    all   all

       Default VACM model
              The default configuration of the agent, as shipped, is functionally
              equivalent to the following entries:
              com2sec   public    default   public
              group     public    v1   public
              group     public    v2c  public
              group     public    usm  public
              view      all  included  .1
              access    public    ""   any  noauth    exact     all  none none

SNMPv3 CONFIGURATION
       engineID STRING
              The  snmpd  agent  needs  to  be configured with an
              engineID to be able to respond to SNMPv3  messages.
              With  this  configuration  file  line, the engineID
              will be configured from STRING.  The default  value
              of  the  engineID  is  configured with the first IP
              address found for the hostname of the machine.

       createUser username (MD5|SHA) authpassphrase [DES]  [priv-
       passphrase]
              This directive should be placed into the "/var/ucd-
              snmp"/snmpd.conf  file  instead of the other normal
              locations.  The reason is that the  information  is
              read  from  the  file  and then the line is removed
              (eliminating the storage of the master password for
              that  user)  and  replaced  with  the  key  that is
              derived from it.  This key is a localized  key,  so
              that  if  it is stolen it can not be used to access
              other agents.  If the password is stolen,  however,
              it can be.

              MD5  and  SHA  are the authentication types to use,
              but you must have built the  package  with  openssl
              installed  in  order  to use SHA.  The only privacy
              protocol currently supported is DES.  If  the  pri-
              vacy  passphrase is not specified, it is assumed to
              be the same as the authentication passphrase.  Note
              that  the users created will be useless unless they
              are also added to the VACM  access  control  tables
              described above.

              Warning:  the minimum pass phrase length is 8 char-
              acters.

              SNMPv3 users can be created at  runtime  using  the
              snmpusm command.


SETTING SYSTEM INFORMATION
       syslocation STRING

       syscontact STRING

              Sets the system location and the system contact for
              the agent.  This information  is  reported  by  the
              'system' table in the mibII tree.

       authtrapenable NUMBER
              Setting  authtrapenable  to 1 enables generation of
              authentication failure traps. The default value  is
              2 (disable).

       trapcommunity STRING
              This  defines  the  default  community string to be
              used when sending traps.  Note  that  this  command
              must  be  used  prior to any of the following three
              commands  that  are  intended  use  this  community
              string.

       trapsink HOST [COMMUNITY [PORT]]

       trap2sink HOST [COMMUNITY [PORT]]

       informsink HOST [COMMUNITY [PORT]]
              These  commands  define  the hosts to receive traps
              (and/or inform notifications). The daemon  sends  a
              Cold  Start  trap when it starts up. If enabled, it
              also sends traps on authentication failures.   Mul-
              tiple  trapsink, trap2sink and informsink lines may
              be specified to specify multiple destinations.  Use
              trap2sink  to  send  SNMPv2 traps and informsink to
              send inform notifications.   If  COMMUNITY  is  not
              specified,  the  string from a preceding trapcommu-
              nity directive will be used. If PORT is not  speci-
              fied,  the  well known SNMP trap port (162) will be
              used.

PASS-THROUGH CONTROL
       pass MIBOID EXEC
              Passes entire control of MIBOID to  the  EXEC  pro-
              gram.   The  EXEC  program  is called in one of the
              following three ways:

              EXEC -g MIBOID

              EXEC -n MIBOID

                     These call lines match to SNMP get and  get-
                     next requests.  It is expected that the EXEC
                     program will take the arguments passed to it
                     and  return the appropriate response through
                     it's stdout.

                     The first line of stdout should be  the  mib
                     OID of the returning value.  The second line
                     should be the TYPE of value returned,  where
                     TYPE  is  one  of  the text strings: string,
                     integer,  unsigned,   objectid,   timeticks,
                     ipaddress,  counter,  or  gauge.   The third
                     line of stdout should be  the  VALUE  corre-
                     sponding with the returned TYPE.

                     For  instance, if a script was to return the
                     value integer value "42" when a request  for
                     .1.3.6.1.4.100  was  requested,  the  script
                     should return the following 3 lines:
                       .1.3.6.1.4.100
                       integer
                       42

                     To indicate that the  script  is  unable  to
                     comply with the request due to an end-of-mib
                     condition or an invalid request, simple exit
                     and  return  no  output to stdout at all.  A
                     snmp error will be  generated  corresponding
                     to the SNMP NO-SUCH-NAME response.

              EXEC -s MIBOID TYPE VALUE

                     For SNMP set requests, the above call method
                     is used.  The TYPE passed to the  EXEC  pro-
                     gram  is  one  of the text strings: integer,
                     counter, gauge, timeticks, ipaddress, objid,
                     or  string,  indicating  the  type  of value
                     passed in the next argument.

                     Return nothing to stdout, and the  set  will
                     assumed to have been successful.  Otherwise,
                     return one of the following error strings to
                     signal an error: not-writable, or wrong-type
                     and the appropriate error response  will  be
                     generated instead.

                      Note:  By   default,   the  only  community
                             allowed to  write  (ie  snmpset)  to
                             your  script  will  be the "private"
                             community,or community #2 if defined
                             differently by the "community" token
                             discussed above.  Which  communities
                             are  allowed  write  access are con-
                             trolled by the RWRITE definition  in
                             the snmplib/snmp_impl.h source file.

EXAMPLE
       See the EXAMPLE.CONF file in the top level  source  direc-
       tory for a more detailed example of how the above informa-
       tion is used in real examples.

RE-READING snmpd.conf and snmpd.local.conf
       The ucd-snmp agent can be forced to re-read its configura-
       tion files.  It can be told to do so by one of two ways:

       1.     An       snmpset       of       integer(1)       to
              1.3.6.1.4.1.2021.100.VERUPDATECONFIG.

       2.     A "kill -HUP" signal sent to the snmpd  agent  pro-
              cess.

FILES
       share/snmp/snmpd.conf

SEE ALSO
       snmp_config(5), snmpd(1), EXAMPLE.conf, read_config(3).



                           27 Jan 2000              SNMPD.CONF(5)