diff options
Diffstat (limited to '')
| -rw-r--r-- | source/configuration/modules/omruleset.rst | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/source/configuration/modules/omruleset.rst b/source/configuration/modules/omruleset.rst new file mode 100644 index 0000000..abba0b2 --- /dev/null +++ b/source/configuration/modules/omruleset.rst @@ -0,0 +1,184 @@ +****************************************** +omruleset: ruleset output/including module +****************************************** + +=========================== =========================================================================== +**Module Name:** **omruleset** +**Author:** `Rainer Gerhards <https://rainer.gerhards.net/>`_ <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 <rainerscript_call.html>`_. 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** +:doc:`$RulesetCreateMainQueue <../ruleset/rsconf1_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 + + +|FmtObsoleteName| 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. + +.. code-block:: none + + $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. + +.. code-block:: none + + $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 <troubleshoot.html>`_ is your friend. + |