diff options
| 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 /doc/v6compatibility.html | |
| parent | 742afce7458505be1a82792c9b5728f58456565d (diff) | |
| download | rsyslog-81b302eb654099a8919458cb3b18168cc7b98ff7.tar.gz rsyslog-81b302eb654099a8919458cb3b18168cc7b98ff7.tar.xz rsyslog-81b302eb654099a8919458cb3b18168cc7b98ff7.zip | |
doc: v6 compatiblity doc added
Diffstat (limited to 'doc/v6compatibility.html')
| -rw-r--r-- | doc/v6compatibility.html | 115 |
1 files changed, 91 insertions, 24 deletions
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 "run" 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 © 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> |