Using filters
Filters perform log routing within syslog-ng: a message passes the filter if the filter expression is true for the particular message. If a log statement includes filters, the messages are sent to the destinations only if they pass all filters of the log path. For example, a filter can select only the messages originating from a particular host. Complex filters can be created using filter functions and logical boolean expressions.
To define a filter, add a filter statement to the syslog-ng configuration file using the following syntax:
filter <identifier> { <filter_type>("<filter_expression>"); };
Then use the filter in a log path, for example:
log {
source(s1);
filter(<identifier>);
destination(d1); };
You can also define the filter inline. For details, see Defining configuration objects inline.
Example: A simple filter statement
The following filter statement selects the messages that contain the word deny and come from the host example.
filter demo_filter { host("example") and match("deny" value("MESSAGE")) };
log {
source(s1);
filter(demo_filter);
destination(d1); };
The following example does the same, but defines the filter inline.
log {
source(s1);
filter { host("example") and match("deny" value("MESSAGE")) };
destination(d1); };
Combining filters with boolean operators
When a log statement includes multiple filter statements, syslog-ng sends a message to the destination only if all filters are true for the message. In other words, the filters are connected with the logical AND operator. In the following example, no message arrives to the destination, because the filters are exclusive (the hostname of a client cannot be example1 and example2 at the same time):
filter demo_filter1 { host("example1"); };
filter demo_filter2 { host("example2"); };
log {
source(s1); source(s2);
filter(demo_filter1); filter(demo_filter2);
destination(d1); destination(d2); };
To select the messages that come from either host example1 or example2, use a single filter expression:
filter demo_filter { host("example1") or host("example2"); };
log {
source(s1); source(s2);
filter(demo_filter);
destination(d1); destination(d2); };
Use the not operator to invert filters, for example, to select the messages that were not sent by host example1:
filter demo_filter { not host("example1"); };
However, to select the messages that were not sent by host example1 or example2, you have to use the and operator (that's how boolean logic works):
filter demo_filter { not host("example1") and not host("example2"); };
Alternatively, you can use parentheses to avoid this confusion:
filter demo_filter { not (host("example1") or host("example2")); };
For a complete description on filter functions, see Filter functions.
The following filter statement selects the messages that contain the word deny and come from the host example.
filter demo_filter { host("example") and match("deny" value("MESSAGE")); };
The value() parameter of the match function limits the scope of the function to the text part of the message (that is, the part returned by the ${MESSAGE} macro). For details on using the match() filter function, see match().
TIP: Filters are often used together with log path flags. For details, see Log path flags.
Comparing macro values in filters
Starting with syslog-ng PE version 4 F1, it is also possible to compare macro values and templates as numerical and string values. String comparison is alphabetical: it determines if a string is alphabetically greater or equal to another string. Use the following syntax to compare macro values or templates. For details on macros and templates, see Customizing message format using macros and templates.
filter <filter-id>
{"<macro-or-template>" operator "<value-or-macro-or-template>"};
Example: Comparing macro values in filters
The following expression selects log messages containing a PID (that is, ${PID} macro is not empty):
filter f_pid {"${PID}" !=""};
The following expression selects log messages that do not contain a PID. Also, it uses a template as the left argument of the operator and compares the values as strings:
filter f_pid {"${HOST}${PID}" eq "${HOST}"};
The following example selects messages with priority level 4 or higher.
filter f_level {"${LEVEL_NUM}" > "5"};
Note that:
-
The macro or template must be enclosed in double-quotes.
-
The $ character must be used before macros.
-
Using comparator operators can be equivalent to using filter functions, but is somewhat slower. For example, using "${HOST}" eq "myhost" is equivalent to using host("myhost" type(string)).
-
You can use any macro in the expression, including user-defined macros from parsers and results of pattern database classifications.
-
The results of filter functions are boolean values, so they cannot be compared to other values.
-
You can use boolean operators to combine comparison expressions.
The following operators are available:
Table 13: Numerical and string comparison operators
| == |
eq |
Equals |
| != |
ne |
Not equal to |
| > |
gt |
Greater than |
| < |
lt |
Less than |
| >= |
ge |
Greater than or equal |
| =< |
le |
Less than or equal |
Using wildcards, special characters, and regular expressions in filters
The host(), match(), and program() filter functions accept regular expressions as parameters. The exact type of the regular expression to use can be specified with the type() option. By default, syslog-ng PE uses PCRE regular expressions.
In regular expressions, the asterisk (*) character means 0, 1 or any number of the previous expression. For example, in the f*ilter expression the asterisk means 0 or more f letters. This expression matches for the following strings: ilter, filter, ffilter, and so on. To achieve the wildcard functionality commonly represented by the asterisk character in other applications, use .* in your expressions, for example, f.*ilter.
Alternatively, if you do not need regular expressions, only wildcards, use type(glob) in your filter:
Example: Filtering with widcards
The following filter matches on hostnames starting with the myhost string, for example, on myhost-1, myhost-2, and so on.
filter f_wildcard {host("myhost*" type(glob));};
For details on using regular expressions in syslog-ng PE, see Using wildcards, special characters, and regular expressions in filters.
To filter for special control characters like the carriage return (CR), use the \r escape prefix in syslog-ng PE version 3.0 and 3.1. In syslog-ng PE 3.2 and later, you can also use the \x escape prefix and the ASCII code of the character. For example, to filter on carriage returns, use the following filter:
filter f_carriage_return {match("\x0d" value ("MESSAGE"));};
