Provided by: snmptrapd_5.9.3+dfsg-2ubuntu3_amd64 bug

NAME

       snmptrapd.conf - configuration file for the Net-SNMP notification receiver

DESCRIPTION

       The  Net-SNMP  notification receiver (trap daemon) uses one or more configuration files to
       control its operation and how incoming traps (and INFORM requests)  should  be  processed.
       This file (snmptrapd.conf) can be located in one of several locations, as described in the
       snmp_config(5) manual page.

IMPORTANT

       Previously, snmptrapd would accept all incoming notifications, and log them  automatically
       (even  if  no  explicit  configuration  was  provided).  Starting with release 5.3, access
       control checks will be applied to incoming notifications. If snmptrapd is  run  without  a
       suitable  configuration file (or equivalent access control settings), then such traps WILL
       NOT be processed.  See the section ACCESS CONTROL for more details.

       As with the agent configuration, the snmptrapd.conf directives can be  divided  into  four
       distinct groups.

TRAPD BEHAVIOUR

       snmpTrapdAddr [<transport-specifier>:]<transport-address>[,...]
              defines  a  list  of  listening  addresses,  on  which  to  receive  incoming  SNMP
              notifications.  See the section LISTENING ADDRESSES in the snmpd(8) manual page for
              more information about the format of listening addresses.

              The default behaviour is to listen on UDP port 162 on all IPv4 interfaces.

       doNotRetainNotificationLogs yes
              disables  support  for  the  NOTIFICATION-LOG-MIB.   Normally the snmptrapd program
              keeps a record of the traps received,  which  can  be  retrieved  by  querying  the
              nlmLogTable and nlmLogvariableTable tables.  This directive can be used to suppress
              this behaviour.

              See the snmptrapd(8) manual page and the NOTIFICATION-LOG-MIB for details.

       doNotLogTraps yes
              disables the logging of notifications altogether.  This is useful if the  snmptrapd
              application  should  only  run  traphandle  hooks  and  should not log traps to any
              location.

       doNotFork yes
              do not fork from the calling shell.

       pidFile PATH
              defines a file in which to store the process ID of the notification  receiver.   By
              default, this ID is not saved.

ACCESS CONTROL

       Starting with release 5.3, it is necessary to explicitly specify who is authorised to send
       traps and informs to the notification receiver (and what types  of  processing  these  are
       allowed  to  trigger).   This  uses  an extension of the VACM model, used in the main SNMP
       agent.

       There are currently three types of processing that can be specified:

              log    log the details of the  notification  -  either  in  a  specified  file,  to
                     standard output (or stderr), or via syslog (or similar).

              execute
                     pass  the  details  of  the  trap  to a specified handler program, including
                     embedded perl.

              net    forward the trap to another notification receiver.

       In the following directives, TYPES will be a (comma-separated) list  of  one  or  more  of
       these tokens.  Most commonly, this will typically be log,execute,net to cover any style of
       processing for a particular category of notification. But it is perfectly  possible  (even
       desirable) to limit certain notification sources to selected processing only.

       authCommunity   TYPES COMMUNITY  [SOURCE [OID | -v VIEW ]]
              authorises  traps  (and  SNMPv2c  INFORM  requests) with the specified community to
              trigger  the  types  of  processing  listed.   By  default,  this  will  allow  any
              notification using this community to be processed.  The SOURCE field can be used to
              specify that the configuration should only apply  to  notifications  received  from
              particular sources - see snmpd.conf(5) for more details.

       authUser   TYPES [-s MODEL] USER  [LEVEL [OID | -v VIEW ]]
              authorises  SNMPv3  notifications  with  the specified user to trigger the types of
              processing  listed.   By  default,  this  will   accept   authenticated   requests.
              (authNoPriv  or  authPriv).  The  LEVEL  field can be used to allow unauthenticated
              notifications (noauth), or to require encryption  (priv),  just  as  for  the  SNMP
              agent.

              With  both  of  these directives, the OID (or -v VIEW) field can be used to retrict
              this configuration to the processing of particular notifications.

              Note:  Unlike the VACM processing described in RFC 3415, this view is only  matched
                     against  the  snmpTrapOID  value  of  the  incoming notification.  It is not
                     applied to the payload varbinds held within that notification.

       authGroup  TYPES [-s MODEL] GROUP  [LEVEL [OID | -v VIEW ]]

       authAccess TYPES [-s MODEL] GROUP VIEW  [LEVEL [CONTEXT]]

       setAccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES
              authorise  notifications  in  the  specified  GROUP  (configured  using  the  group
              directive)  to  trigger the types of processing listed.  See snmpd.conf(5) for more
              details.

       createUser    [-e     ENGINEID]     username     (MD5|SHA|SHA-512|SHA-384|SHA-256|SHA-224)
       authpassphrase [DES|AES]
              See  the snmpd.conf(5) manual page for a description of how to create SNMPv3 users.
              This is roughly the  same,  but  the  file  name  changes  to  snmptrapd.conf  from
              snmpd.conf.

       disableAuthorization yes
              will  disable the above access control checks, and revert to the previous behaviour
              of accepting all incoming notifications.

LOGGING

       format1 FORMAT

       format2 FORMAT
              specify  the  format  used  to  display  SNMPv1  TRAPs  and  SNMPv2   notifications
              respectively.  Note that SNMPv2c and SNMPv3 both use the same SNMPv2 PDU format.

       format DESTINATION FORMAT
              specify  the format used for different destinations.  DESTINATION is one of: print,
              print1, print2, syslog, syslog1, syslog2, execute, execute1, execute2.   print1  is
              used  for  printing  SNMPv1  traps,  print2  is for SNMPv2.  print is used for both
              versions.  syslog is similarly used when sending traps to syslog, and execute  used
              when sending traps to a program such as traptoemail(1).

              The default formats are
              format  print1  %.4y-%.2m-%.2l  %.2h:%.2j:%.2k %B [%b] (via %A [%a]): %N\n\t%W Trap
              (%q) Uptime: %#T\n%v\n
              format print2 %.4y-%.2m-%.2l %.2h:%.2j:%.2k %B [%b]:\n%v\n
              format syslog1 %a: %W Trap (%q) Uptime: %#T%#v\n
              format syslog2 %B [%b]: Trap %#v\n
              format execute %B\n%b\n%V\n%v\n

              See snmptrapd(8) for the layout characters available.

       ignoreAuthFailure yes
              instructs the receiver to ignore authenticationFailure traps.

              Note:  This  currently  only   affects   the   logging   of   such   notifications.
                     authenticationFailure  traps  will  still be passed to trap handler scripts,
                     and forwarded to other notification receivers.  This behaviour should not be
                     relied on, as it is likely to change in future versions.

       logOption string
              specifies  where  notifications  should  be  logged  - to standard output, standard
              error, a specified file or via syslog.  See the  section  LOGGING  OPTIONS  in  the
              snmpcmd(1) manual page for details.

       outputOption string
              specifies various characteristics of how OIDs and other values should be displayed.
              See the section OUTPUT OPTIONS in the snmpcmd(1) manual page for details.

MySQL Logging

       There are two configuration variables that work together to control when queued traps  are
       logged  to  the  MySQL database. A non-zero value must be specified for sqlSaveInterval to
       enable MySQL logging.

       sqlMaxQueue max
              specifies the maximum number of traps to queue before a forced flush to  the  MySQL
              database.

       sqlSaveInterval seconds
              specified  the  number of seconds between periodic queue flushes.  A value of 0 for
              will disable MySQL logging.

NOTIFICATION PROCESSING

       As well as logging incoming notifications, they  can  also  be  forwarded  on  to  another
       notification receiver, or passed to an external program for specialised processing.

       traphandle OID|default PROGRAM [ARGS ...]
              invokes the specified program (with the given arguments) whenever a notification is
              received that matches the OID token.  For SNMPv2c and  SNMPv3  notifications,  this
              token  will  be compared against the snmpTrapOID value taken from the notification.
              For SNMPv1 traps, the generic and specific trap values and the enterprise OID  will
              be converted into the equivalent OID (following RFC 2576).

              Typically,  the  OID token will be the name (or numeric OID) of a NOTIFICATION-TYPE
              object, and the specified program will be invoked for notifications that match this
              OID exactly.  However this token also supports a simple form of wildcard suffixing.
              By appending the character ยด*' to the OID token, the corresponding program will  be
              invoked for any notification based within subtree rooted at the specified OID.  For
              example, an  OID  token  of  .1.3.6.1.4.1*  would  match  any  enterprise  specific
              notification  (including the specified OID itself).  An OID token of .1.3.6.1.4.1.*
              would would work in much the same way, but would not match this exact  OID  -  just
              notifications  that  lay  strictly below this root.  Note that this syntax does not
              support full  regular  expressions  or  wildcards  -  an  OID  token  of  the  form
              oid.*.subids is not valid.

              If  the  OID  field  is  the token default then the program will be invoked for any
              notification not matching another (OID specific) traphandle entry.

       Details of the notification are fed to the program via its standard input.  Note that this
       will always use the SNMPv2-style notification format, with SNMPv1 traps being converted as
       per RFC 2576, before being passed to the program.  The input format is,  if  you  use  the
       default set by the "format execute %B\n%b\n%V\n%v\n", one entry per line:

              HOSTNAME
                     The  name  of  the  host  that  sent  the  notification,  as  determined  by
                     gethostbyaddr(3).

              ADDRESS
                     The transport address, like
                     "[UDP: [172.16.10.12]:23456->[10.150.0.8]]"

              VARBINDS
                     A list of variable bindings describing the contents of the notification, one
                     per line.  The first token on each line (up until a space) is the OID of the
                     varind, and the remainder of the line is its value.  The format of  both  of
                     these   are   controlled   by   the   outputOption   directive  (or  similar
                     configuration).

                     The first OID should  always  be  SNMPv2-MIB::sysUpTime.0,  and  the  second
                     should  be  SNMPv2-MIB::snmpTrapOID.0.  The remaining lines will contain the
                     payload  varbind  list.   For  SNMPv1  traps,  the   final   OID   will   be
                     SNMPv2-MIB::snmpTrapEnterprise.0.

              Example:
                     A  traptoemail  script has been included in the Net-SNMP package that can be
                     used within a traphandle directive:

                     traphandle      default      /usr/bin/perl      /usr/bin/traptoemail      -s
                     mysmtp.somewhere.com -f admin@somewhere.com me@somewhere.com

       forward OID|default DESTINATION
              forwards  notifications  that match the specified OID to another receiver listening
              on DESTINATION.  The interpretation of OID (and default) is the  same  as  for  the
              traphandle directive).

              See  the  section  LISTENING  ADDRESSES  in  the  snmpd(8)  manual  page  for  more
              information about the format of listening addresses.

       addForwarderInfo 1|yes|true|0|no|false

              Each time a trap is forwarded, add an OID with the IP address of  the  system  from
              which the trap has been received. The following OID is added: .1.3.6.1.6.3.18.1.3.x
              (SNMP-COMMUNITY-MIB::snmpTrapAddress.x) where x is the lowest index >= 0 that  does
              not  yet  occur in the trap payload. The end recipient (i.e. the monitoring system)
              can determine the IPv4 address of the original sender by looking  for  the  varbind
              with OID snmpTrapAddress.0. If that OID is not populated it means that the trap has
              been sent directly or in other words that it has not been forwarded.

NOTES

       o      The daemon blocks while executing the traphandle commands.  (This should  be  fixed
              in the future with an appropriate signal catch and wait() combination).

       o      All  directives  listed  with  a  value of "yes" actually accept a range of boolean
              values.  These will accept any of 1,  yes  or  true  to  enable  the  corresponding
              behaviour, or any of 0, no or false to disable it.  The default in each case is for
              the feature to be turned off, so these directives are typically only used to enable
              the appropriate behaviour.

FILES

       /etc/snmp/snmptrapd.conf

SEE ALSO

       snmp_config(5),      snmptrapd(8),      syslog(8),      traptoemail(1),      variables(5),
       netsnmp_config_api(3).