1SNMPTRAPD.CONF(5) Net-SNMP SNMPTRAPD.CONF(5)
2
6 snmptrapd.conf - configuration file for the Net-SNMP notification re‐
7 ceiver
8
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
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 As with the agent configuration, the snmptrapd.conf directives can be
25 divided into four distinct groups.
26
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 The default behaviour is to listen on UDP port 162 on all IPv4
35 interfaces.
36 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 See the snmptrapd(8) manual page and the NOTIFICATION-LOG-MIB
44 for details.
45 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 doNotFork yes
52 do not fork from the calling shell.
53 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
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 There are currently three types of processing that can be specified:
65 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 execute
71 pass the details of the trap to a specified handler pro‐
72 gram, including embedded perl.
73 net forward the trap to another notification receiver.
75 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 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 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 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 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 authGroup TYPES [-s MODEL] GROUP [LEVEL [OID | -v VIEW ]]
108 authAccess TYPES [-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]
110 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 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 disableAuthorization yes
123 will disable the above access control checks, and revert to the
124 previous behaviour of accepting all incoming notifications.
125
127 format1 FORMAT
128 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 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 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 See snmptrapd(8) for the layout characters available.
152 ignoreAuthFailure yes
154 instructs the receiver to ignore authenticationFailure traps.
155 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 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 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
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 sqlMaxQueue max
179 specifies the maximum number of traps to queue before a forced
180 flush to the MySQL database.
181 sqlSaveInterval seconds
183 specified the number of seconds between periodic queue flushes.
184 A value of 0 for will disable MySQL logging.
185
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 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 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 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 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 HOSTNAME
226 The name of the host that sent the notification, as de‐
227 termined by gethostbyaddr(3).
228 ADDRESS
230 The transport address, like
231 "[UDP: [172.16.10.12]:23456->[10.150.0.8]]"
232 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 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 Example:
248 A traptoemail script has been included in the Net-SNMP
249 package that can be used within a traphandle directive:
250 traphandle default /usr/bin/perl /usr/bin/traptoemail -s
252 mysmtp.somewhere.com -f admin@somewhere.com me@some‐
253 where.com
254 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 See the section LISTENING ADDRESSES in the snmpd(8) manual page
261 for more information about the format of listening addresses.
262 addForwarderInfo 1|yes|true|0|no|false
264 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
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 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
288 /etc/snmp/snmptrapd.conf
289
291 snmp_config(5), snmptrapd(8), syslog(8), traptoemail(1), variables(5),
292 netsnmp_config_api(3).
293V5.9.1 13 Mar 2014 SNMPTRAPD.CONF(5)