eCos Reference Manual
Prev | Chapter 52. SNMP for eCos | Next

# 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)

Prev | Home | Next
MIB Compiler | Up | Embedded HTTP Server