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