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
|
Basic Structure
===============
This page introduces the core concepts and structure of rsyslog configuration.
Rsyslog is best thought of as a **highly extensible logging and event
processing framework**. While the general message flow is fixed, almost every
aspect of its processing pipeline can be customized by configuring rsyslog
objects.
Message Flow Overview
---------------------
At a high level, rsyslog processes messages in three main stages:
1. **Inputs**: Messages are received from input modules (e.g., `imuxsock` for
system logs or `imtcp` for TCP-based logging).
2. **Rulesets**: Each message is passed through one or more rulesets. A
ruleset contains a sequence of rules, each with a filter and associated
actions.
3. **Actions (Outputs)**: When a rule matches, its actions are executed.
Actions determine what to do with the message: write to a file, forward to a
remote server, insert into a database, or other processing.
.. mermaid::
flowchart LR
A[Input Modules] --> B[Rulesets]
B --> C[Rules: Filter and Action List]
C --> D[Actions and Outputs]
D --> E[File, DB, Remote,<br>Custom Destinations]
Processing Principles
---------------------
Key rules to understand the rsyslog processing model:
- **Rulesets as Entry Points**:
Inputs submit messages to a ruleset.
If no ruleset is explicitly bound, the default ruleset
(`RSYSLOG_DefaultRuleset`) is used.
Additional, custom rulesets can be defined.
- **Rules within Rulesets**:
A ruleset contains zero or more rules (though zero rules makes no sense).
Rules are evaluated **in order, top to bottom**, within the ruleset.
- **Filter and Action Lists**:
A rule consists of a **filter** (evaluated as true/false) and an
**action list**.
When a filter matches, the action list is executed.
If a filter does not match, rsyslog continues with the next rule.
- **Full Evaluation**:
All rules are evaluated unless message processing is explicitly stopped
by a ``stop`` command. ``stop`` immediately halts processing for that message.
- **Action Lists**:
An action list can contain one or multiple actions.
Actions are executed sequentially.
Actions have no filters inside the same list (filters apply only at the
rule level).
.. mermaid::
flowchart TD
Start([Message Entered]) --> CheckFilter1{Filter 1 Match?}
CheckFilter1 -- Yes --> Action1[Execute Action 1]
CheckFilter1 -- No --> CheckFilter2{Filter 2 Match?}
CheckFilter2 -- Yes --> Action2[Execute Action 2]
CheckFilter2 -- No --> End([Processing Ends])
Action1 --> CheckFilter2
Action2 --> End
Configuration File
------------------
By default, rsyslog loads its configuration from ``/etc/rsyslog.conf``.
This file may include other configuration snippets (commonly under
``/etc/rsyslog.d/``).
To specify a different configuration file, use:
.. code-block:: bash
rsyslogd -f /path/to/your-config.conf
Supported Configuration Formats
-------------------------------
Rsyslog historically supported three configuration syntaxes:
1. **RainerScript (modern style)** – **recommended and actively maintained**
This is the current, fully supported configuration format. It is
clean, structured, and best suited for new and complex configurations.
2. **sysklogd style (legacy)** – **deprecated for new configs**
This format is widely known and still functional, but **hard to grasp for
new users**. It remains an option for experienced admins who know it
well or need to maintain older configurations. Example:
.. code-block:: none
mail.info /var/log/mail.log
mail.err @server.example.net
3. **Legacy rsyslog style (dollar-prefix)** – **deprecated**
This format, with directives starting with `$` (e.g.,
`$ActionFileDefaultTemplate`), is fully supported for backward
compatibility but **not recommended for any new configuration**.
Why Prefer RainerScript?
~~~~~~~~~~~~~~~~~~~~~~~~
RainerScript is easier to read and maintain, avoids side effects with
include files, and supports modern features such as structured filters,
templates, and complex control flow.
**For new configurations, always use RainerScript.**
Legacy formats exist only for compatibility with older setups and
distributions.
Example RainerScript rule:
.. code-block:: rsyslog
if $syslogfacility-text == 'mail' and $syslogseverity-text == 'err' then {
action(type="omfile" file="/var/log/mail-errors.log")
}
Comments
--------
Rsyslog supports:
- **# Comments** — start with `#` and extend to the end of the line.
- **C-style Comments** — start with `/*` and end with `*/`.
These can span multiple lines but cannot be nested.
Processing Order
----------------
- Directives are processed **in order from top to bottom** of the
configuration.
- Once a message is stopped via ``stop`` subsequent statements
will not be evaluated for that message.
Flow Control
~~~~~~~~~~~~
- Control structures (if/else, etc.) are available in RainerScript.
- Filters (e.g., `prifilt()`) provide conditional matching for messages.
See :doc:`../rainerscript/control_structures` and :doc:`filters` for details.
Data Manipulation
~~~~~~~~~~~~~~~~~
Data can be modified using the `set`, `unset`, and `reset` statements.
For details, refer to :doc:`../rainerscript/variable_property_types`.
Inputs
------
- Each input requires a dedicated input module.
- Inputs are defined using the `input()` object after loading the module.
Example:
.. code-block:: rsyslog
module(load="imtcp") # Load TCP input module
input(type="imtcp" port="514") # Listen on TCP port 514
See :doc:`modules/index` for the full list of input modules.
Outputs (Actions)
-----------------
- Actions are responsible for output, such as writing to files, databases,
or forwarding to other systems.
- Actions are configured with the `action()` object.
Example:
.. code-block:: rsyslog
action(type="omfile" file="/var/log/messages") # Write to local file
Rulesets and Rules
------------------
- A **ruleset** acts like a "program" for message processing.
- A ruleset can be bound to specific inputs or used as the default.
Example:
.. code-block:: rsyslog
ruleset(name="fileLogging") {
if prifilt("*.info") then {
action(type="omfile" file="/var/log/info.log")
}
}
.. mermaid::
graph TD
Input1[Input: imtcp] --> Ruleset1
Input2[Input: imudp] --> Ruleset2
Ruleset1 --> Action1[omfile]
Ruleset2 --> Action2[omfwd]
Ruleset2 --> Action3[omelasticsearch]
For details, see :doc:`../concepts/multi_ruleset`.
|
