From 81b302eb654099a8919458cb3b18168cc7b98ff7 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Wed, 13 Jul 2011 12:54:38 +0200 Subject: doc: v6 compatiblity doc added --- doc/manual.html | 7 +-- doc/v6compatibility.html | 115 +++++++++++++++++++++++++++++++++++++---------- 2 files changed, 95 insertions(+), 27 deletions(-) (limited to 'doc') 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.

If you are upgrading from rsyslog v2 or stock sysklogd, be sure to read the rsyslog v3 compatibility notes, and if you are upgrading from v3, read the -rsyslog v4 compatibility notes and +rsyslog v4 compatibility notes, if you upgrade from v4, read the -rsyslog v5 compatibility notes. Ther currently is -no compatibility mode document for v6, as none is required right now. +rsyslog v5 compatibility notes, and +if you upgrade from v5, read the +rsyslog v6 compatibility notes.

Rsyslog will work even if you do not read the doc, but doing so will definitely improve your experience.

Follow the links below for the

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 @@ -Compatibility notes for rsyslog v5 +Compatibility notes for rsyslog v6 -

Compatibility Notes for rsyslog v5

Compatibility Notes for rsyslog v6

Written by Rainer Gerhards -(2009-07-15)

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)

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

HUP processing

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 -rsyslog v4 compatibility notes which elaborate -on the reasons and the (few) things you may need to change. -

Queue Worker Thread Shutdown

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

RainerScript based rsyslog.conf

A better config format was the main release target for rsyslog v6. It comes in the +flavor of so-called RainerScript +(why the +name RainerScript?). 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. +

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

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

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

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

compatibility mode

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

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

abort on config errors

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

outchannels

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 +

+*.* $channel + +

+This was deprecated in v5 and no longer works in v6. Instead, you need to specify +

+*.* :omfile:$channel +

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

[manual index] [rsyslog site]

-- cgit