rsyslog/rsyslog
1
0
Fork 0
mirror of https://github.com/rsyslog/rsyslog.git synced 2025-12-19 17:20:42 +01:00
Code Issues Packages Projects Releases Wiki Activity

first shot at multi-ruleset doc

Browse Source
This commit is contained in:
Rainer Gerhards 2009-07-01 18:57:58 +02:00
parent 7bfa03bdc0
commit 51882ce4de
2 changed files with 199 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/Makefile.am
View File

@ -111,6 +111,7 @@ html_files = \
rsyslog_conf_templates.html \
rsyslog_conf_nomatch.html \
queues_analogy.html \
multi_ruleset.html \
src/classes.dia
grfx_files = \

198
doc/multi_ruleset.html Normal file
View File

@ -0,0 +1,198 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>
<title>Multiple Rulesets in rsyslog</title></head>
<body>
<h1>Multiple Rulesets in rsyslog</h1>
<p>Starting with version 4.5.0 and 5.1.1, <a href="http://www.rsyslog.com">rsyslog</a> supports
multiple rulesets within a single configuration.
This is especially useful for routing the recpetion of remote messages to a set of specific rules.
Note that the input module must support binding to non-standard rulesets, so the functionality
may not be available with all inputs.
<p>In this document, I am using the <a href="imtcp.html">imtcp</a> in this text, an input module
that supports binding to non-standard rulesets as long as rsyslog supports multiple rulesets.
<h2>What is a Ruleset?</h2>
If you have worked with (r)syslog.conf, you know that it is made up of what I call rules (others
tend to call them selectors, an sysklogd term). Each rule consist of a filter and one or more
actions to be carried out when the filter evaluates to true. A filter may be a simple traditional
syslog priority based filter (like &quot;*.*&quot; or &quot;mail.info&quot; or a complex
script-like expression. Details on that are covered in the config file documentation. After the
filter come action specifiers, and an action is something that does something to a message, e.g.
write it to a file or forward it to a remote logging server.
<p>A traditional configuration file is made up of one or more of these rules. When a new
message arrives, its processing starts with the first rule (in order of appearance in
rsyslog.conf) and continues for each rule until either all rules have been processed or
a so-called &quote;discard&quot; action happens, in which case processing stops and the
message is thrown away (what also happens after the last rule has been processed).
<p>The <b>multi-ruleset</b> support now permits to specify more than one such rule sequence.
You can think of a traditional config file just as a single default rule set, which is
automatically bound to each of the inputs. This is even what actually happens. When
rsyslog.conf is processed, the config file parser looks for the directive
<pre>$RuleSet &lt;name&gt;
</pre>
<p>Where name is any name the user likes. If it finds this directive, it begins a new
rule set (if the name was not yet know) or switches to an already-existing one (if the name
was known). All rules defined between this $RuleSet directive and the next one are appended
to the named ruleset. Note that the reserved name "RSYSLOG_DefaultRuleset" is used to
specify rsyslogd's default ruleset. You can use that name whereever you can use a ruleset name,
including when binding an input to it.
<p>Inside a ruleset, messages are processed as described above: they start with the first rule
and rules are processed in the order of appearance of the configuration file until either
there are no more rules or the discard action is executed. Note that with multiple rulesets
no longer <b>all</b> rsyslog.conf rules are executed but <b>only</b> those that are
contained within the specific ruleset.
<p>Inputs must explicitely bind to rulesets. If they don't do, the default ruleset is used.
This brings up the next question:
<h2>What does &quot;To bind to a Ruleset&quot; mean?</h2>
<p>This term is used in the same sense as &quot;to bind an IP address to an interface&quot;:
it means that a specific input, or part of an input (like a tcp listener) will use a specific
ruleset to &quot;pass its messages to&quot;. So when a new message arrives, it will be processed
via the bound ruleset. Rule from all other rulesets are irrelevant and will never be processed.
<p>This makes multiple rulesets very handy to process local and remote message via
seperate means: bind the respective receivers to different rule sets, and you do not need
to seperate the messages by any other method.
<p>Binding to rulesets is input-specifc. For imtcp, this is done via the
<pre>$InputTCPServerBindRuleset &lt;name&gt;
</pre>
directive. Note that &quot;name&quote; must be the name of a ruleset that is already defined
at the time the bind directive is given. There are many ways to make sure this happens, but
I personally think that it is best to define all rule sets at the top of rsyslog.conf and
define the input at the bottom. This kind of reverses its traditional recommended ordering, but
seems to be a really useful and straightforward ways of doing things.
<h2>Examples</h2>
<h3>Split local and remote logging</h3>
<p>Let's say you have a pretty standard system that logs its local messages to the usual
bunch of files that are specified in the default rsyslog.conf. As an example, your rsyslog.conf
might look like this:
<pre>
# ... module loading ...
# The authpriv file has restricted access.
authpriv.* /var/log/secure
# Log all the mail messages in one place.
mail.* /var/log/maillog
# Log cron stuff
cron.* /var/log/cron
# Everybody gets emergency messages
*.emerg *
... more ...
</pre>
<p>Now, you want to add receive messages from a remote system and log these to
a special file, but you do not want to have these messages written to the files
specified above. The traditional approach is to add a rule in front of all others that
filters on the message, processes it and then discards it:
<pre>
# ... module loading ...
# process remote messages
:fromhost-ip, isequal, "192.0.2.1" /var/log/remotefile
& ~
# only messages not from 192.0.21 make it past this point
# The authpriv file has restricted access.
authpriv.* /var/log/secure
# Log all the mail messages in one place.
mail.* /var/log/maillog
# Log cron stuff
cron.* /var/log/cron
# Everybody gets emergency messages
*.emerg *
... more ...
</pre>
<p>Note the tilde character, which is the discard action!. Also note that we assume that
192.0.2.1 is the sole remote sender (to keep it simple).
<p>With multiple rulesets, we can simply define a dedicated ruleset for the remote reception
case and bind it to the receiver. This may be written as follows:
<pre>
# ... module loading ...
# process remote messages
# define new ruleset and add rules to it:
$RuleSet remote
*.* /var/log/remotefile
# only messages not from 192.0.21 make it past this point
# bind ruleset to tcp listener
$InputTCPServerBindRuleset remote
# and activate it:
$InputTCPServerRun 10514
# switch back to the default ruleset:
$RuleSet RSYSLOG_DefaultRuleset
# The authpriv file has restricted access.
authpriv.* /var/log/secure
# Log all the mail messages in one place.
mail.* /var/log/maillog
# Log cron stuff
cron.* /var/log/cron
# Everybody gets emergency messages
*.emerg *
... more ...
</pre>
<p>Here, we need to switch back to the default ruleset after we have defined our custom
one. This is why I recommend a different ordering, which I find more intuitive. The sample
below has it, and it leads to the same results:
<pre>
# ... module loading ...
# at first, this is a copy of the unmodified rsyslog.conf
# The authpriv file has restricted access.
authpriv.* /var/log/secure
# Log all the mail messages in one place.
mail.* /var/log/maillog
# Log cron stuff
cron.* /var/log/cron
# Everybody gets emergency messages
*.emerg *
... more ...
# end of the "regular" rsyslog.conf. Now come the new definitions:
# process remote messages
# define new ruleset and add rules to it:
$RuleSet remote
*.* /var/log/remotefile
# bind ruleset to tcp listener
$InputTCPServerBindRuleset remote
# and activate it:
$InputTCPServerRun 10514
</pre>
<p>Here, we do not switch back to the default ruleset, because this is not needed as it is
completely defined.
<p>Now look at the examples and compare them to the single-ruleset solution. You will notice
that we do <b>not</b> need a real filter in the multi-ruleset case: we can simply use
&quot;*.*&quot; as all messages now means all messages that are being processed by this
rule set and all of them come in via the TCP receiver!
<h2>Performance</h2>
<p>No rule processing can be faster than not processing a rule at all. As such, it is useful
for a high performance system to identify disjunct actions and try to split these off to
different rule sets. In the example section, we had a case where three different tcp listeners
need to write to three different files. This is a perfect example of where multiple rule sets
are easier to use and offer more performance. The performance is better simply because there
is no need to check the reception service - instead messages are automatically pushed to the
right rule set and can be processed by very simple rules (maybe even with
&quot;*.*&quot;-filters, the fastest ones available).
<p>[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
<p><font size="2">This documentation is part of the <a href="http://www.rsyslog.com/">rsyslog</a>
project.<br>
Copyright &copy; 2009 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
<a href="http://www.adiscon.com/">Adiscon</a>.
Released under the GNU GPL version 3 or higher.</font></p>
</body></html>