Adding upstream version 8.2402.0+dfsg.upstream/8.2402.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.
+