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