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, 56 insertions, 0 deletions

diff --git a/source/rainerscript/rainerscript_call.rst b/source/rainerscript/rainerscript_call.rst
new file mode 100644
index 0000000..1dc3fa3
--- /dev/null
+++ b/source/rainerscript/rainerscript_call.rst
@@ -0,0 +1,56 @@
+The rsyslog "call" statement
+============================
+
+The rsyslog "call" statement is used to tie rulesets together. It is
+modelled after the usual programming language "call" statement. Think of
+a ruleset as a subroutine (what it really is!) and you get the picture.
+
+The "call" statement can be used to call into any type of rulesets. If a
+rule set has a queue assigned, the message will be posted to that queue
+and processed asynchronously. Otherwise, the ruleset will be executed
+synchronously and control returns to right after the call when the rule
+set has finished execution.
+
+Note that there is an important difference between asynchronous and
+synchronous execution in regard to the "stop" statement. It will not
+affect processing of the original message when run asynchronously.
+
+The "call" statement replaces the deprecated omruleset module. It offers
+all capabilities omruleset has, but works in a much more efficient way.
+Note that omruleset was a hack that made calling rulesets possible
+within the constraints of the pre-v7 engine. "call" is the clean
+solution for the new engine. Especially for rulesets without associated
+queues (synchronous operation), it has zero overhead (really!).
+omruleset always needs to duplicate messages, which usually means at
+least ~250 bytes of memory writes, some allocs and frees - and even more
+performance-intense operations.
+
+
+syntax
+------
+
+``call rulesetname``
+
+Where "rulesetname" is the name of a ruleset that is defined elsewhere
+inside the configuration. If the call is synchronous or asynchronous
+depends on the ruleset parameters. This cannot be overridden by the
+"call" statement.
+
+compatibility notes
+-------------------
+Note that versions prior to 8.2110.0 had a bug where an explicit
+'queue="direct"' setting in the ruleset definition lead call to treat
+this as if a real queue existed. This could lead to some unexpected
+behaviour. Beginning with 8.2110.0 this is handled consistently and
+correctly.
+
+Under some exotic circumstances, this may look like a change of
+behavior. If so, consider adding a small array-based queue to the
+ruleset in question.
+
+related links
+-------------
+
+-  `Blog posting announcing "call" statement (with
+   sample) <https://rainer.gerhards.net/2012/10/how-to-use-rsyslogs-ruleset-and-call.html>`_
+