Written by Rainer Gerhards (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). 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.
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.
Please see the blog post about rsyslog 6.3.3 config format for details of what is currently supported.
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.
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 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
*.* :omfile:$channel
This documentation is part of the
rsyslog project.
Copyright © 2011 by Rainer Gerhards and
Adiscon. Released under the GNU GPL
version 2 or higher.