summaryrefslogtreecommitdiffstats
path: root/source/configuration/modules/omruleset.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--source/configuration/modules/omruleset.rst184
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.
+