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

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

3 files changed, 238 insertions, 0 deletions

diff --git a/source/configuration/ruleset/index.rst b/source/configuration/ruleset/index.rst
new file mode 100644
index 0000000..429e1a2
--- /dev/null
+++ b/source/configuration/ruleset/index.rst
@@ -0,0 +1,20 @@
+Ruleset-Specific Legacy Configuration Statements
+================================================
+These statements can be used to set ruleset parameters. To set
+these parameters, first use *$Ruleset*, **then** use the other
+configuration directives. Please keep in mind
+that each ruleset has a *main* queue. To specify parameter for these
+ruleset (main) queues, use the main queue configuration directives.
+
+.. toctree::
+   :glob:
+
+   *rule*
+
+-  **$Ruleset** *name* - starts a new ruleset or switches back to one
+   already defined. All following actions belong to that new rule set.
+   the *name* does not yet exist, it is created. To switch back to
+   rsyslog's default ruleset, specify "RSYSLOG\_DefaultRuleset") as the
+   name. All following actions belong to that new rule set. It is
+   advised to also read our paper on
+   :doc:`using multiple rule sets in rsyslog <../../concepts/multi_ruleset>`.
diff --git a/source/configuration/ruleset/rsconf1_rulesetcreatemainqueue.rst b/source/configuration/ruleset/rsconf1_rulesetcreatemainqueue.rst
new file mode 100644
index 0000000..16f73a6
--- /dev/null
+++ b/source/configuration/ruleset/rsconf1_rulesetcreatemainqueue.rst
@@ -0,0 +1,91 @@
+`rsyslog.conf configuration directive <rsyslog_conf_global.html>`_
+
+$RulesetCreateMainQueue
+-----------------------
+
+**Type:** ruleset-specific configuration directive
+
+**Parameter Values:** boolean (on/off, yes/no)
+
+**Available since:** 5.3.5+
+
+**Default:** off
+
+**Description:**
+
+Rulesets may use their own "main" message queue for message submission.
+Specifying this directive, **inside a ruleset definition**, turns this
+on. This is both a performance enhancement and also permits different
+rulesets (and thus different inputs within the same rsyslogd instance)
+to use different types of main message queues.
+
+The ruleset queue is created with the parameters that are specified for
+the main message queue at the time the directive is given. If different
+queue configurations are desired, different main message queue
+directives must be used **in front of** the $RulesetCreateMainQueue
+directive. Note that this directive may only be given once per ruleset.
+If multiple statements are specified, only the first is used and for the
+others error messages are emitted.
+
+Note that the final set of ruleset configuration directives specifies
+the parameters for the default main message queue.
+
+To learn more about this feature, please be sure to read about
+`multi-ruleset support in rsyslog <multi_ruleset.html>`_.
+
+**Caveats:**
+
+The configuration statement "$RulesetCreateMainQueue off" has no effect
+at all. The capability to specify this is an artifact of the legacy
+configuration language.
+
+**Example:**
+
+This example sets up a tcp server with three listeners. Each of these
+three listener is bound to a specific ruleset. As a performance
+optimization, the rulesets all receive their own private queue. The
+result is that received messages can be independently processed. With
+only a single main message queue, we would have some lock contention
+between the messages. This does not happen here. Note that in this
+example, we use different processing. Of course, all messages could also
+have been processed in the same way ($IncludeConfig may be useful in
+that case!).
+
+::
+
+  $ModLoad imtcp
+  # at first, this is a copy of the unmodified rsyslog.conf
+  #define rulesets first
+  $RuleSet remote10514
+  $RulesetCreateMainQueue on # create ruleset-specific queue
+  *.*     /var/log/remote10514
+  
+  $RuleSet remote10515
+  $RulesetCreateMainQueue on # create ruleset-specific queue
+  *.*     /var/log/remote10515
+  
+  $RuleSet remote10516
+  $RulesetCreateMainQueue on # create ruleset-specific queue
+  mail.*	/var/log/mail10516
+  &       ~
+  # note that the discard-action will prevent this messag from 
+  # being written to the remote10516 file - as usual...
+  *.*     /var/log/remote10516
+  
+  # and now define listeners bound to the relevant ruleset
+  $InputTCPServerBindRuleset remote10514
+  $InputTCPServerRun 10514
+  
+  $InputTCPServerBindRuleset remote10515
+  $InputTCPServerRun 10515
+  
+  $InputTCPServerBindRuleset remote10516
+  $InputTCPServerRun 10516
+
+
+Note the positions of the directives. With the legacy language,
+position is very important. It is highly suggested to use
+the *ruleset()* object in RainerScript config language if you intend
+to use ruleset queues. The configuration is much more straightforward in
+that language and less error-prone.
+
diff --git a/source/configuration/ruleset/rsconf1_rulesetparser.rst b/source/configuration/ruleset/rsconf1_rulesetparser.rst
new file mode 100644
index 0000000..0fb9925
--- /dev/null
+++ b/source/configuration/ruleset/rsconf1_rulesetparser.rst
@@ -0,0 +1,127 @@
+$RulesetParser
+--------------
+
+**Type:** ruleset-specific configuration directive
+
+**Parameter Values:** string
+
+**Available since:** 5.3.4+
+
+**Default:** rsyslog.rfc5424 followed by rsyslog.rfc3164
+
+**Description:**
+
+This directive permits to specify which `message
+parsers <../../concepts/messageparser.html>`_ should be used for the ruleset in
+question. It no ruleset is explicitly specified, the default ruleset is
+used. Message parsers are contained in (loadable) parser modules with
+the most common cases (RFC3164 and RFC5424) being build-in into
+rsyslogd.
+
+When this directive is specified the first time for a ruleset, it will
+not only add the parser to the ruleset's parser chain, it will also wipe
+out the default parser chain. So if you need to have them in addition to
+the custom parser, you need to specify those as well.
+
+Order of directives is important. Parsers are tried one after another,
+in the order they are specified inside the config. As soon as a parser
+is able to parse the message, it will do so and no other parsers will be
+executed. If no matching parser can be found, the message will be
+discarded and a warning message be issued (but only for the first 1,000
+instances of this problem, to prevent message generation loops).
+
+Note that the rfc3164 parser will **always** be able to parse a message
+- it may just not be the format that you like. This has two important
+implications: 1) always place that parser at the END of the parser list,
+or the other parsers after it will never be tried and 2) if you would
+like to make sure no message is lost, placing the rfc3164 parser at the
+end of the parser list ensures that.
+
+Multiple parser modules are very useful if you have various devices that
+emit messages that are malformed in various ways. The route to take then
+is
+
+-  make sure you find a custom parser for that device; if there is no
+   one, you may consider writing one yourself (it is not that hard) or
+   getting one written as part of `Adiscon's professional services for
+   rsyslog <http://www.rsyslog.com/professional-services>`_.
+-  load your custom parsers via $ModLoad
+-  create a ruleset for each malformed format; assign the custom parser
+   to it
+-  create a specific listening port for all devices that emit the same
+   malformed format
+-  bind the listener to the ruleset with the required parser
+
+Note that it may be cumbersome to add all rules to all rulesets. To
+avoid this, you can either use $Include or `omruleset <omruleset.html>`_
+(what probably provides the best solution).
+
+More information about rulesets in general can be found in
+:doc:`multi-ruleset support in rsyslog <../../concepts/multi_ruleset>`.
+
+**Caveats:**
+
+currently none known
+
+**Example:**
+
+This example assumes there are two devices emitting malformed messages
+via UDP. We have two custom parsers for them, named "device1.parser" and
+"device2.parser". In addition to that, we have a number of other devices
+sending well-formed messages, also via UDP.
+
+The solution is to listen for data from the two devices on two special
+ports (10514 and 10515 in this example), create a ruleset for each and
+assign the custom parsers to them. The rest of the messages are received
+via port 514 using the regular parsers. Processing shall be equal for
+all messages. So we simply forward the malformed messages to the regular
+queue once they are parsed (keep in mind that a message is never again
+parsed once any parser properly processed it).
+
+::
+
+  $ModLoad imudp
+  $ModLoad pmdevice1 # load parser "device1.parser" for device 1
+  $ModLoad pmdevice2 # load parser "device2.parser" for device 2
+
+  # define ruleset for the first device sending malformed data
+  $Ruleset maldev1
+  $RulesetCreateMainQueue on # create ruleset-specific queue
+  $RulesetParser "device1.parser" # note: this deactivates the default parsers
+  # forward all messages to default ruleset:
+  $ActionOmrulesetRulesetName RSYSLOG\_DefaultRuleset
+  \*.\* :omruleset:
+
+  # define ruleset for the second device sending malformed data
+  $Ruleset maldev2 $RulesetCreateMainQueue on # create ruleset-specific queue
+  $RulesetParser "device2.parser" # note: this deactivates the default parsers
+  # forward all messages to default ruleset:
+  $ActionOmrulesetRulesetName RSYSLOG\_DefaultRuleset
+  \*.\* :omruleset:
+
+  # switch back to default ruleset
+  $Ruleset RSYSLOG\_DefaultRuleset
+  \*.\* /path/to/file
+  auth.info @authlogger.example.net
+  # whatever else you usually do...
+
+  # now define the inputs and bind them to the rulesets
+  # first the default listener (utilizing the default ruleset)
+  $UDPServerRun 514
+
+  # now the one with the parser for device type 1:
+  $InputUDPServerBindRuleset maldev1
+  $UDPServerRun 10514
+
+  # and finally the one for device type 2:
+  $InputUDPServerBindRuleset maldev2
+  $UDPServerRun 10515
+
+For an example of how multiple parser can be chained (and an actual use
+case), please see the example section on the
+`pmlastmsg <pmlastmsg.html>`_ parser module.
+
+Note the positions of the directives. With the current config language,
+**sequence of statements is very important**. This is ugly, but
+unfortunately the way it currently works.
+