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

NAME

6       snmptrapd.conf  -  configuration  file  for  the  Net-SNMP notification
7       receiver
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
20       incoming notifications. If snmptrapd is run without a suitable configu‐
21       ration file (or equivalent access control settings),  then  such  traps
22       WILL  NOT  be  processed.   See  the  section  ACCESS  CONTROL for more
23       details.
24
25       As with the agent configuration, the snmptrapd.conf directives  can  be
26       divided into four distinct groups.
27

TRAPD BEHAVIOUR

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

ACCESS CONTROL

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

LOGGING

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

MySQL Logging

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

NOTIFICATION PROCESSING

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

NOTES

266       o      The  daemon  blocks  while  executing  the  traphandle commands.
267              (This should be fixed in the future with an  appropriate  signal
268              catch and wait() combination).
269
270       o      All  directives  listed  with a value of "yes" actually accept a
271              range of boolean values.  These will accept any  of  1,  yes  or
272              true  to  enable the corresponding behaviour, or any of 0, no or
273              false to disable it.  The default in each case is for  the  fea‐
274              ture  to  be  turned off, so these directives are typically only
275              used to enable the appropriate behaviour.
276

FILES

278       /etc/snmp/snmptrapd.conf
279

SEE ALSO

281       snmp_config(5), snmptrapd(8), syslog(8), traptoemail(1),  variables(5),
282       netsnmp_config_api(3).
283
284
285
286
287V5.8                              13 Mar 2014                SNMPTRAPD.CONF(5)
Impressum