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