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
|
Converting older formats to |FmtAdvancedName|
=============================================
First of all, converting of older formats is not strictly necessary. All
formats can be mixed and matched and play well together.
There are stil a number of reasons to convert older formats:
* existing simple constructs need to be enhanced and become more complex
* aid future extensions
* ensure no side-effects accidentally occur
* unify rsyslog.conf language
Do not overdo conversion
~~~~~~~~~~~~~~~~~~~~~~~~
Note: simple facility and severity based filters which trigger writing to
files can actually be very well expressd in |FmtBasicName|. So if you have
something like::
mail.info /var/log/maillog
We suggest you leave it as-is without conversion. Equally, in our opinion it is
also fine to add new rules like the above. If you still want to convert, the
line may look as follows (completely in new format)::
if prifilt("mail.info") then {
action(type="omfile" file="/var/log/maillog")
}
More compact, this can also be written like::
if prifilt("mail.info") then action(type="omfile" file="/var/log/maillog")
The older-selector-style filter is well-known, so this may also write it as::
mail.info action(type="omfile" file="/var/log/maillog")
There are ample additional possibilities. We suggest to keep things consistent.
Converting Module Load
~~~~~~~~~~~~~~~~~~~~~~
This is very straight-forward. In |FmtObsoleteName| format we use::
$ModLoad module-name
This is very simply converted to::
module(load="module-name")
Sometimes modules provide global settings. In |FmtObsoleteName| format these are given in
individual lines **after** the \$ModLoad. In |FmtAdvancedName| format they are given inside
the module object. This makes it much clearer which module they belong to and
that they actually are global parameters (in contrast to per-action or per-listener
parameters). A typical example is `imtcp`::
$ModLoad imtcp
$InputTCPMaxSession 500
This is converted to::
module(load="imtcp" maxSessions="500")
Note: in |FmtObsoleteName| format it is possible to provide global parameters more than once.
In this case it is unclear which one actually applies. For example::
$ModLoad imtcp
$InputTCPMaxSession 500
...
*.* /var/log/messages
...
$InputTCPMaxSession 200
This is especially problematic if module-global parameters are used multiple times
in include files.
In |FmtAdvancedName| format this is no longer possible. Module-global parameters can only
be applied once when the module is loaded. Any attempt to change them afterwards
results in an error message and will be ignored. The error messages will help you
find and fix multiple settings. Let us assume "200" is the setting actually intended
in above config snippet. So it would be converted to::
module(load="imtcp" maxSessions="200")
...
*.* /var/log/messages
...
Converting Actions
~~~~~~~~~~~~~~~~~~
In general, you have lines like::
filter action
where *filter* is any of the filters and *action* is ... the action to be
carried out. As could be seen above, the filter does **not** necessarily
need to be changed in order to convert the action. All filters also work
with all config formats. It often is best to keep existing filters, at
least while working on the conversion (do not change too many things at once).
The following table lists traditional action syntax and how it can be
converted to new-style ``action()`` objects. The link will bring you to
detail documentation. In these detail documentations all parameters are given.
It is also specified which |FmtObsoleteName| directives map to |FmtAdvancedName|
properties.
This table is not conclusive but covers the most commonly used actions.
.. csv-table::
:header: "|FmtBasicName|", "|FmtAdvancedName|"
:widths: auto
:class: parameter-table
"file path (`/var/log/...`)", "action(type="":doc:`omfile <modules/omfile>`"" file=""/var/log.../"" ...)"
"UDP forwarding (`@remote`)", "action(type="":doc:`omfwd <modules/omfwd>`"" target=""remote"" protocol=""udp"" ...)"
"TCP forwarding (`@@remote`)", "action(type="":doc:`omfwd <modules/omfwd>`"" target=""remote"" protocol=""tcp"" ...)"
"user notify (``:omusrmsg:user``)", "action(type="":doc:`omusrmsg <modules/omusrmsg>`"" users=""user"" ...)"
"module name (``:omxxx:..``)", "action(type="":doc:`omxxx <modules/idx_output>`"" ...)"
Some concrete examples::
OLD: :hostname, contains, "remote-sender" @@central
NEW: :hostname, contains, "remote-sender" action(type="omfwd" target="central" protocol="tcp")
OLD: if $msg contains "error" then @central
NEW: if $msg contains "error" then action(type="omfwd" target="central" protocol="udp")
OLD: *.emerg :omusrmsg:*
NEW: *.emerg action(type="omusrmsg" users="*")
**NOTE:** Some actions do not have a |FmtBasicName| format configuration line. They may
only be called via the ``action()`` syntax. Similarly, some very few actions,
mostly contributed, do not support ``action()`` syntax and thus can only be
configured via |FmtBasicName| and |FmtObsoleteName|. See module doc for details.
Action with Multiple Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In many cases, actions have additional parameters, which also need to be converted. In
|FmtObsoleteName| format the action parameters are given before the actual action call.
To convert such constructs, you need to map all |FmtObsoleteName| parameters to |FmtAdvancedName|
ones. To look these up, you need to turn to three different documentation pages:
* the :doc:`action object <actions>` itself
* the :doc:`output module <modules/idx_output>` that is called in the action (e.g. omfwd)
* the :doc:`queue documentation <../rainerscript/queue_parameters>` (if an action queue is used)
To find the parameter in question, you can other do an on-page search via the browser on these
pages. Often it is very convenient to just use the
`rsyslog doc search engine <https://www.rsyslog.com/doc/master/search.html?q=>`_:
Type the |FmtObsoleteName| format statement into the search box. Most often, one of the first
search results is the matching object description doc page.
Converting Action Chains
~~~~~~~~~~~~~~~~~~~~~~~~
Actions can be chained via the ampersand character ('``&``'). In |FmtAdvancedName|
format this has been replaced by blocks. For example::
*.error /var/log/errorlog
& @remote
becomes::
*.error {
action(type="omfile" file="/var/log/errorlog")
action(type="omfwd" target="remote" protocol="udp")
}
The latter is much easier to understand and less error-prone when extended.
A common construct is to send messages to a remote host based on some message
content and then not further process it. This involves the ``stop`` statement
(or it's very old-time equivalent tilde ('``~``'). It may be specfied as such::
:msg, contains, "error" @remote
& ~
which is equavalent to::
:msg, contains, "error" @remote
& stop
This format is often found in more modern distro's rsyslog.conf. It again is
fully equivalent to::
:msg, contains, "error" {
action(type="omfwd" target="remote" protocol="udp")
stop
}
And, just to prove the point, this is also exactly the same like::
if $msg contains "error" then {
action(type="omfwd" target="remote" protocol="udp")
stop
}
|
