Use this documentation with care! It describes the outdated version 7, which was actively developed around 2014 and is considered dead by the rsyslog team.

This documentation reflects the latest update of the v7-stable branch. It describes the 7.6.8 version, which was never released. As such, it contains some content that does not apply to any released version.

To obtain the doc that properly matches your installed v7 version, obtain the doc set from your distro. Each version of rsyslog contained the version that exactly matches it.

As general advise, it is strongly suggested to upgrade to the current version supported by the rsyslog project. The current version can always be found on the right-hand side info box on the rsyslog web site.

Note that there is only limited rsyslog community support available for the outdated v7 version (officially we do not support it at all, but we usually are able to answer simple questions). If you need to stick with v7, it probably is best to ask your distribution for support.

rsyslog.conf configuration directive

$RulesetParser

Type: ruleset-specific configuration directive

Parameter Values: string

Available since: 5.3.4+

Default: rsyslog.rfc5424 followed by rsyslog.rfc5425

Description:

This directive permits to specify which message parsers should be used for the ruleset in question. It no ruleset is explicitely 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.
  • 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 (what probably provides the best solution).

More information about rulesets in general can be found in multi-ruleset support in rsyslog.

Caveats:

currently none known

Example:

This example assumes there are two devices emiting 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 wellformed 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 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.

[rsyslog.conf overview] [manual index] [rsyslog site]

This documentation is part of the rsyslog project.

Copyright © 2009 by Rainer Gerhards and Adiscon. Released under the GNU GPL version 2 or higher.

Previous topic

$RulesetCreateMainQueue

Next topic

Modules

This Page