syslog-ng Premium Edition 6.0.17 - Administration Guide

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:

at the source when the message is received, and
when the message matches a pattern in the pattern database. For details on using the pattern database, see the section called “Using pattern databases”, for details on creating tags in the pattern database, see the section called “The syslog-ng pattern database format”.

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 PE5.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

Chapter 8. Routing messages: log paths, reliability, and filters > 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); };

Chapter 9. Global options of syslog-ng PE

Configuring global syslog-ng options

The syslog-ng application has a number of global options governing DNS usage, the timestamp format used, and other general points. Each option may have parameters, similarly to driver specifications. To set global options, add an option statement to the syslog-ng configuration file using the following syntax:

options { option1(params); option2(params); ... };

Example 9.1. Using global options

To disable domain name resolving, add the following line to the syslog-ng configuration file:

options { use-dns(no); };

For a detailed list of the available options, see the section called “Global options”. For important global options and recommendations on their use, see Chapter 20, Best practices and examples.

Global options

Chapter 9. Global options of syslog-ng PE > Global options

The following options can be specified in the options statement, as described in the section called “Configuring global syslog-ng options”.

bad-hostname()

Accepted values:	regular expression
Default:	no

Description: A regexp containing hostnames which should not be handled as hostnames.

chain-hostnames()

Accepted values:	`yes` \| `no`
Default:	`no`

Description: Enable or disable the chained hostname format. If a client sends the log message directly to the syslog-ng PE server, the chain-hostnames() option is enabled on the server, and the client sends a hostname in the message that is different from its DNS hostname (as resolved from DNS by the syslog-ng PE server), then the server can append the resolved hostname to the hostname in the message (separated with a / character) when the message is written to the destination.

For example, consider a client-server scenario with the following hostnames: client-hostname-from-the-message, client-hostname-resolved-on-the-server, server-hostname. The hostname of the log message written to the destination depends on the keep-hostname() and the chain-hostnames() options. How keep-hostname() and chain-hostnames() options are related is described in the following table.

		keep-hostname() setting on the server
		yes	no
chain-hostnames() setting on the server	yes	client-hostname-from-the-message	client-hostname-from-the-message / client-hostname-resolved-on-the-server
chain-hostnames() setting on the server	no	client-hostname-from-the-message	client-hostname-resolved-on-the-server

If the log message is forwarded to the syslog-ng PE server via a syslog-ng PE relay, the hostname depends on the settings of the keep-hostname() and the chain-hostnames() options both on the syslog-ng PE relay and the syslog-ng PE server.

For example, consider a client-relay-server scenario with the following hostnames: client-hostname-from-the-message, client-hostname-resolved-on-the-relay, client-hostname-resolved-on-the-server, relay-hostname-resolved-on-the-server. How keep-hostname() and chain-hostnames() options are related is described in the following table.

				chain-hostnames() setting on the server
				yes		no
				keep-hostname() setting on the server		keep-hostname() setting on the server
				yes	no	yes	no
chain- hostnames() setting on the relay	yes	keep- hostname() setting on the relay	yes	client-hostname- from-the-message	client-hostname- from-the-message / relay-hostname- resolved-on-the- server	client-hostname- from-the-message	relay-hostname- resolved-on-the- server
	yes	keep- hostname() setting on the relay	no	client-hostname- from-the-message / client-hostname- resolved-on-the- relay	client-hostname- from-the-message / client-hostname- resolved-on-the- relay / relay- hostname-resolved- on-the-server	client-hostname- from-the-message / client-hostname- resolved-on-the- relay
	no	keep- hostname() setting on the relay	yes	client-hostname- from-the-message	client-hostname- from-the-message / relay-hostname- resolved-on-the- server	client-hostname- from-the-message
	no	keep- hostname() setting on the relay	no	client-hostname- resolved-on-the- relay	client-hostname- resolved-on-the- relay / relay- hostname-resolved- on-the-server	client-hostname- resolved-on-the- relay

The chain-hostnames() option of syslog-ng can interfere with the way syslog-ng PE counts the log source hosts, causing syslog-ng to think there are more hosts logging to the central server, especially if the clients sends a hostname in the message that is different from its real hostname (as resolved from DNS). Disable the chain-hostnames() option on your log sources to avoid any problems related to license counting.

check-hostname()

Accepted values:	`yes` \| `no`
Default:	`no`

Description: Enable or disable checking whether the hostname contains valid characters.

create-dirs()

Accepted values:	`yes` \| `no`
Default:	`no`

Description: Enable or disable directory creation for destination files.

custom-domain()

Accepted values:	string
Default:	`empty string`

Description: Use this option to specify a custom domain name that is appended after the short hostname to receive the FQDN. This option affects every outgoing message: eventlog sources, file sources, MARK messages and internal messages of syslog-ng PE.

If the hostname is a short hostname, the custom domain name is appended after the hostname (for example mypc becomes mypc.customcompany.local).
If the hostname is an FQDN, the domain name part is replaced with the custom domain name (for example if the FQDN in the forwarded message is mypc.mycompany.local and the custom domain name is customcompany.local, the hostname in the outgoing message becomes mypc.customcompany.local).

dir-group()

Accepted values:	groupid
Default:	root

Description: The default group for newly created directories.

dir-owner()

Accepted values:	userid
Default:	root

Description: The default owner of newly created directories.

dir-perm()

Accepted values:	permission value
Default:	0700

Description: The permission mask of directories created by syslog-ng. Log directories are only created if a file after macro expansion refers to a non-existing directory, and directory creation is enabled (see also the create-dirs() option). For octal numbers prefix the number with 0, for example use 0755 for rwxr-xr-x.

To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-perm(). Note that when creating a new directory without specifying attributes for dir-perm(), the default permission of the directories is masked with the umask of the parent process (typically 0022).

dns-cache()

Accepted values:	`yes` \| `no`
Default:	`yes`

Description: Enable or disable DNS cache usage.

NOTE:

This option has no effect if the keep-hostname() option is enabled (keep-hostname(yes)) and the message contains a hostname.

dns-cache-expire()

Accepted values:	number (seconds)
Default:	3600

Description: Number of seconds while a successful lookup is cached.

dns-cache-expire-failed()

Accepted values:	number (seconds)
Default:	60

Description: Number of seconds while a failed lookup is cached.

dns-cache-hosts()

Accepted values:	filename
Default:	unset

Description: Name of a file in /etc/hosts format that contains static IP->hostname mappings. Use this option to resolve hostnames locally without using a DNS. Note that any change to this file triggers a reload in syslog-ng and is instantaneous.

dns-cache-size()

Accepted values:	number of hostnames
Default:	1007

Description: Number of hostnames in the DNS cache.

file-template()

Accepted values:	string
Default:

Description: Specifies a template that file-like destinations use by default. For example:

template t_isostamp { template("$ISODATE $HOST $MSGHDR$MSG\n"); };

options { file-template(t_isostamp); };

flush-lines()

Accepted values:	number (messages)
Default:	1

Description: Specifies how many lines are flushed to a destination at a time. The syslog-ng PE application waits for this number of lines to accumulate and sends them off in a single batch. Setting this number high increases throughput as fully filled frames are sent to the network, but also increases message latency.

flush-timeout() (OBSOLETE)

Accepted values:	time in milliseconds
Default:	10000

Description: This is an obsolete option. Specifies the time syslog-ng waits for lines to accumulate in its output buffer. For details, see the flush-lines() option.

NOTE:

This option will be removed from the list of acceptable options. After that, your configuration will become invalid if it still contains the flush-timeout() option. To avoid future problems, remove this option from your configuration.

frac-digits()

Type:	number (digits of fractions of a second)
Default:	Value of the global option (which defaults to 0)

Description: The syslog-ng application can store fractions of a second in the timestamps according to the ISO8601 format. The frac-digits() parameter specifies the number of digits stored. The digits storing the fractions are padded by zeros if the original timestamp of the message specifies only seconds. Fractions can always be stored for the time the message was received. Note that syslog-ng can add the fractions to non-ISO8601 timestamps as well.

group()

Accepted values:	groupid
Default:	root

Description: The default group of output files. By default, syslog-ng changes the privileges of accessed files (for example /dev/null) to root.root 0600. To disable modifying privileges, use this option with the -1 value.

keep-hostname()

Type:	yes or no
Default:	no

Description: Enable or disable hostname rewriting.

If enabled (keep-hostname(yes)), syslog-ng PE assumes that the incoming log message was sent by the host specified in the HOST field of the message.
If disabled (keep-hostname(no)), syslog-ng PE rewrites the HOST field of the message, either to the IP address (if the use-dns() parameter is set to no), or to the hostname (if the use-dns() parameter is set to yes and the IP address can be resolved to a hostname) of the host sending the message to syslog-ng PE. For details on using name resolution in syslog-ng PE, see the section called “Using name resolution in syslog-ng”.

NOTE:

If the log message does not contain a hostname in its HOST field, syslog-ng PE automatically adds a hostname to the message.

For messages received from the network, this hostname is the address of the host that sent the message (this means the address of the last hop if the message was transferred via a relay).
For messages received from the local host, syslog-ng PE adds the name of the host.

This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

NOTE:

When relaying messages, enable this option on the syslog-ng PE server and also on every relay, otherwise syslog-ng PE will treat incoming messages as if they were sent by the last relay.

keep-timestamp()

Type:	yes or no
Default:	yes

Description: Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Caution:

To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng PE).

log-fifo-size()

Accepted values:	number (messages)
Default:	10000

Description: The number of messages that the output queue can store.

log-msg-size()

Accepted values:	number (bytes)
Default:	65535

Description: Maximum length of a message in bytes. This length includes the entire message (the data structure and individual fields). The maximal value that can be set is 268435456 bytes (256MB). For messages using the IETF-syslog message format (RFC5424), the maximal size of the value of an SDATA field is 64kB.

logstore-journal-shmem-threshold()

Type:	number (bytes)
Default:	536870912

Description: If the size of memory (in bytes) required by journal files increases above this value, syslog-ng PE maps only a single block of every logstore journal into the memory. Default value: 536870912 (512 MB).

If the memory required for the journal files exceeds the logstore-journal-shmem-threshold() limit, syslog-ng PE will store only a single journal block of every journal file in the memory, and — if more blocks are needed for a journal — store the additional blocks on the hard disk. Opening new logstore files means allocating memory for one new journal block for every new file. In extreme situations involving large traffic, this can lead to syslog-ng PE consuming the entire memory of the system. Adjust the journal-block-size() and your file-naming conventions as needed to avoid such situations. For details on logstore journals, see the section called “Journal files”.

Example 9.2. Calculating memory usage of logstore journals

If you are using the default settings (4 journal blocks for every logstore journal, one block is 1MB, logstore-journal-shmem-threshold() is 512MB), this means that syslog-ng PE will allocate 4MB memory for every open logstore file, up to 512MB if you have 128 open logstore files. Opening a new logstore file would require 4 more megabytes of memory for journaling, bringing the total required memory to 516MB, which is above the logstore-journal-shmem-threshold(). In this case, syslog-ng PE switches to storing only a single journal block in the memory, lowering the memory requirements of journaling to 129MB. However, opening more and more logstore files will require more and more memory, and this is not limited, except when syslog-ng PE reaches the maximum number of files that can be open (as set in the --fd-limit command-line option).

Example 9.3. Limiting the memory use of journal files

The following example causes syslog-ng PE to map only a single journal block into the host's memory if the total memory range used by logstore journals would be higher than 32 MB.

options {
    logstore-journal-shmem-threshold(33554432);
};
destination d_messages { logstore("/var/log/messages_logstore.lgs"
                         journal-block-size(19660800)
                         journal-block-count(5)
                         );
};

mark() (DEPRECATED)

Accepted values:	number (seconds)
Default:	1200

Description: The mark-freq() option is an alias for the deprecated mark() option. This is retained for compatibility with syslog-ng version 1.6.x.

mark-freq()

Accepted values:	number (seconds)
Default:	1200

Description: An alias for the obsolete mark() option, retained for compatibility with syslog-ng version 1.6.x. The number of seconds between two MARK messages. MARK messages are generated when there was no message traffic to inform the receiver that the connection is still alive. If set to zero (0), no MARK messages are sent. The mark-freq() can be set for global option and/or every MARK capable destination driver if mark-mode() is periodical or dst-idle or host-idle. If mark-freq() is not defined in the destination, then the mark-freq() will be inherited from the global options. If the destination uses internal mark-mode(), then the global mark-freq() will be valid (does not matter what mark-freq() set in the destination side).

mark-mode()

Default:

internal for pipe, program drivers

none for file, unix-dgram, unix-stream drivers

global for syslog, tcp, udp destinations

host-idle for global option

Description: The mark-mode() option can be set for the following destination drivers: file(), program(), unix-dgram(), unix-stream(), network(), pipe(), syslog() and in global option.

internal: When internal mark mode is selected, internal source should be placed in the log path as this mode does not generate mark by itself at the destination. This mode only yields the mark messages from internal source. This is the mode as syslog-ng PE 3.x worked. MARK will be generated by internal source if there was NO traffic on local sources:

file(), pipe(), unix-stream(), unix-dgram(), program()
dst-idle: Sends MARK signal if there was NO traffic on destination drivers. MARK signal from internal source will be dropped.

MARK signal can be sent by the following destination drivers: network(), syslog(), program(), file(), pipe(), unix-stream(), unix-dgram().
host-idle: Sends MARK signal if there was NO local message on destination drivers. For example MARK is generated even if messages were received from tcp. MARK signal from internal source will be dropped.

MARK signal can be sent by the following destination drivers: network(), syslog(), program(), file(), pipe(), unix-stream(), unix-dgram().
periodical: Sends MARK signal perodically, regardless of traffic on destination driver. MARK signal from internal source will be dropped.

MARK signal can be sent by the following destination drivers: network(), syslog(), program(), file(), pipe(), unix-stream(), unix-dgram().
none: Destination driver drops all MARK messages. If an explicit mark-mode() is not given to the drivers where none is the default value, then none will be used.
global: Destination driver uses the global mark-mode() setting. The syslog-ng interprets syntax error if the global mark-mode() is global.

NOTE:

In case of dst-idle, host-idle and periodical, the MARK message will not be written in the destination, if it is not open yet.

Available in syslog-ng PE 4 LTS and later.

normalize-hostnames()

Accepted values:	`yes` \| `no`
Default:	`no`

Description: If enabled (normalize-hostnames(yes)), syslog-ng PE converts the hostnames to lowercase.

NOTE:

This setting applies only to hostnames resolved from DNS. It has no effect if the keep-hostname() option is enabled, and the message contains a hostname.

on-error()

Accepted values:	drop-message\|drop-property\|fallback-to-string\|silently-drop-message\|silently-drop-property\|silently-fallback-to-string
Default:	drop-message

Description: Controls what happens when type-casting fails and syslog-ng PE cannot convert some data to the specified type. By default, syslog-ng PE drops the entire message and logs the error. Currently the value-pairs() option uses the settings of on-error().

drop-message: Drop the entire message and log an error message to the internal() source. This is the default behavior of syslog-ng PE.
drop-property: Omit the affected property (macro, template, or message-field) from the log message and log an error message to the internal() source.
fallback-to-string: Convert the property to string and log an error message to the internal() source.
silently-drop-message: Drop the entire message silently, without logging the error.
silently-drop-property: Omit the affected property (macro, template, or message-field) silently, without logging the error.
silently-fallback-to-string: Convert the property to string silently, without logging the error.

owner()

Accepted values:	userid
Default:	root

Description: The default owner of output files. By default, syslog-ng changes the privileges of accessed files (for example /dev/null) to root.root 0600. To disable modifying privileges, use this option with the -1 value.

perm()

Accepted values:	permission value
Default:	0600

Description: The default permission for output files. By default, syslog-ng changes the privileges of accessed files (for example /dev/null) to root.root 0600. To disable modifying privileges, use this option with the -1 value.

proto-template()

Accepted values:	name of a template
Default:	The default message format of the used protocol

Description: Specifies a template that protocol-like destinations (for example, network() and syslog()) use by default. For example:

template t_isostamp { template("$ISODATE $HOST $MSGHDR$MSG\n"); };

options { proto-template(t_isostamp); };

recv-time-zone()

Accepted values:	name of the timezone, or the timezone offset
Default:	local timezone

Description: Specifies the time zone associated with the incoming messages, if not specified otherwise in the message or in the source driver. For details, see also the section called “Timezones and daylight saving” and the section called “A note on timezones and timestamps”.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

send-time-zone()

Accepted values:	name of the timezone, or the timezone offset
Default:	local timezone

Description: Specifies the time zone associated with the messages sent by syslog-ng, if not specified otherwise in the message or in the destination driver. For details, see the section called “Timezones and daylight saving”.

stats-freq()

Accepted values:	number (seconds)
Default:	600

Description: The period between two STATS messages in seconds. STATS are log messages sent by syslog-ng, containing statistics about dropped log messages. Set to 0 to disable the STATS messages.

stats-level()

Accepted values:	`0` \| `1` \| `2` \| `3`
Default:	`0`

Description: Specifies the detail of statistics syslog-ng collects about the processed messages.

Level 0 collects only statistics about the sources and destinations
Level 1 contains details about the different connections and log files, but has a slight memory overhead
Level 2 contains detailed statistics based on the hostname.
Level 3 contains detailed statistics based on various message parameters like facility, severity, or tags.

Note that level 2 and 3 increase the memory requirements and CPU load. For details on message statistics, see Chapter 17, Statistics and metrics of syslog-ng.

sync() or sync-freq() (DEPRECATED)

Accepted values:	number (messages)
Default:	0

Description: Obsolete aliases for flush-lines()

threaded()

Accepted values:	yes\|no
Default:	yes

Description: Enable syslog-ng PE to run in multithreaded mode and use multiple CPUs. Available only in syslog-ng Premium Edition 4 F1 and later. See Chapter 18, Multithreading and scaling in syslog-ng PE for details.

time-reap()

Accepted values:	number (seconds)
Default:	60

Description: The time to wait in seconds before an idle destination file is closed. Note that only destination files having macros in their filenames are closed automatically.

time-reopen()

Accepted values:	number (seconds)
Default:	60

Description: The time to wait in seconds before a dead connection is reestablished.

time-sleep() (DEPRECATED)

Accepted values:	number (milliseconds)
Default:	0

Description: The time to wait in milliseconds between each invocation of the poll() iteration.

timestamp-freq()

Type:	number (seconds)
Default:	0

Description: The minimum time (in seconds) that should expire between two timestamping requests. When syslog-ng closes a chunk, it checks how much time has expired since the last timestamping request: if it is higher than the value set in the timestamp-freq() parameter, it requests a new timestamp from the authority set in the timestamp-url() parameter.

By default, timestamping is disabled: the timestamp-freq() global option is set to 0. To enable timestamping, set it to a positive value.

timestamp-url()

Accepted values:	string
Default:

Description: The URL of the Timestamping Authority used to request timestamps to sign logstore chunks. Note that syslog-ng PE currently supports only Timestamping Authorities that conform to RFC3161 Internet X.509 Public Key Infrastructure Time-Stamp Protocol, other protocols like Microsoft Authenticode Timestamping are not supported.

timestamp-policy()

Accepted values:	string
Default:

Description: If the Timestamping Server has timestamping policies configured, specify the OID of the policy to use into the Timestamping policy field. syslog-ng PE will include this ID in the timestamping requests sent to the TSA. This option is available in syslog-ng PE 3.1 and later.

time-zone()

Type:	name of the timezone, or the timezone offset
Default:	unspecified

Description: Convert timestamps to the timezone specified by this option. If this option is not set, then the original timezone information in the message is used. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see the section called “Date-related macros”.

ts-format()

Accepted values:	`rfc3164` \| `bsd` \| `rfc3339` \| `iso`
Default:	`rfc3164`

Description: Specifies the timestamp format used when syslog-ng itself formats a timestamp and nothing else specifies a format (for example: STAMP macros, internal messages, messages without original timestamps). For details, see also the section called “A note on timezones and timestamps”.

By default, timestamps include only seconds. To include fractions of a second (for example, milliseconds) use the frac-digits() option. For details, see the section called “frac-digits()”.

NOTE:

This option applies only to file and file-like destinations. Destinations that use specific protocols (for example, network(), or syslog()) ignore this option. For protocol-like destinations, use a template locally in the destination, or use the proto-template option.

use-dns()

Type:	yes, no, persist_only
Default:	yes

Description: Enable or disable DNS usage. The persist_only option attempts to resolve hostnames locally from file (for example from /etc/hosts). The syslog-ng PE application blocks on DNS queries, so enabling DNS may lead to a Denial of Service attack. To prevent DoS, protect your syslog-ng network endpoint with firewall rules, and make sure that all hosts which may get to syslog-ng are resolvable. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

NOTE:

This option has no effect if the keep-hostname() option is enabled (keep-hostname(yes)) and the message contains a hostname.

use-fqdn()

Type:	yes or no
Default:	no

Description: Add Fully Qualified Domain Name instead of short hostname. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

NOTE:

This option has no effect if the keep-hostname() option is enabled (keep-hostname(yes)) and the message contains a hostname.

use-rcptid() (DEPRECATED)

Accepted values:	`yes` \| `no`
Default:	`no`

Description: The receipt ID function is disabled by default due to performance issues. For details, see also the section called “RCPTID”. This function is now deprecated. Use the use-uniqid() option instead, for details, see the section called “use-uniqid()”.

use-time-recvd() (DEPRECATED)

Accepted values:	`yes` \| `no`
Default:	`no`

Caution:

This option is not available in syslog-ng PE version 3.2 and later. Use the R_ prefixed version of the respective macro instead. Starting with syslog-ng PE version 3.2, the DATE macro equals the S_DATE macro.

Description: This option controls how the time related macros are expanded in filename and content templates. If set to yes, then the non-prefixed versions of the time related macros (for example: HOUR instead of R_HOUR and S_HOUR) refer to the time when the message was received, otherwise it refers to the timestamp which is in the message.

NOTE:

The timestamps in the messages are generated by the originating host and might not be accurate.

This option is deprecated as many users assumed that it controls the timestamp as it is written to logfiles/destinations, which is not the case. To change how messages are formatted, specify a content-template referring to the appropriate prefixed (S_ or R_) time macro.

use-uniqid()

Accepted values:	`yes` \| `no`
Default:	`no`

Description: This option enables generating a globally unique ID. It is generated from the HOSTID and the RCPTID in the format of HOSTID@RCPTID. It has a fixed length: 16+@+8 characters. You can include the unique ID in the message by using the macro. For details, see the section called “UNIQID”.

Enabling this option automatically generates the HOSTID. The HOSTID is a persistent, 32-bits-long cryptographically secure pseudo random number, that belongs to the host that the syslog-ng is running on. If the persist file is damaged, the HOSTID might change.

Enabling this option automatically enables the RCPTID functionality. For details, see the section called “RCPTID”

Please select your product:

To serve you better, please complete the Purpose of your Chat:

Recommended Solutions for Your Problem

syslog-ng Premium Edition 6.0.17 - Administration Guide

Filters

Using filters

Combining filters with boolean operators

Comparing macro values in filters

Using wildcards, special characters, and regular expressions in filters

Tagging messages

Filter functions

facility()

filter()

host()

inlist()

level() or priority()

match()

message()

netmask()

netmask6()

program()

source()

tags()

Dropping messages

Chapter 9. Global options of syslog-ng PE

Configuring global syslog-ng options

Global options

bad-hostname()

chain-hostnames()

check-hostname()

create-dirs()

custom-domain()

dir-group()

dir-owner()

dir-perm()

dns-cache()

dns-cache-expire()

dns-cache-expire-failed()

dns-cache-hosts()

dns-cache-size()

file-template()

flush-lines()

flush-timeout() (OBSOLETE)

frac-digits()

group()

keep-hostname()

keep-timestamp()

log-fifo-size()

log-msg-size()

logstore-journal-shmem-threshold()

mark() (DEPRECATED)

mark-freq()

mark-mode()

normalize-hostnames()

on-error()

owner()

perm()

proto-template()

recv-time-zone()

send-time-zone()

stats-freq()

stats-level()

sync() or sync-freq() (DEPRECATED)

threaded()

time-reap()

time-reopen()

time-sleep() (DEPRECATED)

timestamp-freq()

timestamp-url()

timestamp-policy()

time-zone()

ts-format()

use-dns()

use-fqdn()

use-rcptid() (DEPRECATED)

use-time-recvd() (DEPRECATED)

use-uniqid()