File: //usr/share/doc/rsyslog/html/compatibility/v6compatibility.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Compatibility Notes for rsyslog v6 — rsyslog 8.2006.0 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/rsyslog.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '8.2006.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Compatibility Notes for rsyslog v5" href="v5compatibility.html" />
<link rel="prev" title="Compatibility Notes for rsyslog v7" href="v7compatibility.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="v5compatibility.html" title="Compatibility Notes for rsyslog v5"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="v7compatibility.html" title="Compatibility Notes for rsyslog v7"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">rsyslog 8.2006.0 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Compatibility</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="compatibility-notes-for-rsyslog-v6">
<h1>Compatibility Notes for rsyslog v6<a class="headerlink" href="#compatibility-notes-for-rsyslog-v6" title="Permalink to this headline">¶</a></h1>
<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). 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.</p>
<p>Version 6 offers a better config language and some other improvements.
As the config system has many ties into the rsyslog engine AND all plugins,
the changes are somewhat intrusive. Note, however, that core processing has
not been changed much in v6 and will not. So once the configuration is loaded,
the stability of v6 is quite comparable to v5.</p>
<div class="section" id="property-pri-text">
<h2>Property “pri-text”<a class="headerlink" href="#property-pri-text" title="Permalink to this headline">¶</a></h2>
<p>Traditionally, this property did not only return the textual form
of the pri (“local0.err”), but also appended the numerical value to it
(“local0.err<133>”). This sounds odd and was left unnoticed for some years.
In October 2011, this odd behaviour was brought up on the rsyslog mailing list
by Gregory K. Ruiz-Ade. Code review showed that the behaviour was intentional,
but no trace of what the intention was when it was introduced could be found.
The documentation was also unclear, it said no numerical value was present,
but the samples had it. We agreed that the additional numerical value is
of disadvantage. We also guessed that this property is very rarely being used,
otherwise the problem should have been raised much earlier. However, we
didn’t want to change behaviour in older builds. So v6 was set to clean up
the situation. In v6, text-pri will always return the textual part only
(“local0.err”) and the numerical value will not be contained any longer inside
the string. If you actually need that value, it can fairly easily be added
via the template system.
<strong>If you have used this property previously and relied on the numerical
part, you need to update your rsyslog configuration files.</strong></p>
</div>
<div class="section" id="plugin-abi">
<h2>Plugin ABI<a class="headerlink" href="#plugin-abi" title="Permalink to this headline">¶</a></h2>
<p>The plugin interface has considerably been changed to support the new
config language. All plugins need to be upgraded. This usually does not require
much coding. However, if the new config language shall be supported, more
changes must be made to plugin code. All project-supported plugins have been
upgraded, so this compatibility issue is only of interest for you if you have
custom plugins or use some user-contributed plugins from the rsyslog project
that are not maintained by the project itself (omoracle is an example). Please
expect some further plugin instability during the initial v6 releases.</p>
</div>
<div class="section" id="rainerscript-based-rsyslog-conf">
<h2>RainerScript based rsyslog.conf<a class="headerlink" href="#rainerscript-based-rsyslog-conf" title="Permalink to this headline">¶</a></h2>
<p>A better config format was the main release target for rsyslog v6. It comes in the
flavor of so-called RainerScript
<a class="reference external" href="https://rainer.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 syslogds (like sysklogd or the BSD syslogd) 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>
<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>
<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>
<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 capabilities.</p>
<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.</p>
<p>Please see the
<a class="reference external" href="https://rainer.gerhards.net/2011/07/rsyslog-633-config-format-improvements.html">blog post about rsyslog 6.3.3 config format</a>
for details of what is currently supported.</p>
</div>
<div class="section" id="compatibility-mode">
<h2>compatibility mode<a class="headerlink" href="#compatibility-mode" title="Permalink to this headline">¶</a></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>
<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.</p>
</div>
<div class="section" id="abort-on-config-errors">
<h2>abort on config errors<a class="headerlink" href="#abort-on-config-errors" title="Permalink to this headline">¶</a></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).</p>
</div>
<div class="section" id="default-batch-sizes">
<h2>Default Batch Sizes<a class="headerlink" href="#default-batch-sizes" title="Permalink to this headline">¶</a></h2>
<p>Due to their positive effect on performance and comparatively low overhead,
default batch sizes have been increased. Starting with 6.3.4, the action queues
have a default batch size of 128 messages.</p>
</div>
<div class="section" id="default-action-queue-enqueue-timeout">
<h2>Default action queue enqueue timeout<a class="headerlink" href="#default-action-queue-enqueue-timeout" title="Permalink to this headline">¶</a></h2>
<p>This timeout previously was 2 seconds, and has been reduced to 50ms (starting with 6.5.0). This change
was made as a long timeout will caused delays in the associated main queue, something
that was quite unexpected to users. Now, this can still happen, but the effect is much
less harsh (but still considerable on a busy system). Also, 50ms should be fairly enough
for most output sources, except when they are really broken (like network disconnect). If
they are really broken, even a 2second timeout does not help, so we hopefully get the best
of both worlds with the new timeout. A specific timeout can of course still be configured,
it is just the timeout that changed.</p>
</div>
<div class="section" id="outchannels">
<h2>outchannels<a class="headerlink" href="#outchannels" title="Permalink to this headline">¶</a></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</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>*.* $channel
</pre></div>
</div>
<p>This was deprecated in v5 and no longer works in v6. Instead, you need to specify</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>*.* :omfile:$channel
</pre></div>
</div>
<p>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>
</div>
<div class="section" id="ompipe-default-template">
<h2>ompipe default template<a class="headerlink" href="#ompipe-default-template" title="Permalink to this headline">¶</a></h2>
<p>Starting with 6.5.0, ompipe does no longer use the omfile default template.
Instead, the default template must be set via the module load statement.
An example is</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">module</span><span class="p">(</span><span class="n">load</span><span class="o">=</span><span class="s2">"builtin:ompipe"</span> <span class="n">template</span><span class="o">=</span><span class="s2">"myDefaultTemplate"</span><span class="p">)</span>
</pre></div>
</div>
<p>For obvious reasons, the default template must be defined somewhere in
the config file, otherwise errors will happen during the config load
phase.</p>
</div>
<div class="section" id="omusrmsg">
<h2>omusrmsg<a class="headerlink" href="#omusrmsg" title="Permalink to this headline">¶</a></h2>
<p>The omusrmsg module is used to send messages to users. In legacy-legacy
config format (that is the very old sysklogd style), it was sufficient to use
just the user name to call this action, like in this example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*.*</span> <span class="n">rgerhards</span>
</pre></div>
</div>
<p>This format is very ambiguous and causes headache (see
<a class="reference external" href="https://rainer.gerhards.net/2011/07/why-omusrmsg-is-evil-and-how-it-is.html">blog post on omusrmsg</a>
for details). Thus the format has been superseded by this syntax
(which is legacy format ;-)):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*.*</span> <span class="p">:</span><span class="n">omusrmsg</span><span class="p">:</span><span class="n">rgerhards</span>
</pre></div>
</div>
<p>That syntax is supported since later subversions of version 4.</p>
<p>Rsyslog v6 still supports the legacy-legacy format, but in a very strict
sense. For example, if multiple users or templates are given, no spaces
must be included in the action line. For example, this works up to v5, but no
longer in v6:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*.*</span> <span class="n">rgerhards</span><span class="p">,</span> <span class="n">bgerhards</span>
</pre></div>
</div>
<p>To fix it in a way that is compatible with pre-v4, use (note the removed space!):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*.*</span> <span class="n">rgerhards</span><span class="p">,</span><span class="n">bgerhards</span>
</pre></div>
</div>
<p>Of course, it probably is better to understand in native v6 format:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*.*</span> <span class="n">action</span><span class="p">(</span><span class="nb">type</span><span class="o">=</span><span class="s2">"omusrmsg"</span> <span class="n">users</span><span class="o">=</span><span class="s2">"rgerhards, bgerhards"</span><span class="p">)</span>
</pre></div>
</div>
<p>As you see, here you may include spaces between user names.</p>
<p>In the long term, legacy-legacy format will most probably totally disappear,
so it is a wise decision to change config files at least to the legacy
format (with “:omusrmsg:” in front of the name).</p>
</div>
<div class="section" id="escape-sequences-in-script-based-filters">
<h2>Escape Sequences in Script-Based Filters<a class="headerlink" href="#escape-sequences-in-script-based-filters" title="Permalink to this headline">¶</a></h2>
<p>In v5, escape sequences were very simplistic. Inside a string, “x” meant
“x” with x being any character. This has been changed so that the usual set of
escapes is supported, must importantly “n”, “t”, “xhh” (with hh being hex digits)
and “ooo” with (o being octal digits). So if one of these sequences was used
previously, results are obviously different. However, that should not create any
real problems, because it is hard to envision why someone should have done that
(why write “n” when you can also write “n”?).</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p>Help with configuring/using <code class="docutils literal"><span class="pre">Rsyslog</span></code>:</p>
<ul class="last simple">
<li><a class="reference external" href="http://lists.adiscon.net/mailman/listinfo/rsyslog">Mailing list</a> - best route for general questions</li>
<li>GitHub: <a class="reference external" href="https://github.com/rsyslog/rsyslog/">rsyslog source project</a> - detailed questions, reporting issues
that are believed to be bugs with <code class="docutils literal"><span class="pre">Rsyslog</span></code></li>
<li>Stack Exchange (<a class="reference external" href="https://stackexchange.com/filters/327462/rsyslog">View</a>, <a class="reference external" href="https://serverfault.com/questions/ask?tags=rsyslog">Ask</a>)
- experimental support from rsyslog community</li>
</ul>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p>Contributing to <code class="docutils literal"><span class="pre">Rsyslog</span></code>:</p>
<ul class="last simple">
<li>Source project: <a class="reference external" href="https://github.com/rsyslog/rsyslog/blob/master/README.md">rsyslog project README</a>.</li>
<li>Documentation: <a class="reference external" href="https://github.com/rsyslog/rsyslog-doc/blob/master/README.md">rsyslog-doc project README</a></li>
</ul>
</div>
<p>Copyright 2008-2020 <a class="reference external" href="https://rainer.gerhards.net/">Rainer Gerhards</a>
(<a class="reference external" href="https://www.rainer-gerhards.de/grossrinderfeld/">Großrinderfeld</a>),
and Others.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Compatibility Notes for rsyslog v6</a><ul>
<li><a class="reference internal" href="#property-pri-text">Property “pri-text”</a></li>
<li><a class="reference internal" href="#plugin-abi">Plugin ABI</a></li>
<li><a class="reference internal" href="#rainerscript-based-rsyslog-conf">RainerScript based rsyslog.conf</a></li>
<li><a class="reference internal" href="#compatibility-mode">compatibility mode</a></li>
<li><a class="reference internal" href="#abort-on-config-errors">abort on config errors</a></li>
<li><a class="reference internal" href="#default-batch-sizes">Default Batch Sizes</a></li>
<li><a class="reference internal" href="#default-action-queue-enqueue-timeout">Default action queue enqueue timeout</a></li>
<li><a class="reference internal" href="#outchannels">outchannels</a></li>
<li><a class="reference internal" href="#ompipe-default-template">ompipe default template</a></li>
<li><a class="reference internal" href="#omusrmsg">omusrmsg</a></li>
<li><a class="reference internal" href="#escape-sequences-in-script-based-filters">Escape Sequences in Script-Based Filters</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="v7compatibility.html"
title="previous chapter">Compatibility Notes for rsyslog v7</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="v5compatibility.html"
title="next chapter">Compatibility Notes for rsyslog v5</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/compatibility/v6compatibility.rst.txt"
rel="nofollow">Show Source</a></li>
<li><a href="https://github.com/rsyslog/rsyslog-doc/edit/master/source/compatibility/v6compatibility.rst"
rel="nofollow">Edit on GitHub</a></li>
</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="v5compatibility.html" title="Compatibility Notes for rsyslog v5"
>next</a> |</li>
<li class="right" >
<a href="v7compatibility.html" title="Compatibility Notes for rsyslog v7"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">rsyslog 8.2006.0 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >Compatibility</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
</div>
</body>
</html>