Sweep-fix man page section order to match mdoc(7), part 5/5.
[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.5 2006/02/17 19:40:28 swildner 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 FILES
411 .Bl -tag -width /etc/syslog.conf -compact
412 .It Pa /etc/syslog.conf
413 .Xr syslogd 8
414 configuration file
415 .El
416 .Sh EXAMPLES
417 A configuration file might appear as follows:
418 .Bd -literal
419 # Log all kernel messages, authentication messages of
420 # level notice or higher, and anything of level err or
421 # higher to the console.
422 # Don't log private authentication messages!
423 *.err;kern.*;auth.notice;authpriv.none  /dev/console
424
425 # Log anything (except mail) of level info or higher.
426 # Don't log private authentication messages!
427 *.info;mail.none;authpriv.none          /var/log/messages
428
429 # Log daemon messages at debug level only
430 daemon.=debug                                           /var/log/daemon.debug
431
432 # The authpriv file has restricted access.
433 authpriv.*                                              /var/log/secure
434
435 # Log all the mail messages in one place.
436 mail.*                                                  /var/log/maillog
437
438 # Everybody gets emergency messages, plus log them on another
439 # machine.
440 *.emerg                                                 *
441 *.emerg                                                 @arpa.berkeley.edu
442
443 # Root and Eric get alert and higher messages.
444 *.alert                                                 root,eric
445
446 # Save mail and news errors of level err and higher in a
447 # special file.
448 uucp,news.crit                                          /var/log/spoolerr
449
450 # Pipe all authentication messages to a filter.
451 auth.*                                  |exec /usr/local/sbin/authfilter
452
453 # Save ftpd transactions along with mail and news
454 !ftpd
455 *.*                                                     /var/log/spoolerr
456
457 # Log all security messages to a separate file.
458 security.*                                              /var/log/security
459
460 # Log all writes to /dev/console to a separate file.
461 console.*                                               /var/log/console.log
462
463 # Log ipfw messages without syncing after every message.
464 !ipfw
465 *.*                                                     -/var/log/ipfw
466 .Ed
467 .Sh IMPLEMENTATION NOTES
468 The
469 .Dq kern
470 facility is usually reserved for messages
471 generated by the local kernel.
472 Other messages logged with facility
473 .Dq kern
474 are usually translated to facility
475 .Dq user .
476 This translation can be disabled;
477 see
478 .Xr syslogd 8
479 for details.
480 .Sh SEE ALSO
481 .Xr syslog 3 ,
482 .Xr syslogd 8
483 .Sh BUGS
484 The effects of multiple
485 .Em selectors
486 are sometimes not intuitive.
487 For example
488 .Dq mail.crit,*.err
489 will select
490 .Dq mail
491 facility messages at the level of
492 .Dq err
493 or higher, not at the level of
494 .Dq crit
495 or higher.
496 .Pp
497 In networked environments, note that not all operating systems
498 implement the same set of facilities.
499 The facilities
500 authpriv, cron, ftp, and ntp that are known to this implementation
501 might be absent on the target system.
502 Even worse, DEC UNIX uses
503 facility number 10 (which is authpriv in this implementation) to
504 log events for their AdvFS file system.