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
mailsubsystem 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), andlocal0throughlocal7(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), andemerg(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 keywordnoneserves 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 prioritycritand higher, use this form:mail.crit
To select all cron syslog messages except those with theinfoordebugpriority, 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
timegeneratedorsyslogtag. For more information on properties, see the section called “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 containsChecks whether the provided string matches any part of the text provided by the property. To perform case-insensitive comparisons, use contains_i.isequalCompares the provided string against all of the text provided by the property. These two values must be exactly equal to match. startswithChecks 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.regexCompares the provided POSIX BRE (Basic Regular Expression) against the text provided by the property. ereregexCompares the provided POSIX ERE (Extended Regular Expression) regular expression against the text provided by the property. isemptyChecks 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 stringerrorin their message text, use::msg, contains, "error"
The following filter selects syslog messages received from the host namehost1::hostname, isequal, "host1"
To select syslog messages which do not contain any mention of the wordsfatalanderrorwith 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 usingandandoroperators. - 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 functionsre_match()andre_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 the section called “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”
