1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
<html><head><title>Filter Conditions - rsyslog.conf</title></head>
4
<p>This is a part of the rsyslog.conf documentation.</p>
5
<a href="rsyslog_conf.html">back</a>
6
<h2>Filter Conditions</h2>
7
<p>Rsyslog offers four different types "filter conditions":</p>
9
<li>BSD-style blocks</li>
10
<li>"traditional" severity and facility based selectors</li>
11
<li>property-based filters</li>
12
<li>expression-based filters</li>
15
<p>Rsyslogd supports BSD-style blocks inside rsyslog.conf. Each
16
block of lines is separated from the previous block by a program or
17
hostname specification. A block will only log messages corresponding to
18
the most recent program and hostname specifications given. Thus, a
19
block which selects ‘ppp’ as the program, directly followed by a block
20
that selects messages from the hostname ‘dialhost’, then the second
21
block will only log messages from the ppp program on dialhost.
23
<p>A program specification is a line beginning with ‘!prog’ and
24
the following blocks will be associated with calls to syslog from that
25
specific program. A program specification for ‘foo’ will also match any
26
message logged by the kernel with the prefix ‘foo: ’. Alternatively, a
27
program specification ‘-foo’ causes the following blocks to be applied
28
to messages from any program but the one specified. A hostname
29
specification of the form ‘+hostname’ and the following blocks will be
30
applied to messages received from the specified hostname.
31
Alternatively, a hostname specification ‘-hostname’ causes the
32
following blocks to be applied to messages from any host but the one
33
specified. If the hostname is given as ‘@’, the local hostname will be
34
used. (NOT YET IMPLEMENTED) A program or hostname specification may be
35
reset by giving the program or hostname as ‘*’.</p>
36
<p>Please note that the "#!prog", "#+hostname" and "#-hostname"
37
syntax available in BSD syslogd is not supported by rsyslogd. By
38
default, no hostname or program is set.</p>
40
<p><b>Selectors are the traditional way of filtering syslog
41
messages.</b> They have been kept in rsyslog with their original
42
syntax, because it is well-known, highly effective and also needed for
43
compatibility with stock syslogd configuration files. If you just need
44
to filter based on priority and facility, you should do this with
45
selector lines. They are <b>not</b> second-class citizens
46
in rsyslog and offer the best performance for this job.</p>
47
<p>The selector field itself again consists of two parts, a
48
facility and a priority, separated by a period (".''). Both parts are
49
case insensitive and can also be specified as decimal numbers, but
50
don't do that, you have been warned. Both facilities and priorities are
51
described in rsyslog(3). The names mentioned below correspond to the
52
similar LOG_-values in /usr/include/rsyslog.h.<br>
54
The facility is one of the following keywords: auth, authpriv, cron,
55
daemon, kern, lpr, mail, mark, news, security (same as auth), syslog,
56
user, uucp and local0 through local7. The keyword security should not
57
be used anymore and mark is only for internal use and therefore should
58
not be used in applications. Anyway, you may want to specify and
59
redirect these messages here. The facility specifies the subsystem that
60
produced the message, i.e. all mail programs log with the mail facility
61
(LOG_MAIL) if they log using syslog.<br>
63
The priority is one of the following keywords, in ascending order:
64
debug, info, notice, warning, warn (same as warning), err, error (same
65
as err), crit, alert, emerg, panic (same as emerg). The keywords error,
66
warn and panic are deprecated and should not be used anymore. The
67
priority defines the severity of the message.<br>
69
The behavior of the original BSD syslogd is that all messages of the
70
specified priority and higher are logged according to the given action.
71
Rsyslogd behaves the same, but has some extensions.<br>
73
In addition to the above mentioned names the rsyslogd(8) understands
74
the following extensions: An asterisk ("*'') stands for all facilities
75
or all priorities, depending on where it is used (before or after the
76
period). The keyword none stands for no priority of the given facility.<br>
78
You can specify multiple facilities with the same priority pattern in
79
one statement using the comma (",'') operator. You may specify as much
80
facilities as you want. Remember that only the facility part from such
81
a statement is taken, a priority part would be skipped.</p>
82
<p>Multiple selectors may be specified for a single action using
83
the semicolon (";'') separator. Remember that each selector in the
84
selector field is capable to overwrite the preceding ones. Using this
85
behavior you can exclude some priorities from the pattern.</p>
86
<p>Rsyslogd has a syntax extension to the original BSD source,
87
that makes its use more intuitively. You may precede every priority
88
with an equation sign ("='') to specify only this single priority and
89
not any of the above. You may also (both is valid, too) precede the
90
priority with an exclamation mark ("!'') to ignore all that
91
priorities, either exact this one or this and any higher priority. If
92
you use both extensions than the exclamation mark must occur before the
93
equation sign, just use it intuitively.</p>
94
<h3>Property-Based Filters</h3>
95
<p>Property-based filters are unique to rsyslogd. They allow to
96
filter on any property, like HOSTNAME, syslogtag and msg. A list of all
97
currently-supported properties can be found in the <a href="property_replacer.html">property replacer documentation</a>
98
(but keep in mind that only the properties, not the replacer is
99
supported). With this filter, each properties can be checked against a
100
specified value, using a specified compare operation.</p>
101
<p>A property-based filter must start with a colon in column 0.
102
This tells rsyslogd that it is the new filter type. The colon must be
103
followed by the property name, a comma, the name of the compare
104
operation to carry out, another comma and then the value to compare
105
against. This value must be quoted. There can be spaces and tabs
106
between the commas. Property names and compare operations are
107
case-sensitive, so "msg" works, while "MSG" is an invalid property
108
name. In brief, the syntax is as follows:</p>
109
<p><code><b>:property, [!]compare-operation, "value"</b></code></p>
110
<p>The following <b>compare-operations</b> are
111
currently supported:</p>
112
<table id="table1" border="1" width="100%">
116
<td>Checks if the string provided in value is contained in
117
the property. There must be an exact match, wildcards are not supported.</td>
121
<td>Compares the "value" string provided and the property
122
contents. These two values must be exactly equal to match. The
123
difference to contains is that contains searches for the value anywhere
124
inside the property value, whereas all characters must be identical for
125
isequal. As such, isequal is most useful for fields like syslogtag or
126
FROMHOST, where you probably know the exact contents.</td>
130
<td>Checks if the value is found exactly at the beginning
131
of the property value. For example, if you search for "val" with
132
<p><code><b>:msg, startswith, "val"</b></code></p>
133
<p>it will be a match if msg contains "values are in this
134
message" but it won't match if the msg contains "There are values in
135
this message" (in the later case, contains would match). Please note
136
that "startswith" is by far faster than regular expressions. So even
137
once they are implemented, it can make very much sense
138
(performance-wise) to use "startswith".</p>
143
<td>Compares the property against the provided POSIX
149
<td>Compares the property against the provided POSIX
155
<p>You can use the bang-character (!) immediately in front of a
156
compare-operation, the outcome of this operation is negated. For
157
example, if msg contains "This is an informative message", the
158
following sample would not match:</p>
159
<p><code><b>:msg, contains, "error"</b></code></p>
160
<p>but this one matches:</p>
161
<p><code><b>:msg, !contains, "error"</b></code></p>
162
<p>Using negation can be useful if you would like to do some
163
generic processing but exclude some specific events. You can use the
164
discard action in conjunction with that. A sample would be:</p>
166
/var/log/allmsgs-including-informational.log<br>
167
:msg, contains, "informational" <font color="#ff0000" size="4">~</font>
169
*.* /var/log/allmsgs-but-informational.log</b></code></p>
170
<p>Do not overlook the red tilde in line 2! In this sample, all
171
messages are written to the file allmsgs-including-informational.log.
172
Then, all messages containing the string "informational" are discarded.
173
That means the config file lines below the "discard line" (number 2 in
174
our sample) will not be applied to this message. Then, all remaining
175
lines will also be written to the file allmsgs-but-informational.log.</p>
176
<p><b>Value</b> is a quoted string. It supports some
177
escape sequences:</p>
178
<p>\" - the quote character (e.g. "String with \"Quotes\"")<br>
179
\\ - the backslash character (e.g. "C:\\tmp")</p>
180
<p>Escape sequences always start with a backslash. Additional
181
escape sequences might be added in the future. Backslash characters <b>must</b>
182
be escaped. Any other sequence then those outlined above is invalid and
183
may lead to unpredictable results.</p>
184
<p>Probably, "msg" is the most prominent use case of property
185
based filters. It is the actual message text. If you would like to
186
filter based on some message content (e.g. the presence of a specific
187
code), this can be done easily by:</p>
188
<p><code><b>:msg, contains, "ID-4711"</b></code></p>
189
<p>This filter will match when the message contains the string
190
"ID-4711". Please note that the comparison is case-sensitive, so it
191
would not match if "id-4711" would be contained in the message.</p>
192
<p><code><b>:msg, regex, "fatal .* error"</b></code></p>
193
<p>This filter uses a POSIX regular expression. It matches when
195
string contains the words "fatal" and "error" with anything in between
196
(e.g. "fatal net error" and "fatal lib error" but not "fatal error" as
197
two spaces are required by the regular expression!).</p>
198
<p>Getting property-based filters right can sometimes be
199
challenging. In order to help you do it with as minimal effort as
200
possible, rsyslogd spits out debug information for all property-based
201
filters during their evaluation. To enable this, run rsyslogd in
202
foreground and specify the "-d" option.</p>
203
<p>Boolean operations inside property based filters (like
204
'message contains "ID17" or message contains "ID18"') are currently not
205
supported (except for "not" as outlined above). Please note that while
206
it is possible to query facility and severity via property-based
207
filters, it is far more advisable to use classic selectors (see above)
209
<h3>Expression-Based Filters</h3>
210
Expression based filters allow
211
filtering on arbitrary complex expressions, which can include boolean,
212
arithmetic and string operations. Expression filters will evolve into a
213
full configuration scripting language. Unfortunately, their syntax will
214
slightly change during that process. So if you use them now, you need
215
to be prepared to change your configuration files some time later.
216
However, we try to implement the scripting facility as soon as possible
217
(also in respect to stage work needed). So the window of exposure is
218
probably not too long.<br>
220
Expression based filters are indicated by the keyword "if" in column 1
221
of a new line. They have this format:<br>
223
if expr then action-part-of-selector-line<br>
225
"If" and "then" are fixed keywords that mus be present. "expr" is a
226
(potentially quite complex) expression. So the <a href="expression.html">expression documentation</a> for
227
details. "action-part-of-selector-line" is an action, just as you know
228
it (e.g. "/var/log/logfile" to write to that file).<br>
230
A few quick samples:<br>
233
*.* /var/log/file1 # the traditional way<br>
234
if $msg contains 'error' /var/log/errlog # the expression-based way<br>
237
Right now, you need to specify numerical values if you would like to
238
check for facilities and severity. These can be found in <a href="http://www.ietf.org/rfc/rfc3164.txt">RFC 3164</a>.
239
If you don't like that, you can of course also use the textual property
240
- just be sure to use the right one. As expression support is enhanced,
241
this will change. For example, if you would like to filter on message
242
that have facility local0, start with "DEVNAME" and have either
243
"error1" or "error0" in their message content, you could use the
244
following filter:<br>
247
if $syslogfacility-text == 'local0' and $msg
248
startswith 'DEVNAME' and ($msg contains 'error1' or $msg contains
249
'error0') then /var/log/somelog<br>
252
Please note that the above <span style="font-weight: bold;">must
253
all be on one line</span>! And if you would like to store all
254
messages except those that contain "error1" or "error0", you just need
258
if $syslogfacility-text == 'local0' and $msg
259
startswith 'DEVNAME' and <span style="font-weight: bold;">not</span>
260
($msg contains 'error1' or $msg contains
261
'error0') then /var/log/somelog<br>
264
If you would like to do case-insensitive comparisons, use
265
"contains_i" instead of "contains" and "startswith_i" instead of
268
Note that regular expressions are currently NOT
269
supported in expression-based filters. These will be added later when
270
function support is added to the expression engine (the reason is that
271
regular expressions will be a separate loadable module, which requires
272
some more prequisites before it can be implemented).<br>
274
<p>[<a href="manual.html">manual index</a>]
275
[<a href="rsyslog_conf.html">rsyslog.conf</a>]
276
[<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
277
<p><font size="2">This documentation is part of the
278
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
279
Copyright © 2008 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
280
<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL
281
version 2 or higher.</font></p>
added
removed
doc/rsyslog_conf_filter.html
