A Basic Introduction to Rsyslog Filters

Property-based filters

Property based filters allow you to filter syslog messages using syslog properties such as hostname, msg, timegenerated or sysylogtag. Specified property value can be compared to one of the compare-operations described below.

Property-based filter must start with a colon (:). To define the filter, use the following syntax:

:property, [!]compare-operation, "value"

The optional exclamation point (!) negates the output of the compare-operation. Other Boolean operators are currently not supported in property-based filters.

Property-based Properties

Some of the commonly used rsyslog properties include:

• msg – the MSG part of the message.
• hostname – hostname from the message
• source – alias for HOSTNAME
• timegenerated – timestamp when the message was RECEIVED. Always in high resolution
• fromhost – hostname of the system the message was received from.
• fromhost-ip – The same as fromhost, but always as an IP address.
• syslogtag- TAG from the message
• programname – the “static” part of the tag, as defined by BSD syslogd. For example, when TAG is “named[12345]”, programname is “named”.

For a comprehensive list and description all currently-supported properties, you can check ryslog properties.

Property-based Compare-Operations

Some of the property-based compare operations include;

• contains – Checks if the string provided in value is contained in the property. There must be an exact match, wildcards are not supported. A case insensitive option is contains_i.
• isequal – Compares the “value” string provided and the property contents. These two values must be exactly equal to match. isequal is most useful for fields like syslogtag or FROMHOST, where you probably know the exact contents.
• startswith – Checks if the value is found exactly at the beginning of the property value. For example, if you search for “val” with :msg, startswith, "val" it will be a match if msg contains “values are in this message” but it won’t match if the msg contains “There are values in this message”. To perform case insensitive comparisons, use startswith_i.
• regex – Compares the property against the provided POSIX BRE regular expression.
• ereregex – Compares the property against the provided POSIX ERE regular expression.
• isempty – Checks if the property is empty.

To select syslog messages which contain the string error in their message text;

:msg, contains, "error"

The following filter selects syslog messages received from the host name test.example.com:

:hostname, isequal, "test.example.com"

To write all messages including messages with string error to a log file, /var/log/all-msgs-with-error.log and then write all messages without the string error to aall-msgs-with-error.log

*.* /var/log/all-msgs-with-error.log
:msg, contains, "error"  ~
*.* /var/log/all-msgs-without-error.log

The tilde on line 2 discards any message with string error.

Expression-based filters

Expression based filters allow filtering on arbitrary complex expressions, which can include boolean, arithmetic and string operations.

These 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

• “if” and “then” are fixed keywords that mus be present.
• 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 Examples

To log messages that contains an string error in a log file called /var/log/errors.log;

if $msg contains 'error' then /var/log/errors.log

To split  the log file created by progA into two files based on the presence of the “informational” string in the messages;

if $programname == 'progA' then {
   action(type="omfile" file="/var/log/progA.log")
   if $msg contains 'informational' then
     action(type="omfile" file="/var/log/progAinfo.log")
   else
     action(type="omfile" file="/var/log/progAnoinfo.log")
}

That is all about rsyslog filters. Hope you found this helpful.

In our next tutorial, we will learn about introduction to rsyslog actions and templates configuration.