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