diff options
author | Rainer Gerhards <rgerhards@adiscon.com> | 2009-07-02 15:29:37 +0200 |
---|---|---|
committer | Rainer Gerhards <rgerhards@adiscon.com> | 2009-07-02 15:29:37 +0200 |
commit | 1dee20014346a2f20b0db190cfdd8d9c7f57232e (patch) | |
tree | 50a737c24a24f4ee079d4df12ca3e51178636ec6 /doc | |
parent | 51882ce4dece319008118f2b7d2fc7d4de4ce244 (diff) | |
download | rsyslog-1dee20014346a2f20b0db190cfdd8d9c7f57232e.tar.gz rsyslog-1dee20014346a2f20b0db190cfdd8d9c7f57232e.tar.xz rsyslog-1dee20014346a2f20b0db190cfdd8d9c7f57232e.zip |
completed ruleset documentation
Diffstat (limited to 'doc')
-rw-r--r-- | doc/manual.html | 1 | ||||
-rw-r--r-- | doc/multi_ruleset.html | 139 | ||||
-rw-r--r-- | doc/rsyslog_conf_global.html | 6 |
3 files changed, 113 insertions, 33 deletions
diff --git a/doc/manual.html b/doc/manual.html index 307f9a82..0d371146 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -52,6 +52,7 @@ generic syslog application design</a><!-- not good as it currently is ;) <li><a <li><a href="build_from_repo.html">obtaining rsyslog from the source repository</a></li> <li><a href="ipv6.html">rsyslog and IPv6</a> (which is fully supported)</li> <li><a href="rsyslog_secure_tls.html">native TLS encryption for syslog</a></li> +<li><a href="multi_ruleset.html">using multiple rule sets in rsyslog</a></li> <li><a href="rsyslog_stunnel.html">ssl-encrypting syslog with stunnel</a></li> <li><a href="rsyslog_mysql.html">writing syslog messages to MySQL (and other databases as well)</a></li> <li><a href="rsyslog_high_database_rate.html">writing massive amounts of syslog messages to a database</a></li> diff --git a/doc/multi_ruleset.html b/doc/multi_ruleset.html index 532edbcf..8d8c614f 100644 --- a/doc/multi_ruleset.html +++ b/doc/multi_ruleset.html @@ -8,13 +8,14 @@ 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. +<p>In this document, I am using <a href="imtcp.html">imtcp</a>, an input module +that supports binding to non-standard rulesets since rsyslog started to support them. <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 "*.*" or "mail.info" or a complex +tend to call them selectors, a 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 as simple as a +traditional +syslog priority based filter (like "*.*" or "mail.info" or a as complex as a 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. @@ -33,7 +34,8 @@ rsyslog.conf is processed, the config file parser looks for the directive <pre>$RuleSet <name> </pre> -<p>Where name is any name the user likes. If it finds this directive, it begins a new +<p>Where name is any name the user likes (but must not start with "RSYSLOG_", which +is the name space reserved for rsyslog use). 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 @@ -46,9 +48,9 @@ there are no more rules or the discard action is executed. Note that with multip 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. +<p>Inputs must explicitely bind to rulesets. If they don't do, the default ruleset is bound. -This brings up the next question: +<p>This brings up the next question: <h2>What does "To bind to a Ruleset" mean?</h2> <p>This term is used in the same sense as "to bind an IP address to an interface": @@ -67,8 +69,19 @@ to seperate the messages by any other method. directive. Note that "name"e; 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. +define the inputs at the bottom. This kind of reverses the traditional recommended ordering, but +seems to be a really useful and straightforward way of doing things. +<h2>Can I use a different Ruleset as the default?</h2> +<p>This is possible by using the + +<pre>$DefaultRuleset <name> +</pre> + +Directive. Please note, however, that this directive is actually global: that is, it does not +modify the ruleset to which the next input is bound but rather provides a system-wide +default rule set for those inputs that did not explicitly bind to one. As such, the directive +can not be used as a work-around to bind inputs to non-default rulesets that do not support +ruleset binding. <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 @@ -78,13 +91,13 @@ might look like this: <pre> # ... module loading ... # The authpriv file has restricted access. -authpriv.* /var/log/secure +authpriv.* /var/log/secure # Log all the mail messages in one place. -mail.* /var/log/maillog +mail.* /var/log/maillog # Log cron stuff -cron.* /var/log/cron +cron.* /var/log/cron # Everybody gets emergency messages -*.emerg * +*.emerg * ... more ... </pre> @@ -96,18 +109,18 @@ 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 +: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 +authpriv.* /var/log/secure # Log all the mail messages in one place. -mail.* /var/log/maillog +mail.* /var/log/maillog # Log cron stuff -cron.* /var/log/cron +cron.* /var/log/cron # Everybody gets emergency messages -*.emerg * +*.emerg * ... more ... </pre> @@ -122,7 +135,7 @@ case and bind it to the receiver. This may be written as follows: # process remote messages # define new ruleset and add rules to it: $RuleSet remote -*.* /var/log/remotefile +*.* /var/log/remotefile # only messages not from 192.0.21 make it past this point # bind ruleset to tcp listener @@ -133,13 +146,13 @@ $InputTCPServerRun 10514 # switch back to the default ruleset: $RuleSet RSYSLOG_DefaultRuleset # The authpriv file has restricted access. -authpriv.* /var/log/secure +authpriv.* /var/log/secure # Log all the mail messages in one place. -mail.* /var/log/maillog +mail.* /var/log/maillog # Log cron stuff -cron.* /var/log/cron +cron.* /var/log/cron # Everybody gets emergency messages -*.emerg * +*.emerg * ... more ... </pre> @@ -151,19 +164,20 @@ below has it, and it leads to the same results: # ... module loading ... # at first, this is a copy of the unmodified rsyslog.conf # The authpriv file has restricted access. -authpriv.* /var/log/secure +authpriv.* /var/log/secure # Log all the mail messages in one place. -mail.* /var/log/maillog +mail.* /var/log/maillog # Log cron stuff -cron.* /var/log/cron +cron.* /var/log/cron # Everybody gets emergency messages -*.emerg * +*.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 +*.* /var/log/remotefile # bind ruleset to tcp listener $InputTCPServerBindRuleset remote @@ -172,12 +186,72 @@ $InputTCPServerRun 10514 </pre> <p>Here, we do not switch back to the default ruleset, because this is not needed as it is -completely defined. +completely defined when we begin the "remote" ruleset. <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 "*.*" 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! +rule set and all of them come in via the TCP receiver! This is what makes using multiple +rulesets so much easier. + +<h3>Split local and remote logging for three different ports</h3> +<p>This example is almost like the first one, but it extends it a little bit. While it is +very similar, I hope it is different enough to provide a useful example why you may want +to have more than two rulesets. + +<p>Again, we would like to use the "regular" log files for local logging, only. But +this time we set up three syslog/tcp listeners, each one listening to a different +port (in this example 10514, 10515, and 10516). Logs received from these receivers shall go into +different files. Also, logs received from 10516 (and only from that port!) with +"mail.*" priority, shall be written into a specif file and <b>not</b> be +written to 10516's general log file. + +<p>This is the config: + +<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 rulesets first +$RuleSet remote10514 +*.* /var/log/remote10514 + +$RuleSet remote10515 +*.* /var/log/remote10515 + +$RuleSet remote10516 +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 listners bound to the relevant ruleset +$InputTCPServerBindRuleset remote10514 +$InputTCPServerRun 10514 + +$InputTCPServerBindRuleset remote10515 +$InputTCPServerRun 10515 + +$InputTCPServerBindRuleset remote10516 +$InputTCPServerRun 10516 +</pre> + +<p>Note that the "mail.*" rule inside the "remote10516"e; ruleset does +not affect processing inside any other rule set, including the default rule set. + <h2>Performance</h2> <p>No rule processing can be faster than not processing a rule at all. As such, it is useful @@ -189,6 +263,9 @@ is no need to check the reception service - instead messages are automatically p right rule set and can be processed by very simple rules (maybe even with "*.*"-filters, the fastest ones available). +<p>In the long term, multiple rule sets will probably lay the foundation for even better +optimizations. So it is not a bad idea to get aquainted with them. + <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> diff --git a/doc/rsyslog_conf_global.html b/doc/rsyslog_conf_global.html index 332b6282..03842758 100644 --- a/doc/rsyslog_conf_global.html +++ b/doc/rsyslog_conf_global.html @@ -110,7 +110,8 @@ that no rebind is done. This directive is useful for use with load-balancers.</l <li>$DefaultNetstreamDriverKeyFile </path/to/keyfile.pem></li> <li><b>$DefaultRuleset</b> <i>name</i> - changes the default ruleset for unbound inputs to the provided <i>name</i> (the default default ruleset is named -"RSYSLOG_DefaultRuleset"). +"RSYSLOG_DefaultRuleset"). It is advised to also read +our paper on <a href="multi_ruleset.html">using multiple rule sets in rsyslog</a>.</li> <li><b>$CreateDirs</b> [<b>on</b>/off] - create directories on an as-needed basis</li> <li><a href="rsconf1_dircreatemode.html">$DirCreateMode</a></li> <li><a href="rsconf1_dirgroup.html">$DirGroup</a></li> @@ -218,7 +219,8 @@ large enough for the whole message. (Introduced with 4.1.5). Once set, it affect All following actions belong to that new rule set. the <i>name</i> does not yet exist, it is created. To swith back to rsyslog's default ruleset, specify "RSYSLOG_DefaultRuleset") as the name. -All following actions belong to that new rule set.</li> +All following actions belong to that new rule set. It is advised to also read +our paper on <a href="multi_ruleset.html">using multiple rule sets in rsyslog</a>.</li> <li><b>$OptimizeForUniprocessor</b> [on/<b>off</b>] - turns on optimizatons which lead to better performance on uniprocessors. If you run on multicore-machiens, turning this off lessens CPU load. The default may change as uniprocessor systems become less common. [available since 4.1.0]</li> |