Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SNMPTRAPD.CONF(5)		   Net-SNMP		     SNMPTRAPD.CONF(5)

NAME
       snmptrapd.conf  -  configuration	file for the Net-SNMP notification re-
       ceiver

DESCRIPTION
       The Net-SNMP notification receiver (trap	daemon)	uses one or more  con-
       figuration  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_con-
       fig(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 in-
       coming notifications. If	snmptrapd is run without a suitable configura-
       tion 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  in-
	      coming  SNMP notifications.  See the section LISTENING ADDRESSES
	      in the snmpd(8) manual page for more information about the  for-
	      mat 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 sn-
	      mptrapd  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  use-
	      ful  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 notifica-
	      tion 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	speci-
		     fied  file, to standard output (or	stderr), or via	syslog
		     (or similar).

	      execute
		     pass the details of the trap to a specified handler  pro-
		     gram, 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 cate-
       gory 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	speci-
	      fied 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 trig-
	      ger  the	types of processing listed.  By	default, this will ac-
	      cept 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 particu-
	      lar 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 noti-
	      fications	 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, exe-
	      cute, 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  exe-
	      cute  used  when	sending	 traps	to  a program such as traptoe-
	      mail(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 notifica-
		     tions.  authenticationFailure traps will still be	passed
		     to	trap handler scripts, and forwarded to other notifica-
		     tion 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 de-
	      tails.

       outputOption string
	      specifies	various	characteristics	of how OIDs and	 other	values
	      should be	displayed.  See	the section OUTPUT OPTIONS in the snm-
	      pcmd(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)	 when-
	      ever 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  en-
	      terprise	OID will be converted into the equivalent OID (follow-
	      ing RFC 2576).

	      Typically, the OID token will be the name	(or numeric OID) of  a
	      NOTIFICATION-TYPE	 object, and the specified program will	be in-
	      voked 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 correspond-
	      ing  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 notifica-
	      tion (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 in-
       put.  Note that this will always	use the	SNMPv2-style notification for-
       mat,  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 de-
		     termined 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::sn-
		     mpTrapEnterprise.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/local/bin/traptoe-
		     mail   -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::sn-
	      mpTrapAddress.x) where x is the lowest index >= 0	that does  not
	      yet occur	in the trap payload. The end recipient (i.e. the moni-
	      toring 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  fea-
	      ture  to	be  turned off,	so these directives are	typically only
	      used to enable the appropriate behaviour.

FILES
       /usr/local/etc/snmp/snmptrapd.conf

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

V5.9				  13 Mar 2014		     SNMPTRAPD.CONF(5)

NAME | DESCRIPTION | IMPORTANT | TRAPD BEHAVIOUR | ACCESS CONTROL | LOGGING | MySQL Logging | NOTIFICATION PROCESSING | NOTES | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=snmptrapd.conf&sektion=5&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help