Filters

• 1: Using filters
• 2: Combining filters with boolean operators
• 3: Comparing macro values in filters
• 4: Using wildcards, special characters, and regular expressions in filters
• 5: Tagging messages
• 6: Filter functions
• 6.1: facility()
• 6.2: filter()
• 6.3: host()
• 6.4: in-list()
• 6.5: level() or priority()
• 6.6: match()
• 6.7: message()
• 6.8: netmask()
• 6.9: netmask6()
• 6.10: program()
• 6.11: rate-limit()
• 6.11.1: Options of rate-limit() filter
• 6.12: source()
• 6.13: tags()

1 - Using filters

Filters perform log routing: 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.conf 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);
    };

2 - Combining filters with boolean operators

When a log statement includes multiple filter statements, AxoSyslog 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), or optionally to the content of any other macro. The template() parameter of the match function can be used to run a filter against a combination of macros. For details on using the match() filter function, see match().

3 - Comparing macro values in filters

In AxoSyslog you can 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. For details on macros and templates, see Customize message format using macros and templates.

Use the following syntax to compare macro values or templates.

    filter <filter-id>
        {"<macro-or-template>" operator "<value-or-macro-or-template>"};

String and numerical comparison

AxoSyslog versions earlier than 4.0 used separate operators for string comparisons (for example, eq). In version 4.0 and later, you can simply use the mathematical symbols as operators (like ==, !=, >=), and AxoSyslog automatically determines how to compare the arguments from their type. The logic behind that is similar to JavaScript:

• If both sides of the comparisons are strings, then the comparison is string.
• If one of the arguments is numeric, then the comparison is numeric.
• Literal numbers (numbers not enclosed in quotes) are numeric.
• You can explicitly type-cast an argument into a number.

For example:

• if ("${.apache.httpversion}" == 1.0)

  The right side of the == operator is 1.0, which is a floating point literal, so the comparison is numeric.

• if (double("${.apache.httpversion}") == "1.0")

  The left side is explicitly type cast into double, the right side is string (because of the quotes), so the comparison is numeric.

• if ("${.apache.request}" == "/wp-admin/login.php")

  The left side is not type-cast, so it’s a string, the right side is a string, so the comparison is string.

Note: You can still use the old string operators if you want to, they are available for backwards compatibility.

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}" == "${HOST}"};

The following example selects messages with priority level higher than 5.

    filter f_level {"${LEVEL_NUM}" > 5};

Make sure to:

• Enclose macros and templates in double-quotes.
• Use the $ character before macros.

Note that:

• You can use type casting anywhere where you can use templates to apply a type to the result of the template expansion.
• Using comparator operators can be equivalent to using filter functions, but is somewhat slower. For example, using "${HOST}" == "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.

Comparison operators

The following numerical and string comparison operators are available.

4 - 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, AxoSyslog 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 AxoSyslog, 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 AxoSyslog version 3.0 and 3.1. In AxoSyslog 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"));};

5 - Tagging messages

You can label the messages with custom tags. Tags are simple labels, identified by their names, which must be unique. Currently AxoSyslog can tag a message at the following places:

• At the source when the message is received.
  • AxoSyslog automatically adds the .source.<id_of_the_source_statement> tag to every incoming message.
  • You can add custom tag using the tags() option of the source.

  • AxoSyslog 4.7 and newer automatically adds the following tags if it encounters errors when parsing syslog messages.

    • message.utf8_sanitized
    • message.parse_error
    • syslog.missing_pri
    • syslog.missing_timestamp
    • syslog.invalid_hostname
    • syslog.unexpected_framing
    • syslog.rfc3164_missing_header
    • syslog.rfc5424_unquoted_sdata_value
• When the message matches a pattern in the pattern database. For details on using the pattern database, see Using pattern databases, for details on creating tags in the pattern database, see The pattern database format.
• Tags can be also added and deleted using rewrite rules. For details, see Adding and deleting tags.

You can use the tags() filter to select only specific messages.

• Tagging messages and also filtering on the tags is very fast, much faster than other types of filters.
• Tags are available locally, that is, if you add tags to a message on the client, these tags will not be available on the server.
• To include the tags in the message, use the ${TAGS} macro in a template. Alternatively, if you are using the IETF-syslog message format, you can include the ${TAGS} macro in the .SDATA.meta part of the message. Note that the ${TAGS} macro is available only in AxoSyslog 3.1.1 and later.

For an example on tagging, see Example: Adding tags and filtering messages with tags.

6 - Filter functions

The following functions may be used in the filter statement, as described in Filters.

Filter functions available in AxoSyslog

6.1 - facility()

Description: Match messages having one of the listed facility codes.

The facility() filter accepts both the name and the numerical code of the facility or the importance level. Facility codes 0-23 are predefined and can be referenced by their usual name. Facility codes above 24 are not defined.

You can use the facility filter the following ways:

• Use a single facility name, for example, facility(user)

• Use a single facility code, for example, facility(1)

• Use a facility range (works only with facility names), for example, facility(local0..local5)

The AxoSyslog application recognizes the following facilities: (Note that some of these facilities are available only on specific platforms.)

syslog Message Facilities recognized by the facility() filter

6.2 - filter()

Description: Call another filter rule and evaluate its value. For example:

   filter demo_filter { host("example") and match("deny" value("MESSAGE")) };
    filter inverted_demo_filter { not filter(demo_filter) }

6.3 - host()

Description: Match messages by using a regular expression against the hostname field of log messages. Note that you can filter only on the actual content of the HOST field of the message (or what it was rewritten to). That is, AxoSyslog will compare the filter expression to the content of the ${HOST} macro. This means that for the IP address of a host will not match, even if the IP address and the hostname field refers to the same host. To filter on IP addresses, use the netmask() filter.

   filter demo_filter { host("example") };

6.4 - in-list()

Description: Matches the value of the specified field to a list stored in a file, allowing you to do simple, file-based black- and whitelisting. The file must be a plain-text file, containing one entry per line.

The AxoSyslog application loads the entire file, and compares the value of the specified field (for example, ${PROGRAM}) to entries in the file. When you use the in-list() filter, note the following points:

• Comparing the values is case-sensitive.
• Only exact matches are supported, partial and substring matches are not.
• If you modify the list file, reload the configuration of AxoSyslog for the changes to take effect.
• Make sure that there is an empty line in the file after the last entry. If the last entry is the last line, it will be excluded from the list.

Available in AxoSyslog 3.5 and later.

Example: Selecting messages using the in-list() filter

Create a text file that contains the programs (as in the ${PROGRAM} field of their log messages) you want to select. For example, you want to forward only the logs of a few applications from a host: kernel, sshd, and sudo. Create the /etc/syslog-ng/programlist.list file with the following contents. Note the empty line after the last entry.

kernel
sshd
sudo

The following filter selects only the messages of the listed applications:

   filter f_whitelist { in-list("/etc/syslog-ng/programlist.list", value("PROGRAM")); };

Create the appropriate sources and destinations for your environment, then create a log path that uses the previous filter to select only the log messages of the applications you need:

   log {
        source(s_all);
        filter(f_whitelist);
        destination(d_logserver); };

To create a blacklist filter, simply negate the in-list() filter:

   filter f_blacklist { not in-list("/etc/syslog-ng/programlist.list", value("PROGRAM")); };

6.5 - level() or priority()

Description: The level() filter selects messages corresponding to a single importance level, or a level-range. To select messages of a specific level, use the name of the level as a filter parameter, for example, use the following to select warning messages:

   level(warning)

To select a range of levels, include the beginning and the ending level in the filter, separated with two dots (..). For example, to select every message of error or higher level, use the following filter:

   level(err..emerg)

The level() filter accepts the following levels: emerg, alert, crit, err, warning, notice, info, debug.

6.6 - match()

Description: Match a regular expression to the headers and the message itself (that is, the values returned by the MSGHDR and MSG macros). Note that in AxoSyslog version 2.1 and earlier, the match() filter was applied only to the text of the message, excluding the headers. This functionality has been moved to the message() filter.

To limit the scope of the match to a specific part of the message (identified with a macro), use the match(regexp value("MACRO")) syntax. Do not include the $ sign in the parameter of the value() option.

The value() parameter accepts both built-in macros and user-defined ones created with a parser or using a pattern database. For details on macros and parsers, see Templates and macros, Parsing messages with comma-separated and similar values, and Using parser results in filters and templates.

Starting with version 3.22, the match() filter can work on templates as well. This means that you can a match against an expression combined of macros, instead of a single macro. Note that when using a template, you must reference macros with the $ sign (unlike when using the value() parameter). For example:

   match("^my-regular-expression" template("${HOST}|${PROGRAM}${PID}|${MESSAGE}"));

Using a template with a single macro is equivalent with using the value() parameter. For example, the following two lines are equivalent:

   match("^my-regular-expression" value("MESSAGE"));
    match("^my-regular-expression" template("${MESSAGE}"));

6.7 - message()

Description: Match a regular expression to the text of the log message, excluding the headers (that is, the value returned by the MSG macros). Note that in syslog-ng version 2.1 and earlier, this functionality was performed by the match() filter.

6.8 - netmask()

Description: Select only messages sent by a host whose IP address belongs to the specified IPv4 subnet. Note that this filter checks the IP address of the last-hop relay (the host that actually sent the message to AxoSyslog), not the contents of the HOST field of the message. You can use both the dot-decimal and the CIDR notation to specify the netmask. For example, 192.168.5.0/255.255.255.0 or 192.168.5.0/24. To filter IPv6 addresses, see netmask6().

6.9 - netmask6()

Description: Select only messages sent by a host whose IP address belongs to the specified IPv6 subnet. Note that this filter checks the IP address of the last-hop relay (the host that actually sent the message to AxoSyslog), not the contents of the HOST field of the message. You can use both the regular and the compressed format to specify the IP address, for example, 1080:0:0:0:8:800:200C:417A or 1080::8:800:200C:417A. If you do not specify the address, localhost is used.

Use the netmask (also called prefix) to specify how many of the leftmost bits of the address comprise the netmask (values 1-128 are valid). For example, the following specify a 60-bit prefix: 12AB:0000:0000:CD30:0000:0000:0000:0000/60 or 12AB::CD30:0:0:0:0/60. Note that if you set an IP address and a prefix, AxoSyslog will ignore the bits of the address after the prefix. To filter IPv4 addresses, see netmask().

The netmask6() filter is available in AxoSyslog 3.7 and later.

6.10 - program()

Description: Match messages by using a regular expression against the program name field of log messages.

6.11 - rate-limit()

Description: Limits messages rate based on arbitrary keys in each message. The key will be resolved using the key() option. Each resolution will be allowed to have the number of messages each second, set by the rate() option. For example if key($HOST) and rate(5000) are set, and there are 2 hosts sending messages to AxoSyslog, a total of 10000 messages will be allowed by the rate-limit() filter, 5000 from the first and 5000 from the second host. If key() was not set instead, then 5000 messages would be allowed each second, regardless of their content.

Example: Using the rate-limit() filter

The following example depicts the scenario described in the description part of this section.

   filter f_rate_limit {
                    rate-limit(
                    key("$HOST")
                    rate(5000)
                    );
                };

6.11.1 - Options of rate-limit() filter

The rate-limit() filter has the following options.

key()

Description: The resolved template, that will be used to create unique rate-limit token buckets. In AxoSyslog version 4.4 and earlier, the name of this option was template().

rate()

Description: The number of messages for each unique macro resolution, that will be let through (matched) by the filter each second.

6.12 - source()

Description: Select messages of a source statement. This filter can be used in embedded log statements if the parent statement contains multiple source groups — only messages originating from the selected source group are sent to the destination of the embedded log statement.

6.13 - tags()

Description: Select messages labeled with the specified tag. Every message automatically has the tag of its source in .source.<id_of_the_source_statement> format. This option is available only in AxoSyslog 3.1 and later.

Example: Adding tags and filtering messages with tags

   source s_tcp {
        network(ip(192.168.1.1) port(1514) tags("tcp", "router"));
    };

Use the tags() option of the filters to select only specific messages:

   filter f_tcp {
        tags(".source.s_tcp");
    };
    
    filter f_router {
        tags("router");
    };

   filter f_tag_filter {tags(".classifier.system");};