1.\" $NetBSD: syslog.conf.5,v 1.28 2023/12/31 23:39:27 uwe Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" from: @(#)syslog.conf.5 8.1 (Berkeley) 6/9/93 31.\" 32.Dd November 9, 2013 33.Dt SYSLOG.CONF 5 34.Os 35.Sh NAME 36.Nm syslog.conf 37.Nd 38.Xr syslogd 8 39configuration file 40.Sh DESCRIPTION 41The 42.Nm 43file is the configuration file for the 44.Xr syslogd 8 45program. 46It consists of extended options 47.Po 48lines with one 49.Ar key\^ Ns Li = Ns Ar value 50assignment 51.Pc 52and blocks of lines separated by 53.Em program 54and 55.Em hostname 56specifications, with each line containing two fields: the 57.Em selector 58field which specifies the types of messages and priorities to which the 59line applies, and an 60.Em action 61field which specifies the action to be taken if a message 62.Xr syslogd 8 63receives matches the selection criteria. 64The 65.Em selector 66field is separated from the 67.Em action 68field by one or more tab characters. 69.Pp 70Blank lines and lines whose first non-blank character is a hash 71.Pq Ql # 72character are ignored. 73.\" 74.Ss Selectors 75.Pp 76The 77.Em selector Ns s 78function 79are encoded as a 80.Em facility , 81a period 82.Pq Ql \&. , 83an optional set of 84.Em comparison flags 85.Pq Oo Li \&! Oc Ns Op Li <=> , 86and a 87.Em level , 88with no intervening white-space. 89Both the 90.Em facility 91and the 92.Em level 93are case insensitive. 94.Pp 95The 96.Em facility 97describes the part of the system generating the message, and is one of 98the following keywords: 99.Ic auth , 100.Ic authpriv , 101.Ic cron , 102.Ic daemon , 103.Ic ftp , 104.Ic kern , 105.Ic lpr , 106.Ic mail , 107.Ic mark , 108.Ic news , 109.Ic syslog , 110.Ic user , 111.Ic uucp , 112and 113.Ic local0 114through 115.Ic local7 . 116These keywords 117.Po 118with the exception of 119.Ic mark 120.Pc 121correspond to the similar 122.Ql LOG_ 123values specified to the 124.Xr openlog 3 125and 126.Xr syslog 3 127library routines. 128.Pp 129The 130.Em comparison flags 131may be used to specify exactly what levels are logged. 132If unspecified, the default comparison is 133.Ql >= 134.Pq greater than or equal to , 135or, if the 136.Fl U 137option is passed to 138.Xr syslogd 8 , 139.Ql = 140.Pq equal to . 141Comparison flags beginning with 142.Ql \&! 143will have their logical sense inverted. 144Thus, 145.Ql !=info 146means all levels except info and 147.Ql !notice 148has the same meaning as 149.Ql <notice . 150.Pp 151The 152.Em level 153describes the severity of the message, and is a keyword from the 154following ordered list (higher to lower): 155.Ic emerg , 156.Ic alert , 157.Ic crit , 158.Ic err , 159.Ic warning , 160.Ic notice , 161.Ic info , 162and 163.Ic debug . 164These keywords correspond to the 165similar 166.Ql LOG_ 167values specified to the 168.Xr syslog 3 169library routine. 170.Pp 171Each block of lines is separated from the previous block by a 172.Em program 173or 174.Em hostname 175specification. 176A block will only log messages corresponding to the most recent 177.Em program 178and 179.Em hostname 180specifications given. 181Consider the case of a block that selects 182.Ql pppd 183as the 184.Em program , 185directly followed by a block that selects messages from the 186.Em hostname 187.Ql dialhost . 188The second block will log only messages from the 189.Xr pppd 8 190program from the host 191.Sq dialhost . 192.Pp 193A 194.Em program 195specification of the form 196.Ql #!+prog1,prog2 197or 198.Ql !+prog1,prog2 199will cause subsequent blocks to be applied to messages logged by the 200specified programs. 201A 202.Em program 203specification of the form 204.Ql #!-prog1,prog2 205or 206.Ql !-prog1,prog2 207will cause subsequent blocks to be applied to messages logged by programs 208other than the ones specified. 209A 210.Em program 211specification of the form 212.Ql #!prog1,prog2 213or 214.Ql !prog1,prog2 215is equivalent to 216.Ql !+prog1,prog2 . 217Program selectors may also match kernel-generated messages. 218For example, a program specification of 219.Ql !+subsys 220will match kernel-generated messages of the form 221.Ql subsys: here is a message . 222The special specification 223.Ql !* 224will cause subsequent blocks to apply to all programs. 225.Pp 226A 227.Em hostname 228specification of the form 229.Ql #+host1,host2 230or 231.Ql +host1,host2 232will cause subsequent blocks to be applied to messages received from 233the specified hosts. 234A 235.Em hostname 236specification of the form 237.Ql #-host1,host2 238or 239.Ql -host1,host2 240will cause subsequent blocks to be applied to messages from hosts other 241than the ones specified. 242If the hostname is given as 243.Ql @ , 244the local hostname will be used. 245The special specification 246.Ql +* 247will cause subsequent blocks to apply to all hosts. 248.Pp 249See 250.Xr syslog 3 251for a further descriptions of both the 252.Em facility 253and 254.Em level 255keywords and their significance. 256It is preferred that selections be made based on 257.Em facility 258rather than 259.Em program , 260since the latter can vary in a networked environment. 261However, there are cases where a 262.Em facility 263may be too broadly defined. 264.Pp 265If a received message matches the specified 266.Em facility , 267and the specified 268.Em level 269comparison is true, 270and the first word in the message after the date matches the 271.Em program , 272the action specified in the 273.Em action 274field will be taken. 275.Pp 276Multiple 277.Em selectors 278may be specified for a single 279.Em action 280by separating them with semicolon 281.Pq Ql \&; 282characters. 283It is important to note, however, that each 284.Em selector 285can modify the ones preceding it. 286.Pp 287Multiple 288.Em facilities 289may be specified for a single 290.Em level 291by separating them with comma 292.Pq Ql \&, 293characters. 294.Pp 295An asterisk 296.Pq Ql \&* 297can be used to specify all 298.Em facilities 299or all 300.Em levels . 301.Pp 302The special 303.Em facility 304.Ic mark 305receives a message at priority 306.Ql info 307every 20 minutes 308.Po see 309.Xr syslogd 8 310.Pc . 311This is not enabled by a 312.Em facility 313field containing an asterisk. 314.Pp 315The special 316.Em level 317.Ql none 318disables a particular 319.Em facility . 320.\" 321.Ss Actions 322.Pp 323The 324.Em action 325field of each line specifies the action to be taken when the 326.Em selector 327field selects a message. 328There are five forms: 329.Bl -bullet 330.It 331A pathname beginning with a leading slash 332.Pq Ql \&/ . 333Selected messages are appended to the file, unless 334pathname points to an existing FIFO special file. 335.Xr syslogd 8 336treats FIFO specially by opening them in non-blocking mode and 337discarding messages sent when no reader is listening on the other side. 338.Pp 339To ensure that kernel messages are written to disk promptly, 340.Xr syslogd 8 341calls 342.Xr fsync 2 343after writing messages from the kernel. 344Other messages are not synced explicitly. 345You may disable syncing of files specified to receive kernel messages 346by prefixing the pathname with a minus sign 347.Pq Ql \- . 348Note that use of this option may cause the loss of log information in 349the event of a system crash immediately following the write attempt. 350However, using this option may prove to be useful if your system's 351kernel is logging many messages. 352.Pp 353Normally the priority and version is not written to file. 354In order to use syslog-sign you may prefix a pathname with the plus sign 355.Pq Ql + . 356If both switches are used the order has to be 357.Ql +\- . 358.It 359A hostname preceded by an at sign 360.Pq Ql @ . 361Selected messages are forwarded to the 362.Xr syslogd 8 363program on the named host with UDP. 364.It 365A hostname preceded by an at sign 366.Pq Ql @ , 367and enclosed in brackets 368.Pq Ql [] . 369Selected messages are forwarded with TLS to the 370.Xr syslogd 8 371program on the named host. 372After the closing bracket a colon 373.Pq Ql \&: 374and a port number or service name may be appended. 375Additional parameters are configured in parentheses in the form of 376.Ar key\^ Ns Li = Ns Ar value . 377Recognized keywords are 378.Ic subject , 379.Ic fingerprint , 380.Ic cert , 381and 382.Ic verify . 383.It 384A comma separated list of users. 385Selected messages are written to those users 386if they are logged in. 387.It 388An asterisk 389.Pq Ql * . 390Selected messages are written to all logged-in users. 391.It 392A vertical bar 393.Pq Ql | 394followed by a command to which to pipe the selected messages. 395The command string is passed to 396.Pa /bin/sh 397for evaluation, so the usual shell metacharacters or input/output 398redirection can occur. 399.Po 400Note that redirecting 401.Xr stdio 3 402buffered output from the invoked command can cause additional delays, 403or even lost output data in case a logging subprocess exits with a 404signal. 405.Pc 406The command itself runs with 407.Va stdout 408and 409.Va stderr 410redirected to 411.Pa /dev/null . 412Upon receipt of a 413.Dv SIGHUP , 414.Xr syslogd 8 415will close the pipe to the process. 416If the process does not exit voluntarily, it will be sent a 417.Dv SIGTERM 418signal after a grace period of up to 60 seconds. 419.Pp 420The command will only be started once data arrives that should be 421piped to it. 422If the command exits, it will be restarted as necessary. 423.Pp 424If it is desired that the subprocess should receive exactly one line of 425input, this can be achieved by exiting after reading and processing the 426single line. 427A wrapper script can be used to achieve this effect, if necessary. 428Note that this method can be very resource-intensive if many log messages 429are being piped through the filter. 430.Pp 431Unless the command is a full pipeline, it may be useful to 432start the command with 433.Ic exec 434so that the invoking shell process does not wait for the command to 435complete. 436Note that the command is started with the UID of the 437.Xr syslogd 8 438process, normally the superuser. 439.Pp 440Just like with files a plus sign 441.Pq Ql + 442will leave the priority and version information intact. 443.El 444.Sh "TLS OPTIONS" 445Additional options are used for TLS configuration: 446.Bl -tag -width Ic 447.It Ic tls_server 448Enables TLS server mode. 449.It Ic tls_bindport 450Service name or port number to bind to. 451Default is 452.Ql syslog . 453.Em As long as no official port is assigned this option is required 454.Em for TLS servers. 455.It Ic tls_bindhost 456Hostname or IP to bind to. 457.It Ic tls_gen_cert 458Automatically generate a private key and certificate. 459.It Ic tls_key 460File with private key. 461Default is 462.Pa /etc/openssl/default.key 463.It Ic tls_cert 464File with certificate to use. 465Default is 466.Pa /etc/openssl/default.crt 467.It Ic tls_ca 468File with CA certificate to use. 469.It Ic tls_cadir 470Directory containing CA certificates. 471.It Ic tls_verify 472If set to 473.Ql off 474then certificate authentication is skipped. 475.It Ic tls_allow_fingerprints 476List of fingerprints of trusted client certificates. 477.It Ic tls_allow_clientcerts 478List of filenames with trusted client certificates. 479.El 480.Pp 481One function of TLS is mutual authentication of client and server. 482Unless authentication is disabled by setting 483.Ql tls_verify=off 484the following rules are used. 485.Ss "Client Authentication" 486A client can be configured not to check a server's certificate by 487setting the 488.Em action Ap s 489parameter 490.Ql verify 491to 492.Ql off . 493If the server's certificate is signed by a trusted CA then it is checked 494if its hostname or IP is given in its certificate 495.Po 496as a CommonName, as a 497.Tn DNS 498SubjectAltName, or as an 499.Tn IP 500SubjectAltName 501.Pc . 502If any match is found then the server is authenticated. 503If a 504.Ql subject 505parameter is given then it is can satisfy this test as well. 506This allows DNS-independent configurations using the server's IP address in the 507destination and adding its hostname as 508.Ql subject 509to authenticate the TLS connection without having to add the IP to the X.509 510certificate. 511.Pp 512If no CA is used or no trust path between CA and server certificate exists, then 513hash value of the server's certificate is compared with the hash given in 514.Ql fingerprint 515and the hash of the certificate in 516.Ql cert . 517If the hashes are equal then the server is authenticated. 518.Ss "Server Authentication" 519If using a CA and the client's certificate is signed by it then the client is 520authenticated. 521Otherwise the hash of the client's certificate is compared with the hashes given 522in 523.Ql tls_allow_fingerprints , 524and the hashes of the certificates given in 525.Ql tls_allow_clientcerts 526options. 527On any match the client is authenticated. 528.Sh BUFFERING OPTIONS 529.Xr syslogd 8 530is able to buffer temporary not writable messages in memory. 531To limit the memory consumed for this buffering the following options may be 532given: 533.Pp 534.Bl -tag -width Ic -compact 535.It Ic file_queue_length 536.It Ic pipe_queue_length 537.It Ic tls_queue_length 538The maximum number of messages buffered for one destination of type file, 539pipe, or TLS respectively. 540Defaults are 5411024 for files and pipes and \-1 (no limit) for TLS. 542.Pp 543.It Ic file_queue_size 544.It Ic pipe_queue_size 545.It Ic tls_queue_size 546The maximum memory usage in bytes of messages buffered for one destination. 547Defaults are 548.Tn 1M 549for files and pipes, and 550.Tn 16M 551for TLS. 552.El 553.Pp 554Values for these options can be specified using the usual suffixes accepted by 555.Xr dehumanize_number 3 . 556.Sh SIGNING OPTIONS 557.Xr syslogd 8 558is able to digitally sign all processed messages. 559The used protocol is defined by RFC\~5848 (syslog-sign): 560at the start of a session the signing sender sends so called certificate 561blocks containing its public key; after that it periodically sends a signed 562message containing hashes of previous messages. 563.Pp 564To detect later manipulation one has to keep a copy of the key used for 565signing (otherwise an attacker could alter the logs and sign them with his 566own key). 567If TLS is used with a DSA key then the same key will be used for signing. 568This is the recommended setup because it makes it easy to have copies of 569the certificate (with the public key) in backups. 570Otherwise new keys are generated on every restart and for certain verification 571it is necessary to have copies of all used keys. 572So logging only to a local file is not secure; at least the used keys should 573be logged to another host. 574.Bl -tag -width Ic 575.It Ic sign_sg 576Enables signing. 577Set this option to enable syslog-sign and select how to assign 578messages to signature groups (subsets of messages that are signed together). 579To enable later signature verification and detection of lost messages the 580assignment should be chosen such that all messages of one signature group 581are written to the same file. 582Four possible values for this option are: 583.Bl -tag -width Ds 584.It Li 0 585Use one global signature group for all messages. 586.It Li 1 587Use one signature group per priority. 588.It Li 2 589Use signature groups for ranges of priorities. 590.It Li 3 591Use one signature group per destination. 592This is a custom strategy not defined by the standard. 593With this setting one signature group is set up for 594every file and network action. 595.El 596.It Ic sign_delim_sg2 597This option is only evaluated with 598.Ql sign_sg=2 599and allows to configure the priority ranges for signature groups. 600The parameters are numerical values used as the maximum priority for one group. 601The default is to use one signature groups per facility, which is equal to 602setting 603.Dl sign_delim_sg2=7 15 23 31 39 ... 604.El 605.Sh FILES 606.Bl -tag -width Pa 607.It Pa /etc/syslog.conf 608The 609.Xr syslogd 8 610configuration file. 611.It Pa /usr/share/examples/syslogd/verify.pl 612Example script to verify message signatures. 613.Po 614Requires Perl and modules not part of 615.Nx . 616.Pc 617.El 618.Sh EXAMPLES 619A configuration file might appear as follows: 620.Bd -literal 621# Log all kernel messages, authentication messages of 622# level notice or higher and anything of level err or 623# higher to the console. 624# Don't log private authentication messages! 625*.err;kern.*;auth.notice;authpriv.none /dev/console 626 627# Log anything (except mail) of level info or higher. 628# Don't log private authentication messages! 629*.info;mail.none;authpriv.none /var/log/messages 630 631# Log daemon messages at debug level only 632daemon.=debug /var/log/daemon.debug 633 634# The authpriv file has restricted access. 635# Write logs with priority for later verification with syslog-sign. 636authpriv.* +/var/log/secure 637 638# Log all the mail messages in one place. 639mail.* /var/log/maillog 640 641# Everybody gets emergency messages, plus log them on another 642# machine. 643*.emerg * 644*.emerg @arpa.berkeley.edu 645 646# Log all messages of level info or higher to another 647# machine using TLS with an alternative portname and a 648# fingerprint for authentication 649*.info @[logserver]:1234(fingerprint="SHA1:01:02:...") 650 651# Root and Eric get alert and higher messages. 652*.alert root,eric 653 654# Save mail and news errors of level err and higher in a 655# special file. 656mail,news.err /var/log/spoolerr 657 658# Pipe all authentication messages to a filter. 659auth.* |exec /usr/local/sbin/authfilter 660 661# Log kernel messages to a separate file without syncing each message. 662kern.* -/var/log/kernlog 663 664# Save ftpd transactions along with mail and news. 665!ftpd 666*.* /var/log/spoolerr 667 668# Send all error messages from a RAID array through a filter. 669!raid0 670kern.err |exec /usr/local/sbin/raidfilter 671 672# Save pppd messages from dialhost to a separate file. 673!pppd 674+dialhost 675*.* /var/log/dialhost-pppd 676 677# Save non-local log messages from all programs to a separate file. 678!* 679-@ 680*.* /var/log/foreign 681 682# Generate digital signatures for all messages 683# to each file or network destination. 684sign_sg=3 685.Ed 686.Sh SEE ALSO 687.Xr syslog 3 , 688.Xr syslogd 8 689.Sh HISTORY 690The 691.Nm 692file appeared in 693.Bx 4.3 , 694along with 695.Xr syslogd 8 . 696.Sh BUGS 697The effects of multiple selectors are sometimes not intuitive. 698For example 699.Ql mail.crit;*.err 700will select 701.Ql mail 702facility messages at 703the level of 704.Ql err 705or higher, not at the level of 706.Ql crit 707or higher. 708