Synchronize syslogd with FreeBSD. Primarily syslogd.c/1.129. This primarily
[dragonfly.git] / usr.sbin / syslogd / syslog.conf.5
1 .\" Copyright (c) 1990, 1991, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\"    must display the following acknowledgement:
14 .\"     This product includes software developed by the University of
15 .\"     California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\"     @(#)syslog.conf.5       8.1 (Berkeley) 6/9/93
33 .\" $FreeBSD: src/usr.sbin/syslogd/syslog.conf.5,v 1.35 2004/07/03 18:35:53 ru Exp $
34 .\" $DragonFly: src/usr.sbin/syslogd/syslog.conf.5,v 1.3 2004/08/09 20:11:19 dillon Exp $
35 .\"
36 .Dd June 9, 1993
37 .Dt SYSLOG.CONF 5
38 .Os
39 .Sh NAME
40 .Nm syslog.conf
41 .Nd
42 .Xr syslogd 8
43 configuration file
44 .Sh DESCRIPTION
45 The
46 .Nm
47 file is the configuration file for the
48 .Xr syslogd 8
49 program.
50 It consists of
51 blocks of lines separated by
52 .Em program
53 and
54 .Em hostname
55 specifications (separations appear along on the line),
56 with each line containing two fields: the
57 .Em selector
58 field which specifies the types of messages and priorities to which the
59 line applies, and an
60 .Em action
61 field which specifies the action to be taken if a message
62 .Xr syslogd 8
63 receives matches the selection criteria.
64 The
65 .Em selector
66 field is separated from the
67 .Em action
68 field by one or more tab characters or spaces.
69 .Pp
70 Note that if you use spaces as separators, your
71 .Nm
72 might be incompatible with other Unices or Unix-like systems.
73 This functionality was added for ease of configuration
74 (e.g.\& it is possible to cut-and-paste into
75 .Nm ) ,
76 and to avoid possible mistakes.
77 This change however preserves
78 backwards compatibility with the old style of
79 .Nm
80 (i.e., tab characters only).
81 .Pp
82 The
83 .Em selectors
84 are encoded as a
85 .Em facility ,
86 a period
87 .Pq Dq \&. ,
88 an optional set of comparison flags
89 .Pq Oo \&! Oc Op <=> ,
90 and a
91 .Em level ,
92 with no intervening white-space.
93 Both the
94 .Em facility
95 and the
96 .Em level
97 are case insensitive.
98 .Pp
99 The
100 .Em facility
101 describes the part of the system generating the message, and is one of
102 the following keywords: auth, authpriv, console, cron, daemon, ftp, kern,
103 lpr, mail, mark, news, ntp, security, syslog, user, uucp and local0 through
104 local7.
105 These keywords (with the exception of mark) correspond to
106 similar
107 .Dq Dv LOG_
108 values specified to the
109 .Xr openlog 3
110 and
111 .Xr syslog 3
112 library routines.
113 .Pp
114 The
115 .Em comparison flags
116 may be used to specify exactly what is logged.
117 The default comparison is
118 .Dq =>
119 (or, if you prefer,
120 .Dq >= ) ,
121 which means that messages from the specified
122 .Em facility
123 list, and of a priority
124 level equal to or greater than
125 .Em level
126 will be logged.
127 Comparison flags beginning with
128 .Dq Li \&!
129 will have their logical sense inverted.
130 Thus
131 .Dq !=info
132 means all levels except info and
133 .Dq !notice
134 has the same meaning as
135 .Dq <notice .
136 .Pp
137 The
138 .Em level
139 describes the severity of the message, and is a keyword from the
140 following ordered list (higher to lower): emerg, alert, crit, err,
141 warning, notice, info and debug.
142 These keywords correspond to
143 similar
144 .Dq Dv LOG_
145 values specified to the
146 .Xr syslog 3
147 library routine.
148 .Pp
149 Each block of lines is separated from the previous block by a
150 .Em program
151 or
152 .Em hostname
153 specification.
154 A block will only log messages corresponding to the most recent
155 .Em program
156 and
157 .Em hostname
158 specifications given.
159 Thus, with a block which selects
160 .Ql ppp
161 as the
162 .Em program ,
163 directly followed by a block that selects messages from the
164 .Em hostname
165 .Ql dialhost ,
166 the second block will only log messages
167 from the
168 .Xr ppp 8
169 program on dialhost.
170 .Pp
171 A
172 .Em program
173 specification is a line beginning with
174 .Ql #!prog
175 or
176 .Ql !prog
177 (the former is for compatibility with the previous syslogd, if one is sharing
178 .Nm
179 files, for example)
180 and the following blocks will be associated with calls to
181 .Xr syslog 3
182 from that specific program.
183 A
184 .Em program
185 specification for
186 .Ql foo
187 will also match any message logged by the kernel with the prefix
188 .Ql "foo: " .
189 The
190 .Ql #!+prog
191 or
192 .Ql !+prog
193 specification works just like the previous one,
194 and the
195 .Ql #!-prog
196 or
197 .Ql !-prog
198 specification will match any message but the ones from that
199 program.
200 Multiple programs may be listed, separated by commas:
201 .Ql !prog1,prog2
202 matches messages from either program, while
203 .Ql !-prog1,prog2
204 matches all messages but those from
205 .Ql prog1
206 or
207 .Ql prog2 .
208 .Pp
209 A
210 .Em hostname
211 specification of the form
212 .Ql #+hostname
213 or
214 .Ql +hostname
215 means the following blocks will be applied to messages
216 received from the specified hostname.
217 Alternatively, the
218 .Em hostname
219 specification
220 .Ql #-hostname
221 or
222 .Ql -hostname
223 causes the following blocks to be applied to messages
224 from any host but the one specified.
225 If the hostname is given as
226 .Ql @ ,
227 the local hostname will be used.
228 As for program specifications, multiple comma-seprarated
229 values may be specified for hostname specifications.
230 .Pp
231 A
232 .Em program
233 or
234 .Em hostname
235 specification may be reset by giving the program or hostname as
236 .Ql * .
237 .Pp
238 See
239 .Xr syslog 3
240 for further descriptions of both the
241 .Em facility
242 and
243 .Em level
244 keywords and their significance.
245 It's preferred that selections be made on
246 .Em facility
247 rather than
248 .Em program ,
249 since the latter can easily vary in a networked environment.
250 In some cases,
251 though, an appropriate
252 .Em facility
253 simply doesn't exist.
254 .Pp
255 If a received message matches the specified
256 .Em facility
257 and is of the specified
258 .Em level
259 .Em (or a higher level) ,
260 and the first word in the message after the date matches the
261 .Em program ,
262 the action specified in the
263 .Em action
264 field will be taken.
265 .Pp
266 Multiple
267 .Em selectors
268 may be specified for a single
269 .Em action
270 by separating them with semicolon
271 .Pq Dq \&;
272 characters.
273 It is important to note, however, that each
274 .Em selector
275 can modify the ones preceding it.
276 .Pp
277 Multiple
278 .Em facilities
279 may be specified for a single
280 .Em level
281 by separating them with comma
282 .Pq Dq \&,
283 characters.
284 .Pp
285 An asterisk
286 .Pq Dq *
287 can be used to specify all
288 .Em facilities ,
289 all
290 .Em levels ,
291 or all
292 .Em programs .
293 .Pp
294 The special
295 .Em facility
296 .Dq mark
297 receives a message at priority
298 .Dq info
299 every 20 minutes
300 (see
301 .Xr syslogd 8 ) .
302 This is not enabled by a
303 .Em facility
304 field containing an asterisk.
305 .Pp
306 The special
307 .Em level
308 .Dq none
309 disables a particular
310 .Em facility .
311 .Pp
312 The
313 .Em action
314 field of each line specifies the action to be taken when the
315 .Em selector
316 field selects a message.
317 There are five forms:
318 .Bl -bullet
319 .It
320 A pathname (beginning with a leading slash).
321 Selected messages are appended to the file.
322 .Pp
323 To ensure that kernel messages are written to disk promptly,
324 .Nm
325 calls
326 .Xr fsync 2
327 after writing messages from the kernel.
328 Other messages are not synced explicitly.
329 You may prefix a pathname with the minus sign,
330 .Dq - ,
331 to forego syncing the specified file after every kernel message.
332 Note that you might lose information if the system crashes
333 immediately following a write attempt.
334 Nevertheless, using the
335 .Dq -
336 option may improve performance,
337 especially if the kernel is logging many messages.
338 .It
339 A hostname (preceded by an at
340 .Pq Dq @
341 sign).
342 Selected messages are forwarded to the
343 .Xr syslogd 8
344 program on the named host.
345 .It
346 A comma separated list of users.
347 Selected messages are written to those users
348 if they are logged in.
349 .It
350 An asterisk.
351 Selected messages are written to all logged-in users.
352 .It
353 A vertical bar
354 .Pq Dq \&| ,
355 followed by a command to pipe the selected
356 messages to.
357 The command is passed to
358 .Xr sh 1
359 for evaluation, so usual shell metacharacters or input/output
360 redirection can occur.
361 (Note however that redirecting
362 .Xr stdio 3
363 buffered output from the invoked command can cause additional delays,
364 or even lost output data in case a logging subprocess exited with a
365 signal.)
366 The command itself runs with
367 .Em stdout
368 and
369 .Em stderr
370 redirected to
371 .Pa /dev/null .
372 Upon receipt of a
373 .Dv SIGHUP ,
374 .Xr syslogd 8
375 will close the pipe to the process.
376 If the process didn't exit
377 voluntarily, it will be sent a
378 .Dv SIGTERM
379 signal after a grace period of up to 60 seconds.
380 .Pp
381 The command will only be started once data arrives that should be piped
382 to it.
383 If it exited later, it will be restarted as necessary.
384 So if it
385 is desired that the subprocess should get exactly one line of input only
386 (which can be very resource-consuming if there are a lot of messages
387 flowing quickly), this can be achieved by exiting after just one line of
388 input.
389 If necessary, a script wrapper can be written to this effect.
390 .Pp
391 Unless the command is a full pipeline, it's probably useful to
392 start the command with
393 .Em exec
394 so that the invoking shell process does not wait for the command to
395 complete.
396 Warning: the process is started under the UID invoking
397 .Xr syslogd 8 ,
398 normally the superuser.
399 .El
400 .Pp
401 Blank lines and lines whose first non-blank character is a hash
402 .Pq Dq #
403 character are ignored.
404 .Sh EXAMPLES
405 A configuration file might appear as follows:
406 .Bd -literal
407 # Log all kernel messages, authentication messages of
408 # level notice or higher, and anything of level err or
409 # higher to the console.
410 # Don't log private authentication messages!
411 *.err;kern.*;auth.notice;authpriv.none  /dev/console
412
413 # Log anything (except mail) of level info or higher.
414 # Don't log private authentication messages!
415 *.info;mail.none;authpriv.none          /var/log/messages
416
417 # Log daemon messages at debug level only
418 daemon.=debug                                           /var/log/daemon.debug
419
420 # The authpriv file has restricted access.
421 authpriv.*                                              /var/log/secure
422
423 # Log all the mail messages in one place.
424 mail.*                                                  /var/log/maillog
425
426 # Everybody gets emergency messages, plus log them on another
427 # machine.
428 *.emerg                                                 *
429 *.emerg                                                 @arpa.berkeley.edu
430
431 # Root and Eric get alert and higher messages.
432 *.alert                                                 root,eric
433
434 # Save mail and news errors of level err and higher in a
435 # special file.
436 uucp,news.crit                                          /var/log/spoolerr
437
438 # Pipe all authentication messages to a filter.
439 auth.*                                  |exec /usr/local/sbin/authfilter
440
441 # Save ftpd transactions along with mail and news
442 !ftpd
443 *.*                                                     /var/log/spoolerr
444
445 # Log all security messages to a separate file.
446 security.*                                              /var/log/security
447
448 # Log all writes to /dev/console to a separate file.
449 console.*                                               /var/log/console.log
450
451 # Log ipfw messages without syncing after every message.
452 !ipfw
453 *.*                                                     -/var/log/ipfw
454 .Ed
455 .Sh IMPLEMENTATION NOTES
456 The
457 .Dq kern
458 facility is usually reserved for messages
459 generated by the local kernel.
460 Other messages logged with facility
461 .Dq kern
462 are usually translated to facility
463 .Dq user .
464 This translation can be disabled;
465 see
466 .Xr syslogd 8
467 for details.
468 .Sh FILES
469 .Bl -tag -width /etc/syslog.conf -compact
470 .It Pa /etc/syslog.conf
471 .Xr syslogd 8
472 configuration file
473 .El
474 .Sh BUGS
475 The effects of multiple
476 .Em selectors
477 are sometimes not intuitive.
478 For example
479 .Dq mail.crit,*.err
480 will select
481 .Dq mail
482 facility messages at the level of
483 .Dq err
484 or higher, not at the level of
485 .Dq crit
486 or higher.
487 .Pp
488 In networked environments, note that not all operating systems
489 implement the same set of facilities.
490 The facilities
491 authpriv, cron, ftp, and ntp that are known to this implementation
492 might be absent on the target system.
493 Even worse, DEC UNIX uses
494 facility number 10 (which is authpriv in this implementation) to
495 log events for their AdvFS file system.
496 .Sh SEE ALSO
497 .Xr syslog 3 ,
498 .Xr syslogd 8