packages/net/snmp/agent/v2_0/doc/snmp-manpages.sgml

   1 <!-- HEY YOU!!!!!!!!! -->
   2 <!-- this file is automatically generated by the script -->
   3 <!--       ./prepare-manpages.sh      -->
   4 <!-- so PLEASE do not modify it: your changes will be lost -->
   5
   6
   7   <sect1 id="net-snmp-agent-manpages-snmpd.conf">
   8     <title>snmpd.conf</title>
   9     <screen>
  10 SNMPD.CONF(5)                                       SNMPD.CONF(5)
  11
  12
  13
  14 NAME
  15        share/snmp/snmpd.conf  -  configuration  file for the ucd-
  16        snmp SNMP agent.
  17
  18 DESCRIPTION
  19        snmpd.conf is the configuration file which defines how the
  20        ucd-smnp SNMP agent operates.  These files may contain any
  21        of the directives found in the DIRECTIVES  section  below.
  22        This  file  is  not  required for the agent to operate and
  23        report mib entries.
  24
  25 PLEASE READ FIRST
  26        First, make sure you have read the  snmp_config(5)  manual
  27        page  that  describes how the ucd-snmp configuration files
  28        operate, where they are located  and  how  they  all  work
  29        together.
  30
  31 EXTENSIBLE-MIB
  32        The  ucd-snmp  SNMP  agent reports much of its information
  33        through queries to the 1.3.6.1.4.1.2021 section of the mib
  34        tree.   Every  mib in this section has the following table
  35        entries in it.
  36
  37        .1 -- index
  38               This is the table's index numbers for each  of  the
  39               DIRECTIVES listed below.
  40
  41        .2 -- name
  42               The  name of the given table entry.  This should be
  43               unique, but is not required to be.
  44
  45        .100 -- errorFlag
  46               This is a flag returning either the integer value 1
  47               or  0 if an error is detected for this table entry.
  48
  49        .101 -- errorMsg
  50               This is a DISPLAY-STRING describing any error trig-
  51               gering the errorFlag above.
  52
  53        .102 -- errorFix
  54               If  this entry is SNMPset to the integer value of 1
  55               AND the errorFlag defined above is indeed  a  1,  a
  56               program  or script will get executed with the table
  57               entry name from above as the argument.  The program
  58               to  be  executed is configured in the config.h file
  59               at compile time.
  60
  61    Directives
  62        proc NAME
  63
  64        proc NAME MAX
  65
  66        proc NAME MAX MIN
  67
  68               Checks to see if the NAME'd processes  are  running
  69               on  the  agent's  machine.  An error flag (1) and a
  70               description  message  are  then   passed   to   the
  71               1.3.6.1.4.1.2021.2.100  and  1.3.6.1.4.1.2021.2.101
  72               mib tables (respectively) if the NAME'd program  is
  73               not  found  in  the  process  table  as reported by
  74               "/bin/ps -e".
  75
  76               If MAX and MIN are not specified, MAX is assumed to
  77               be infinity and MIN is assumed to be 1.
  78
  79               If  MAX  is specified but MIN is not specified, MIN
  80               is assumed to be 0.
  81
  82        procfix NAME PROG ARGS
  83               This registers a command  that  knows  how  to  fix
  84               errors   with   the   given   process  NAME.   When
  85               1.3.6.1.4.1.2021.2.102 for a given NAMEd program is
  86               set to the integer value of 1, this command will be
  87               called.  It defaults to a compiled value set  using
  88               the PROCFIXCMD definition in the config.h file.
  89
  90        exec NAME PROG ARGS
  91
  92        exec MIBNUM NAME PROG ARGS
  93
  94               If  MIBNUM is not specified, the agent executes the
  95               named PROG with arguments of ARGS and  returns  the
  96               exit status and the first line of the STDOUT output
  97               of   the   PROG   program   to   queries   of   the
  98               1.3.6.1.4.1.2021.8.100  and  1.3.6.1.4.1.2021.8.101
  99               mib  tables  (respectively).   All  STDOUT   output
 100               beyond the first line is silently truncated.
 101
 102               If  MIBNUM  is  specified,  it  acts  as  above but
 103               returns the exit status  to  MIBNUM.100.0  and  the
 104               entire  STDOUT  output to the table MIBNUM.101 in a
 105               mib table.  In this case, the MIBNUM.101  mib  con-
 106               tains the entire STDOUT output, one mib table entry
 107               per line of output (ie, the first line is output as
 108               MIBNUM.101.1,  the second at MIBNUM.101.2, etc...).
 109
 110               Note:  The MIBNUM must be specified in dotted-inte-
 111                      ger  notation  and  can  not be specified as
 112                      ".iso.org.dod.internet..."  (should  instead
 113                      be
 114
 115               Note:  The  agent caches the exit status and STDOUT
 116                      of the executed program for 30 seconds after
 117                      the  initial  query.   This  is  to increase
 118                      speed and maintain consistency  of  informa-
 119                      tion  for  consecutive  table  queries.  The
 120                      cache can be flushed by a  snmp-set  request
 121                      of  integer(1)  to 1.3.6.1.4.1.2021.100.VER-
 122                      CLEARCACHE.
 123
 124        execfix NAME PROG ARGS
 125               This registers a command  that  knows  how  to  fix
 126               errors  with  the  given  exec  or  sh  NAME.  When
 127               1.3.6.1.4.1.2021.8.102 for a given NAMEd  entry  is
 128               set to the integer value of 1, this command will be
 129               called.  It defaults to a compiled value set  using
 130               the EXECFIXCMD definition in the config.h file.
 131
 132        disk PATH
 133
 134        disk PATH [ MINSPACE | MINPERCENT% ]
 135
 136               Checks  the  named disks mounted at PATH for avail-
 137               able disk space.  If the disk space  is  less  than
 138               MINSPACE  (kB) if specified or less than MINPERCENT
 139               (%) if a  %  sign  is  specified,  or  DEFDISKMINI-
 140               MUMSPACE  (kB)  if  not  specified,  the associated
 141               entry in the 1.3.6.1.4.1.2021.9.100 mib table  will
 142               be  set to (1) and a descriptive error message will
 143               be returned to queries of 1.3.6.1.4.1.2021.9.101.
 144
 145        load MAX1
 146
 147        load MAX1 MAX5
 148
 149        load MAX1 MAX5 MAX15
 150
 151               Checks the load average of the machine and  returns
 152               an error flag (1), and an text-string error message
 153               to   queries   of    1.3.6.1.4.1.2021.10.100    and
 154               1.3.6.1.4.1.2021.10.101   (respectively)  when  the
 155               1-minute, 5-minute, or  15-minute  averages  exceed
 156               the associated maximum values.  If any of the MAX1,
 157               MAX5, or MAX15 values are unspecified, they default
 158               to a value of DEFMAXLOADAVE.
 159
 160        file FILE [MAXSIZE]
 161               Monitors  file sizes and makes sure they don't grow
 162               beyond a certain size.  MAXSIZE defaults  to  infi-
 163               nite  if  not specified, and only monitors the size
 164               without reporting errors about it.
 165
 166    Errors
 167        Any errors in obtaining the above information are reported
 168        via    the    1.3.6.1.4.1.2021.101.100    flag   and   the
 169        1.3.6.1.4.1.2021.101.101 text-string description.
 170
 171 SMUX SUB-AGENTS
 172        To enable and SMUX based sub-agent, such as gated, use the
 173        smuxpeer configuration entry
 174
 175        smuxpeer OID PASS
 176               For gated a sensible entry might be
 177
 178        .1.3.6.1.4.1.4.1.3 secret
 179
 180 ACCESS CONTROL
 181        snmpd  supports the View-Based Access Control Model (vacm)
 182        as defined in RFC 2275.  To this end,  it  recognizes  the
 183        following  keywords  in  the  configuration file: com2sec,
 184        group, access, and view  as  well  as  some  easier-to-use
 185        wrapper   directives:  rocommunity,  rwcommunity,  rouser,
 186        rwuser.
 187
 188        rocommunity COMMUNITY [SOURCE] [OID]
 189
 190        rwcommunity COMMUNITY [SOURCE] [OID]
 191               These create read-only and  read-write  communities
 192               that  can  be used to access the agent.  They are a
 193               quick method of using the following com2sec, group,
 194               access,  and view directive lines.  They are not as
 195               efficient either, as groups aren't created  so  the
 196               tables  are possibly larger.  In other words: don't
 197               use these if you have complex situations to set up.
 198
 199               The  format  of the SOURCE is token is described in
 200               the com2sec directive section below.  The OID token
 201               restricts  access  for that community to everything
 202               below that given OID.
 203
 204        rouser USER [noauth|auth|priv] [OID]
 205
 206        rwuser USER [noauth|auth|priv] [OID]
 207               Creates a  SNMPv3  USM  user  in  the  VACM  access
 208               configuration  tables.   Again,  its more efficient
 209               (and powerful) to use the combined com2sec,  group,
 210               access, and view directives instead.
 211
 212               The minimum level of authentication and privacy the
 213               user must use  is  specified  by  the  first  token
 214               (which  defaults  to  "auth").   The  OID parameter
 215               restricts access for that user to everything  below
 216               the given OID.
 217
 218        com2sec NAME SOURCE COMMUNITY
 219               This   directive   specifies  the  mapping  from  a
 220               source/community pair to a  security  name.  SOURCE
 221               can be a hostname, a subnet, or the word "default".
 222               A subnet can be specified as  IP/MASK  or  IP/BITS.
 223               The first source/community combination that matches
 224               the incoming packet is selected.
 225
 226        group NAME MODEL SECURITY
 227               This directive defines the mapping  from  security-
 228               model/securityname  to  group.  MODEL is one of v1,
 229               v2c, or usm.
 230
 231        access NAME CONTEXT MODEL LEVEL PREFX READ WRITE NOTIFY
 232               The  access  directive  maps  from   group/security
 233               model/security  level  to  a view.  MODEL is one of
 234               any, v1, v2c, or usm.   LEVEL  is  one  of  noauth,
 235               auth,  or priv.  PREFX specifies how CONTEXT should
 236               be matched against the context of the incoming pdu,
 237               either  exact  or  prefix.   READ, WRITE and NOTIFY
 238               specifies the view to be used for the corresponding
 239               access.   For  v1  or  v2c  access,  LEVEL  will be
 240               noauth, and CONTEXT will be empty.
 241
 242        view NAME TYPE SUBTREE [MASK]
 243               The defines the named view. TYPE is either included
 244               or  excluded.   MASK is a list of hex octets, sepa-
 245               rated by '.' or ':'.  The MASK defaults to "ff"  if
 246               not specified.
 247
 248               The  reason  for the mask is, that it allows you to
 249               control access to one row in a table,  in  a  rela-
 250               tively  simple  way.  As  an example, as an ISP you
 251               might consider giving each customer access  to  his
 252               or her own interface:
 253
 254               view cust1 included interfaces.ifTable.ifEntry.ifIndex.1 ff.a0
 255               view cust2 included interfaces.ifTable.ifEntry.ifIndex.2 ff.a0
 256
 257               (interfaces.ifTable.ifEntry.ifIndex.1 == .1.3.6.1.2.1.2.2.1.1.1,
 258               ff.a0 == 11111111.10100000. which nicely covers up and including
 259               the row index, but lets the user vary the field of the row)
 260
 261        VACM Examples:
 262               #       sec.name  source          community
 263               com2sec local     localhost       private
 264               com2sec mynet     10.10.10.0/24   public
 265               com2sec public    default         public
 266
 267               #             sec.model  sec.name
 268               group mygroup v1         mynet
 269               group mygroup v2c        mynet
 270               group mygroup usm        mynet
 271               group local   v1         local
 272               group local   v2c        local
 273               group local   usm        local
 274               group public  v1         public
 275               group public  v2c        public
 276               group public  usm        public
 277
 278               #           incl/excl subtree                          mask
 279               view all    included  .1                               80
 280               view system included  system                           fe
 281               view mib2   included  .iso.org.dod.internet.mgmt.mib-2 fc
 282
 283               #              context sec.model sec.level prefix read   write notify
 284               access mygroup ""      any       noauth    exact  mib2   none  none
 285               access public  ""      any       noauth    exact  system none  none
 286               access local   ""      any       noauth    exact  all    all   all
 287
 288        Default VACM model
 289               The default configuration of the agent, as shipped, is functionally
 290               equivalent to the following entries:
 291               com2sec   public    default   public
 292               group     public    v1   public
 293               group     public    v2c  public
 294               group     public    usm  public
 295               view      all  included  .1
 296               access    public    ""   any  noauth    exact     all  none none
 297
 298 SNMPv3 CONFIGURATION
 299        engineID STRING
 300               The  snmpd  agent  needs  to  be configured with an
 301               engineID to be able to respond to SNMPv3  messages.
 302               With  this  configuration  file  line, the engineID
 303               will be configured from STRING.  The default  value
 304               of  the  engineID  is  configured with the first IP
 305               address found for the hostname of the machine.
 306
 307        createUser username (MD5|SHA) authpassphrase [DES]  [priv-
 308        passphrase]
 309               This directive should be placed into the "/var/ucd-
 310               snmp"/snmpd.conf  file  instead of the other normal
 311               locations.  The reason is that the  information  is
 312               read  from  the  file  and then the line is removed
 313               (eliminating the storage of the master password for
 314               that  user)  and  replaced  with  the  key  that is
 315               derived from it.  This key is a localized  key,  so
 316               that  if  it is stolen it can not be used to access
 317               other agents.  If the password is stolen,  however,
 318               it can be.
 319
 320               MD5  and  SHA  are the authentication types to use,
 321               but you must have built the  package  with  openssl
 322               installed  in  order  to use SHA.  The only privacy
 323               protocol currently supported is DES.  If  the  pri-
 324               vacy  passphrase is not specified, it is assumed to
 325               be the same as the authentication passphrase.  Note
 326               that  the users created will be useless unless they
 327               are also added to the VACM  access  control  tables
 328               described above.
 329
 330               Warning:  the minimum pass phrase length is 8 char-
 331               acters.
 332
 333               SNMPv3 users can be created at  runtime  using  the
 334               snmpusm command.
 335
 336
 337 SETTING SYSTEM INFORMATION
 338        syslocation STRING
 339
 340        syscontact STRING
 341
 342               Sets the system location and the system contact for
 343               the agent.  This information  is  reported  by  the
 344               'system' table in the mibII tree.
 345
 346        authtrapenable NUMBER
 347               Setting  authtrapenable  to 1 enables generation of
 348               authentication failure traps. The default value  is
 349               2 (disable).
 350
 351        trapcommunity STRING
 352               This  defines  the  default  community string to be
 353               used when sending traps.  Note  that  this  command
 354               must  be  used  prior to any of the following three
 355               commands  that  are  intended  use  this  community
 356               string.
 357
 358        trapsink HOST [COMMUNITY [PORT]]
 359
 360        trap2sink HOST [COMMUNITY [PORT]]
 361
 362        informsink HOST [COMMUNITY [PORT]]
 363               These  commands  define  the hosts to receive traps
 364               (and/or inform notifications). The daemon  sends  a
 365               Cold  Start  trap when it starts up. If enabled, it
 366               also sends traps on authentication failures.   Mul-
 367               tiple  trapsink, trap2sink and informsink lines may
 368               be specified to specify multiple destinations.  Use
 369               trap2sink  to  send  SNMPv2 traps and informsink to
 370               send inform notifications.   If  COMMUNITY  is  not
 371               specified,  the  string from a preceding trapcommu-
 372               nity directive will be used. If PORT is not  speci-
 373               fied,  the  well known SNMP trap port (162) will be
 374               used.
 375
 376 PASS-THROUGH CONTROL
 377        pass MIBOID EXEC
 378               Passes entire control of MIBOID to  the  EXEC  pro-
 379               gram.   The  EXEC  program  is called in one of the
 380               following three ways:
 381
 382               EXEC -g MIBOID
 383
 384               EXEC -n MIBOID
 385
 386                      These call lines match to SNMP get and  get-
 387                      next requests.  It is expected that the EXEC
 388                      program will take the arguments passed to it
 389                      and  return the appropriate response through
 390                      it's stdout.
 391
 392                      The first line of stdout should be  the  mib
 393                      OID of the returning value.  The second line
 394                      should be the TYPE of value returned,  where
 395                      TYPE  is  one  of  the text strings: string,
 396                      integer,  unsigned,   objectid,   timeticks,
 397                      ipaddress,  counter,  or  gauge.   The third
 398                      line of stdout should be  the  VALUE  corre-
 399                      sponding with the returned TYPE.
 400
 401                      For  instance, if a script was to return the
 402                      value integer value "42" when a request  for
 403                      .1.3.6.1.4.100  was  requested,  the  script
 404                      should return the following 3 lines:
 405                        .1.3.6.1.4.100
 406                        integer
 407                        42
 408
 409                      To indicate that the  script  is  unable  to
 410                      comply with the request due to an end-of-mib
 411                      condition or an invalid request, simple exit
 412                      and  return  no  output to stdout at all.  A
 413                      snmp error will be  generated  corresponding
 414                      to the SNMP NO-SUCH-NAME response.
 415
 416               EXEC -s MIBOID TYPE VALUE
 417
 418                      For SNMP set requests, the above call method
 419                      is used.  The TYPE passed to the  EXEC  pro-
 420                      gram  is  one  of the text strings: integer,
 421                      counter, gauge, timeticks, ipaddress, objid,
 422                      or  string,  indicating  the  type  of value
 423                      passed in the next argument.
 424
 425                      Return nothing to stdout, and the  set  will
 426                      assumed to have been successful.  Otherwise,
 427                      return one of the following error strings to
 428                      signal an error: not-writable, or wrong-type
 429                      and the appropriate error response  will  be
 430                      generated instead.
 431
 432                       Note:  By   default,   the  only  community
 433                              allowed to  write  (ie  snmpset)  to
 434                              your  script  will  be the "private"
 435                              community,or community #2 if defined
 436                              differently by the "community" token
 437                              discussed above.  Which  communities
 438                              are  allowed  write  access are con-
 439                              trolled by the RWRITE definition  in
 440                              the snmplib/snmp_impl.h source file.
 441
 442 EXAMPLE
 443        See the EXAMPLE.CONF file in the top level  source  direc-
 444        tory for a more detailed example of how the above informa-
 445        tion is used in real examples.
 446
 447 RE-READING snmpd.conf and snmpd.local.conf
 448        The ucd-snmp agent can be forced to re-read its configura-
 449        tion files.  It can be told to do so by one of two ways:
 450
 451        1.     An       snmpset       of       integer(1)       to
 452               1.3.6.1.4.1.2021.100.VERUPDATECONFIG.
 453
 454        2.     A "kill -HUP" signal sent to the snmpd  agent  pro-
 455               cess.
 456
 457 FILES
 458        share/snmp/snmpd.conf
 459
 460 SEE ALSO
 461        snmp_config(5), snmpd(1), EXAMPLE.conf, read_config(3).
 462
 463
 464
 465                            27 Jan 2000              SNMPD.CONF(5)
 466     </screen>
 467   </sect1>
 468
 469
 470 <!-- Keep this comment at the end of the file
 471 Local variables:
 472 mode: sgml
 473 sgml-omittag:nil
 474 sgml-shorttag:t
 475 sgml-namecase-general:t
 476 sgml-general-insert-case:lower
 477 sgml-minimize-attributes:nil
 478 sgml-always-quote-attributes:t
 479 sgml-indent-step:2
 480 sgml-indent-data:t
 481 sgml-parent-document:("tcpip.sgml" "book" "chapter")
 482 sgml-exposed-tags:nil
 483 sgml-local-catalogs:nil
 484 sgml-local-ecat-files:nil
 485 sgml-doctype:"book"
 486 End:
 487 -->
 488