1SNMPTRAPD.CONF(5)                  Net-SNMP                  SNMPTRAPD.CONF(5)
2
3
4

NAME

6       snmptrapd.conf  -  configuration file for the Net-SNMP notification re‐
7       ceiver
8

DESCRIPTION

10       The Net-SNMP notification receiver (trap daemon) uses one or more  con‐
11       figuration  files  to control its operation and how incoming traps (and
12       INFORM requests) should be processed.  This file  (snmptrapd.conf)  can
13       be  located  in one of several locations, as described in the snmp_con‐
14       fig(5) manual page.
15

IMPORTANT

17       Previously, snmptrapd would accept all incoming notifications, and  log
18       them  automatically  (even  if no explicit configuration was provided).
19       Starting with release 5.3, access control checks will be applied to in‐
20       coming notifications. If snmptrapd is run without a suitable configura‐
21       tion file (or equivalent access control settings), then such traps WILL
22       NOT be processed.  See the section ACCESS CONTROL for more details.
23
24       As  with  the agent configuration, the snmptrapd.conf directives can be
25       divided into four distinct groups.
26

TRAPD BEHAVIOUR

28       snmpTrapdAddr [<transport-specifier>:]<transport-address>[,...]
29              defines a list of listening addresses, on which to  receive  in‐
30              coming  SNMP notifications.  See the section LISTENING ADDRESSES
31              in the snmpd(8) manual page for more information about the  for‐
32              mat of listening addresses.
33
34              The  default  behaviour is to listen on UDP port 162 on all IPv4
35              interfaces.
36
37       doNotRetainNotificationLogs yes
38              disables support for the NOTIFICATION-LOG-MIB.  Normally the sn‐
39              mptrapd  program keeps a record of the traps received, which can
40              be retrieved by querying the nlmLogTable and nlmLogvariableTable
41              tables.  This directive can be used to suppress this behaviour.
42
43              See  the  snmptrapd(8)  manual page and the NOTIFICATION-LOG-MIB
44              for details.
45
46       doNotLogTraps yes
47              disables the logging of notifications altogether.  This is  use‐
48              ful  if  the  snmptrapd  application  should only run traphandle
49              hooks and should not log traps to any location.
50
51       doNotFork yes
52              do not fork from the calling shell.
53
54       pidFile PATH
55              defines a file in which to store the process ID of the notifica‐
56              tion receiver.  By default, this ID is not saved.
57

ACCESS CONTROL

59       Starting with release 5.3, it is necessary to explicitly specify who is
60       authorised to send traps and informs to the notification receiver  (and
61       what  types  of processing these are allowed to trigger).  This uses an
62       extension of the VACM model, used in the main SNMP agent.
63
64       There are currently three types of processing that can be specified:
65
66              log    log the details of the notification - either in a  speci‐
67                     fied  file, to standard output (or stderr), or via syslog
68                     (or similar).
69
70              execute
71                     pass the details of the trap to a specified handler  pro‐
72                     gram, including embedded perl.
73
74              net    forward the trap to another notification receiver.
75
76       In  the following directives, TYPES will be a (comma-separated) list of
77       one or more of these tokens.  Most commonly,  this  will  typically  be
78       log,execute,net to cover any style of processing for a particular cate‐
79       gory of notification. But it is perfectly possible (even desirable)  to
80       limit certain notification sources to selected processing only.
81
82       authCommunity   TYPES COMMUNITY  [SOURCE [OID | -v VIEW ]]
83              authorises  traps  (and SNMPv2c INFORM requests) with the speci‐
84              fied community to trigger the types of  processing  listed.   By
85              default,  this  will allow any notification using this community
86              to be processed.  The SOURCE field can be used to  specify  that
87              the  configuration  should  only apply to notifications received
88              from particular sources - see snmpd.conf(5) for more details.
89
90       authUser   TYPES [-s MODEL] USER  [LEVEL [OID | -v VIEW ]]
91              authorises SNMPv3 notifications with the specified user to trig‐
92              ger  the  types of processing listed.  By default, this will ac‐
93              cept authenticated  requests.   (authNoPriv  or  authPriv).  The
94              LEVEL  field  can be used to allow unauthenticated notifications
95              (noauth), or to require encryption (priv), just as for the  SNMP
96              agent.
97
98              With both of these directives, the OID (or -v VIEW) field can be
99              used to retrict this configuration to the processing of particu‐
100              lar notifications.
101
102              Note:  Unlike  the  VACM  processing described in RFC 3415, this
103                     view is only matched against the snmpTrapOID value of the
104                     incoming  notification.  It is not applied to the payload
105                     varbinds held within that notification.
106
107       authGroup  TYPES [-s MODEL] GROUP  [LEVEL [OID | -v VIEW ]]
108
109       authAccess TYPES [-s MODEL] GROUP VIEW  [LEVEL [CONTEXT]]
110
111       setAccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES
112              authorise notifications in the specified GROUP (configured using
113              the  group directive) to trigger the types of processing listed.
114              See snmpd.conf(5) for more details.
115
116       createUser             [-e              ENGINEID]              username
117       (MD5|SHA|SHA-512|SHA-384|SHA-256|SHA-224) authpassphrase [AES]
118              See  the  snmpd.conf(5)  manual page for a description of how to
119              create SNMPv3 users.  This is roughly the  same,  but  the  file
120              name changes to snmptrapd.conf from snmpd.conf.
121
122       disableAuthorization yes
123              will  disable the above access control checks, and revert to the
124              previous behaviour of accepting all incoming notifications.
125

LOGGING

127       format1 FORMAT
128
129       format2 FORMAT
130              specify the format used to display SNMPv1 TRAPs and SNMPv2 noti‐
131              fications  respectively.   Note that SNMPv2c and SNMPv3 both use
132              the same SNMPv2 PDU format.
133
134       format DESTINATION FORMAT
135              specify the format used for different destinations.  DESTINATION
136              is one of: print, print1, print2, syslog, syslog1, syslog2, exe‐
137              cute, execute1, execute2.  print1 is used  for  printing  SNMPv1
138              traps,  print2  is for SNMPv2.  print is used for both versions.
139              syslog is similarly used when sending traps to syslog, and  exe‐
140              cute  used  when  sending  traps  to  a program such as traptoe‐
141              mail(1).
142
143              The default formats are
144              format print1 %.4y-%.2m-%.2l  %.2h:%.2j:%.2k  %B  [%b]  (via  %A
145              [%a]): %N\n\t%W Trap (%q) Uptime: %#T\n%v\n
146              format print2 %.4y-%.2m-%.2l %.2h:%.2j:%.2k %B [%b]:\n%v\n
147              format syslog1 %a: %W Trap (%q) Uptime: %#T%#v\n
148              format syslog2 %B [%b]: Trap %#v\n
149              format execute %B\n%b\n%V\n%v\n
150
151              See snmptrapd(8) for the layout characters available.
152
153       ignoreAuthFailure yes
154              instructs the receiver to ignore authenticationFailure traps.
155
156              Note:  This currently only affects the logging of such notifica‐
157                     tions.  authenticationFailure traps will still be  passed
158                     to trap handler scripts, and forwarded to other notifica‐
159                     tion receivers.  This behaviour should not be relied  on,
160                     as it is likely to change in future versions.
161
162       logOption string
163              specifies  where  notifications  should  be logged - to standard
164              output, standard error, a specified file or via syslog.  See the
165              section  LOGGING  OPTIONS  in the snmpcmd(1) manual page for de‐
166              tails.
167
168       outputOption string
169              specifies various characteristics of how OIDs and  other  values
170              should be displayed.  See the section OUTPUT OPTIONS in the snm‐
171              pcmd(1) manual page for details.
172

MySQL Logging

174       There are two configuration variables that  work  together  to  control
175       when  queued  traps  are logged to the MySQL database. A non-zero value
176       must be specified for sqlSaveInterval to enable MySQL logging.
177
178       sqlMaxQueue max
179              specifies the maximum number of traps to queue before  a  forced
180              flush to the MySQL database.
181
182       sqlSaveInterval seconds
183              specified  the number of seconds between periodic queue flushes.
184              A value of 0 for will disable MySQL logging.
185

NOTIFICATION PROCESSING

187       As well as logging incoming notifications, they can also  be  forwarded
188       on  to  another notification receiver, or passed to an external program
189       for specialised processing.
190
191       traphandle OID|default PROGRAM [ARGS ...]
192              invokes the specified program (with the given  arguments)  when‐
193              ever a notification is received that matches the OID token.  For
194              SNMPv2c and SNMPv3 notifications, this token  will  be  compared
195              against  the snmpTrapOID value taken from the notification.  For
196              SNMPv1 traps, the generic and specific trap values and  the  en‐
197              terprise  OID will be converted into the equivalent OID (follow‐
198              ing RFC 2576).
199
200              Typically, the OID token will be the name (or numeric OID) of  a
201              NOTIFICATION-TYPE  object, and the specified program will be in‐
202              voked for notifications that match this  OID  exactly.   However
203              this  token  also  supports a simple form of wildcard suffixing.
204              By appending the character ´*' to the OID token, the correspond‐
205              ing  program  will  be invoked for any notification based within
206              subtree rooted at the specified OID.  For example, an OID  token
207              of  .1.3.6.1.4.1*  would match any enterprise specific notifica‐
208              tion (including the specified OID  itself).   An  OID  token  of
209              .1.3.6.1.4.1.*  would would work in much the same way, but would
210              not match this exact OID - just notifications that lay  strictly
211              below  this  root.   Note that this syntax does not support full
212              regular expressions or wildcards - an  OID  token  of  the  form
213              oid.*.subids is not valid.
214
215              If  the  OID field is the token default then the program will be
216              invoked for any notification not matching another (OID specific)
217              traphandle entry.
218
219       Details of the notification are fed to the program via its standard in‐
220       put.  Note that this will always use the SNMPv2-style notification for‐
221       mat,  with  SNMPv1  traps being converted as per RFC 2576, before being
222       passed to the program.  The input format is, if you use the default set
223       by the "format execute %B\n%b\n%V\n%v\n", one entry per line:
224
225              HOSTNAME
226                     The  name  of the host that sent the notification, as de‐
227                     termined by gethostbyaddr(3).
228
229              ADDRESS
230                     The transport address, like
231                     "[UDP: [172.16.10.12]:23456->[10.150.0.8]]"
232
233              VARBINDS
234                     A list of variable bindings describing  the  contents  of
235                     the  notification, one per line.  The first token on each
236                     line (up until a space) is the OID of the varind, and the
237                     remainder  of  the line is its value.  The format of both
238                     of these are controlled by the outputOption directive (or
239                     similar configuration).
240
241                     The  first  OID should always be SNMPv2-MIB::sysUpTime.0,
242                     and the second should be SNMPv2-MIB::snmpTrapOID.0.   The
243                     remaining  lines  will  contain the payload varbind list.
244                     For SNMPv1 traps, the final OID will  be  SNMPv2-MIB::sn‐
245                     mpTrapEnterprise.0.
246
247              Example:
248                     A  traptoemail  script  has been included in the Net-SNMP
249                     package that can be used within a traphandle directive:
250
251                     traphandle default /usr/bin/perl /usr/bin/traptoemail  -s
252                     mysmtp.somewhere.com   -f   admin@somewhere.com  me@some‐
253                     where.com
254
255       forward OID|default DESTINATION
256              forwards notifications that match the specified OID  to  another
257              receiver  listening  on  DESTINATION.  The interpretation of OID
258              (and default) is the same as for the traphandle directive).
259
260              See the section LISTENING ADDRESSES in the snmpd(8) manual  page
261              for more information about the format of listening addresses.
262
263       addForwarderInfo 1|yes|true|0|no|false
264
265              Each time a trap is forwarded, add an OID with the IP address of
266              the system from which the trap has been received. The  following
267              OID  is  added:  .1.3.6.1.6.3.18.1.3.x  (SNMP-COMMUNITY-MIB::sn‐
268              mpTrapAddress.x) where x is the lowest index >= 0 that does  not
269              yet occur in the trap payload. The end recipient (i.e. the moni‐
270              toring system) can determine the IPv4 address  of  the  original
271              sender by looking for the varbind with OID snmpTrapAddress.0. If
272              that OID is not populated it means that the trap has  been  sent
273              directly or in other words that it has not been forwarded.
274

NOTES

276       o      The  daemon  blocks  while  executing  the  traphandle commands.
277              (This should be fixed in the future with an  appropriate  signal
278              catch and wait() combination).
279
280       o      All  directives  listed  with a value of "yes" actually accept a
281              range of boolean values.  These will accept any  of  1,  yes  or
282              true  to  enable the corresponding behaviour, or any of 0, no or
283              false to disable it.  The default in each case is for  the  fea‐
284              ture  to  be  turned off, so these directives are typically only
285              used to enable the appropriate behaviour.
286

FILES

288       /etc/snmp/snmptrapd.conf
289

SEE ALSO

291       snmp_config(5), snmptrapd(8), syslog(8), traptoemail(1),  variables(5),
292       netsnmp_config_api(3).
293
294
295
296
297V5.9.3                            13 Mar 2014                SNMPTRAPD.CONF(5)
Impressum