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
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>Filter Conditions - rsyslog.conf</title></head>
<body>
<p>This is a part of the rsyslog.conf documentation.</p>
<a href="rsyslog_conf.html">back</a>
<h2>Filter Conditions</h2>
<p>Rsyslog offers three different types "filter conditions":</p>
<ul>
<li><a href="http://www.rainerscript.com/">RainerScript</a>-based filters</li>
<li>"traditional" severity and facility based selectors</li>
<li>property-based filters</li>
</ul>
<h3>RainerScript-Based Filters</h3>
RainerScript based filters are the prime means of creating complex rsyslog configuration.
The permit filtering on arbitrary complex expressions, which can include boolean,
arithmetic and string operations. They also support full nesting of filters, just
as you know from other scripting environments.
<br>
Scripts based filters are indicated by the keyword "if", as usual.
They have this format:<br>
<br>
if expr then block else block
<br>
"If" and "then" are fixed keywords that mus be present. "expr" is a
(potentially quite complex) expression. So the <a href="expression.html">expression documentation</a> for
details.
The keyword "else" and its associated block is optional. Note that a block can contain either
a single action (chain), or an arbitrary complex script enclosed in curly braces, e.g.:
<br>
<pre>
if $programname == 'prog1' then {
action(type="omfile" file="/var/log/prog1.log")
if $msg contains 'test' then
action(type="omfile" file="/var/log/prog1test.log")
else
action(type="omfile" file="/var/log/prog1notest.log")
}
</pre>
<br>
Other types of filtes can also be combined with the pure RainerScript ones. This makes
it particularly easy to migrate from early config files to RainerScript. Also, the traditional
syslog PRI-based filters are a good and easy to use addition. While they are legacy, we still
recommend there use where they are up to the job. We do NOT, however, recommend property-based
filters any longer. As an example, the following is perfectly valid:
<br>
<pre>
if $fromhost == 'host1' then {
mail.* action(type="omfile" file="/var/log/host1/mail.log")
*.err /var/log/host1/errlog # this is also still valid
#
# more "old-style rules" ...
#
} else {
mail.* action(type="omfile" file="/var/log/mail.log")
*.err /var/log/errlog
#
# more "old-style rules" ...
#
}
</pre>
<br>
Right now, you need to specify numerical values if you would like to
check for facilities and severity. These can be found in <a href="http://www.ietf.org/rfc/rfc3164.txt">RFC 3164</a>.
If you don't like that, you can of course also use the textual property
- just be sure to use the right one. As expression support is enhanced,
this will change. For example, if you would like to filter on message
that have facility local0, start with "DEVNAME" and have either
"error1" or "error0" in their message content, you could use the
following filter:<br>
<br>
<code>
if $syslogfacility-text == 'local0' and $msg
startswith 'DEVNAME' and ($msg contains 'error1' or $msg contains
'error0') then /var/log/somelog<br>
</code>
<br>
Please note that the above <span style="font-weight: bold;">must
all be on one line</span>! And if you would like to store all
messages except those that contain "error1" or "error0", you just need
to add a "not":<br>
<br>
<code>
if $syslogfacility-text == 'local0' and $msg
startswith 'DEVNAME' and <span style="font-weight: bold;">not</span>
($msg contains 'error1' or $msg contains
'error0') then /var/log/somelog<br>
</code>
<br>
If you would like to do case-insensitive comparisons, use
"contains_i" instead of "contains" and "startswith_i" instead of
"startswith".<br>
<br>
Regular expressions are supported via functions (see function list).
<h3>Selectors</h3>
<p><b>Selectors are the traditional way of filtering syslog
messages.</b> They have been kept in rsyslog with their original
syntax, because it is well-known, highly effective and also needed for
compatibility with stock syslogd configuration files. If you just need
to filter based on priority and facility, you should do this with
selector lines. They are <b>not</b> second-class citizens
in rsyslog and offer the best performance for this job.</p>
<p>The selector field itself again consists of two parts, a
facility and a priority, separated by a period (".''). Both parts are
case insensitive and can also be specified as decimal numbers, but
don't do that, you have been warned. Both facilities and priorities are
described in syslog(3). The names mentioned below correspond to the
similar LOG_-values in /usr/include/syslog.h.<br>
<br>
The facility is one of the following keywords: auth, authpriv, cron,
daemon, kern, lpr, mail, mark, news, security (same as auth), syslog,
user, uucp and local0 through local7. The keyword security should not
be used anymore and mark is only for internal use and therefore should
not be used in applications. Anyway, you may want to specify and
redirect these messages here. The facility specifies the subsystem that
produced the message, i.e. all mail programs log with the mail facility
(LOG_MAIL) if they log using syslog.<br>
<br>
The priority is one of the following keywords, in ascending order:
debug, info, notice, warning, warn (same as warning), err, error (same
as err), crit, alert, emerg, panic (same as emerg). The keywords error,
warn and panic are deprecated and should not be used anymore. The
priority defines the severity of the message.<br>
<br>
The behavior of the original BSD syslogd is that all messages of the
specified priority and higher are logged according to the given action.
Rsyslogd behaves the same, but has some extensions.<br>
<br>
In addition to the above mentioned names the rsyslogd(8) understands
the following extensions: An asterisk ("*'') stands for all facilities
or all priorities, depending on where it is used (before or after the
period). The keyword none stands for no priority of the given facility.<br>
<br>
You can specify multiple facilities with the same priority pattern in
one statement using the comma (",'') operator. You may specify as much
facilities as you want. Remember that only the facility part from such
a statement is taken, a priority part would be skipped.</p>
<p>Multiple selectors may be specified for a single action using
the semicolon (";'') separator. Remember that each selector in the
selector field is capable to overwrite the preceding ones. Using this
behavior you can exclude some priorities from the pattern.</p>
<p>Rsyslogd has a syntax extension to the original BSD source,
that makes its use more intuitively. You may precede every priority
with an equals sign ("='') to specify only this single priority and
not any of the above. You may also (both is valid, too) precede the
priority with an exclamation mark ("!'') to ignore all that
priorities, either exact this one or this and any higher priority. If
you use both extensions than the exclamation mark must occur before the
equals sign, just use it intuitively.</p>
<h3>Property-Based Filters</h3>
<p>Property-based filters are unique to rsyslogd. They allow to
filter on any property, like HOSTNAME, syslogtag and msg. A list of all
currently-supported properties can be found in the <a href="property_replacer.html">property replacer documentation</a>
(but keep in mind that only the properties, not the replacer is
supported). With this filter, each properties can be checked against a
specified value, using a specified compare operation.</p>
<p>A property-based filter must start with a colon in column 0.
This tells rsyslogd that it is the new filter type. The colon must be
followed by the property name, a comma, the name of the compare
operation to carry out, another comma and then the value to compare
against. This value must be quoted. There can be spaces and tabs
between the commas. Property names and compare operations are
case-sensitive, so "msg" works, while "MSG" is an invalid property
name. In brief, the syntax is as follows:</p>
<p><code><b>:property, [!]compare-operation, "value"</b></code></p>
<p>The following <b>compare-operations</b> are
currently supported:</p>
<table id="table1" border="1" width="100%">
<tbody>
<tr>
<td>contains</td>
<td>Checks if the string provided in value is contained in
the property. There must be an exact match, wildcards are not supported.</td>
</tr>
<tr>
<td>isempty</td>
<td>Checks if the property is empty. The value is discarded. This is
especially useful when working with normalized data, where some fields
may be populated based on normalization result.
Available since 6.6.2.
</tr>
<tr>
<td>isequal</td>
<td>Compares the "value" string provided and the property
contents. These two values must be exactly equal to match. The
difference to contains is that contains searches for the value anywhere
inside the property value, whereas all characters must be identical for
isequal. As such, isequal is most useful for fields like syslogtag or
FROMHOST, where you probably know the exact contents.</td>
</tr>
<tr>
<td>startswith</td>
<td>Checks if the value is found exactly at the beginning
of the property value. For example, if you search for "val" with
<p><code><b>:msg, startswith, "val"</b></code></p>
<p>it will be a match if msg contains "values are in this
message" but it won't match if the msg contains "There are values in
this message" (in the later case, contains would match). Please note
that "startswith" is by far faster than regular expressions. So
it makes very much sense (performance-wise) to use "startswith".</p>
<p>Note: when processing syslog messages, please note that $msg usually
starts with a space. The reason for this is RFC3164. Please read the
<a href="http://www.rsyslog.com/log-normalization-and-the-leading-space/">detail
description</a> of what that means to you. In short, you need to make sure
that you include the first space if you use "startswith", otherwise you will
not get matches.
</td>
</tr>
<tr>
<td>regex</td>
<td>Compares the property against the provided POSIX
BRE regular
expression.</td>
</tr>
<tr>
<td>ereregex</td>
<td>Compares the property against the provided POSIX
ERE regular
expression.</td>
</tr>
</tbody>
</table>
<p>You can use the bang-character (!) immediately in front of a
compare-operation, the outcome of this operation is negated. For
example, if msg contains "This is an informative message", the
following sample would not match:</p>
<p><code><b>:msg, contains, "error"</b></code></p>
<p>but this one matches:</p>
<p><code><b>:msg, !contains, "error"</b></code></p>
<p>Using negation can be useful if you would like to do some
generic processing but exclude some specific events. You can use the
discard action in conjunction with that. A sample would be:</p>
<p><code><b>*.*
/var/log/allmsgs-including-informational.log<br>
:msg, contains, "informational" <font color="#ff0000" size="4">~</font>
<br>
*.* /var/log/allmsgs-but-informational.log</b></code></p>
<p>Do not overlook the red tilde in line 2! In this sample, all
messages are written to the file allmsgs-including-informational.log.
Then, all messages containing the string "informational" are discarded.
That means the config file lines below the "discard line" (number 2 in
our sample) will not be applied to this message. Then, all remaining
lines will also be written to the file allmsgs-but-informational.log.</p>
<p><b>Value</b> is a quoted string. It supports some
escape sequences:</p>
<p>\" - the quote character (e.g. "String with \"Quotes\"")<br>
\\ - the backslash character (e.g. "C:\\tmp")</p>
<p>Escape sequences always start with a backslash. Additional
escape sequences might be added in the future. Backslash characters <b>must</b>
be escaped. Any other sequence then those outlined above is invalid and
may lead to unpredictable results.</p>
<p>Probably, "msg" is the most prominent use case of property
based filters. It is the actual message text. If you would like to
filter based on some message content (e.g. the presence of a specific
code), this can be done easily by:</p>
<p><code><b>:msg, contains, "ID-4711"</b></code></p>
<p>This filter will match when the message contains the string
"ID-4711". Please note that the comparison is case-sensitive, so it
would not match if "id-4711" would be contained in the message.</p>
<p><code><b>:msg, regex, "fatal .* error"</b></code></p>
<p>This filter uses a POSIX regular expression. It matches when
the
string contains the words "fatal" and "error" with anything in between
(e.g. "fatal net error" and "fatal lib error" but not "fatal error" as
two spaces are required by the regular expression!).</p>
<p>Getting property-based filters right can sometimes be
challenging. In order to help you do it with as minimal effort as
possible, rsyslogd spits out debug information for all property-based
filters during their evaluation. To enable this, run rsyslogd in
foreground and specify the "-d" option.</p>
<p>Boolean operations inside property based filters (like
'message contains "ID17" or message contains "ID18"') are currently not
supported (except for "not" as outlined above). Please note that while
it is possible to query facility and severity via property-based
filters, it is far more advisable to use classic selectors (see above)
for those cases.</p>
<p>[<a href="manual.html">manual index</a>]
[<a href="rsyslog_conf.html">rsyslog.conf</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 © 2008 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>
|
