1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>Compatibility notes for rsyslog v6</title>
</head>
<body>
<h1>Compatibility Notes for rsyslog v6</h1>
<p><small><i>Written by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a>
(2011-10-27)</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). 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>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>
<h2>Property "pri-text"</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.
<p><b>If you have used this property previously and relied on the numerical
part, you need to update your rsyslog configuration files.</b>
<h2>Plugin ABI</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 instablity during the initial v6 releases.
<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.
<p>Please see the
<a href="http://blog.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.
<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>Default Batch Sizes</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.
<h2>Default action queue enqueue timeout</h2>
<p>This timeout previously was 2seconds, 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.
<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.
<h2>ompipe default template</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
<blockquote><code>
module(load="builtin:ompipe" template="myDefaultTemplate")
</code> </blockquote>
<p>For obvious reasons, the default template must be defined somewhere in
the config file, otherwise errors will happen during the config load
phase.
<h2>omusrmsg</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 suffucient to use
just the user name to call this action, like in this example:
<blockquote><code>
*.* rgerhards
</code> </blockquote>
This format is very ambigious and causes headache (see
<a href="http://blog.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 ;-)):
<blockquote><code>
*.* :omusrmsg:rgerhards
</code> </blockquote>
That syntax is supported since later subversions of version 4.
<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:
<blockquote><code>
*.* rgerhards, bgerhards
</code> </blockquote>
To fix it in a way that is compatible with pre-v4, use (note the removed space!):
<blockquote><code>
*.* rgerhards,bgerhards
</code> </blockquote>
Of course, it probably is better to understand in native v6 format:
<blockquote><code>
*.* action(type="omusrmsg" users="rgerhards, bgerhards")
</code> </blockquote>
As you see, here you may include spaces between user names.
<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).
<h2>Escape Sequences in Script-Based Filters</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>[<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>
|
