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.16.2.11 2003/03/12 22:08:15 trhodes Exp $
  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 A
 200 .Em hostname
 201 specification of the form
 202 .Ql #+hostname
 203 or
 204 .Ql +hostname
 205 means the following blocks will be applied to messages
 206 received from the specified hostname.
 207 Alternatively, the
 208 .Em hostname
 209 specification
 210 .Ql #-hostname
 211 or
 212 .Ql -hostname
 213 causes the following blocks to be applied to messages
 214 from any host but the one specified.
 215 If the hostname is given as
 216 .Ql @ ,
 217 the local hostname will be used.
 218 A
 219 .Em program
 220 or
 221 .Em hostname
 222 specification may be reset by giving the program or hostname as
 223 .Ql * .
 224 .Pp
 225 See
 226 .Xr syslog 3
 227 for further descriptions of both the
 228 .Em facility
 229 and
 230 .Em level
 231 keywords and their significance.
 232 It's preferred that selections be made on
 233 .Em facility
 234 rather than
 235 .Em program ,
 236 since the latter can easily vary in a networked environment.
 237 In some cases,
 238 though, an appropriate
 239 .Em facility
 240 simply doesn't exist.
 241 .Pp
 242 If a received message matches the specified
 243 .Em facility
 244 and is of the specified
 245 .Em level
 246 .Em (or a higher level) ,
 247 and the first word in the message after the date matches the
 248 .Em program ,
 249 the action specified in the
 250 .Em action
 251 field will be taken.
 252 .Pp
 253 Multiple
 254 .Em selectors
 255 may be specified for a single
 256 .Em action
 257 by separating them with semicolon
 258 .Pq Dq \&;
 259 characters.
 260 It is important to note, however, that each
 261 .Em selector
 262 can modify the ones preceding it.
 263 .Pp
 264 Multiple
 265 .Em facilities
 266 may be specified for a single
 267 .Em level
 268 by separating them with comma
 269 .Pq Dq \&,
 270 characters.
 271 .Pp
 272 An asterisk
 273 .Pq Dq *
 274 can be used to specify all
 275 .Em facilities ,
 276 all
 277 .Em levels ,
 278 or all
 279 .Em programs .
 280 .Pp
 281 The special
 282 .Em facility
 283 .Dq mark
 284 receives a message at priority
 285 .Dq info
 286 every 20 minutes
 287 (see
 288 .Xr syslogd 8 ) .
 289 This is not enabled by a
 290 .Em facility
 291 field containing an asterisk.
 292 .Pp
 293 The special
 294 .Em level
 295 .Dq none
 296 disables a particular
 297 .Em facility .
 298 .Pp
 299 The
 300 .Em action
 301 field of each line specifies the action to be taken when the
 302 .Em selector
 303 field selects a message.
 304 There are five forms:
 305 .Bl -bullet
 306 .It
 307 A pathname (beginning with a leading slash).
 308 Selected messages are appended to the file.
 309 .It
 310 A hostname (preceded by an at
 311 .Pq Dq @
 312 sign).
 313 Selected messages are forwarded to the
 314 .Xr syslogd 8
 315 program on the named host.
 316 .It
 317 A comma separated list of users.
 318 Selected messages are written to those users
 319 if they are logged in.
 320 .It
 321 An asterisk.
 322 Selected messages are written to all logged-in users.
 323 .It
 324 A vertical bar
 325 .Pq Dq \&| ,
 326 followed by a command to pipe the selected
 327 messages to.  The command is passed to
 328 .Xr sh 1
 329 for evaluation, so usual shell metacharacters or input/output
 330 redirection can occur.  (Note however that redirecting
 331 .Xr stdio 3
 332 buffered output from the invoked command can cause additional delays,
 333 or even lost output data in case a logging subprocess exited with a
 334 signal.)  The command itself runs with
 335 .Em stdout
 336 and
 337 .Em stderr
 338 redirected to
 339 .Pa /dev/null .
 340 Upon receipt of a
 341 .Dv SIGHUP ,
 342 .Xr syslogd 8
 343 will close the pipe to the process.  If the process didn't exit
 344 voluntarily, it will be sent a
 345 .Dv SIGTERM
 346 signal after a grace period of up to 60 seconds.
 347 .Pp
 348 The command will only be started once data arrives that should be piped
 349 to it.  If it exited later, it will be restarted as necessary.  So if it
 350 is desired that the subprocess should get exactly one line of input only
 351 (which can be very resource-consuming if there are a lot of messages
 352 flowing quickly), this can be achieved by exiting after just one line of
 353 input.  If necessary, a script wrapper can be written to this effect.
 354 .Pp
 355 Unless the command is a full pipeline, it's probably useful to
 356 start the command with
 357 .Em exec
 358 so that the invoking shell process does not wait for the command to
 359 complete.  Warning: the process is started under the UID invoking
 360 .Xr syslogd 8 ,
 361 normally the superuser.
 362 .El
 363 .Pp
 364 Blank lines and lines whose first non-blank character is a hash
 365 .Pq Dq #
 366 character are ignored.
 367 .Sh EXAMPLES
 368 A configuration file might appear as follows:
 369 .Bd -literal
 370 # Log all kernel messages, authentication messages of
 371 # level notice or higher, and anything of level err or
 372 # higher to the console.
 373 # Don't log private authentication messages!
 374 *.err;kern.*;auth.notice;authpriv.none  /dev/console
 375
 376 # Log anything (except mail) of level info or higher.
 377 # Don't log private authentication messages!
 378 *.info;mail.none;authpriv.none          /var/log/messages
 379
 380 # Log daemon messages at debug level only
 381 daemon.=debug                                           /var/log/daemon.debug
 382
 383 # The authpriv file has restricted access.
 384 authpriv.*                                              /var/log/secure
 385
 386 # Log all the mail messages in one place.
 387 mail.*                                                  /var/log/maillog
 388
 389 # Everybody gets emergency messages, plus log them on another
 390 # machine.
 391 *.emerg                                                 *
 392 *.emerg                                                 @arpa.berkeley.edu
 393
 394 # Root and Eric get alert and higher messages.
 395 *.alert                                                 root,eric
 396
 397 # Save mail and news errors of level err and higher in a
 398 # special file.
 399 uucp,news.crit                                          /var/log/spoolerr
 400
 401 # Pipe all authentication messages to a filter.
 402 auth.*                                  |exec /usr/local/sbin/authfilter
 403
 404 # Save ftpd transactions along with mail and news
 405 !ftpd
 406 *.*                                                     /var/log/spoolerr
 407
 408 # Log all security messages to a separate file.
 409 security.*                                              /var/log/security
 410
 411 # Log all writes to /dev/console to a separate file.
 412 console.*                                               /var/log/console.log
 413 .Ed
 414 .Sh IMPLEMENTATION NOTES
 415 The
 416 .Dq kern
 417 facility is usually reserved for messages
 418 generated by the local kernel.
 419 Other messages logged with facility
 420 .Dq kern
 421 are usually translated to facility
 422 .Dq user .
 423 This translation can be disabled;
 424 see
 425 .Xr syslogd 8
 426 for details.
 427 .Sh FILES
 428 .Bl -tag -width /etc/syslog.conf -compact
 429 .It Pa /etc/syslog.conf
 430 .Xr syslogd 8
 431 configuration file
 432 .El
 433 .Sh BUGS
 434 The effects of multiple
 435 .Em selectors
 436 are sometimes not intuitive.
 437 For example
 438 .Dq mail.crit,*.err
 439 will select
 440 .Dq mail
 441 facility messages at the level of
 442 .Dq err
 443 or higher, not at the level of
 444 .Dq crit
 445 or higher.
 446 .Pp
 447 In networked environments, note that not all operating systems
 448 implement the same set of facilities.  The facilities
 449 authpriv, cron, ftp, and ntp that are known to this implementation
 450 might be absent on the target system.  Even worse, DEC UNIX uses
 451 facility number 10 (which is authpriv in this implementation) to
 452 log events for their AdvFS file system.
 453 .Sh SEE ALSO
 454 .Xr syslog 3 ,
 455 .Xr syslogd 8