Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

25.4. Using the New Configuration Format

In rsyslog version 7, available for Red Hat Enterprise Linux 6 in the rsyslog7 package, a new configuration syntax is introduced. This new configuration format aims to be more powerful, more intuitive, and to prevent common mistakes by not permitting certain invalid constructs. The syntax enhancement is enabled by the new configuration processor that relies on RainerScript. The legacy format is still fully supported and it is used by default in the /etc/rsyslog.conf configuration file. To install rsyslog 7, see Section 25.1.1, “Upgrading to rsyslog version 7”.
RainerScript is a scripting language designed for processing network events and configuring event processors such as rsyslog. The version of RainerScript in rsyslog version 5 is used to define expression-based filters, see Example 25.3, “Expression-based Filters”. The version of RainerScript in rsyslog version 7 implements the input() and ruleset() statements, which permit the /etc/rsyslog.conf configuration file to be written in the new syntax. The new syntax differs mainly in that it is much more structured; parameters are passed as arguments to statements, such as input, action, template, and module load. The scope of options is limited by blocks. This enhances readability and reduces the number of bugs caused by misconfiguration. There is also a significant performance gain. Some functionality is exposed in both syntaxes, some only in the new one.
Compare the configuration written with legacy-style parameters: 
$InputFileName /tmp/inputfile
$InputFileTag tag1:
$InputFileStateFile inputfile-state
$InputRunFileMonitor
and the same configuration with the use of the new format statement: 
input(type="imfile" file="/tmp/inputfile" tag="tag1:" statefile="inputfile-state")
This significantly reduces the number of parameters used in configuration, improves readability, and also provides higher execution speed. For more information on RainerScript statements and parameters see the section called “Online Documentation”.

25.4.1. Rulesets

Leaving special directives aside, rsyslog handles messages as defined by rules that consist of a filter condition and an action to be performed if the condition is true. With a traditionally written /etc/rsyslog.conf file, all rules are evaluated in order of appearance for every input message. This process starts with the first rule and continues until all rules have been processed or until the message is discarded by one of the rules.
However, rules can be grouped into sequences called rulesets. With rulesets, you can limit the effect of certain rules only to selected inputs or enhance the performance of rsyslog by defining a distinct set of actions bound to a specific input. In other words, filter conditions that will be inevitably evaluated as false for certain types of messages can be skipped. The legacy ruleset definition in /etc/rsyslog.conf can look as follows: 
$RuleSet rulesetname
rule
rule2
The rule ends when another rule is defined, or the default ruleset is called as follows: 
$RuleSet RSYSLOG_DefaultRuleset
With the new configuration format in rsyslog 7, the input() and ruleset() statements are reserved for this operation. The new format ruleset definition in /etc/rsyslog.conf can look as follows: 
ruleset(name="rulesetname") { 
      rule
      rule2
      call rulesetname2
      … 
}
Replace rulesetname with an identifier for your ruleset. The ruleset name cannot start with RSYSLOG_ since this namespace is reserved for use by rsyslog. RSYSLOG_DefaultRuleset then defines the default set of rules to be performed if the message has no other ruleset assigned. With rule and rule2 you can define rules in filter-action format mentioned above. With the call parameter, you can nest rulesets by calling them from inside other ruleset blocks.
After creating a ruleset, you need to specify what input it will apply to: 
input(type="input_type" port="port_num" ruleset="rulesetname");
Here you can identify an input message by input_type, which is an input module that gathered the message, or by port_num – the port number. Other parameters such as file or tag can be specified for input(). Replace rulesetname with a name of the ruleset to be evaluated against the message. In case an input message is not explicitly bound to a ruleset, the default ruleset is triggered.
You can also use the legacy format to define rulesets, for more information see the section called “Online Documentation”.

Example 25.11. Using rulesets

The following rulesets ensure different handling of remote messages coming from different ports. Add the following into /etc/rsyslog.conf: 
ruleset(name="remote-6514") {
    action(type="omfile" file="/var/log/remote-6514")
}

ruleset(name="remote-601") {
    cron.* action(type="omfile" file="/var/log/remote-601-cron")
    mail.* action(type="omfile" file="/var/log/remote-601-mail")
}

input(type="imtcp" port="6514" ruleset="remote-6514");
input(type="imtcp" port="601" ruleset="remote-601");
Rulesets shown in the above example define log destinations for the remote input from two ports, in case of port 601, messages are sorted according to the facility. Then, the TCP input is enabled and bound to rulesets. Note that you must load the required modules (imtcp) for this configuration to work.