syslog-ng Premium Edition 7.0.14 - Administration Guide

Preface Introduction to syslog-ng The concepts of syslog-ng Installing syslog-ng The syslog-ng PE quick-start guide The syslog-ng PE configuration file Collecting log messages — sources and source drivers
How sources work default-network-drivers: Receive and parse common syslog messages internal: Collecting internal messages file: Collecting messages from text files wildcard-file: Collecting messages from multiple text files linux-audit: Collecting messages from Linux audit logs network: Collecting messages using the RFC3164 protocol (network() driver) osquery: Collect and parse osquery result logs pipe: Collecting messages from named pipes program: Receiving messages from external applications python: writing server-style Python sources python-fetcher: writing fetcher-style Python sources snmptrap: Read Net-SNMP traps sun-streams: Collecting messages on Sun Solaris syslog: Collecting messages using the IETF syslog protocol (syslog() driver) system: Collecting the system-specific log messages of a platform systemd-journal: Collecting messages from the systemd-journal system log storage systemd-syslog: Collecting systemd messages using a socket tcp, tcp6, udp, udp6: Collecting messages from remote hosts using the BSD syslog protocol unix-stream, unix-dgram: Collecting messages from UNIX domain sockets windowsevent: Collecting Windows event logs
Sending and storing log messages — destinations and destination drivers
elasticsearch2: Sending messages directly to Elasticsearch version 2.0 or higher (DEPRECATED) elasticsearch-http: Sending messages to Elasticsearch HTTP Event Collector file: Storing messages in plain-text files hdfs: Storing messages on the Hadoop Distributed File System (HDFS) http: Posting messages over HTTP kafka: Publishing messages to Apache Kafka logstore: Storing messages in encrypted files mongodb: Storing messages in a MongoDB database network: Sending messages to a remote log server using the RFC3164 protocol (network() driver) pipe: Sending messages to named pipes program: Sending messages to external applications python: writing custom Python destinations smtp: Generating SMTP messages (e-mail) from logs splunk-hec: Sending messages to Splunk HTTP Event Collector sql: Storing messages in an SQL database stackdriver: Sending logs to the Google Stackdriver cloud syslog: Sending messages to a remote logserver using the IETF-syslog protocol syslog-ng(): Forward logs to another syslog-ng node tcp, tcp6, udp, udp6: Sending messages to a remote log server using the legacy BSD-syslog protocol (tcp(), udp() drivers) unix-stream, unix-dgram: Sending messages to UNIX domain sockets usertty: Sending messages to a user terminal — usertty() destination Client-side failover
Routing messages: log paths, flags, and filters Global options of syslog-ng PE TLS-encrypted message transfer Advanced Log Transfer Protocol Reliability and minimizing the loss of log messages Manipulating messages parser: Parse and segment structured messages Processing message content with a pattern database Correlating log messages Enriching log messages with external data Monitoring statistics and metrics of syslog-ng Multithreading and scaling in syslog-ng PE Troubleshooting syslog-ng Best practices and examples The syslog-ng manual pages

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 14: Numerical and string comparison operators
Numerical operator String operator Meaning
== 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"));};

Tagging messages

You can label the messages with custom tags. Tags are simple labels, identified by their names, which must be unique. Currently syslog-ng PE can tag a message at two different places:

When syslog-ng receives a message, it automatically adds the .source.<id_of_the_source_statement> tag to the message. Use the tags() option of the source to add custom tags, and the tags() option of the filters to select only specific messages.

NOTE:
  • 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 syslog-ng PE 3.1.1 and later.

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

Related Documents