omruleset: ruleset output/including module

Module Name:

omruleset

Author:

Rainer Gerhards <rgerhards@adiscon.com>

Warning

This module is outdated and only provided to support configurations that already use it. Do no longer use it in new configurations. It has been replaced by the much more efficient “call” RainerScript statement. The “call” statement supports everything omruleset does, but in an easier to use way.

Available Since: 5.3.4

Deprecated in: 7.2.0+

Purpose

This is a very special “output” module. It permits to pass a message object to another rule set. While this is a very simple action, it enables very complex configurations, e.g. it supports high-speed “and” conditions, sending data to the same file in a non-racy way, include-ruleset functionality as well as some high-performance optimizations (in case the rule sets have the necessary queue definitions).

While it leads to a lot of power, this output module offers seemingly easy functionality. The complexity (and capabilities) arise from how everything can be combined.

With this module, a message can be sent to processing to another ruleset. This is somewhat similar to a “#include” in the C programming language. However, one needs to keep on the mind that a ruleset can contain its own queue and that a queue can run in various modes.

Note that if no queue is defined in the ruleset, the message is enqueued into the main message queue. This most often is not optimal and means that message processing may be severely deferred. Also note that when the ruleset’s target queue is full and no free space can be acquired within the usual timeout, the message object may actually be lost. This is an extreme scenario, but users building an audit-grade system need to know this restriction. For regular installations, it should not really be relevant.

At minimum, be sure you understand the $RulesetCreateMainQueue directive as well as the importance of statement order in rsyslog.conf before using omruleset!

Recommended Use:

  • create rulesets specifically for omruleset

  • create these rulesets with their own main queue

  • decent queueing parameters (sizes, threads, etc) should be used for the ruleset main queue. If in doubt, use the same parameters as for the overall main queue.

  • if you use multiple levels of ruleset nesting, double check for endless loops - the rsyslog engine does not detect these

obsolete legacy directives

Note

Parameter names are case-insensitive.

  • $ActionOmrulesetRulesetName ruleset-to-submit-to This directive specifies the name of the ruleset that the message provided to omruleset should be submitted to. This ruleset must already have been defined. Note that the directive is automatically reset after each :omruleset: action and there is no default. This is done to prevent accidental loops in ruleset definition, what can happen very quickly. The :omruleset: action will NOT be honored if no ruleset name has been defined. As usual, the ruleset name must be specified in front of the action that it modifies.

Examples

Ruleset for Write-to-file action

This example creates a ruleset for a write-to-file action. The idea here is that the same file is written based on multiple filters, problems occur if the file is used together with a buffer. That is because file buffers are action-specific, and so some partial buffers would be written. With omruleset, we create a single action inside its own ruleset and then pass all messages to it whenever we need to do so. Of course, such a simple situation could also be solved by a more complex filter, but the method used here can also be utilized in more complex scenarios (e.g. with multiple listeners). The example tries to keep it simple. Note that we create a ruleset-specific main queue (for simplicity with the default main queue parameters) in order to avoid re-queueing messages back into the main queue.

$ModLoad omruleset # define ruleset for commonly written file
$RuleSet CommonAction
$RulesetCreateMainQueue on
*.* /path/to/file.log

#switch back to default ruleset
$ruleset RSYSLOG_DefaultRuleset

# begin first action
# note that we must first specify which ruleset to use for omruleset:
$ActionOmrulesetRulesetName CommonAction
mail.info :omruleset:
# end first action

# begin second action
# note that we must first specify which ruleset to use for omruleset:
$ActionOmrulesetRulesetName CommonAction
:FROMHOST, isequal, "myhost.example.com" :omruleset:
#end second action

# of course, we can have "regular" actions alongside :omrulset: actions
*.* /path/to/general-message-file.log

High-performance filter condition

The next example is used to create a high-performance nested and filter condition. Here, it is first checked if the message contains a string “error”. If so, the message is forwarded to another ruleset which then applies some filters. The advantage of this is that we can use high-performance filters where we otherwise would need to use the (much slower) expression-based filters. Also, this enables pipeline processing, in that second ruleset is executed in parallel to the first one.

$ModLoad omruleset
# define "second" ruleset
$RuleSet nested
$RulesetCreateMainQueue on
# again, we use our own queue
mail.* /path/to/mailerr.log
kernel.* /path/to/kernelerr.log
auth.* /path/to/autherr.log

#switch back to default ruleset
$ruleset RSYSLOG_DefaultRuleset

# begin first action - here we filter on "error"
# note that we must first specify which ruleset to use for omruleset:
$ActionOmrulesetRulesetName nested
:msg, contains, "error" :omruleset:
#end first action

# begin second action - as an example we can do anything else in
# this processing. Note that these actions are processed concurrently
# to the ruleset "nested"
:FROMHOST, isequal, "myhost.example.com" /path/to/host.log
#end second action

# of course, we can have "regular" actions alongside :omrulset: actions
*.* /path/to/general-message-file.log

Caveats/Known Bugs

The current configuration file language is not really adequate for a complex construct like omruleset. Unfortunately, more important work is currently preventing me from redoing the config language. So use extreme care when nesting rulesets and be sure to test-run your config before putting it into production, ensuring you have a sufficiently large probe of the traffic run over it. If problems arise, the rsyslog debug log is your friend.

See also

Help with configuring/using Rsyslog:

See also

Contributing to Rsyslog:

Copyright 2008-2023 Rainer Gerhards (Großrinderfeld), and Others.