Chat now with support
Chat with Support

syslog-ng Premium Edition 6.0.18 - Administration Guide

Preface Chapter 1. Introduction to syslog-ng Chapter 2. The concepts of syslog-ng Chapter 3. Installing syslog-ng Chapter 4. The syslog-ng PE quick-start guide Chapter 5. The syslog-ng PE configuration file Chapter 6. Collecting log messages — sources and source drivers Chapter 7. Sending and storing log messages — destinations and destination drivers Chapter 8. Routing messages: log paths, reliability, and filters Chapter 9. Global options of syslog-ng PE Chapter 10. TLS-encrypted message transfer Chapter 11. FIPS-compliant syslog-ng Chapter 12.  Reliable Log Transfer Protocol™ Chapter 13. Reliability and minimizing the loss of log messages Chapter 14. Manipulating messages Chapter 15. Parsing and segmenting structured messages Chapter 16. Processing message content with a pattern database Chapter 17. Statistics and metrics of syslog-ng Chapter 18. Multithreading and scaling in syslog-ng PE Chapter 19. Troubleshooting syslog-ng Chapter 20. Best practices and examples

Using disk-based and memory buffering

The syslog-ng Premium Edition application can store messages on the local hard disk if the destination (for example, the central log server) or the network connection to the destination becomes unavailable. The syslog-ng PE application automatically sends the stored messages to the destination when the connection is reestablished. The disk buffer is used as a queue: when the connection to the destination is reestablished, syslog-ng PE sends the messages to the destination in the order they were received.

NOTE:

Disk-based buffering can be used in conjunction with flow-control. For details on flow-control, see the section called “Managing incoming and outgoing messages with flow-control”.

The following destination drivers can use disk-based buffering: elasticsearch(), elasticsearch2(), hdfs(), kafka(), mongodb(), program(), smtp(), snmp(), sql(), unix-dgram(), and unix-stream(). The network(), syslog(), tcp(), and tcp6() destination drivers can also use disk-based buffering, except when using the udp transport method. (The other destinations or protocols do not provide the necessary feedback mechanisms required for disk-based buffering.)

Every such destination uses a separate disk buffer (similarly to the output buffers controlled by log-fifo-size()). The hard disk space is not pre-allocated, so ensure that there is always enough free space to store the disk buffers even when the disk buffers are full.

If syslog-ng PE is restarted (using the /etc/init.d/syslog-ng restart command, or another appropriate command on your platform), it automatically saves any unsent messages from the disk buffer and the output queue. After the restart, syslog-ng PE sends the saved messages to the destination. In other words, the disk buffer is persistent. The disk buffer is also resistant to syslog-ng PE crashes.

The syslog-ng PE application supports two types of disk buffering: reliable and normal. For details, see the section called “Enabling reliable disk-based buffering” and the section called “Enabling normal disk-based buffering”, respectively.

Message handling and normal disk-based buffering. When you use disk-based buffering, and the reliable() option is set to no, syslog-ng PE handles outgoing messages the following way:

Figure 8.6. Handling outgoing messages in syslog-ng PE

Handling outgoing messages in syslog-ng PE

  • Output queue: Messages from the output queue are sent to the destination (for example, your central log server). The syslog-ng PE application puts the outgoing messages directly into the output queue, unless the output queue is full. By default, the output queue can hold 64 messages (you can adjust it using the quot-size() option).

  • Disk buffer: If the output queue is full, disk-buffering is enabled, and reliable() is set to no, syslog-ng PE puts the outgoing messages into the disk buffer of the destination. (The disk buffer is enabled if the log-disk-fifo-size() parameter of the destination is larger than 0. This option specifies the size of the disk buffer in bytes.)

  • Overflow queue: If the output queue is full and the disk buffer is disabled or full, syslog-ng PE puts the outgoing messages into the overflow queue of the destination. (The overflow queue is identical to the output buffer used by other destinations.) The log-fifo-size() parameter specifies the number of messages stored in the overflow queue. For details on sizing the log-fifo-size() parameter, see also the section called “Managing incoming and outgoing messages with flow-control”.

NOTE:

Using disk buffer can significantly decrease performance.

Message handling and reliable disk-based buffering. When you use disk-based buffering, and the reliable() option is set to yes, syslog-ng PE handles outgoing messages the following way.

The mem-buf-size() option determines when flow-control is triggered. All messages arriving to the log path that includes the destination using the disk-buffer are written into the disk-buffer, until the size of the disk-buffer reaches (disk-buf-size() minus mem-buf-size()). Above that size, messages are written into both the disk-buffer and the memory-buffer, indicating that flow-control needs to slow down the message source. These messages are not taken out from the control window (governed by log-iw-size()), causing the control window to fill up. If the control window is full, the flow-control completely stops reading incoming messages from the source. (As a result, mem-buf-size() must be at least as large as log-iw-size().)

Enabling reliable disk-based buffering

The following destination drivers can use disk-based buffering: elasticsearch(), elasticsearch2(), hdfs(), kafka(), mongodb(), program(), smtp(), snmp(), sql(), unix-dgram(), and unix-stream(). The network(), syslog(), tcp(), and tcp6() destination drivers can also use disk-based buffering, except when using the udp transport method. (The other destinations or protocols do not provide the necessary feedback mechanisms required for disk-based buffering.)

To enable reliable disk-based buffering, use the disk-buffer(reliable(yes)) parameter in the destination. Use reliable disk-based buffering if you do not want to lose logs in case of reload/restart, unreachable destination or syslog-ng PE crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. The filename of the reliable disk buffer file is the following: <syslog-ng path>/var/syslog-ng-00000.rqf.

Example 8.7. Example for using reliable disk-based buffering

destination d_BSD {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-size(10000)
                disk-buf-size(2000000)
                reliable(yes)
            )
        );
}; 

Enabling normal disk-based buffering

The following destination drivers can use disk-based buffering: elasticsearch(), elasticsearch2(), hdfs(), kafka(), mongodb(), program(), smtp(), snmp(), sql(), unix-dgram(), and unix-stream(). The network(), syslog(), tcp(), and tcp6() destination drivers can also use disk-based buffering, except when using the udp transport method. (The other destinations or protocols do not provide the necessary feedback mechanisms required for disk-based buffering.)

To enable normal disk-based buffering, use the disk-buffer(reliable(no)) parameter in the destination. Use normal disk-based buffering if you want a solution that is faster than the reliable disk-based buffering. In this case, disk buffering will be less reliable and it is possible to lose logs in case of syslog-ng PE crash. The filename of the normal disk buffer file is the following: <syslog-ng path>/var/syslog-ng-00000.qf.

It is possible to use this option without using the disk-buffer plugin. In this case, use the log-disk-fifo-size() parameter in the destination.

Example 8.8. Example for using normal disk-based buffering

When using the disk-buffer plugin

destination d_BSD {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-length(10000)
                disk-buf-size(2000000)
                reliable(no)
            )
        );
        }; 

Without disk-buffer plugin

destination d_BSD {
    network(
            "127.0.0.1"
            port(3333)
            log-disk-fifo-size(2000000)
            log-fifo-size(10000)
        );
}; 

Enabling memory buffering

To enable memory buffering, use the log-fifo-size() parameter in the destination. All destination drivers can use memory buffering. Use memory buffering if you want to send logs to destinations where disk-based buffering is not available. Or if you want the fastest solution, and if syslog-ng PE crash or network downtime is never expected. In these cases, losing logs is possible. This solution does not use disk-based buffering, logs are stored only in the memory.

Example 8.9. Example for using memory buffering

destination d_BSD {
    network(
            "127.0.0.1"
            port(3333)
            log-fifo-size(10000)
        );
};

Client-side failover

syslog-ng PE can detect if the remote server of a network destination becomes unaccessible, and start sending messages to a secondary server. Multiple failover servers can be configured, so if the secondary server becomes unaccessible as well, syslog-ng PE will switch to the third server in the list, and so on. If there are no more failover servers left, syslog-ng PE returns to the beginning of a list and attempts to connect to the primary server.

When syslog-ng PE starts up, it will always try to connect to the primary server first, but once it fails over to a secondary server, it will not automatically attempt to return to the primary server even if it becomes available. If syslog-ng PE is restarted, it will attempt to connect the primary server. Reloading the configuration of syslog-ng PE will not cause syslog-ng PE to return to the primary server, unless the configuration of the destination has changed.

If syslog-ng PE uses TLS-encryption to communicate with the remote server, syslog-ng PE checks the certificate of the failover server as well. The certificates of the failover servers should match their domain names or IP addresses — for details, see the section called “Encrypting log messages with TLS”. Note that when mutual authentication is used, the syslog-ng PE client sends the same certificate to every server.

The primary server and the failover servers must be accessible with the same communication method: it is not possible to use different destination drivers or options for the different servers.

NOTE:

Client-side failover works only for TCP-based connections (including TLS-encrypted connections), that is, the syslog() and network() destination drivers (excluding UDP transport).

Client-side failover is not supported in the sql() driver, even though it may use a TCP connection to access a remote database.

For details on configuring failover servers, see the section called “network() destination options” and the section called “syslog() destination options”.

Filters

The following sections describe how to select and filter log messages.

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>"); };

Example 8.10. 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")) };

For the filter to have effect, include it in a log statement:

log {
        source(s1);
        filter(demo_filter);
        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 the section called “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 the section called “match()”.

TIP:

Filters are often used together with log path flags. For details, see the section called “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 the section called “Customizing message format”.

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

Example 8.11. 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"};

The following filter selects messages which have the collector word in the soc@0.device structured data field.

filter f_fwd_collectors {"${.SDATA.soc@0.device}" eq "collector"};

This filter expresison selects messages, which has the FW string in the soc@0.class structured data field.

filter f_debug { match("FW" value(".SDATA.soc@0.class") type("string")); };

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 8.2. 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 POSIX regular expressions.

To use other expression types, add the type() option after the regular expression. For example:

message("^(.+)\\1$" type("pcre"))

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 8.12. 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 the section called “Regular expressions”.

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 8.14, “Adding tags and filtering messages with tags”.

Filter functions

The following functions may be used in the filter statement, as described in the section called “Filters”.

Table 8.3. Filter functions available in syslog-ng PE

Name Description
facility() Filter messages based on the sending facility.
filter() Call another filter function.
host() Filter messages based on the sending host.
inlist() File-based whitelisting and blacklisting.
level() or priority() Filter messages based on their priority.
match() Use a regular expression to filter messages based on a specified header or content field.
message() Use a regular expression to filter messages based on their content.
netmask() Filter messages based on the IP address of the sending host.
program() Filter messages based on the sending application.
source() Select messages of the specified syslog-ng PE source statement.
tags() Select messages having the specified tag.

facility()
Synopsis: facility(<facility-name>) or facility(<facility-code>) or facility(<facility-name>..<facility-name>)

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 syslog-ng application recognizes the following facilities: (Note that some of these facilities are available only on specific platforms.)

Table 8.4. syslog Message Facilities recognized by the facility() filter

Numerical Code Facility name Facility
0 kern kernel messages
1 user user-level messages
2 mail mail system
3 daemon system daemons
4 auth security/authorization messages
5 syslog messages generated internally by syslogd
6 lpr line printer subsystem
7 news network news subsystem
8 uucp UUCP subsystem
9 cron clock daemon
10 authpriv security/authorization messages
11 ftp FTP daemon
12 ntp NTP subsystem
13 security log audit
14 console log alert
15 solaris-cron clock daemon
16-23 local0..local7 locally used facilities (local0-local7)

filter()
Synopsis: filter(filtername)

Description: Call another filter rule and evaluate its value.

host()
Synopsis: host(regexp)

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, syslog-ng PE 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") };
inlist()
Synopsis: in-list("</path/to/file.list>", value("<field-to-filter>"));

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 syslog-ng PE 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 syslog-ng PE for the changes to take effect.

Available in syslog-ng PE and later.

Example 8.13. 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:

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")); };

level() or priority()
Synopsis: level(<priority-level>) or level(<priority-level>..<priority-level>)

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.

match()
Synopsis: match(regexp)

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 syslog-ng 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 the section called “Templates and macros”, the section called “Parsing messages with comma-separated and similar values”, and the section called “Using parser results in filters and templates”.

message()
Synopsis: message(regexp)

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.

netmask()
Synopsis: netmask(ipv4/mask)

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 syslog-ng PE), 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 the section called “netmask6()”.

netmask6()
Synopsis: netmask6(ipv6/mask)

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 syslog-ng PE), 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, syslog-ng PE will ignore the bits of the address after the prefix. To filter IPv4 addresses, see the section called “netmask()”.

The netmask6() filter is available in syslog-ng PE 5.0.8 and 5.2.2 and later.

Caution:

If the IP address is not syntactically correct, the filter will never match. The syslog-ng PE application currently does not send a warning for such configuration errors.

program()
Synopsis: program(regexp)

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

source()
Synopsis: source id

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.

tags()
Synopsis: tag

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 syslog-ng 3.1 and later.

Example 8.14. 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");
    };

NOTE:

The syslog-ng PE application automatically adds the class of the message as a tag using the .classifier.<message-class> format. For example, messages classified as "system" receive the .classifier.system tag. Use the tags() filter function to select messages of a specific class.

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

Dropping messages

To skip the processing of a message without sending it to a destination, create a log statement with the appropriate filters, but do not include any destination in the statement, and use the final flag.

Example 8.15. Skipping messages

The following log statement drops all debug level messages without any further processing.

filter demo_debugfilter { level(debug); };
log { source(s_all); filter(demo_debugfilter); flags(final); };

Related Documents