25.3. Basic Configuration of Rsyslog

The main configuration file for rsyslog is /etc/rsyslog.conf. Here, you can specify global directives, modules, and rules that consist of filter and action parts. Also, you can add comments in the form of text following a hash sign (#).

25.3.1. Filters

A rule is specified by a filter part, which selects a subset of syslog messages, and an action part, which specifies what to do with the selected messages. To define a rule in your /etc/rsyslog.conf configuration file, define both, a filter and an action, on one line and separate them with one or more spaces or tabs.
rsyslog offers various ways to filter syslog messages according to selected properties. The available filtering methods can be divided into Facility/Priority-based, Property-based, and Expression-based filters.
Facility/Priority-based filters
The most used and well-known way to filter syslog messages is to use the facility/priority-based filters which filter syslog messages based on two conditions: facility and priority separated by a dot. To create a selector, use the following syntax:
FACILITY.PRIORITY
where:
  • FACILITY specifies the subsystem that produces a specific syslog message. For example, the mail subsystem handles all mail-related syslog messages. FACILITY can be represented by one of the following keywords (or by a numerical code): kern (0), user (1), mail (2), daemon (3), auth (4), syslog (5), lpr (6), news (7), uucp (8), cron (9), authpriv (10), ftp (11), and local0 through local7 (16 - 23).
  • PRIORITY specifies a priority of a syslog message. PRIORITY can be represented by one of the following keywords (or by a number): debug (7), info (6), notice (5), warning (4), err (3), crit (2), alert (1), and emerg (0).
    The aforementioned syntax selects syslog messages with the defined or higher priority. By preceding any priority keyword with an equal sign (=), you specify that only syslog messages with the specified priority will be selected. All other priorities will be ignored. Conversely, preceding a priority keyword with an exclamation mark (!) selects all syslog messages except those with the defined priority.
In addition to the keywords specified above, you may also use an asterisk (*) to define all facilities or priorities (depending on where you place the asterisk, before or after the comma). Specifying the priority keyword none serves for facilities with no given priorities. Both facility and priority conditions are case-insensitive.
To define multiple facilities and priorities, separate them with a comma (,). To define multiple selectors on one line, separate them with a semi-colon (;). Note that each selector in the selector field is capable of overwriting the preceding ones, which can exclude some priorities from the pattern.

Example 25.1. Facility/Priority-based Filters

The following are a few examples of simple facility/priority-based filters that can be specified in /etc/rsyslog.conf. To select all kernel syslog messages with any priority, add the following text into the configuration file:
kern.*
To select all mail syslog messages with priority crit and higher, use this form:
mail.crit
To select all cron syslog messages except those with the info or debug priority, set the configuration in the following form:
cron.!info,!debug
Property-based filters
Property-based filters let you filter syslog messages by any property, such as timegenerated or syslogtag. For more information on properties, see Section 25.3.3, “Properties”. You can compare each of the specified properties to a particular value using one of the compare-operations listed in Table 25.1, “Property-based compare-operations”. Both property names and compare operations are case-sensitive.
Property-based filter must start with a colon (:). To define the filter, use the following syntax:
:PROPERTY, [!]COMPARE_OPERATION, "STRING"
where:
  • The PROPERTY attribute specifies the desired property.
  • The optional exclamation point (!) negates the output of the compare-operation. Other Boolean operators are currently not supported in property-based filters.
  • The COMPARE_OPERATION attribute specifies one of the compare-operations listed in Table 25.1, “Property-based compare-operations”.
  • The STRING attribute specifies the value that the text provided by the property is compared to. This value must be enclosed in quotation marks. To escape certain character inside the string (for example a quotation mark (")), use the backslash character (\).

Table 25.1. Property-based compare-operations

Compare-operation Description
contains Checks whether the provided string matches any part of the text provided by the property. To perform case-insensitive comparisons, use contains_i.
isequal Compares the provided string against all of the text provided by the property. These two values must be exactly equal to match.
startswith Checks whether the provided string is found exactly at the beginning of the text provided by the property. To perform case-insensitive comparisons, use startswith_i.
regex Compares the provided POSIX BRE (Basic Regular Expression) against the text provided by the property.
ereregex Compares the provided POSIX ERE (Extended Regular Expression) regular expression against the text provided by the property.
isempty Checks if the property is empty. The value is discarded. This is especially useful when working with normalized data, where some fields may be populated based on normalization result.

Example 25.2. Property-based Filters

The following are a few examples of property-based filters that can be specified in /etc/rsyslog.conf. To select syslog messages which contain the string error in their message text, use:
:msg, contains, "error"
The following filter selects syslog messages received from the host name host1:
:hostname, isequal, "host1"
To select syslog messages which do not contain any mention of the words fatal and error with any or no text between them (for example, fatal lib error), type:
:msg, !regex, "fatal .* error"
Expression-based filters
Expression-based filters select syslog messages according to defined arithmetic, Boolean or string operations. Expression-based filters use rsyslog's own scripting language called RainerScript to build complex filters.
The basic syntax of expression-based filter looks as follows:
if EXPRESSION then ACTION else ACTION
where:
  • The EXPRESSION attribute represents an expression to be evaluated, for example: $msg startswith 'DEVNAME' or $syslogfacility-text == 'local0'. You can specify more than one expression in a single filter by using and and or operators.
  • The ACTION attribute represents an action to be performed if the expression returns the value true. This can be a single action, or an arbitrary complex script enclosed in curly braces.
  • Expression-based filters are indicated by the keyword if at the start of a new line. The then keyword separates the EXPRESSION from the ACTION. Optionally, you can employ the else keyword to specify what action is to be performed in case the condition is not met.
With expression-based filters, you can nest the conditions by using a script enclosed in curly braces as in Example 25.3, “Expression-based Filters”. The script allows you to use facility/priority-based filters inside the expression. On the other hand, property-based filters are not recommended here. RainerScript supports regular expressions with specialized functions re_match() and re_extract().

Example 25.3. Expression-based Filters

The following expression contains two nested conditions. The log files created by a program called prog1 are split into two files based on the presence of the "test" string in the message.
if $programname == 'prog1' then {
   action(type="omfile" file="/var/log/prog1.log")
   if $msg contains 'test' then
     action(type="omfile" file="/var/log/prog1test.log")
   else
     action(type="omfile" file="/var/log/prog1notest.log")
}
See Section 25.10, “Online Documentation” for more examples of various expression-based filters. RainerScript is the basis for rsyslog's new configuration format, see Section 25.4, “Using the New Configuration Format”