Bring in Jeff Wheelhouse's CLOG / circular log file support for syslogd,
[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.4 2004/10/30 20:26:48 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 percent sign
354 .Pq Dq \&% ,
355 followed by a pathname (beginning with a leading slash).  Selected messages
356 are written to a circular log file.  See clog(8) for a discussion of
357 circular log files.
358 .It
359 A vertical bar
360 .Pq Dq \&| ,
361 followed by a command to pipe the selected
362 messages to.
363 The command is passed to
364 .Xr sh 1
365 for evaluation, so usual shell metacharacters or input/output
366 redirection can occur.
367 (Note however that redirecting
368 .Xr stdio 3
369 buffered output from the invoked command can cause additional delays,
370 or even lost output data in case a logging subprocess exited with a
371 signal.)
372 The command itself runs with
373 .Em stdout
374 and
375 .Em stderr
376 redirected to
377 .Pa /dev/null .
378 Upon receipt of a
379 .Dv SIGHUP ,
380 .Xr syslogd 8
381 will close the pipe to the process.
382 If the process didn't exit
383 voluntarily, it will be sent a
384 .Dv SIGTERM
385 signal after a grace period of up to 60 seconds.
386 .Pp
387 The command will only be started once data arrives that should be piped
388 to it.
389 If it exited later, it will be restarted as necessary.
390 So if it
391 is desired that the subprocess should get exactly one line of input only
392 (which can be very resource-consuming if there are a lot of messages
393 flowing quickly), this can be achieved by exiting after just one line of
394 input.
395 If necessary, a script wrapper can be written to this effect.
396 .Pp
397 Unless the command is a full pipeline, it's probably useful to
398 start the command with
399 .Em exec
400 so that the invoking shell process does not wait for the command to
401 complete.
402 Warning: the process is started under the UID invoking
403 .Xr syslogd 8 ,
404 normally the superuser.
405 .El
406 .Pp
407 Blank lines and lines whose first non-blank character is a hash
408 .Pq Dq #
409 character are ignored.
410 .Sh EXAMPLES
411 A configuration file might appear as follows:
412 .Bd -literal
413 # Log all kernel messages, authentication messages of
414 # level notice or higher, and anything of level err or
415 # higher to the console.
416 # Don't log private authentication messages!
417 *.err;kern.*;auth.notice;authpriv.none  /dev/console
418
419 # Log anything (except mail) of level info or higher.
420 # Don't log private authentication messages!
421 *.info;mail.none;authpriv.none          /var/log/messages
422
423 # Log daemon messages at debug level only
424 daemon.=debug                                           /var/log/daemon.debug
425
426 # The authpriv file has restricted access.
427 authpriv.*                                              /var/log/secure
428
429 # Log all the mail messages in one place.
430 mail.*                                                  /var/log/maillog
431
432 # Everybody gets emergency messages, plus log them on another
433 # machine.
434 *.emerg                                                 *
435 *.emerg                                                 @arpa.berkeley.edu
436
437 # Root and Eric get alert and higher messages.
438 *.alert                                                 root,eric
439
440 # Save mail and news errors of level err and higher in a
441 # special file.
442 uucp,news.crit                                          /var/log/spoolerr
443
444 # Pipe all authentication messages to a filter.
445 auth.*                                  |exec /usr/local/sbin/authfilter
446
447 # Save ftpd transactions along with mail and news
448 !ftpd
449 *.*                                                     /var/log/spoolerr
450
451 # Log all security messages to a separate file.
452 security.*                                              /var/log/security
453
454 # Log all writes to /dev/console to a separate file.
455 console.*                                               /var/log/console.log
456
457 # Log ipfw messages without syncing after every message.
458 !ipfw
459 *.*                                                     -/var/log/ipfw
460 .Ed
461 .Sh IMPLEMENTATION NOTES
462 The
463 .Dq kern
464 facility is usually reserved for messages
465 generated by the local kernel.
466 Other messages logged with facility
467 .Dq kern
468 are usually translated to facility
469 .Dq user .
470 This translation can be disabled;
471 see
472 .Xr syslogd 8
473 for details.
474 .Sh FILES
475 .Bl -tag -width /etc/syslog.conf -compact
476 .It Pa /etc/syslog.conf
477 .Xr syslogd 8
478 configuration file
479 .El
480 .Sh BUGS
481 The effects of multiple
482 .Em selectors
483 are sometimes not intuitive.
484 For example
485 .Dq mail.crit,*.err
486 will select
487 .Dq mail
488 facility messages at the level of
489 .Dq err
490 or higher, not at the level of
491 .Dq crit
492 or higher.
493 .Pp
494 In networked environments, note that not all operating systems
495 implement the same set of facilities.
496 The facilities
497 authpriv, cron, ftp, and ntp that are known to this implementation
498 might be absent on the target system.
499 Even worse, DEC UNIX uses
500 facility number 10 (which is authpriv in this implementation) to
501 log events for their AdvFS file system.
502 .Sh SEE ALSO
503 .Xr syslog 3 ,
504 .Xr syslogd 8