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