Note: rsyslog has changed significantly in the last few years, effectively introducing a programming-language interface into the configuration file and giving the administrator much finer control over log messages. We won't cover these features due to time and due to the pre-emption of logging responsibilities by systemd-journald.

As discussed in the Introduction, the rsyslog package provides a consistent framework for logging system messages. Messages are received by the rsyslog daemon, rsyslogd, through a local socket or through a network port, if the message was logged remotely. Once the message is received, rsyslogd must decide what to do with it. This is the traditional purpose of the configuration file /etc/syslog.conf and this section of the new file /etc/rsyslog.conf (called the rules section) has the same format and syntax as the traditional syslog.conf file. We will cover the rules section of rsyslog.conf later in this section.

The rsyslog.conf file has sections that were not in the traditional syslog.conf. These sections usually appear first in the file. We will cover only the global directives section, which is divided into two parts:

• the module directives. rsyslogd is modular, and capabilities are enabled by loading modules. Traditionally, these capabilities were either always on, or were controlled by arguments given to syslogd when it was started. The arguments were kept in an /etc/sysconfig file for syslog. (This file, now rsyslogd, appears for compatibility only.)
  
• other global directives. This includes all directives other than modules or their support directives.
  

Unfortunately, this has become so complex with the recent release that a complete discussion is beyond our scope (and beyond mine at this writing.) We will, however, introduce the two directives sections so that we can use the most interesting rsyslogd feature, remote logging.

Although the directives to enable remote logging are covered here, remote logging will be covered more completely in a later section in this module.

Important Notes:

• The usual mechanism for getting a daemon to reread its configuration file is to send the daemon a HUP signal. A HUP signal will only cause rsyslogd to close and reopen its log files. If you modify its configuration file you should restart the daemon using service.
• rsyslog has introduced the use of a configuration directory /etc/rsyslog.d. File with the extension .conf in this directory are included by rsyslog.conf. The include happens between the modules/templates section and the rules section. Thus the included files can have modules and templates as well as rules. Create a .conf file in this directory if possible and avoid modifying rsyslog.conf itself. Note that this is only possible if you want to add modules and rules. If you need to modify existing rules or delete current modules you must still modify rsyslog.conf.
  

Module directives

To enable a module, use the directive

$Modload modname.so

where modname is one of the module names listed below. There are several modules that should always be loaded, and a few that are of interest in our brief look at rsyslogd. Modules are classified as input, output, or library. We will only cover a few modules, and they are all input modules:

There are many more modules. The interested reader is referred to the documentation in /usr/share/doc. As indicated, you should definitely have the first two modules loaded, as well as either of the other two, if you want to allow rsyslogd to log remote messages. (Note: this means rsyslogd will log the message on the local machine. The event occurred on a remote machine.) Again, although the directives to enable remote logging are covered here, remote logging will be covered more completely in a later section.

Other directives

The only other directives we will cover are those that specify the output of log messages. Traditional syslog had a standard format for logging messages - rsyslog provides for the specification of message templates so that the administrator can log messages as she prefers. The two directives we will cover set rsyslogd's format for logging local and remote messages.

Most templates are user-defined. However, if the template name starts with RSYSLOG_, the template name is reserved for an internal rsyslog template. The two that we are interested in are

RSYSLOG_TraditionalFileFormat  - the traditional format for local messages

RSYSLOG_TraditionalForwardFormat - the traditional format for messages forwarded to a remote machine. (Note: using this strangely duplicates the hostname when forwarding to a machine running sysklogd.)

#### MODULES ####

$ModLoad imuxsock.so   

$ModLoad imklog.so   
#$ModLoad immark.so   

# Provides UDP syslog reception
#$ModLoad imudp.so
#$UDPServerRun 514

# Provides TCP syslog reception
#$ModLoad imtcp.so 
#$InputTCPServerRun 514


#### GLOBAL DIRECTIVES ####

# Use default timestamp format
$ActionFileDefaultTemplate RSYSLOG_TraditionalFileFormat

#$ActionFileEnableSync on

As you can see, many of them are commented out. Since this version of rsyslog does not accept log messages from another machine (remote logging), no servers are started on either a UDP or TCP port. In addition, there is no $ActionForwardDefaultTemplate, so it will use the new rsyslog message format when forwarding messages to a remote machine.

The rules section

This section configures which messages get logged where. To begin with, let's look at the format of an rsyslog message. Each message consists of the message text itself, a tag, and two values used to classify the message:

• the facility. This indicates the type of message. Currently known facilities are auth, authpriv, cron, daemon, kern, lpr, mail, news, syslog, user, uucp, and local0 through local7. Of these, a few need description
• the difference between auth and authpriv is whether the authentication message is secure or not.
• the kern facility is used by the imklog module when it translates a kernel log message and gives it to syslogd for logging
• mark is used to time-stamp the log file. By default, syslog outputs a mark message to the general log file at intervals.
• the local0 through local7 facilities are reserved for the user.
• the priority indicates the severity of the message. Priorities are ordered. From lowest to highest priority they are debug, info, notice, warning, err, crit, alert, emerg.

The /etc/syslog.conf file consists of multiple rules. Each rule is one or more lines. Rules that continue to a second or later line must have their newlines escaped. The format is simply two fields separated by whitespace:

selector         action

Where selector is a list of facility priority specifiers in the format facility.priority, and action is the destination for the log message. Each message whose facility matches that of the selector and whose priority is at least as high as the priority in the selector, is logged to the destination. For example, the rule below

authpriv.info    /var/log/secure

logs all messages with the facility authpriv and the priority info or higher in the log file /var/log/secure.

Lines starting with # and empty lines are ignored.

More complex selectors

Complete control over which facility.priority combinations result in an action is provided by additional syntax:

• facility1,facility2,facility3.priority indicates the same priority for each facility. The rule matches messages with any of the given facilities (and with priority at least as high) as that indicated.

• * in either the facility or priority position matches all possible values. Thus, mail.* and mail.debug are the same. 

• none as a priority indicates no priorities match.

• if the priority is prefixed by =, only that priority exactly matches. Thus mail.=err only matches mail messages with the priority err. Normally mail messages with priority err or higher would match.

• if the priority is prefixed by !=, that priority only is excluded. If the priority is prefixed by !, that priority and all higher priorities are excluded.

• facility1.priority1;facility2.priority2 The rule matches messages just like two separate rules with the same action. Here, the selectors may overlap, with later selectors modifying earlier ones. This allows the use of the *, =, or ! modifiers above to select exactly the facility.priority combinations you want.
  

Examples

Suppose you want two logs of mail messages. You want info messages to go to /var/log/mail.info and all other mail messages to go to /var/log/mail. This could be accomplished by the two rsyslog.conf lines below:

mail.*;mail.!=info    /var/log/mail

mail.=info    /var/log/mail.info

We want to log all messages of info level or higher in /var/log/messages, except kern messages:

*.info;kern.none    /var/log/messages

As discussed previously, these configuration changes should be placed in a new file in /etc/rsyslog.d, and rsyslog restarted.

action syntax

The action is normally a file, in which case it must have an absolute path. The file is normally synced (flushed) after the message has been written. (Note: this was the default behavior with sysklogd. rsyslogd evidently has turned off this behavior, but put it under control of the $ActionFileEnableSync directive.)

Other syntax includes

• if the path to the log file is prefixed with a dash the logfile is not synced after each message. Note that this is the default with rsyslogd anyway, and can be countered with the $ActionFileEnableSync directive. If the default (not syncing) is left in place, messages may be lost if there is a system crash, but read the messages about $ActionFileEnableSync on the Internet before you add it. It may be a serious performance hit.
  

• the action may be a tty device path, or /dev/console to write the logfile to a specified tty

• the action may be a user name to write the message to the terminal of the specified user if they are logged in

• if the action is *, the message is broadcast as a wall message.

• the action may indicate a domain name or IP address of another machine, prefixed with @. This is a request for rsyslog to log the message remotely to that machine. Remote logging is discussed in the section on Security Issues.

More examples

The rsyslog.conf(5) man page on linux has many additional examples. Check it out.

Copyright 2015 Greg Boyd - All Rights Reserved.