File: //usr/share/doc/rsyslog/html/compatibility/v7compatibility.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 v7 — 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 v6" href="v6compatibility.html" />
<link rel="prev" title="Compatibility Notes for rsyslog v8" href="v8compatibility.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="v6compatibility.html" title="Compatibility Notes for rsyslog v6"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="v8compatibility.html" title="Compatibility Notes for rsyslog v8"
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-v7">
<h1>Compatibility Notes for rsyslog v7<a class="headerlink" href="#compatibility-notes-for-rsyslog-v7" title="Permalink to this headline">¶</a></h1>
<p>This document describes things to keep in mind when moving from v6 to v7. 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 v6
and want to use v7 without hassle.</p>
<p>Version 7 builds on the new config language introduced in v6 and extends it.
Other than v6, it not just only extends the config language, but provides
considerable changes to core elements as well. The result is much more power and
ease of use as well (this time that is not contradictionary).</p>
<div class="section" id="bsd-style-blocks">
<h2>BSD-Style blocks<a class="headerlink" href="#bsd-style-blocks" title="Permalink to this headline">¶</a></h2>
<p>BSD style blocks are no longer supported (for good reason). See the
<a class="reference external" href="http://www.rsyslog.com/g/BSD">rsyslog BSD blocks info page</a>
for more information and how to upgrade your config.</p>
</div>
<div class="section" id="cee-properties">
<h2>CEE-Properties<a class="headerlink" href="#cee-properties" title="Permalink to this headline">¶</a></h2>
<p>In rsyslog v6, CEE properties could not be used across disk-based queues. If this was
done, their content was reset. This was a missing feature in v6. In v7, this feature
has been implemented. Consequently, situations where the previous behaviour were
desired need now to be solved differently. We do not think that this will cause any
problems to anyone, especially as in v6 this was announced as a missing feature.</p>
</div>
<div class="section" id="omusrmsg-using-just-a-username-or-is-deprecated">
<h2>omusrmsg: using just a username or “*” is deprecated<a class="headerlink" href="#omusrmsg-using-just-a-username-or-is-deprecated" title="Permalink to this headline">¶</a></h2>
<p>In legacy config format, the asterisk denotes writing the message to all users.
This is usually used for emergency messages and configured like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*.</span><span class="n">emerg</span> <span class="o">*</span>
</pre></div>
</div>
<p>Unfortunately, the use of this single character conflicts with other uses, for
example with the multiplication operator. While rsyslog up to versions v7.4 preserves the meaning of
asterisk as an action, it is deprecated and will probably be removed in future versions.
Consequently, a warning message is emitted. To make this warning go away, the action must
be explicitly given, as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*.</span><span class="n">emerg</span> <span class="p">:</span><span class="n">omusrmsg</span><span class="p">:</span><span class="o">*</span>
</pre></div>
</div>
<p>The same holds true for user names. For example</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*.</span><span class="n">emerg</span> <span class="n">john</span>
</pre></div>
</div>
<p>at a minimum should be rewritten as</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*.</span><span class="n">emerg</span> <span class="p">:</span><span class="n">omusrmsg</span><span class="p">:</span><span class="n">john</span>
</pre></div>
</div>
<p>Of course, for even more clarity the new RainerScript style of action can
also be used:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*.</span><span class="n">emerg</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">"john"</span><span class="p">)</span>
</pre></div>
</div>
<p>In Rainer’s blog, there is more
<a class="reference external" href="https://rainer.gerhards.net/2011/07/why-omusrmsg-is-evil-and-how-it-is.html">background information on why omusrmsg needed to be changed</a>
available.</p>
</div>
<div class="section" id="omruleset-and-discard-action-are-deprecated">
<h2>omruleset and discard (~) action are deprecated<a class="headerlink" href="#omruleset-and-discard-action-are-deprecated" title="Permalink to this headline">¶</a></h2>
<p>Both continue to work, but have been replaced by better alternatives.</p>
<p>The discard action (tilde character) has been replaced by the “stop”
RainerScript directive. It is considered more intuitive and offers slightly
better performance.</p>
<p>The omruleset module has been replaced by the “call” RainerScript directive.
Call permits to execute a ruleset like a subroutine, and does so with much
higher performance than omruleset did. Note that omruleset could be run off
an async queue. This was more a side than a desired effect and is not supported
by the call statement. If that effect was needed, it can simply be simulated by
running the called rulesets actions asynchronously (what in any case is the right
way to handle this).</p>
<p>Note that the deprecated modules emit warning messages when being used.
They tell that the construct is deprecated and which statement is to be used
as replacement. This does <strong>not</strong> affect operations: both modules are still
fully operational and will not be removed in the v7 timeframe.</p>
</div>
<div class="section" id="retries-of-output-plugins-that-do-not-do-proper-replies">
<h2>Retries of output plugins that do not do proper replies<a class="headerlink" href="#retries-of-output-plugins-that-do-not-do-proper-replies" title="Permalink to this headline">¶</a></h2>
<p>Some output plugins may not be able to detect if their target is capable of
accepting data again after an error (technically, they always return OK when
TryResume is called). Previously, the rsyslog core engine suspended such an action
after 1000 successive failures. This lead to potentially a large amount of
errors and error messages. Starting with 7.2.1, this has been reduced to 10
successive failures. This still gives the plugin a chance to recover. In extreme
cases, a plugin may now enter suspend mode where it previously did not do so.
In practice, we do NOT expect that.</p>
</div>
<div class="section" id="omfile-file-creation-time">
<h2>omfile: file creation time<a class="headerlink" href="#omfile-file-creation-time" title="Permalink to this headline">¶</a></h2>
<p>Originally, omfile created files immediately during startup, no matter if
they were written to or not. In v7, this has changed. Files are only created
when they are needed for the first time.</p>
<p>Also, in pre-v7 files were created <em>before</em> privileges were dropped. This meant
that files could be written to locations where the actual desired rsyslog
user was <em>not</em> permitted to. In v7, this has been fixed. This is fix also
the prime reason that files are now created on demand (which is later in the
process and after the privilege drop).</p>
</div>
<div class="section" id="notes-for-the-7-3-7-4-branch">
<h2>Notes for the 7.3/7.4 branch<a class="headerlink" href="#notes-for-the-7-3-7-4-branch" title="Permalink to this headline">¶</a></h2>
<div class="section" id="last-message-repeated-n-times-processing">
<h3>“last message repeated n times” Processing<a class="headerlink" href="#last-message-repeated-n-times-processing" title="Permalink to this headline">¶</a></h3>
<p>This processing has been optimized and moved to the input side. This results
in usually far better performance and also de-couples different sources
from the same
processing. It is now also integrated in to the more generic rate-limiting
processing.</p>
<div class="section" id="user-noticable-changes">
<h4>User-Noticable Changes<a class="headerlink" href="#user-noticable-changes" title="Permalink to this headline">¶</a></h4>
<p>The code works almost as before, with two exceptions:</p>
<ul class="simple">
<li>The suppression amount can be different, as the new algorithm
precisely check’s a single source, and while that source is being
read. The previous algorithm worked on a set of mixed messages
from multiple sources.</li>
<li>The previous algorithm wrote a “last message repeated n times” message
at least every 60 seconds. For performance reasons, we do no longer do
this but write this message only when a new message arrives or rsyslog
is shut down.</li>
</ul>
<p>Note that the new algorithms needs support from input modules. If old
modules which do not have the necessary support are used, duplicate
messages will most probably not be detected. Upgrading the module code is
simple, and all rsyslog-provided plugins support the new method, so this
should not be a real problem (crafting a solution would result in rather
complex code - for a case that most probably would never happen).</p>
</div>
<div class="section" id="performance-implications">
<h4>Performance Implications<a class="headerlink" href="#performance-implications" title="Permalink to this headline">¶</a></h4>
<p>In general, the new method enables far faster output processing. However, it
needs to be noted that the “last message repeated n” processing needs parsed
messages in order to detect duplicated. Consequently, if it is enabled the
parser step cannot be deferred to the main queue processing thread and
thus must be done during input processing. The changes workload distribution
and may have (good or bad) effect on the overall performance. If you have
a very high performance installation, it is suggested to check the performance
profile before deploying the new version.</p>
<p><strong>Note:</strong> for high-performance
environments it is highly recommended NOT to use “last message repeated n times”
processing but rather the other (more efficient) rate-limiting methods. These
also do NOT require the parsing step to be done during input processing.</p>
</div>
</div>
<div class="section" id="stricter-string-template-processing">
<h3>Stricter string-template Processing<a class="headerlink" href="#stricter-string-template-processing" title="Permalink to this headline">¶</a></h3>
<p>Previously, no error message for invalid string template parameters
was generated.
Rather a malformed template was generated, and error information emitted
at runtime. However, this could be quite confusing. Note that the new code
changes user experience: formerly, rsyslog and the affected
actions properly started up, but the actions did not produce proper
data. Now, there are startup error messages and the actions are NOT
executed (due to missing template due to template error).</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>
<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 v7</a><ul>
<li><a class="reference internal" href="#bsd-style-blocks">BSD-Style blocks</a></li>
<li><a class="reference internal" href="#cee-properties">CEE-Properties</a></li>
<li><a class="reference internal" href="#omusrmsg-using-just-a-username-or-is-deprecated">omusrmsg: using just a username or “*” is deprecated</a></li>
<li><a class="reference internal" href="#omruleset-and-discard-action-are-deprecated">omruleset and discard (~) action are deprecated</a></li>
<li><a class="reference internal" href="#retries-of-output-plugins-that-do-not-do-proper-replies">Retries of output plugins that do not do proper replies</a></li>
<li><a class="reference internal" href="#omfile-file-creation-time">omfile: file creation time</a></li>
<li><a class="reference internal" href="#notes-for-the-7-3-7-4-branch">Notes for the 7.3/7.4 branch</a><ul>
<li><a class="reference internal" href="#last-message-repeated-n-times-processing">“last message repeated n times” Processing</a><ul>
<li><a class="reference internal" href="#user-noticable-changes">User-Noticable Changes</a></li>
<li><a class="reference internal" href="#performance-implications">Performance Implications</a></li>
</ul>
</li>
<li><a class="reference internal" href="#stricter-string-template-processing">Stricter string-template Processing</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="v8compatibility.html"
title="previous chapter">Compatibility Notes for rsyslog v8</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="v6compatibility.html"
title="next chapter">Compatibility Notes for rsyslog v6</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/compatibility/v7compatibility.rst.txt"
rel="nofollow">Show Source</a></li>
<li><a href="https://github.com/rsyslog/rsyslog-doc/edit/master/source/compatibility/v7compatibility.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="v6compatibility.html" title="Compatibility Notes for rsyslog v6"
>next</a> |</li>
<li class="right" >
<a href="v8compatibility.html" title="Compatibility Notes for rsyslog v8"
>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>