Provided by: snmpd_5.2.1.2-4ubuntu2_i386 bug

NAME

       snmpd.conf - configuration file for the Net-SNMP SNMP agent

DESCRIPTION

       snmpd.conf  is  the  configuration  file which defines how the Net-SNMP
       SNMP agent operates.  These files may contain  any  of  the  directives
       found  in  the DIRECTIVES section below.  If this file is not found (or
       does not contain any access control directives), the agent will run but
       will not respond to any requests.

PLEASE READ FIRST

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

       Also,  you  might  consider looking into the snmpconf application (perl
       script) which can help you build an snmpd.conf file  by  prompting  you
       for  information.   You  should try it.  Really.  Go ahead.  Right now.
       Run:

              snmpconf -g basic_setup

       to  get  you  started.  See  the  snmpconf(1)  manual  page  for   more
       information.

EXTENSIBLE-MIB

       The Net-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  triggering  the
              errorFlag above.

       .102 -- errorFix
              If this entry is set 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  net-snmp-
              config.h file at compile time.

   Directives
       proc NAME

       proc NAME MAX

       proc NAME MAX MIN

              Checks  to see if processes called NAME are running on the agent
              machine.  An error flag (1) and a description message  are  then
              passed       to       the      1.3.6.1.4.1.2021.2.1.100      and
              1.3.6.1.4.1.2021.2.1.101  MIB  columns  (respectively)  if   the
              NAME’d  program is not found in the process table as reported by
              " -acx".

              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.1.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 net-snmp-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.1.100    and   1.3.6.1.4.1.2021.8.1.101   mib
              columns (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
              contains 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-integer  notation
                     and  can  not  be specified as ".iso.org.dod.internet..."
                     (should instead be .1.3.6.1...).

              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
                     information 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.VERCLEARCACHE.

       extend NAME PROG ARGS

       extend MIBNUM NAME PROG ARGS

              This  is  similar  to the ’exec’ directive, but uses a different
              MIB output structure (for both forms)  which  covers  multi-line
              output   as  standard.   See  NET-SNMP-EXTEND-MIB  for  details.
              Output is cached for each entry separately,  controlled  by  the
              NET-SNMP-AGENT-MIB::nsCacheTable.

       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.1.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 net-snmp-config.h file.

       disk PATH

       disk PATH [ MINSPACE | MINPERCENT% ]

              Checks the named disks mounted at PATH for available disk space.
              If the disk space is less than MINSPACE  (kB)  if  specified  or
              less   than  MINPERCENT  (%)  if  a  %  sign  is  specified,  or
              DEFDISKMINIMUMSPACE (kB) if not specified, the associated  entry
              in the 1.3.6.1.4.1.2021.9.1.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.1.101.

       includeAllDisks MINPERCENT%

              Adds  all  the  disks  that can be found on the system using the
              setmntent(3) and getmntent(3), or fopen(3) and getmntent(3),  or
              setfsent(3)  and  getfsent(3) system calls. If none of the above
              system calls are available then it adds the root partition  "/",
              (which  is  assumed to exist on any UNIX based system) using the
              statfs(2) system call.

              There can only be one ’includeAllDisks’ directive in the config-
              uration  file.  It  can  be  used in conjunction with the ’disk’
              directive. They may be used in any order. The  ’disk’  directive
              overrides  the  disk  usage  specified  by the ’includeAllDisks’
              directive, no matter in which order they are  specified  in  the
              configuration file.

              The ’includeAllDisks’ directive only includes the disks that are
              mounted when the snmpd daemon  is  started.  It  cannot  include
              disks  that are dynamically loadable, such as with automount. So
              the preferred way is to mount all the disks that will ever  need
              to be monitored before starting the snmpd daemon.

       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.1.100      and     1.3.6.1.4.1.2021.10.1.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 (in kilobytes).  MAXSIZE defaults  to  infinite  if
              not  specified,  and  only  monitors  the size without reporting
              errors about it.  A maximum of 20 files can be monitored.

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

AGENTX SUB-AGENTS

       To enable AgentX support in the SNMP master agent,  put  the  following
       line in your snmpd.conf file:

       master agentx
              See README.agentx for further details.

       AgentXSocket addr
              This  defines  the  address  the  master  agent listens at.  The
              default is /var/agentx/master. By default the Unix Domain socket
              is  accessible  only  to subagents which have the same userid as
              the agent.  Another possibility is localhost:705

       AgentXTimeout addr
              Defines the timeout period for an AgentX request.  Default is  1
              second.

       AgentXRetries addr
              Defines the number of retries for an AgentX request.  Default is
              5 retries.

       You can also put  the  following  in  your  subagent.conf  file  (where
       "subagent" is the name you used in your init_snmp("subagent") api call:

       agentPingInterval NUM
              This makes the subagent try and reconnect every NUM  seconds  to
              the master if it ever becomes (or starts) disconnected.

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 smuxpeer  .1.3.6.1.4.1.4.1.3
              secret

DYNAMICALLY LOADABLE MODULES

       If  the agent is built with support for the UCD-DLMOD-MIB it is capable
       of loading agent MIB modules dynamically at startup through  the  dlmod
       directive  and  during  runtime  through use of the UCD-DLMOD-MIB.  The
       following directive loads the shared object module file PATH which uses
       the module name prefix NAME.

       dlmod NAME PATH

ACCESS CONTROL

       snmpd supports the View-Based Access Control Model (VACM) as defined in
       RFC 2575.  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.   If  IPv6  support  has  been  enabled,  the  rocommunity6 and
       rwcommunity6 tokens will also be available.  This section  defines  how
       to  configure  the  snmpd program to accept various types and levels of
       access.

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

       rwuser USER [noauth|auth|priv [OID]]
              Creates a SNMPv3 USM  user  in  the  VACM  access  configuration
              tables.  It is more efficient (and powerful) to use the combined
              group, access, and view directives instead,  but  these  wrapper
              directives are much simpler.

              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.

       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 wrapper around the
              more complex and  powerful  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.
              If your setup is simple or you don’t mind  a  small  performance
              hit, use these directives.

              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.

       rocommunity6 COMMUNITY [SOURCE [OID]]

       rwcommunity6 COMMUNITY [SOURCE [OID]]
              They   are   the  alternative  directives  to  the  rocommunity,
              rwcommunity for the transport  domain  UDPIPv6.  They  are  only
              valid in specifing UDPIPv6 as transport domain.

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

       com2sec [-Cn CONTEXT] 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.   For  example,  given  a  directive  "com2sec  myLocal
              10.10.10.0/24  public"  then  this  would match requests from IP
              addresses 10.10.10.0 through to 10.10.10.255, but not  one  from
              10.10.11.1  or  similar.  The first source/community combination
              that matches the incoming packet is selected.  If a  CONTEXT  is
              specified,  the community name gets mapped to the SNMPv3 CONTEXT
              of the same name, otherwise the default context ("") is used.

       com2sec6  [-Cn CONTEXT] NAME SOURCE COMMUNITY
              This directive is the IPv6 version of com2sec.  A subnet can  be
              specified  as  IPv6/IPv6MASK  or IPv6/BITS.  It is only valid in
              specifing UDPIPv6 as transport domain.

       group NAME MODEL SECURITY
              This      directive      defines      the      mapping      from
              securitymodel/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]
              This  defines  the  named  view.  TYPE  is  either  included  or
              excluded.   MASK  is  a  list of hex octets, separated 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  relatively 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
              com2sec6 mynet     fec0::/64       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.  If this
              directive is omitted, the default value of the engineID is built
              from  2  fairly random elements: a random number and the current
              time in seconds.

       createUser  [-e  ENGINEID]  username  (MD5|SHA)  authpassphrase   [DES]
       [privpassphrase]

              MD5 and SHA are the  authentication  types  to  use.   The  only
              privacy  protocol  currently  supported  is DES.  If the privacy
              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.

              SHA  authentication  and  DES  privacy  require  OpenSSL  to  be
              installed and the agent to be built with OpenSSL  support.   MD5
              authentication may be used without OpenSSL.

              Warning: the minimum pass phrase length is 8 characters.

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

              Instead of figuring out how to use this directive and  where  to
              put   it   (see  below),  just  run  "net-snmp-config  --create-
              snmpv3-user" instead, which will add one of these lines  to  the
              right place.

              This     directive     should     be     placed     into     the
              /var/lib/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.

              If you need to localize the user to a particular EngineID  (this
              is  useful  mostly  in the similar snmptrapd.conf file), you can
              use the -e argument to specify an EngineID as a hex  value  (EG,
              "0x01020304").

              If  you  want  to  generate either your master or localized keys
              directly, replace the given password with a hexstring (preceeded
              by  a  "0x")  and  precede  the  hex  string by a -m or -l token
              (respectively).  EGs:

              [these keys are *not* secure but are easy to visually parse for
              counting purposes.  Please generate random keys instead of using
              these examples]

              createUser myuser SHA -l 0x0001020304050607080900010203040506070809 AES -l 0x00010203040506070809000102030405
              createUser myuser SHA -m 0x0001020304050607080900010203040506070809 AES -m 0x0001020304050607080900010203040506070809

              Due to the way localization happens, localized privacy keys  are
              expected  to be the length needed by the algorithm (128 bits for
              all supported algorithms).  Master encryption keys, though, need
              to  be  the  length required by the authentication algorithm not
              the length required by the encrypting algorithm (MD5: 16  bytes,
              SHA: 20 bytes).

SETTING SYSTEM INFORMATION

       syslocation STRING

       syscontact STRING

       sysname STRING
              Sets  the system location, system contact or system name for the
              agent.  This information is reported in the ’system’  group  the
              mibII    tree.    Ordinarily   these   objects   (sysLocation.0,
              sysContact.0 and sysName.0) are read-write.  However, specifying
              the  value  for  one  of these objects by giving the appropriate
              token makes the corresponding object read-only, and attempts  to
              set  the  value of the object will result in a notWritable error
              response.

       sysservices NUMBER
              Sets the value of the system.sysServices.0 object.  For a  host,
              a good value is 72.

       sysdescr STRING

       sysobjectid OID
              Sets  the  system  description  or  object  ID  for  the  agent.
              Although these values are not SNMP-writable, it  is  conceivable
              that  a  network  administrator  may  wish  to configure them to
              something other than the default values.

       agentaddress [<transport-specifier>:]<transport-address>[,...]
              Makes the agent list on the specified  comma-separated  list  of
              listening  addresses  instead of the default behaviour, which is
              to listen on UDP port 161  on  all  IPv4  interfaces.   See  the
              section LISTENING ADDRESSES in the snmpd(8) manual page for more
              information  about  the  format  of  listening  addresses.   For
              example, specifying agentaddress 161,tcp:161,localhost:9161 will
              make the agent listen on UDP port 161 on  all  IPv4  interfaces,
              TCP  port  161  on all IPv4 interfaces and UDP port 9161 only on
              the interface associated with the localhost address.

       agentgroup groupid
              Change to this gid after opening port. The groupid may refer  to
              a group by name or a number if the group number starts with ’#’.
              For example, specifying agentgroup snmp will cause the agent  to
              run  as the snmp group or agentgroup #10 will cause the agent to
              run as the group with groupid 10.

       agentuser uid
              Change to this uid after opening port. The userid may refer to a
              user by name or a number if the user number starts with ’#’. For
              example, specifying agentuser snmp will cause the agent  to  run
              as the snmp user or agentuser #10 will cause the agent to run as
              the user with userid 10.

       interface NAME TYPE SPEED
              For interfaces where the agent fails to guess correctly  on  the
              type   and   speed,   this   directive   can  supply  additional
              information.  TYPE is a type value as given in  the  IANAifType-
              MIB.

       ignoredisk STRING
              When  scanning  for available disk devices the agent might block
              in trying to open all possible disk devices. This might lead  to
              a  timeout when walking the device tree. Sometimes the next walk
              will run without timeout, sometimes it will timeout  every  time
              you try it.

              If  you  experience  such behaviour you might add this directive
              and give all device names not to be checked (i.e.  opened).  You
              might  have  more  than one such directive in your configuration
              file stating all devices  not  to  be  opened.  You  might  also
              specify  those devices using wildcards similar to the syntax you
              can use in a bourne shell (see examples below).

              Note: For a list of devices  scanned  for  every  system  please
              consult   the   sources   (host/hr_disk.c)  and  check  for  the
              Add_HR_Disk_entry() calls relevant for your type of OS.

              Examples:

              ignoredisk /dev/rdsk/c0t2d0

              This directive prevents the device /dev/rdsk/c0t2d0  from  being
              scanned.

              ignoredisk /dev/rdsk/c0t[!6]d0

              This  directive  prevents  all  devices  /dev/rdsk/c0tXd0 except
              .../c0t6d0 from being scanned. For most systems similar  is  the
              following directive:

              ignoredisk /dev/rdsk/c0t[0-57-9a-f]d0

              ignoredisk /dev/rdsk/c1*

              This  directive  prevents  all  devices whose device names start
              with /dev/rdsk/c1 from being scanned.

              ignoredisk /dev/rdsk/c?t0d0

              This directive prevents all devices /dev/rdsk/cXt0d0 (’X’  might
              be any char) from being scanned.

              You might use more than one such wildcard expression in any such
              directive.

       storageUseNFS NUMBER
              Setting storageUseNFS to 1 causes  all  NFS  and  NFS-like  file
              systems  to  be marked as ’Network Disks’ in the hrStorageTable.
              This is according to RFC 2790.   Not  setting  storageUseNFS  or
              setting  it  to  2  causes  NFS  and NFS-like file systems to be
              marked as ’Fixed Disks’ as it has been in previous  versions  of
              the ucd-snmp SNMP agent.

       authtrapenable NUMBER
              Setting authtrapenable to 1 enables generation of authentication
              failure traps.  The default value  is  disabled(2).   Ordinarily
              the  corresponding  object  (snmpEnableAuthenTraps.0)  is  read-
              write, but setting its value via this  token  makes  the  object
              read-only,  and  attempts  to  set  the value of the object will
              result in a notWritable error response.

       override [-rw] OID TYPE VALUE
              This directive allows you to override a particular  OID  with  a
              different  value  (and possibly a different type of value).  The
              -rw flag will allow snmp SETs to  modify  it’s  value  as  well.
              (note  that  if  you’re  overriding original functionality, that
              functionality will be entirely lost.  Thus SETS will do  nothing
              more  than  modify  the  internal  overridden value and will not
              perform  any  of  the  original  functionality  intended  to  be
              provided  by  the  MIB  object.   It’s  an  emulation only.)  An
              example:

              override sysDescr.0 octet_str "my own sysDescr"

              That line will set the sysDescr.0 value to "my own sysDescr"  as
              well  as  make  it  modifiable  with SNMP SETs as well (which is
              actually illegal according to the MIB specifications).

              Note that care must be taken when using this.  For  example,  if
              you  try  to  override  a  property  of the 3rd interface in the
              ifTable with a new value and  later  the  numbering  within  the
              ifTable  changes it’s index ordering you’ll end up with problems
              and your modified value won’t appear in the right place  in  the
              table.

              Valid   TYPEs  are:  integer,  uinteger,  octet_str,  object_id,
              counter, null (for gauge’s, use "uinteger"; for bit strings, use
              "octet_str").  Note that setting an object to "null" effectively
              delete’s it as being accessible.  No VALUE needs to be given  if
              the object type is null.

              More types should be available in the future.

SETTING UP TRAP AND/OR INFORM DESTINATIONS

       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.  Multiple 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
              trapcommunity  directive will be used. If PORT is not specified,
              the well known SNMP trap port (162) will be used.

       trapsess [SNMPCMD_ARGS] HOST
              This is a more generic trap configuration token that allows  any
              type  of  trap  destination  to be specified with any version of
              SNMP.  See the snmpcmd(1) manual page for further details on the
              arguments  that  can be passed as SNMPCMD ARGS .  In addition to
              the arguments listed there, the special argument  -Ci  specifies
              that  you  want  inform  notifications  to  be  used  instead of
              unacknowledged traps (this requires  that  you  also  specify  a
              version number of v2c or v3 as well).

PROXY SUPPORT

       proxy [-Cn CONTEXTNAME] [SNMPCMD ARGS] HOST OID [REMOTEOID]

              This token specifies that any incoming requests under OID should
              be proxied on to another HOST  instead.   If  a  CONTEXTNAME  is
              specified,  it  assigns the proxied tree to a particular context
              name within the local agent.  This is the proper  way  to  query
              multiple  agents  through  a  single  proxy.  Assign each remote
              agent to a different context name.  Then you can  use  "snmpwalk
              -n  contextname1" to walk one remote proxied agent and "snmpwalk
              -n contextname2" to walk another, assuming you are using  SNMPv3
              to talk to the proxy (snmpv1 and snmpv2c context mappings aren’t
              currently supported but might be in  the  future).   Optionally,
              relocate  the  local  OID  tree  to  the  new  location  at  the
              REMOTEOID.   To  authenticate  to  HOST  you  should   use   the
              appropriate set of SNMPCMD ARGS.  See the snmpcmd(1) manual page
              for details.

              Examples:
              # assigns the entire mib tree on remotehost1 to the context of the
              # same name:
              proxy -Cn remotehost1 -v 1 -c public remotehost1 .1.3
              # ditto, but for remotehost 2
              proxy -Cn remotehost2 -v 1 -c public remotehost2 .1.3
              # proxies only the ucdavis enterprises tree to the remote host using snmpv1
              proxy -v 1 -c public remotehost .1.3.6.1.4.1.2021
              # uses v3 to access remotehost and converts the remote .1.3.6.1.2.1.1
              # oid to local .1.3.6.1.3.10 oid (another way to access mulitple hosts
              # without using contexts)
              proxy -v 3 -l noAuthNoPriv -u user remotehost .1.3.6.1.3.10 .1.3.6.1.2.1.1

PASS-THROUGH CONTROL

       pass MIBOID EXEC
              (If you’re writing perl scripts, please see  the  embedded  perl
              support  information  later in this manual page).  Passes entire
              control of MIBOID to the EXEC  program.   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 getnext 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 corresponding 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.  An SNMP error will be  generated  corresponding  to
                     the SNMP noSuchName response.

              EXEC -s MIBOID TYPE VALUE

                     For  SNMP  set  requests,  the above call method is used.
                     The TYPE passed to the EXEC program 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
                             controlled  by  the  RWRITE  definition  in   the
                             snmplib/snmp_impl.h source file.

              Example (in snmpd.conf):

              pass .1.3.6.1.4.1.2021.255 /path/to/local/passtest

       pass_persist MIBOID EXEC
              Passes entire control of MIBOID to the EXEC program.  Similar to
              pass, but the EXEC program continues to run  after  the  initial
              request  is  answered.   Also,  pass and pass_persist block till
              they return.

              Upon initialization, EXEC  is  passed  the  string  "PING\n"  in
              stdin, and it should respond by printing "PONG\n" to stdout.

              For  get and getnext requests, EXEC program is passed two lines,
              the command (get or getnext) and the MIB OID.  It should  return
              three  lines, the MIB OID, the TYPE of value returned, the VALUE
              corresponding with the returned TYPE.

              For example, if the value for .1.3.6.1.4.100 was requested,  the
              following 2 lines would be passed in to stdin:
                get
                .1.3.6.1.4.100

              To return the value, say, 42, the script would write to stdout:
                .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,  print
              "NONE\n" to stdout.

              Example (in snmpd.conf):

              pass_persist                               .1.3.6.1.4.1.2021.255
              /path/to/local/pass_persisttest

EMBEDDED PERL SUPPORT

       Warning: though embedded perl is working, not  much  functionality  has
       been  implemented  yet and thus writing mib module pieces for the agent
       within perl is not trivial at this point.   It  should  get  better  in
       future releases.

       The  net-snmp  package has ability to call perl scripts directly inside
       the agent through embedded perl technology (similar to mod_perl for the
       apache  web server).  This must be turned on at compile time by passing
       --enable-embedded-perl to the configure  script  when  the  package  is
       built.   To see if your package was built with embedded perl, run "net-
       snmp-config --configure-options" and see if that flag was used.

       If compiled in,  it  defines  the  following  snmpd.conf  configuration
       directives:

       disablePerl true
              This  will turn off perl support entirely.  If the embedded perl
              support stops working due to a change in perl,  etc,  this  will
              stop any calls to the perl core.

       perlInitFile FILE
              Use  FILE  as  the  initialization  file.  This file is normally
              /usr/share/snmp/snmp_perl.pl but this token  can  override  that
              default.   This file performs any in-perl initialization that is
              needed before the  rest  of  the  perl  directives  (below)  are
              called.  It is sourced once just before the first perl directive
              is  parsed.   See  the  default  file  for  an  example  of  the
              initialization it performs.

       perl EXPRESSION
              Calls perl to evaluate an expression.  Normally you’d want to do
              something like register a  function  to  call  when  an  OID  is
              requested, but you can really do anything perl related you want.
              For example:

              perl print "hello world\n";

              is the most basic hello world example.

              The init script by default initializes a $agent  variable  which
              is  a  pointer  to a NetSnmp::agent object through which you can
              register callbacks when a section of the OID tree is hit:
              perl use Data::Dumper;
              perl sub myroutine  { print "got called: ",Dumper(@_),"\n"; }
              perl $agent->register(’mylink’, ’.1.3.6.1.8765’, \&myroutine);

              Sourcing an external file:
              perl ’do /path/to/file.pl’;

              No better examples exist at the moment, unfortunately.  Look for
              improved support in future releases.  Comments on how this looks
              as an architecture are certainly appreciated now.

DISMAN-EVENT-MIB SUPPORT (READ: SENDING TRAPS ON ERRORS)

       Warning: this implementation has not been  extensively  tested  and  is
       additionally  not  known to be entirely complete.  The concepts defined
       here should function appropriately, however, but no promises  are  made
       at this time.

       If  your  agent was compiled with support for the DISMAN-EVENT-MIB (you
       can enable this by running  the  net-snmp  configure  script  with  the
       --with-mib-modules=disman/event-mib  argument)  you  have  support  for
       having the agent check its own data at regular intervals  and  to  send
       out   traps  when  certain  conditions  occur.   Traps  are  sent  when
       expressions are first noticed, not once per evaluation.   Once  a  test
       expression  fires a trap, the test will have to fail again before a new
       trap is sent.  See the DISMAN-EVENT-MIB documentation for more details.
       This  can  be  configured  either using the MIB tables themselves or by
       using these special key words:

       agentSecName NAME
              The DISMAN-EVENT-MIB support requires  a  valid  user  name  for
              which  to  scan  your  agent with.  This can either be specified
              using the agentSecName token or by explicitly list  one  on  the
              "monitor"  lines  described  below  using the -u switch.  Either
              way, a "rouser" line (or  equivalent  access  control  settings)
              must also be specified with the same security name name.  If you
              need an example, just do something like this:

                     agentSecName internal
                     rouser internal

              And everything below should work just fine.

       monitor [OPTIONS] NAME EXPRESSION
              This token tells the agent to monitor itself for problems  based
              on  EXPRESSION.   Expression  is a simple expression based on an
              oid, a comparison operator (!=, ==, <, <=, >, >=) and an integer
              value  (see  the  examples  below).  NAME is merely an arbitrary
              name of your choosing for administrative purposes only.  OPTIONS
              include the following possibilities:

              -t     Use  a  threshold  monitor  instead of a boolean monitor.
                     This means that expression  should  be  a  low  and  high
                     value.   If the given OID passes beyond the high value, a
                     rising alarm will triggered.  A falling alarm  will  then
                     be triggered after it falls below the low value.

              -r FREQUENCY
                     Monitors  the  given  expression every FREQUENCY seconds.
                     The default is 600 (10 minutes).

              -u SECNAME
                     Use the SECNAME security  name  for  scanning  the  local
                     host.   Specifically,  this  SECNAME  must  then be given
                     access control rights via  something  like  the  "rouser"
                     snmpd.conf  token for this expression to be valid at all.
                     If not specified,  it  uses  the  default  security  name
                     specified  by  the agentsecname snmpd.conf token.  Either
                     the -u  flag  or  a  valid  agentsecname  token  must  be
                     specified  (and  that  name  must  be given proper access
                     control rights via a "rouser" token).

              -o OID Specifies additional object values to be  delivered  with
                     in  the  resulting  trap  in  addition to the normal trap
                     objects.  This is useful for obtaining other  columns  in
                     the table for the row that triggered the expression.  See
                     the examples below for more details.

              -e EVENTNAME
                     Specifies an event name that describes what  to  do  when
                     the  trigger  is fired.  Currently, this must be the name
                     of a notificationEvent event as described below.

              The following example configuration checks the  hrSWRunPerfTable
              table  (listing  running  processes)  for  any  process which is
              consuming > 10Mb of memory.  It performs this  check  every  600
              seconds (the default).  For every process it finds exceeding the
              limit, it will end out exactly one notification.  In addition to
              the  normal  hrSWRunPerfMem  oid and value sent in the trap, the
              hrSWRunName object will also be sent.  Note that the hrSWRunName
              object  actually  occurs  in  a  different  table, but since the
              indexes to the two tables are the same this works out alright.

                     rouser me
                     monitor -u me -o sysUpTime.0 -o hrSWRunName "high process memory" hrSWRunPerfMem > 10000

              The above line would produce a  trap  which,  when  formated  by
              snmptrapd, would look like:

                     2002-04-05 13:33:53 localhost.localdomain [udp:127.0.0.1:32931]:
                             sysUpTimeInstance = Timeticks: (1629) 0:00:16.29        snmpTrapOID.0 = OID: mteTriggerFired    mteHotTrigger = high process memory     mteHotTargetName =      mteHotContextName =     mteHotOID = OID: hrSWRunPerfMem.1968    mteHotValue = 28564     hrSWRunName.1968 = "xemacs"

              This  shows  my  xemacs  process  using 28Mb of resident memory.
              Which, considering it’s xemacs, is not that surprising.

              Threshold example:

                     monitor -t -r 15 -o prNames -o prErrMessage "process table" prErrorFlag 0 1

       notificationEvent NAME NOTIFICATION [[-w] OID_OBJECT ...]
              This will create a notification event, which  can  be  fired  by
              attaching  it  to  a  monitor using a monitor’s -e switch and an
              identical NAME field.  The NOTIFICATION to be sent should be the
              OID  of a notification.  Additional objects can be included, and
              by default the suffix of the row/object being monitored will  be
              appended  to  the object identifier unless it’s told not to be a
              wild-card object by prefixing it with the  -w  switch.   EG,  if
              you’re  monitoring the ifTable and you want your trap to include
              the ifDescr object for the row that was  discovered,  don’t  add
              the -w switch and the .INDEX field will be appended.  If the OID
              is fully qualified (EG, "sysContact.0") and no  instance  suffix
              should  be  appended  to it then add a -w switch before it.  See
              the linkUpDownNotifications token below  for  example  usage  of
              this token to send the linkUp and linkDown traps.

       linkUpDownNotifications yes
              This will make the DISMAN-EVENT-MIB support watch the ifTable to
              determine when a network interface is taken up  or  down.   When
              this   happens,  a  linkUp  or  linkDown  notification  will  be
              triggered.  This is exactly equivalent to doing:

                     notificationEvent  linkUpTrap    linkUp   ifIndex ifAdminStatus ifOperStatus
                     notificationEvent  linkDownTrap  linkDown ifIndex ifAdminStatus ifOperStatus

                     monitor  -r 60 -e linkUpTrap   "Generate linkUp" ifOperStatus != 2
                     monitor  -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2

       defaultMonitors yes
              By default,  the  agent  and  the  DISMAN-EVENT-MIB  support  do
              nothing  until  configured.   Typically  people  wish to watch a
              bunch of tables  within  the  UCD-SNMP-MIB  which  are  designed
              specifically  for  reporting  problems.  If the "defaultMonitors
              yes" line is  put  into  the  snmpd.conf  file  (which  must  be
              accompanied  by  an  appropriate  agentSecName line and a rouser
              line), the following monitoring conditions will be installed:

                     monitor   -o prNames -o prErrMessage "process table" prErrorFlag != 0
                     monitor   -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
                     monitor   -o extNames -o extOutput "extTable" extResult != 0
                     monitor   -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
                     monitor   -o laNames -o laErrMessage  "laTable" laErrorFlag != 0
                     monitor   -o fileName -o fileErrorMsg  "fileTable" fileErrorFlag != 0

DEBUGGING AND OTHER EXTENSIBILITY NOTES

       If you’re trying to figure out  aspects  of  the  various  mib  modules
       (possibly  some that you’ve added yourself), the following may help you
       spit out some useful debugging information.  First off, please read the
       snmpd  manual  page  on  the -D flag.  Then the following configuration
       snmpd.conf token, combined with the -D flag, can produce useful output:

       injectHandler HANDLER modulename
              This  will  insert new handlers into the section of the mib tree
              referenced by "modulename".  The types of handlers available for
              insertion are:
              stash_cache  - Caches information returned from the lower level.  This
                             greatly help the performance of the agent, at the cost
                             of caching the data such that its no longer "live" for
                             30 seconds (in this future, this will be configurable).
                             Note that this means snmpd will use more memory as well
                             while the information is cached.  Currently this only
                             works for handlers registered using the table_iterator
                             support, which is only a few mib tables.  To use it,
                             you need to make sure to install it before the
                             table_iterator point in the chain, so to do this:

                                injectHandler stash_cache NAME table_iterator

                             If you want a table to play with, try walking the
                             nsModuleTable with and without this injected.

              debug        - Prints out lots of debugging information when
                             the -Dhelper:debug flag is passed to the snmpd
                             application.

              read_only    - Forces turning off write support for the given module.

              serialize    - If a module is failing to handle multiple requests
                             properly (using the new 5.0 module API), this will force
                             the module to only receive one request at a time.

              bulk_to_next - If a module registers to handle getbulk support, but
                             for some reason is failing to implement it properly,
                             this module will convert all getbulk requests to
                             getnext requests before the final module receives it.

       Figuring out module names
              To figure out which modules you can inject things into, snmpwalk
              the nsModuleTable which will  give  you  a  list  of  all  named
              modules registered within the agent.

EXAMPLE CONFIGURATION FILE

       See  the EXAMPLE.CONF file in the top level source directory for a more
       detailed example of how the above information is used in real examples.

RE-READING snmpd.conf AND snmpd.local.conf

       The  Net-SNMP  agent  can be forced to re-read its configuration files.
       It can be told to do so by one of two ways:

       1.     An snmpset of integer(1) to  UCD-SNMP-MIB::versionUpdateConfig.0
              (.1.3.6.1.4.1.2021.100.11.0)

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

FILES

       /etc/snmp/snmpd.conf

SEE ALSO

       snmpconf(1),   snmpusm(1),   snmp.conf(5),   snmp_config(5),  snmpd(8),
       EXAMPLE.conf, read_config(3).