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
|
******************************************
omruleset: ruleset output/including module
******************************************
=========================== ===========================================================================
**Module Name:** **omruleset**
**Author:** `Rainer Gerhards <https://rainer.gerhards.net/>`_ <rgerhards@adiscon.com>
=========================== ===========================================================================
.. warning::
This module is outdated and only provided to support configurations that
already use it. **Do no longer use it in new configurations.** It has
been replaced by the much more efficient `"call" RainerScript
statement <rainerscript_call.html>`_. The "call" statement supports
everything omruleset does, but in an easier to use way.
**Available Since**: 5.3.4
**Deprecated in**: 7.2.0+
Purpose
=======
This is a very special "output" module. It permits to pass a message
object to another rule set. While this is a very simple action, it
enables very complex configurations, e.g. it supports high-speed "and"
conditions, sending data to the same file in a non-racy way,
include-ruleset functionality as well as some high-performance
optimizations (in case the rule sets have the necessary queue
definitions).
While it leads to a lot of power, this output module offers seemingly
easy functionality. The complexity (and capabilities) arise from how
everything can be combined.
With this module, a message can be sent to processing to another
ruleset. This is somewhat similar to a "#include" in the C programming
language. However, one needs to keep on the mind that a ruleset can
contain its own queue and that a queue can run in various modes.
Note that if no queue is defined in the ruleset, the message is enqueued
into the main message queue. This most often is not optimal and means
that message processing may be severely deferred. Also note that when the
ruleset's target queue is full and no free space can be acquired within
the usual timeout, the message object may actually be lost. This is an
extreme scenario, but users building an audit-grade system need to know
this restriction. For regular installations, it should not really be
relevant.
**At minimum, be sure you understand the**
:doc:`$RulesetCreateMainQueue <../ruleset/rsconf1_rulesetcreatemainqueue>`
**directive as well as the importance of statement order in rsyslog.conf
before using omruleset!**
**Recommended Use:**
- create rulesets specifically for omruleset
- create these rulesets with their own main queue
- decent queueing parameters (sizes, threads, etc) should be used for
the ruleset main queue. If in doubt, use the same parameters as for
the overall main queue.
- if you use multiple levels of ruleset nesting, double check for
endless loops - the rsyslog engine does not detect these
|FmtObsoleteName| directives
============================
.. note::
Parameter names are case-insensitive.
- **$ActionOmrulesetRulesetName** ruleset-to-submit-to
This directive specifies the name of the ruleset that the message
provided to omruleset should be submitted to. This ruleset must
already have been defined. Note that the directive is automatically
reset after each :omruleset: action and there is no default. This is
done to prevent accidental loops in ruleset definition, what can
happen very quickly. The :omruleset: action will NOT be honored if no
ruleset name has been defined. As usual, the ruleset name must be
specified in front of the action that it modifies.
Examples
========
Ruleset for Write-to-file action
--------------------------------
This example creates a ruleset for a write-to-file action. The idea here
is that the same file is written based on multiple filters, problems
occur if the file is used together with a buffer. That is because file
buffers are action-specific, and so some partial buffers would be
written. With omruleset, we create a single action inside its own
ruleset and then pass all messages to it whenever we need to do so. Of
course, such a simple situation could also be solved by a more complex
filter, but the method used here can also be utilized in more complex
scenarios (e.g. with multiple listeners). The example tries to keep it
simple. Note that we create a ruleset-specific main queue (for
simplicity with the default main queue parameters) in order to avoid
re-queueing messages back into the main queue.
.. code-block:: none
$ModLoad omruleset # define ruleset for commonly written file
$RuleSet CommonAction
$RulesetCreateMainQueue on
*.* /path/to/file.log
#switch back to default ruleset
$ruleset RSYSLOG_DefaultRuleset
# begin first action
# note that we must first specify which ruleset to use for omruleset:
$ActionOmrulesetRulesetName CommonAction
mail.info :omruleset:
# end first action
# begin second action
# note that we must first specify which ruleset to use for omruleset:
$ActionOmrulesetRulesetName CommonAction
:FROMHOST, isequal, "myhost.example.com" :omruleset:
#end second action
# of course, we can have "regular" actions alongside :omrulset: actions
*.* /path/to/general-message-file.log
High-performance filter condition
---------------------------------
The next example is used to create a high-performance nested and filter
condition. Here, it is first checked if the message contains a string
"error". If so, the message is forwarded to another ruleset which then
applies some filters. The advantage of this is that we can use
high-performance filters where we otherwise would need to use the (much
slower) expression-based filters. Also, this enables pipeline
processing, in that second ruleset is executed in parallel to the first
one.
.. code-block:: none
$ModLoad omruleset
# define "second" ruleset
$RuleSet nested
$RulesetCreateMainQueue on
# again, we use our own queue
mail.* /path/to/mailerr.log
kernel.* /path/to/kernelerr.log
auth.* /path/to/autherr.log
#switch back to default ruleset
$ruleset RSYSLOG_DefaultRuleset
# begin first action - here we filter on "error"
# note that we must first specify which ruleset to use for omruleset:
$ActionOmrulesetRulesetName nested
:msg, contains, "error" :omruleset:
#end first action
# begin second action - as an example we can do anything else in
# this processing. Note that these actions are processed concurrently
# to the ruleset "nested"
:FROMHOST, isequal, "myhost.example.com" /path/to/host.log
#end second action
# of course, we can have "regular" actions alongside :omrulset: actions
*.* /path/to/general-message-file.log
Caveats/Known Bugs
==================
The current configuration file language is not really adequate for a
complex construct like omruleset. Unfortunately, more important work is
currently preventing me from redoing the config language. So use extreme
care when nesting rulesets and be sure to test-run your config before
putting it into production, ensuring you have a sufficiently large probe
of the traffic run over it. If problems arise, the `rsyslog debug
log <troubleshoot.html>`_ is your friend.
|
