-
Notifications
You must be signed in to change notification settings - Fork 24
/
Copy pathsnmptrapd.conf.5.def
315 lines (314 loc) · 12.3 KB
/
snmptrapd.conf.5.def
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
.TH SNMPTRAPD.CONF 5 "13 Mar 2014" VVERSIONINFO "Net-SNMP"
.SH NAME
snmptrapd.conf - configuration file for the Net-SNMP notification receiver
.SH 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 (\fBsnmptrapd.conf\fR) can be located in
one of several locations, as described in the
.IR snmp_config (5)
manual page.
.SH IMPORTANT
Previously,
.B 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
.B snmptrapd
is run without a suitable configuration file (or equivalent access
control settings), then such traps \fBWILL NOT\fR
be processed.
See the section \fBACCESS CONTROL\fR for more details.
.PP
As with the agent configuration, the
.I snmptrapd.conf
directives can be divided into four distinct groups.
.SH TRAPD BEHAVIOUR
.IP "snmpTrapdAddr [<transport-specifier>:]<transport-address>[,...]"
defines a list of listening addresses, on which to receive
incoming SNMP notifications.
See the section
.B LISTENING ADDRESSES
in the
.IR snmpd (8)
manual page for more information about the format of listening
addresses.
.IP
The default behaviour is to
listen on UDP port 162 on all IPv4 interfaces.
.IP "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 \fCnlmLogTable\fR and \fCnlmLogvariableTable\fR tables.
This directive can be used to suppress this behaviour.
.IP
See the
.IR snmptrapd (8)
manual page and the NOTIFICATION\-LOG\-MIB for details.
.IP "doNotLogTraps yes"
disables the logging of notifications altogether.
This is useful if the \fBsnmptrapd\fR application should
only run traphandle hooks and should not log traps to any location.
.IP "doNotFork yes"
do not fork from the calling shell.
.IP "pidFile PATH"
defines a file in which to store the process ID of the
notification receiver. By default, this ID is not saved.
.SH 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.
.PP
There are currently three types of processing that can be specified:
.RS
.IP "log"
log the details of the notification - either in a specified file,
to standard output (or stderr), or via \fIsyslog\fR (or similar).
.IP "execute"
pass the details of the trap to a specified handler program, including
embedded perl.
.IP "net"
forward the trap to another notification receiver.
.RE
.PP
In the following directives, \fITYPES\fR will be a (comma-separated)
list of one or more of these tokens. Most commonly, this will
typically be \fIlog,execute,net\fR 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.
.IP "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
.IR snmpd.conf (5)
for more details.
.IP "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.
(\fIauthNoPriv\fR or \fIauthPriv\fR). The LEVEL field can
be used to allow unauthenticated notifications (\fInoauth\fR),
or to require encryption (\fIpriv\fR), just as for the SNMP agent.
.IP
With both of these directives, the OID (or \fI\-v VIEW\fR) field
can be used to retrict this configuration to the processing of
particular notifications.
.RS
.IP "Note:"
Unlike the VACM processing described in RFC 3415, this view is
\fBonly\fR matched against the \fCsnmpTrapOID\fR value of the
incoming notification. It is not applied to the payload varbinds
held within that notification.
.RE
.IP "authGroup TYPES [\-s MODEL] GROUP [LEVEL [OID | \-v VIEW ]]"
.IP "authAccess TYPES [\-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]"
.IP "setAccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES"
authorise notifications in the specified GROUP
(configured using the \fIgroup\fR directive)
to trigger the types of processing listed.
See
.IR snmpd.conf (5)
for more details.
.IP "createUser [-e ENGINEID] username (MD5|SHA|SHA-512|SHA-384|SHA-256|SHA-224) authpassphrase [DES|AES]"
See the
.IR 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.
.IP "disableAuthorization yes"
will disable the above access control checks, and revert to the
previous behaviour of accepting all incoming notifications.
.IP
.\" XXX - Explain why this is a Bad Idea
.\"
.SH LOGGING
.IP "format1 FORMAT"
.IP "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.
.IP "format DESTINATION FORMAT"
specify the format used for different destinations.
DESTINATION is one of:
.IR print ", " print1 ", " print2 ", "
.IR syslog ", " syslog1 ", " syslog2 ", "
.IR execute ", " execute1 ", " execute2 .
.I print1
is used for printing SNMPv1 traps,
.I print2
is for SNMPv2.
.I print
is used for both versions.
.I syslog
is similarly used when sending traps to syslog, and
.I execute
used when sending traps to a program such as
.IR traptoemail (1).
.IP
The default formats are
.br
.I format print1 %.4y-%.2m-%.2l %.2h:%.2j:%.2k %B [%b] (via %A [%a]): %N\en\et%W Trap (%q) Uptime: %#T\en%v\en
.br
.I format print2 %.4y-%.2m-%.2l %.2h:%.2j:%.2k %B [%b]:\en%v\en
.br
.I format syslog1 %a: %W Trap (%q) Uptime: %#T%#v\en
.br
.I format syslog2 %B [%b]: Trap %#v\en
.br
.I format execute %B\en%b\en%V\en%v\en
.IP
See
.IR snmptrapd (8)
for the layout characters available.
.IP "ignoreAuthFailure yes"
instructs the receiver to ignore \fIauthenticationFailure\fR traps.
.RS
.IP Note:
This currently only affects the logging of such notifications.
\fIauthenticationFailure\fR 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.
.RE
.IP "logOption string"
specifies where notifications should be logged - to standard
output, standard error, a specified file or via \fIsyslog\fR.
See the section LOGGING OPTIONS in the
.IR snmpcmd (1)
manual page for details.
.IP "outputOption string"
specifies various characteristics of how OIDs and other values
should be displayed.
See the section OUTPUT OPTIONS in the
.IR snmpcmd (1)
manual page for details.
.SH 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.
.RE
.IP "sqlMaxQueue max"
specifies the maximum number of traps to queue before a forced flush
to the MySQL database.
.RE
.IP "sqlSaveInterval seconds"
specified the number of seconds between periodic queue flushes.
A value of 0 for will disable MySQL logging.
.SH 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.
.IP "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
\fCsnmpTrapOID\fR 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).
.IP
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 \fC.1.3.6.1.4.1*\fP would match any enterprise
specific notification (including the specified OID itself).
An OID token of \fC.1.3.6.1.4.1.*\fP 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 \fCoid.*.subids\fR is \fBnot\fC valid.
.IP
If the OID field is the token \fIdefault\fR then the program will be
invoked for any notification not matching another (OID specific)
\fItraphandle\fR entry.
.PP
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\en%b\en%V\en%v\en", one entry per line:
.RS
.IP HOSTNAME
The name of the host that sent the notification, as determined by
.IR gethostbyaddr (3).
.br
.IP ADDRESS
The transport address, like
.br
"[UDP: [172.16.10.12]:23456->[10.150.0.8]]"
.\"
.\" XXX - What about non-IPv4 transports?
.\"
.IP 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 \fIoutputOption\fR
directive (or similar configuration).
.IP
The first OID should always be \fCSNMPv2\-MIB::sysUpTime.0\fR,
and the second should be \fCSNMPv2\-MIB::snmpTrapOID.0\fR.
The remaining lines will contain the payload varbind list.
For SNMPv1 traps, the final OID will be \fCSNMPv2\-MIB::snmpTrapEnterprise.0\fR.
.br
.IP Example:
A \fBtraptoemail\fR script has been included in the Net-SNMP package that
can be used within a \fItraphandle\fR directive:
.br
.RS
.P
traphandle default /usr/bin/perl BINDIR/traptoemail \-s mysmtp.somewhere.com \-f [email protected] [email protected]
.RE
.RE
.IP "forward OID|default DESTINATION"
forwards notifications that match the specified OID
to another receiver listening on DESTINATION.
The interpretation of OID (and \fIdefault\fR) is the same
as for the \fItraphandle\fR directive).
.IP
See the section
.B LISTENING ADDRESSES
in the
.IR snmpd (8)
manual page for more information about the format of listening
addresses.
.RE
.P
addForwarderInfo 1|yes|true|0|no|false
.IP
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.
.SH NOTES
.IP o
The daemon blocks while executing the \fItraphandle\fR commands.
(This should
be fixed in the future with an appropriate signal catch and wait()
combination).
.IP o
All directives listed with a value of "yes" actually accept a range
of boolean values. These will accept any of \fI1\fR, \fIyes\fR or
\fItrue\fR to enable the corresponding behaviour,
or any of \fI0\fR, \fIno\fR or \fIfalse\fR 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.
.SH FILES
SYSCONFDIR/snmp/snmptrapd.conf
.SH "SEE ALSO"
snmp_config(5), snmptrapd(8), syslog(8), traptoemail(1), variables(5), netsnmp_config_api(3).