From 21cd86bb63efc8cb52d13cc32fdb1444b6d8c033 Mon Sep 17 00:00:00 2001 From: Konstantin Schmitt Date: Mon, 12 Nov 2012 16:03:57 +0100 Subject: doc: upgrade ruleset doc to v7 config system --- doc/Makefile.am | 1 + doc/multi_ruleset.html | 132 +++++++----------------- doc/multi_ruleset_legacy_format.html | 192 +++++++++++++++++++++++++++++++++++ 3 files changed, 227 insertions(+), 98 deletions(-) create mode 100644 doc/multi_ruleset_legacy_format.html diff --git a/doc/Makefile.am b/doc/Makefile.am index bded9453..8bf463fc 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -130,6 +130,7 @@ html_files = \ rsyslog_conf_nomatch.html \ queues_analogy.html \ multi_ruleset.html \ + multi_ruleset_legacy_format.html \ dev_oplugins.html \ free_support.html \ imudp.html \ diff --git a/doc/multi_ruleset.html b/doc/multi_ruleset.html index da65b4ba..37c54065 100644 --- a/doc/multi_ruleset.html +++ b/doc/multi_ruleset.html @@ -31,7 +31,7 @@ You can think of a traditional config file just as a single default rule set, wh 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 -
$RuleSet <name>
+
ruleset(name="rulesetname");
 

 
 
Where name is any name the user likes (but must not start with "RSYSLOG_", which
@@ -63,7 +63,7 @@ to seperate the messages by any other method.
 
 
Binding to rulesets is input-specifc. For imtcp, this is done via the 
 
-
$InputTCPServerBindRuleset <name>
+
input(type="imptcp" port="514" ruleset="rulesetname");
 

 
 directive. Note that "name" must be the name of a ruleset that is already defined
@@ -116,8 +116,12 @@ filters on the message, processes it and then discards it:
 
 # ... module loading ...
 # process remote messages
-:fromhost-ip, isequal, "192.0.2.1"    /var/log/remotefile
-& ~
+if $fromhost-ip == '192.168.152.137' then {
+        action(type="omfile" file="/var/log/remotefile02")
+		stop
+	}
+
+
 # only messages not from 192.0.21 make it past this point
 
 # The authpriv file has restricted access.
@@ -131,7 +135,7 @@ cron.*                                /var/log/cron
 ... more ...
 

 
-
Note the tilde character, which is the discard action!. Also note that we assume that
+
Note that "stop" is the discard action!. Also note that we assume that
 192.0.2.1 is the sole remote sender (to keep it simple).
 
 
With multiple rulesets, we can simply define a dedicated ruleset for the remote reception
@@ -141,66 +145,15 @@ case and bind it to the receiver. This may be written as follows:
 # ... module loading ...
 # process remote messages
 # define new ruleset and add rules to it:
-$RuleSet remote
-*.*           /var/log/remotefile
+ruleset(name="remote"){
+	action(type="omfile" file="/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 ...
+# bind ruleset to tcp listener and activate it:
+input(type="imptcp" port="10514" ruleset="remote")
 

 
-
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:
-
-
-# ... 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
-

-
-
Here, we do not switch back to the default ruleset, because this is not needed as it is
-completely defined when we begin the "remote" ruleset.
-
-
Now look at the examples and compare them to the single-ruleset solution. You will notice
-that we do not 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! This is what makes using multiple
-rulesets so much easier.
-
 
Split local and remote logging for three different ports

 
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
@@ -217,47 +170,34 @@ written to 10516's general log file.
 
 
 # ... 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(name="remote10514"){
+	action(type="omfile" file="/var/log/remote10514")
+}
 
-$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
+ruleset(name="remote10515"){
+	action(type="omfile" file="/var/log/remote10515")
+}
 
-# and now define listners bound to the relevant ruleset
-$InputTCPServerBindRuleset remote10514
-$InputTCPServerRun 10514
+ruleset(name="test1"){
+	if prifilt("mail.*") then {
+		/var/log/mail10516
+		stop
+		# note that the stop-command will prevent this message from 
+		# being written to the remote10516 file - as usual...	
+	}
+	/var/log/remote10516
+}
 
-$InputTCPServerBindRuleset remote10515
-$InputTCPServerRun 10515
 
-$InputTCPServerBindRuleset remote10516
-$InputTCPServerRun 10516
+# and now define listners bound to the relevant ruleset
+input(type="imptcp" port="10514" ruleset="remote10514")
+input(type="imptcp" port="10515" ruleset="remote10515")
+input(type="imptcp" port="10516" ruleset="remote10516")
 

 
-
Note that the "mail.*" rule inside the "remote10516" ruleset does
-not affect processing inside any other rule set, including the default rule set.
+
 
 
 
Performance

@@ -289,10 +229,6 @@ dedicated queue for each of the inputs.
 
By default, rulesets do not have their own queue. It must be activated via the
 $RulesetCreateMainQueue directive.
 
-
Future Enhancements

-
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.
-
 
[manual index] [rsyslog site]

 
This documentation is part of the rsyslog
 project.

diff --git a/doc/multi_ruleset_legacy_format.html b/doc/multi_ruleset_legacy_format.html
new file mode 100644
index 00000000..5a9e7a4a
--- /dev/null
+++ b/doc/multi_ruleset_legacy_format.html
@@ -0,0 +1,192 @@
+
+
+Multiple Rulesets in legacy format
+
+
Multiple Rulesets in rsyslog

+
Starting with version 4.5.0 and 5.1.1, rsyslog 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.

+Attention: this guide is shortened and only contains the samples in legacy format.
+Please follow this link to the full guide in the new config format "list": http://www.rsyslog.com/doc/multi_ruleset.html
+
+
+
Examples

+
Split local and remote logging

+
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:
+
+
+# ... 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 ...
+

+
+
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:
+
+
+# ... 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 ...
+

+
+
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).
+
+
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:
+
+
+# ... 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 ...
+

+
+
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:
+
+
+# ... 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
+

+
+
Here, we do not switch back to the default ruleset, because this is not needed as it is
+completely defined when we begin the "remote" ruleset.
+
+
Now look at the examples and compare them to the single-ruleset solution. You will notice
+that we do not 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! This is what makes using multiple
+rulesets so much easier.
+
+
Split local and remote logging for three different ports

+
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.
+
+
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 not be
+written to 10516's general log file.
+
+
This is the config:
+
+
+# ... 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
+

+
+
Note that the "mail.*" rule inside the "remote10516" ruleset does
+not affect processing inside any other rule set, including the default rule set.
+
+
+
[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 3 or higher.

+
-- 
cgit v1.2.3