doc: v6 compatiblity doc added

author: Rainer Gerhards <rgerhards@adiscon.com> 2011-07-13 12:54:38 +0200
committer: Rainer Gerhards <rgerhards@adiscon.com> 2011-07-13 12:54:38 +0200
commit: 81b302eb654099a8919458cb3b18168cc7b98ff7 (patch)
tree: 04d703bf6b1bf4e184215c9bdb7f072c284f4fde
parent: 742afce7458505be1a82792c9b5728f58456565d (diff)
download: rsyslog-81b302eb654099a8919458cb3b18168cc7b98ff7.tar.gz
rsyslog-81b302eb654099a8919458cb3b18168cc7b98ff7.tar.xz
rsyslog-81b302eb654099a8919458cb3b18168cc7b98ff7.zip
3 files changed, 99 insertions, 30 deletions
diff --git a/doc/manual.html b/doc/manual.html
index 19dcadb5..761417f1 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -30,10 +30,11 @@ between rsyslog and syslog-ng</a>.</p>
 <p>If you are upgrading from rsyslog v2 or stock sysklogd,
 <a href="v3compatibility.html">be sure to read the rsyslog v3 compatibility notes</a>,
 and if you are upgrading from v3, read the
-<a href="v4compatibility.html">rsyslog v4 compatibility notes</a> and
+<a href="v4compatibility.html">rsyslog v4 compatibility notes</a>,
 if you upgrade from v4, read the
-<a href="v5compatibility.html">rsyslog v5 compatibility notes</a>. Ther currently is
-no compatibility mode document for v6, as none is required right now.
+<a href="v5compatibility.html">rsyslog v5 compatibility notes</a>, and
+if you upgrade from v5, read the
+<a href="v6compatibility.html">rsyslog v6 compatibility notes</a>.
 <p>Rsyslog will work even
 if you do not read the doc, but doing so will definitely improve your experience.</p>
 <p><b>Follow the links below for the</b></p>
diff --git a/doc/v6compatibility.html b/doc/v6compatibility.html
index 6d60062f..e67efff3 100644
--- a/doc/v6compatibility.html
+++ b/doc/v6compatibility.html
@@ -1,30 +1,97 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html><head><title>Compatibility notes for rsyslog v5</title>
+<html><head><title>Compatibility notes for rsyslog v6</title>
 </head>
 <body>
-<h1>Compatibility Notes for rsyslog v5</h1>
+<h1>Compatibility Notes for rsyslog v6</h1>
 <p><small><i>Written by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a>
-(2009-07-15)</i></small></p>
-<p>The changes introduced in rsyslog v5 are numerous, but not very intrusive.
-This document describes things to keep in mind when moving from v4 to v5. It 
+(2011-07-13)</i></small></p>
+<p>
+This document describes things to keep in mind when moving from v5 to v6. It 
 does not list enhancements nor does it talk about compatibility concerns introduced
-by earlier versions (for this, see their respective compatibility documents).
-<h2>HUP processing</h2>
-<p>The $HUPisRestart directive is supported by some early v5 versions, but has been removed
-in 5.1.3 and above.  That means that restart-type HUP processing is no longer
-available. This processing was redundant and had a lot a drawbacks. 
-For details, please see the
-<a href="v4compatibility.html">rsyslog v4 compatibility notes</a> which elaborate
-on the reasons and the (few) things you may need to change.
-<h2>Queue Worker Thread Shutdown</h2>
-<p>Previous rsyslog versions had the capability to &quot;run&quot; on zero queue worker
-if no work was required. This was done to save a very limited number of resources. However,
-it came at the price of great complexity. In v5, we have decided to let a minium of one
-worker run all the time. The additional resource consumption is probably not noticable at
-all, however, this enabled us to do some important code cleanups, resulting in faster
-and more reliable code (complex code is hard to maintain and error-prone). From the
-regular user's point of view, this change should be barely noticable. I am including the
-note for expert users, who will notice it in rsyslog debug output and other analysis tools.
-So it is no error if each queue in non-direct mode now always runs at least one worker
-thread.
+by earlier versions (for this, see their respective compatibility documents). Its focus
+is primarily on what you need to know if you used a previous version and want to use the
+current one without hassle. Note that versions prior to 6.3.3 did not have any notable compatibility
+concerns. So all said here is for 6.3.3 and above.
+<h2>RainerScript based rsyslog.conf</h2>
+<p>A better config format was the main release target for rsyslog v6. It comes in the
+flavor of so-called RainerScript
+(<a href="http://blog.gerhards.net/2008/02/introducing-rainerscript-and-some.html">why the
+name RainerScript?</a>). RainerScript supports legacy syslog.conf format, much as you know it
+from other syslogd's (like sysklogd or the BSD syslogd's) as well as previous versions
+of rsyslog. Initial work on RainerScript began in v4, and the if-construct was already
+supported in v4 and v5. Version 6 has now taken this further. After long discussions we
+decided to use the legacy format as a basis, and lightly extend it by native RainerScript
+constructs. The main goal was to make sure that previous knowledge and config systems
+could still be used while offering a much more intuitive and powerful way of configuring
+rsyslog.
+<p>RainerScript has been implemented from scratch and with new tools (flex/bison, for those in the
+know). Starting with 6.3.3, this new config file processor replaces the legacy one. Note that
+the new processor handles all formats, extended RainerScript as well as legacy syslog.conf format.
+There are some legacy construct that were especially hard to translate. You'll read about them in
+other parts of this document (especially outchannels, which require a format change).
+
+<p>In v6, all legacy formats are supported. In the long term, we may remove some of the ugly
+rsyslog-specific constructs. Good candidates are all configuration commands starting with
+a dollar sign, like "$ActionFileDefaultTemplate"). However, this will not be the case before
+rsyslog v7 or (much more likely) v8/9. Right now, you also need to use these commands, because
+not all have already been converted to the new RainerScript format.
+
+<p>In 6.3.3, the new parser is used, but almost none of the extended RainerScript capabilities
+are available. They will incrementally be introduced with the following releases. Note that for
+some features (most importantly if-then-else nested blocks), the v6 core engine is not
+capable enough. It is our aim to provide a much better config language to as many rsyslog
+users as quickly as possible. As such, we refrain from doing big engine changes in v6. This
+in turn means we cannot introduce some features into RainerScript that we really want to see.
+These features will come up with rsyslog v7, which will have even better flow control
+capabilities inside the core engine. Note that v7 will fully support v6 RainerScript.
+Let us also say that the v6 version is not a low-end quick hack: it offers full-fledged
+syslog message processing control, capable of doing the best you can find inside the
+industry. We just say that v7 will come up with even more advanced capabilites.
+<p>Please note that we tried hard to make the RainerScript parser compatible with
+all legacy config files. However, we may have failed in one case or another. So if you
+experience problems during config processing, chances are there may be a problem
+on the rsyslog side. In that case, please let us know.
+
+<h2>compatibility mode</h2>
+<p>Compatibility mode (specified via -c option) has been removed. This was a migration aid from
+sysklogd and very early versions of rsyslog. As all major distros now have rsyslog as their
+default, and thus ship rsyslog-compliant config files, there is no longer a need for
+compatibility mode. Removing it provides easier to maintain code. Also, practice has shown
+that many users were confused by compatibility mode (and even some package maintainers got
+it wrong). So this not only cleans up the code but rather removes a frequent source of
+error.
+<p>It must be noted, though, that this means rsyslog is no longer a 100% drop-in replacement
+for sysklogd. If you convert an extremely old system, you need to checks its config and
+probably need to apply some very mild changes to the config file.
+<h2>abort on config errors</h2>
+<p>Previous versions accepted some malformedness inside the config file without aborting. This
+could lead to some uncertainty about which configuration was actually running. In v6 there
+are some situations where config file errors can not be ignored. In these cases rsyslog
+emits error messages to stderr, and then exists with a non-zero exit code. It is important
+to check for those cases as this means log data is potentially lost.
+Please note that
+the root problem is the same for earlier versions as well. With them, it was just harder
+to spot why things went wrong (and if at all).
+<h2>outchannels</h2>
+<p>Outchannels are a to-be-removed feature of rsyslog, at least as far as the config
+syntax is concerned. Nevertheless, v6 still supports it, but a new syntax is required
+for the action. Let's assume your outchannel is named "channel". The previous syntax was
+<blockquote><code>
+*.* $channel
+</code>
+</blockquote>
+This was deprecated in v5 and no longer works in v6. Instead, you need to specify
+<blockquote><code>
+*.* :omfile:$channel
+</code></blockquote>
+Note that this syntax is available starting with rsyslog v4. It is important to keep on your
+mind that future versions of rsyslog will require different syntax and/or drop outchannel support
+completely. So if at all possible, avoid using this feature. If you must use it, be prepared for
+future changes and watch announcements very carefully.
+<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; 2011 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 2 or higher.</font></p>
 </body></html>
diff --git a/grammar/debian.new b/grammar/debian.new
index 6cf9b5e5..4dbb5907 100644
--- a/grammar/debian.new
+++ b/grammar/debian.new
@@ -154,11 +154,12 @@ then	/dev/tty10
 # remote host is: name/ip:port, e.g. 192.168.0.1:514, port optional
 #*.* @@remote-host:514
 # ### end of the forwarding rule ###
-if $msg contains "error" then
+if $msg contains "error" then {
     action(type="omfwd" protocol="tcp" target="10.0.0.1:514"
            action.retryCount="-1"
            queue.type="linkedList" queue.fileName="fwdRule" queue.maxDiskSpace="1g"
            queue.saveOnShutdown="on"
           )
-    & action(type="omfile" target="/var/log/somelog.log")
-    & action(type="omuser" target="all")
+    action(type="omfile" target="/var/log/somelog.log")
+    action(type="omuser" target="all")
+}
author	Rainer Gerhards <rgerhards@adiscon.com>	2011-07-13 12:54:38 +0200
committer	Rainer Gerhards <rgerhards@adiscon.com>	2011-07-13 12:54:38 +0200
commit	81b302eb654099a8919458cb3b18168cc7b98ff7 (patch)
tree	04d703bf6b1bf4e184215c9bdb7f072c284f4fde
parent	742afce7458505be1a82792c9b5728f58456565d (diff)
download	rsyslog-81b302eb654099a8919458cb3b18168cc7b98ff7.tar.gz rsyslog-81b302eb654099a8919458cb3b18168cc7b98ff7.tar.xz rsyslog-81b302eb654099a8919458cb3b18168cc7b98ff7.zip