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
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
Basic Structure
===============
This section describes how rsyslog configuration basically works. Think
of rsyslog as a big logging and event processing toolset. It can be considered
a framework with some basic processing that is fixed in the way data flows,
but is highly customizable in the details of this message flow. During
configuration, this customization is done by defining and customizing
the rsyslog objects.
Quick overview of message flow and objects
------------------------------------------
Messages enter rsyslog with the help of input modules. Then, they are
passed to a ruleset, where rules are conditionally applied. When a rule
matches, the message is transferred to an action, which then does
something to the message, e.g. writes it to a file, database or
forwards it to a remote host.
Processing Principles
---------------------
- inputs submit received messages to rulesets
* if the ruleset is not specifically bound, the default ruleset is used
- by default, there is one ruleset (RSYSLOG_DefaultRuleset)
- additional rulesets can be user-defined
- each ruleset contains zero or more rules
* while it is permitted to have zero rules inside a ruleset,
this obviously makes no sense
- a rule consists of a filter and an action list
- filters provide yes/no decisions and thus control-of-flow capability
- if a filter "matches" (filter says "yes"), the corresponding
action list is executed. If it does not match, nothing special
happens
- rules are evaluated in sequence from the first to the last rule
**inside** the given ruleset. No rules from unrelated rulesets are
ever executed.
- all rules are **always** fully evaluated, no matter if a filter matches
or not (so we do **not** stop at the first match). If message processing
shall stop, the "discard" action (represented by the tilde character or the
stop command) must explicitly be executed. If discard is executed,
message processing immediately stops, without evaluating any further rules.
- an action list contains one or many actions
- inside an action list no further filters are possible
- to have more than one action inside a list, the ampersand character
must be placed in the position of the filter, and this must immediately
follow the previous action
- actions consist of the action call itself (e.g. ":omusrmsg:") as
well as all action-defining configuration statements ($Action... directives)
- if legacy format is used (see below), $Action... directives **must** be
specified in front of the action they are intended to configure
- some config directives automatically refer to their previous values
after being applied, others not. See the respective doc for details. Be
warned that this is currently not always properly documented.
- in general, rsyslog v5 is heavily outdated and its native config language
is a pain. The rsyslog project strongly recommends using at least version 7,
where these problems are solved and configuration is much easier.
- legacy configuration statements (those starting with $) do **not** affect
RainerScript objects (e.g. actions).
Configuration File
------------------
Upon startup, rsyslog reads its configuration from the ``rsyslog.conf``
file by default. This file may contain references to include other
config files.
A different "root" configuration file can be specified via the ``-f <file>``
rsyslogd command line option. This is usually done within some init
script or similar facility.
Statement Types
---------------
Rsyslog supports three different types of configuration statements
concurrently:
- **sysklogd** - this is the plain old format, taught everywhere and
still pretty useful for simple use cases. Note that some
constructs are no longer supported because they are incompatible with
newer features. These are mentioned in the compatibility docs.
- **legacy rsyslog** - these are statements that begin with a dollar
sign. They set some (case-insensitive) configuration parameters and
modify e.g. the way actions operate. This is the only format supported
in pre-v6 versions of rsyslog. It is still fully supported in v6 and
above. Note that some plugins and features may still only be available
through legacy format (because plugins need to be explicitly upgraded
to use the new style format, and this hasn't happened to all plugins).
- **RainerScript** - the new style format. This is the best and most
precise format to be used for more complex cases. As with the legacy
format, RainerScript parameters are also case-insensitive.
The rest of this page assumes RainerScript based rsyslog.conf.
The rsyslog.conf files consists of statements. For old style (sysklogd &
legacy rsyslog), lines do matter. For new style (RainerScript) line
spacing is irrelevant. Most importantly, this means with new style
actions and all other objects can split across lines as users want to.
Recommended use of Statement Types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In general it is recommended to use RainerScript type statements, as
these provide clean and easy to read control-of-flow as well as
no doubt about which parameters are active. They also have no
side-effects with include files, which can be a major obstacle with
legacy rsyslog statements.
For very simple things sysklogd statement types are still suggested,
especially if the full config consists of such simple things. The
classical sample is writing to files (or forwarding) via priority.
In sysklogd, this looks like:
::
mail.info /var/log/mail.log
mail.err @server.example.net
This is hard to beat in simplicity, still being taught in courses
and a lot of people know this syntax. It is perfectly fine to use
these constructs even in newly written config files.
**As a rule of thumb, RainerScript config statements should be used
when**
- configuration parameters are required (e.g. the ``Action...``
type of legacy statements)
- more elaborate control-of-flow is required (e.g. when multiple
actions must be nested under the same condition)
It is usually **not** recommended to use rsyslog legacy config format
(those directives starting with a dollar sign). However, a few
settings and modules have not yet been converted to RainerScript. In
those cases, the legacy syntax must be used.
Comments
--------
There are two types of comments:
- **#-Comments** - start with a hash sign (#) and run to the end of the
line
- **C-style Comments** - start with /\* and end with \*/, just like in
the C programming language. They can be used to comment out multiple
lines at once. Comment nesting is not supported, but #-Comments can be
contained inside a C-style comment.
Processing Order
----------------
Directives are processed from the top of rsyslog.conf to the bottom.
Order matters. For example, if you stop processing of a message,
obviously all statements after the stop statement are never evaluated.
Flow Control Statements
~~~~~~~~~~~~~~~~~~~~~~~
Flow control is provided by:
- :doc:`Control Structures <../rainerscript/control_structures>`
- :doc:`Filter Conditions <filters>`
Data Manipulation Statements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Data manipulation is achieved by **set**, **unset** and **reset** statements
which are :doc:`documented here in detail <../rainerscript/variable_property_types>`.
Inputs
------
Every input requires an input module to be loaded and a listener defined
for it. Full details can be found inside the :doc:`rsyslog
modules <modules/index>` documentation. Once loaded, inputs
are defined via the **input()** object.
Outputs
-------
Outputs are also called "actions". A small set of actions is pre-loaded
(like the output file writer, which is used in almost every
rsyslog.conf), others must be loaded just like inputs.
An action is invoked via the **action(type="type" ...)** object. Type is
mandatory and must contain the name of the plugin to be called (e.g.
"omfile" or "ommongodb"). Other parameters may be present. Their type and
use depends on the output plugin in question.
Rulesets and Rules
------------------
Rulesets and rules form the basis of rsyslog processing. In short, a
rule is a way how rsyslog shall process a specific message. Usually,
there is a type of filter (if-statement) in front of the rule. Complex
nesting of rules is possible, much like in a programming language.
Rulesets are containers for rules. A single ruleset can contain many
rules. In the programming language analogy, one may think of a ruleset
like being a program. A ruleset can be "bound" (assigned) to a specific
input. In the analogy, this means that when a message comes in via that
input, the "program" (ruleset) bound to it will be executed (but not any
other!).
There is detailed documentation available for
:doc:`rsyslog rulesets <../concepts/multi_ruleset>`.
For quick reference, rulesets are defined as follows:
::
ruleset(name="rulesetname") {
action(type="omfile" file="/path/to/file")
action(type="..." ...)
/* and so on... */
}
|
