diff options
Diffstat (limited to '')
| -rw-r--r-- | source/configuration/ruleset/rsconf1_rulesetparser.rst | 127 |
1 files changed, 127 insertions, 0 deletions
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. + |