SYSLOG.CONF(5)

NAME
syslog.conf - configuration file format for syslogd(8)

DESCRIPTION
The syslog.conf file is the configuration file for the syslogd(8) program. It consists of lines of rules for logging, with each line containing at least two fields: the selector field which specifies the types of messages and priorities to which the line applies, and an action field which specifies the action to be taken if a message syslogd(8) receives matches the selection criteria. A rule may also have an option field for a setting that applies only to that rule.

The fields are separated by one or more tab characters or spaces. A rule may be divided into several lines if the leading line ends with a single backslash ('\') character.

    RULE     := SELECTOR  ACTION  [;OPTION]
    SELECTOR := [SELECTOR;]facility[,facility].[!=]severity
    ACTION   := /path/to/file
             |= |/path/to/named/pipe
    	 |= @remote[.host.tld][:PORT]
    OPTION   := [OPTION,]
    	 |= RFC3164
    	 |= RFC5424
             |= rotate=SIZE:COUNT
    secure_mode [0,1,2]
    include /etc/syslog.d/*.conf
    notify  /path/to/script-on-rotate

The selector field specifies a pattern of facilities and priorities belonging to the specified action. The action details where or what to do with the selected input. The option field, which must start with the semi-colon option delimiter (';'), currently supports log formatting and log rotation. The default log format is the traditional RFC3164 (included here for completeness), except for remote syslog targets where the BSD format (without both timestamp and hostname) is the default. The user must explicitly set RFC3164 on a remote logging target. RFC5424 is the newest format with RFC3339 time stamps, msgid, structured data, and more. The BSD format cannot be set, it is only the default for remote targets for compatibility reasons.

BSD:
    myproc[8710]: Kilroy was here.
RFC3164:
    Aug 24 05:14:15 192.0.2.1 myproc[8710]: Kilroy was here.
RFC5424:
    2003-08-24T05:14:15.000003-07:00 192.0.2.1 myproc 8710 - - Kilroy was here.

The log rotation, which is only relevant for files, details the max SIZE:COUNT a file can reach before it is rotated, and later compressed. This feature is mostly intended for embedded systems that do not want to have cron or a separate log rotate daemon.

Comments, lines starting with a hash mark ('#'), and empty lines are ignored. If an error occurs during parsing the whole line is ignored.

Additional options include ‘secure_mode <0-2>’ which is the same as the syslogd -s commandline option. Note: command line option always wins, so you need to drop -s from the command line to use this .conf file option instead.

0   act as a syslog sink, listening on UDP port 514 by default, as well as support for sending to remote syslog servers
1   only support for sending to remote syslog servers, no Internet ports open
2   no Internet ports open at all, and no remote logging possible

    # Example: only allow logging to remote servers
    secure_mode 1

The ‘notify <PATH>’ option specifies the path to an executable program which will get called whenever a log file has been rotated, with the name of the file, less its rotation suffix ‘.0’, as an argument. For example: ‘notify /sbin/on-log-rotate.sh’. Any number of notifiers may be installed.

The ‘include <PATH/*.conf>’ option can be used to include all files with names ending in '.conf' and not beginning with a '.' contained in the directory following the keyword. This keyword can only be used in the first level configuration file. The included example /etc/syslog.conf has the following at the end:

    #
    # Drop your subsystem .conf file in /etc/syslog.d/
    #
    include /etc/syslog.d/*.conf

Note that if you use spaces as separators, your syslog.conf might be incompatible with other Unices or Unix-like systems. This functionality was added for ease of configuration (e.g. it is possible to cut-and-paste into syslog.conf), and to avoid possible mistakes. This change however preserves backwards compatibility with the old style of syslog.conf (i.e., tab characters only).

SELECTORS
The selector field consists of two parts, a facility and a priority, separated by a period ('.'). Both parts are case insensitive and can also be specified as decimal numbers corresponding to the definitions in /usr/include/syslog.h. It is safer to use symbolic names rather than decimal numbers. Both facilities and priorities are described in syslogp(3). The names mentioned below correspond to the similar ‘LOG_FOO’ values in /usr/include/syslog.h.

The facility is one of the following keywords:
Code | Facility | Description
0 | kern | Kernel log messages
1 | user | User-level messages
2 | mail | Mail system
3 | daemon | General system daemons
4 | auth | Security/authorization messages
5 | syslog | Messages generated by syslogd
6 | lpr | Line printer subsystem
7 | news | Network news subsystem
8 | uucp | UNIX-to-UNIX copy
9 | cron | Clock/cron daemon (BSD, Linux)
10 | authpriv | Security/authorization messages (private)
11 | ftp | FTP daemon
12 | ntp | NTP subsystem
13 | security | Log audit
14 | console | Log alert
15 | unused | Clock/cron daemon (Solaris)
16 | local0 | Reserved for local/system use
17 | local1 | Reserved for local/system use
18 | local2 | Reserved for local/system use
19 | local3 | Reserved for local/system use
20 | local4 | Reserved for local/system use
21 | local5 | Reserved for local/system use
22 | local6 | Reserved for local/system use
23 | local7 | Reserved for local/system use

Notice, several of the above listed facilities are not supported by the standard C library (GLIBC, musl libc, or uClibc) on Linux. libsyslog, shipped with sysklogd, however, supports all the above facilities in full. Also, the keyword ‘mark’ is only for internal use and should therefore not be used in applications. The facility specifies the subsystem that produced the message, e.g. all mail programs log with the mail facility, ‘LOG_MAIL’, if they log using syslog.

In most cases anyone can log to any facility, so we rely on convention for the correct facility to be chosen. However, generally only the kernel can log to the ‘kern’ facility. This because the implementation of openlog(3) and syslog(3) in GLIBC does not allow logging to the ‘kern’ facility.

The priority is one of the following keywords, in ascending order:
Value | Severity | Description
0 | emergency | System is unusable
1 | alert | Action must be taken immediately
2 | critical | Critical conditions
3 | error | Error conditions
4 | warning | Warning conditions
5 | notice | Normal but significant conditions
6 | info | Informational messages
7 | debug | Debug-level messages

The default log level of most applications is ‘notice’, meaning only ‘notice’ and above are forwarded to syslogd. See setlogmask(3) for more information on how to change the default log level of your application.

In addition to the above mentioned facility and priority names, syslogd(8) understands the following extensions:

*   An asterisk ('*') matches all facilities or all priorities, depending on where it is used (before or after the period).
none
    The keyword ‘none’ stands for no priority of the given facility.
,   Multiple facilities may be specified for a single priority pattern in one statement using the comma (',') operator to separate the facilities. You may specify as many facilities as you want. Please note that only the facility part from such a statement is taken, a priority part would be ignored.
;   Multiple selectors may be specified for a single action using the semicolon (';') separator. Selectors are processed from left to right, with each selector being able to overwrite preceding ones. Using this behavior you are able to exclude some priorities from the pattern.
=   This version of syslogd(8) has a syntax extension to the original BSD source, which makes its use more intuitive. You may precede every priority with an equation sign ('=') to specify that only this single priority should be matched, instead of the default: this priority and all higher priorities.
!   You may also precede the priority with an exclamation mark ('!') if you want to ignore this priority and all higher priorities. You may even use both the exclamation mark and the equation sign if you want to ignore a single priority. If both extensions are used, the exclamation mark must occur before the equation sign.

ACTIONS
The action field of a rule is the destination or target for a match. It can be a file, a UNIX named pipe, the console, or a remote machine.

  Regular File
Typically messages are logged to real files. The filename is specified with an absolute path name.

You may prefix each entry with a minus sign ('-') to avoid syncing the file after each log message. Note that you might lose information if the system crashes right after a write attempt. Nevertheless this might give you back some performance, especially if you run programs that use logging in a very verbose manner.

  Named Pipes
This version of syslogd(8) supports logging to named pipes (FIFOs). A FIFO, or named pipe, can be used as a destination for log messages by prepending a pipe symbol ('|') to the name of the file. This can be very handy for debugging. Note that the FIFO must be created with the mkfifo(1) command before syslogd is started.

  Terminal and Console
If the file you specified is a tty, special tty-handling is done, same with /dev/console.

  Remote Machine
Full remote logging support is available in syslogd, i.e. to send messages to a remote syslog server, and and to receive messages from remote hosts. To forward messages to another host, prepend the hostname with the at sign ('@'). If a port number is added after a colon (':') then that port will be used as the destination port rather than the usual syslog port.

This feature makes it possible to collect all syslog messages in a network on a central host. This reduces administration needs and can be really helpful when debugging distributed systems.

Using a named pipe log method, messages from remote hosts can be sent to a log program. By reading log messages line by line such a program is able to sort log messages by host name or program name on the central log host. This way it is possible to split the log into separate files.

By default messages to remote remote hosts were formatted in the original BSD style, without timestamp or hostname. As of syslogd v2.0 the default includes timestamp and hostname. It is also possible to enable the new RFC5424 style formatting, append ';RFC5424' after the hostname.

  List of Users
Usually critical messages are also directed to ‘root’ on that machine. You can specify a list of users that ought to receive the log message on their terminal by writing their usernames. You may specify more than one user by separating the usernames with commas (','). Only logged in users will receive the log messages.

  Everyone logged on
Emergency messages often go to all users currently online to notify them that something strange is happening with the system. To specify this wall(1) feature use an asterisk ('*').

IMPLEMENTATION NOTES
The “kern” facility is usually reserved for messages generated by the local kernel. Other messages logged with facility “kern” are usually translated to facility “user”. This translation can be disabled; see syslogd(8) for details.

FILES
/etc/syslog.conf
    syslogd(8) configuration file
/etc/syslog.d/*.conf
    Recommended directory for .conf snippets

EXAMPLES
This section lists some examples, partially from actual site setups.

  Catch Everything
This example matches all facilities and priorities and stores everything in the file /var/log/syslog in RFC5424 format. Every time the file reaches 10 MiB it is rotated and five files in total are kept, including the non-rotated file.

    # Match all log messages, store in RC5424 format and rotate every 10 MiB
    #
    *.*                          /var/log/critical    ;rotate=10M:5,RFC5424

  Critical
This stores all messages of priority ‘crit’ in the file /var/log/critical, with the exception of any kernel messages.

    # Store critical stuff in critical
    #
    *.=crit;kern.none            /var/log/critical

  Kernel
This is an example of the 2nd selector overwriting part of the first one. The first selector selects kernel messages of priority ‘info’ and higher. The second selector filters out kernel messages of priority ‘error’ and higher. This leaves just priorities ‘info’, ‘notice’, and ‘warning’ to get logged.

    # Kernel messages are stored in the kernel file, critical messages and
    # higher ones also go to another host and to the console
    #
    kern.*                       /var/log/kernel
    kern.crit                    @arpa.berkeley.edu   ;RFC5424
    kern.crit                    /dev/console
    kern.info;kern.!err          /var/log/kernel.info

The first rule directs any message that has the kernel facility to the file /var/log/kernel. Recall that only the kernel itself can log to this facility.

The second statement directs all kernel messages of priority ‘crit’ and higher to the remote host ‘arpa.berkeley.edu’ in RFC5424 style formatting. This is useful, because if the host crashes and the disks get irreparable errors you might not be able to read the stored messages. If they're on a remote host, too, you still can try to find out the reason for the crash.

The third rule directs kernel messages of priority ‘crit’ and higher to the actual console, so the person who works on the machine will get them, too.

The fourth line tells syslogd to save all kernel messages that come with priorities from ‘info’ up to ‘warning’ in the file /var/log/kernel.info.

  Redirecting to a TTY
This directs all messages that use ‘mail.info’ (in source ‘LOG_MAIL | LOG_INFO’) to /dev/tty12, the 12th console. For example the tcpwrapper tcpd(8) uses this as its default.

    # The tcp wrapper logs with mail.info, we display
    # all the connections on tty12
    #
    mail.=info                   /dev/tty12

  Redirecting to a file
This pattern matches all messages that come with the ‘mail’ facility, except for the ‘info’ priority. These will be stored in the file /var/log/mail.

    # Write all mail related logs to a file
    #
    mail.*;mail.!=info           /var/log/mail

  Single Priority from Two Facilities
This will extract all messages that come either with ‘mail.info’ or with ‘news.info’ and store them in the file /var/log/info.

    # Log all mail.info and news.info messages to info
    #
    mail,news.=info              /var/log/info

  Advanced Filtering, part 1
This logs all messages that come with either the ‘info’ or the ‘notice’ priority into the file /var/log/messages, except for all messages that use the ‘mail’ facility.

    # Log info and notice messages to messages file
    #
    *.=info;*.=notice;\
    	mail.none            /var/log/messages

  Advanced Filtering, part 2
This statement logs all messages that come with the ‘info’ priority to the file /var/log/messages. But any message with either ‘mail’ or the ‘news’ facility are not logged.

    # Log info messages to messages file
    #
    *.=info;\
    	mail,news.none       /var/log/messages

  Wall Messages
This rule tells syslogd to write all emergency messages to all currently logged in users. This is the wall action.

    # Emergency messages will be displayed using wall
    #
    *.=emerg                     *

  Alerting Users
This rule directs all messages of priority ‘alert’ or higher to the terminals of the operator, i.e. of the users 'root' and 'eric', if they're logged in.

    # Any logged in root user and Eric get alert and higher messages.
    #
    *.alert                      root,eric

  Log Rotation
This example logs all messages except kernel messages to the file /var/log/messages without syncing ('-') the file after each log message. When the file reaches 100 kiB it is rotated. In total are only 10 rotated files, including the main file itself and compressed files kept. The size argument takes the same modifiers as the syslogd(8) command line option, -r.

    # Log all messages, including kernel, to the messages file rotate it
    # every 100 kiB and keep up to 10 aged out, and compressed, files.
    #
    *.*;kern.none               -/var/log/messages    ;rotate=100k:10

  Logging to Remote Syslog Server
This rule redirects all messages to one remote host called ‘finlandia’, with RFC5424 style formatting, and another remote host called ‘sibelius’, but on a non-standard port and with RFC3164 formatting (i.e., including timestamp and hostname).

    *.*                          @finlandia           ;RFC5424
    *.*                          @sibelius:5514       ;RFC3164

SEE ALSO
syslog(3), syslogd(8)

BUGS
The effects of multiple selectors are sometimes not intuitive. For example “mail.crit,*.err” will select “mail” facility messages at the level of “err” or higher, not at the level of “crit” or higher.

In networked environments, note that not all operating systems implement the same set of facilities. The facilities authpriv, cron, ftp, and ntp that are known to this implementation might be absent on the target system. Even worse, DEC UNIX uses facility number 10 (which is authpriv in this implementation) to log events for their AdvFS file system.