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