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. 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 December 10, 2020 32.Dt SYSLOG.CONF 5 33.Os 34.Sh NAME 35.Nm syslog.conf 36.Nd 37.Xr syslogd 8 38configuration file 39.Sh DESCRIPTION 40The 41.Nm 42file is the configuration file for the 43.Xr syslogd 8 44program. 45It consists of 46blocks of lines separated by 47.Em program , 48.Em hostname 49or 50.Em property-based filter 51specifications (separations appear alone on their lines), 52with each line containing two fields: the 53.Em selector 54field which specifies the types of messages and priorities to which the 55line applies, and an 56.Em action 57field which specifies the action to be taken if a message 58.Xr syslogd 8 59receives matches the selection criteria. 60The 61.Em selector 62field is separated from the 63.Em action 64field by one or more tab characters or spaces. 65.Pp 66A special 67.Em include 68keyword can be used to include all files with names ending in '.conf' and not 69beginning with a '.' contained in the directory following the keyword. 70This keyword can only be used in the first level configuration file. 71.Pp 72Note that if you use spaces as separators, your 73.Nm 74might be incompatible with other Unices or Unix-like systems. 75This functionality was added for ease of configuration 76(e.g.,\& it is possible to cut-and-paste into 77.Nm ) , 78and to avoid possible mistakes. 79This change however preserves 80backwards compatibility with the old style of 81.Nm 82(i.e., tab characters only). 83.Pp 84The 85.Em selectors 86are encoded as a 87.Em facility , 88a period 89.Pq Dq \&. , 90an optional set of comparison flags 91.Pq Oo \&! Oc Op <=> , 92and a 93.Em level , 94with no intervening white-space. 95Both the 96.Em facility 97and the 98.Em level 99are case insensitive. 100.Pp 101The 102.Em facility 103describes the part of the system generating the message, and is one of 104the following keywords: 105.Cm auth , authpriv , console , cron , daemon , ftp , kern , lpr , 106.Cm mail , mark , news , ntp , security , syslog , user , uucp , 107and 108.Cm local0 109through 110.Cm local7 . 111These keywords (with the exception of mark) correspond to 112similar 113.Dq Dv LOG_ 114values specified to the 115.Xr openlog 3 116and 117.Xr syslog 3 118library routines. 119.Pp 120The 121.Em comparison flags 122may be used to specify exactly what is logged. 123The default comparison is 124.Dq => 125(or, if you prefer, 126.Dq >= ) , 127which means that messages from the specified 128.Em facility 129list, and of a priority 130level equal to or greater than 131.Em level 132will be logged. 133Comparison flags beginning with 134.Dq Li \&! 135will have their logical sense inverted. 136Thus 137.Dq !=info 138means all levels except info and 139.Dq !notice 140has the same meaning as 141.Dq <notice . 142.Pp 143The 144.Em level 145describes the severity of the message, and is a keyword from the 146following ordered list (higher to lower): 147.Cm emerg , crit , alert , err , warning , notice , info 148and 149.Cm debug . 150These keywords correspond to 151similar 152.Dq Dv LOG_ 153values specified to the 154.Xr syslog 3 155library routine. 156.Pp 157Each block of lines is separated from the previous block by a 158.Em program , 159.Em hostname 160or 161.Em property-based filter 162specification. 163A block will only log messages corresponding to the most recent 164.Em program , 165.Em hostname 166and 167.Em property-based filter 168specifications given. 169Thus, with a block which selects 170.Ql ppp 171as the 172.Em program , 173directly followed by a block that selects messages from the 174.Em hostname 175.Ql dialhost , 176the second block will only log messages 177from the 178.Xr ppp 8 179program on dialhost. 180.Pp 181A 182.Em program 183specification is a line beginning with 184.Ql #!prog 185or 186.Ql !prog 187(the former is for compatibility with the previous syslogd, if one is sharing 188.Nm 189files, for example) 190and the following blocks will be associated with calls to 191.Xr syslog 3 192from that specific program. 193A 194.Em program 195specification for 196.Ql foo 197will also match any message logged by the kernel with the prefix 198.Ql "foo: " . 199The 200.Ql #!+prog 201or 202.Ql !+prog 203specification works just like the previous one, 204and the 205.Ql #!-prog 206or 207.Ql !-prog 208specification will match any message but the ones from that 209program. 210Multiple programs may be listed, separated by commas: 211.Ql !prog1,prog2 212matches messages from either program, while 213.Ql !-prog1,prog2 214matches all messages but those from 215.Ql prog1 216or 217.Ql prog2 . 218.Pp 219A 220.Em hostname 221specification of the form 222.Ql #+hostname 223or 224.Ql +hostname 225means the following blocks will be applied to messages 226received from the specified hostname. 227Alternatively, the 228.Em hostname 229specification 230.Ql #-hostname 231or 232.Ql -hostname 233causes the following blocks to be applied to messages 234from any host but the one specified. 235If the hostname is given as 236.Ql @ , 237the local hostname will be used. 238As for program specifications, multiple comma-separated 239values may be specified for hostname specifications. 240.Pp 241A 242.Em property-based filter 243specification is a line beginning with 244.Ql #: 245or 246.Ql \&: 247and the following blocks will be applied only when filter value 248matches given filter propertie's value. 249See 250.Sx PROPERTY-BASED FILTERS 251section for more details. 252.Pp 253A 254.Em program , 255.Em hostname 256or 257.Em property-based filter 258specification may be reset by giving 259.Ql * 260as an argument. 261.Pp 262See 263.Xr syslog 3 264for further descriptions of both the 265.Em facility 266and 267.Em level 268keywords and their significance. 269It is preferred that selections be made on 270.Em facility 271rather than 272.Em program , 273since the latter can easily vary in a networked environment. 274In some cases, 275though, an appropriate 276.Em facility 277simply does not exist. 278.Pp 279If a received message matches the specified 280.Em facility 281and is of the specified 282.Em level 283.Em (or a higher level) , 284and the first word in the message after the date matches the 285.Em program , 286the action specified in the 287.Em action 288field will be taken. 289.Pp 290Multiple 291.Em selectors 292may be specified for a single 293.Em action 294by separating them with semicolon 295.Pq Dq \&; 296characters. 297It is important to note, however, that each 298.Em selector 299can modify the ones preceding it. 300.Pp 301Multiple 302.Em facilities 303may be specified for a single 304.Em level 305by separating them with comma 306.Pq Dq \&, 307characters. 308.Pp 309An asterisk 310.Pq Dq * 311can be used to specify all 312.Em facilities , 313all 314.Em levels , 315or all 316.Em programs . 317.Pp 318The special 319.Em facility 320.Dq mark 321receives a message at priority 322.Dq info 323every 20 minutes 324(see 325.Xr syslogd 8 ) . 326This is not enabled by a 327.Em facility 328field containing an asterisk. 329.Pp 330The special 331.Em level 332.Dq none 333disables a particular 334.Em facility . 335.Pp 336The 337.Em action 338field of each line specifies the action to be taken when the 339.Em selector 340field selects a message. 341There are five forms: 342.Bl -bullet 343.It 344A pathname (beginning with a leading slash). 345Selected messages are appended to the file. 346.Pp 347To ensure that kernel messages are written to disk promptly, 348.Nm 349calls 350.Xr fsync 2 351after writing messages from the kernel. 352Other messages are not synced explicitly. 353You may prefix a pathname with the minus sign, 354.Dq - , 355to forego syncing the specified file after every kernel message. 356Note that you might lose information if the system crashes 357immediately following a write attempt. 358Nevertheless, using the 359.Dq - 360option may improve performance, 361especially if the kernel is logging many messages. 362.It 363A hostname (preceded by an at 364.Pq Dq @ 365sign). 366Selected messages are forwarded to the 367.Xr syslogd 8 368program on the named host. 369If a port number is added after a colon 370.Pq Ql :\& 371then that port will be used as the destination port 372rather than the usual syslog port. 373IPv6 addresses can be used 374by surrounding the address portion with 375square brackets 376.Po 377.Ql [\& 378and 379.Ql ]\& 380.Pc . 381.It 382A comma separated list of users. 383Selected messages are written to those users 384if they are logged in. 385.It 386An asterisk. 387Selected messages are written to all logged-in users. 388.It 389A vertical bar 390.Pq Dq \&| , 391followed by a command to pipe the selected 392messages to. 393The command is passed to 394.Xr sh 1 395for evaluation, so usual shell metacharacters or input/output 396redirection can occur. 397(Note however that redirecting 398.Xr stdio 3 399buffered output from the invoked command can cause additional delays, 400or even lost output data in case a logging subprocess exited with a 401signal.) 402The command itself runs with 403.Em stdout 404and 405.Em stderr 406redirected to 407.Pa /dev/null . 408Upon receipt of a 409.Dv SIGHUP , 410.Xr syslogd 8 411will close the pipe to the process. 412If the process did not exit 413voluntarily, it will be sent a 414.Dv SIGTERM 415signal after a grace period of up to 60 seconds. 416.Pp 417The command will only be started once data arrives that should be piped 418to it. 419If it exited later, it will be restarted as necessary. 420So if it 421is desired that the subprocess should get exactly one line of input only 422(which can be very resource-consuming if there are a lot of messages 423flowing quickly), this can be achieved by exiting after just one line of 424input. 425If necessary, a script wrapper can be written to this effect. 426.Pp 427Unless the command is a full pipeline, it is probably useful to 428start the command with 429.Em exec 430so that the invoking shell process does not wait for the command to 431complete. 432Warning: the process is started under the UID invoking 433.Xr syslogd 8 , 434normally the superuser. 435.El 436.Pp 437Blank lines and lines whose first non-blank character is a hash 438.Pq Dq # 439character are ignored. 440If 441.Ql # 442is placed in the middle of the line, the 443.Ql # 444character and the rest of the line after it is ignored. 445To prevent special meaning, the 446.Ql # 447character may be escaped with 448.Ql \e ; 449in this case preceding 450.Ql \e 451is removed and 452.Ql # 453is treated as an ordinary character. 454.Sh PROPERTY-BASED FILTERS 455.Em program , 456.Em hostname 457specifications performs exact match filtering against explicit field only. 458.Em Property-based filters 459feature substring and regular expressions (see 460.Xr re_format 7 ) 461matching against various message attributes. 462Filter specification starts with 463.Ql #: 464or 465.Ql \&: 466followed by three comma-separated fields 467.Em property , operator , \&"value\&" . 468Value must be double-quoted. 469A double quote and backslash must be escaped by a backslash. 470.Pp 471Following 472.Em properties 473are supported as test value: 474.Pp 475.Bl -bullet -compact 476.It 477.Ql msg 478- body of the message received. 479.It 480.Ql programname 481- program name sent the message 482.It 483.Ql hostname 484- hostname of message's originator 485.It 486.Ql source 487- an alias for hostname 488.El 489.Pp 490Operator specifies a comparison function between 491.Em propertie's 492 value against filter's value. 493Possible operators: 494.Pp 495.Bl -bullet -compact 496.It 497.Ql contains 498- true if filter value is found as a substring of 499.Em property 500.It 501.Ql isequal 502- true if filter value is equal to 503.Em property 504.It 505.Ql startswith 506- true if property starts with filter value 507.It 508.Ql regex 509- true if property matches basic regular expression defined in filter value 510.It 511.Ql ereregex 512- true if property matches extended regular expression defined in filter value 513.El 514.Pp 515Operator may be prefixed by 516.Pp 517.Bl -bullet -compact 518.It 519.Ql \&! 520- to invert compare logic 521.It 522.Ql icase_ 523- to make comparison function case insensitive 524.El 525.Sh IMPLEMENTATION NOTES 526The 527.Dq kern 528facility is usually reserved for messages 529generated by the local kernel. 530Other messages logged with facility 531.Dq kern 532are usually translated to facility 533.Dq user . 534This translation can be disabled; 535see 536.Xr syslogd 8 537for details. 538.Sh FILES 539.Bl -tag -width /etc/syslog.conf -compact 540.It Pa /etc/syslog.conf 541.Xr syslogd 8 542configuration file 543.El 544.Sh EXAMPLES 545A configuration file might appear as follows: 546.Bd -literal 547# Log all kernel messages, authentication messages of 548# level notice or higher, and anything of level err or 549# higher to the console. 550# Do not log private authentication messages! 551*.err;kern.*;auth.notice;authpriv.none;mail.crit /dev/console 552 553# Log anything (except mail) of level info or higher. 554# Do not log private authentication messages! 555*.info;mail.none;authpriv.none /var/log/messages 556 557# Log daemon messages at debug level only 558daemon.=debug /var/log/daemon.debug 559 560# The authpriv file has restricted access. 561authpriv.* /var/log/secure 562 563# Log all the mail messages in one place. 564mail.* /var/log/maillog 565 566# Everybody gets emergency messages, plus log them on another 567# machine. 568*.emerg * 569*.emerg @arpa.berkeley.edu 570 571# Root and Eric get alert and higher messages. 572*.alert root,eric 573 574# Save mail and news errors of level err and higher in a 575# special file. 576uucp,news.crit /var/log/spoolerr 577 578# Pipe all authentication messages to a filter. 579auth.* |exec /usr/local/sbin/authfilter 580 581# Log all security messages to a separate file. 582security.* /var/log/security 583 584# Log all writes to /dev/console to a separate file. 585console.* /var/log/console.log 586 587# Save ftpd transactions along with mail and news 588!ftpd 589*.* /var/log/spoolerr 590 591# Log ipfw messages without syncing after every message. 592!ipfw 593*.* -/var/log/ipfw 594 595# Log ipfw messages with "Deny" in the message body. 596:msg, contains, ".*Deny.*" 597*.* /var/log/ipfw.deny 598 599# Reset program name filtering 600!* 601 602# Log messages from bird or bird6 into one file 603:programname, regex, "^bird6?$" 604*.* /var/log/bird-all.log 605 606# Log messages from servers in racks 10-19 in multiple locations, case insensitive 607:hostname, icase_ereregex, "^server-(dcA|podB|cdn)-rack1[0-9]{2}\\..*" 608*.* /var/log/racks10..19.log 609.Ed 610.Sh SEE ALSO 611.Xr syslog 3 , 612.Xr syslogd 8 613.Sh BUGS 614The effects of multiple 615.Em selectors 616are sometimes not intuitive. 617For example 618.Dq mail.crit,*.err 619will select 620.Dq mail 621facility messages at the level of 622.Dq err 623or higher, not at the level of 624.Dq crit 625or higher. 626.Pp 627In networked environments, note that not all operating systems 628implement the same set of facilities. 629The facilities 630authpriv, cron, ftp, and ntp that are known to this implementation 631might be absent on the target system. 632Even worse, DEC UNIX uses 633facility number 10 (which is authpriv in this implementation) to 634log events for their AdvFS file system. 635