syslog-ng Premium Edition 7.0.30 - Administration Guide

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
	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
			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	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 and sockets.

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 fully qualified domain name (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:	-1

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

Starting with version 7.0.9, the default value of this option is -1, so syslog-ng PE does not change the ownership, unless explicitly configured to do so.

dns-cache()

Accepted values:	yes | no
Default:	yes

Description: Enable or disable DNS cache usage.

dns-cache-expire()

Accepted values:	number
Default:	3600

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

dns-cache-expire-failed()

Accepted values:	number
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
Default:	100

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. Increasing this number increases throughput as more messages are sent in a single batch, but also increases message latency.

The syslog-ng PE application flushes the messages if it has sent flush-lines() number of messages, or the queue became empty. If you stop or reload syslog-ng PE or in case of network sources, the connection with the client is closed, syslog-ng PE automatically sends the unsent messages to the destination.

flush-timeout()

Accepted values:	time in milliseconds
Default:	10000

Description: Specifies the time syslog-ng waits for lines to accumulate in its output buffer. For more information, see the flush-lines() option.

frac-digits()

Type:	number
Default:	0

Description: The syslog-ng PE 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.

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.

jvm-options()

Type:	list
Default:	N/A

Description: Specify the Java Virtual Machine (JVM) settings of your Java destination from the syslog-ng PE configuration file.

For example:

jvm-options("-Xss1M -XX:+TraceClassLoading")

license()

Description: This option block enables setting license features. It has the following options:

report-host-usage()
Accepted values:	yes|no
Default:	no
Description: This option enables a monthly report generation about the number of consumed license hosts. The periodical reports are created in the beginning of each month, however if syslog-ng is stopped during the relevant month change, a late generation is attempted in the next startup. The report files are in JSON format containing the hostname, reporting period, reporting timestamp and the number of consumed license hosts. All report files are located in directory <syslog-ng path>/var/reports/. This feature is not usable with invalid or unlimited license.

Caution: If we use option report-host-usage() together with option reset-license-counter(), the license counter will reset every day at midnight. This means that the monthly report files can only contain the maximum host usage value of the days of the reported month rather than the expected overall monthly counted hosts, which can result in a big difference.

When the host usage report is generated, the following (example) message is logged into the internal() source: License host usage report; data='{ "Monthly-Consumed-License-Hosts": 56, "Reporting-Timestamp": "2022-05-10T03:43:48+0200", "Host": "syslog-ng.balabit", "Reporting-Period": "2022-04-01 -- 2022-04-30" }'

options
{
  license(
    report-host-usage(yes)
  )
}

reset-license-counter()
Accepted values:	yes|no
Default:	no
Description: When set to yes, syslog-ng PE resets the host-limit counter and the list of known hosts every day at midnight (local time). That way, you can make syslog-ng PE forget old clients that do not exist anymore. This is especially useful in large datacenters or cloud environments where the client hosts are deployed and removed frequently. This feature is available from syslog-ng PE version 7.0.11.

Caution: The license-counter reset is hard-coded to midnight. If syslog-ng PE is reloaded at midnight, just before the license-counter is reset, the license-counter reset will be rescheduled for the next midnight. If this happens repeatedly, the license-counter will never be reset.

When the counter is reset, the following message is logged into the internal() source: Resetting license host-counter; currently used hosts='1'

options
{
  license(
    reset-license-counter(yes)
  )
}

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:	65536

Description: Maximum length of a message in bytes. This length includes the entire message (the data structure and individual fields). The maximum value that you can set is 268435456 bytes (256 MiB).

For messages using the IETF-syslog message format (RFC5424), the maximal size of the value of an SDATA field is 64 KiB.

For details on how encoding affects the size of the message, see Message size and encoding.

You can use human-readable units when setting configuration options. For details, see Notes about the configuration syntax.

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

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. If set, syslog-ng changes the owner of accessed files (for example, /dev/null) to this value, and the permissions to the value set in the perm() option.

Starting with version 7.0.9, the default value of this option is -1, so syslog-ng PE does not change the ownership, unless explicitly configured to do so.

pass-unix-credentials()

Accepted values:	yes|no
Default:	yes

Description: Enable syslog-ng PE to collect UNIX credential information (that is, the PID, user ID, and group of the sender process) for messages received using UNIX domain sockets. Available only in syslog-ng Premium Edition 5 F5 and later. Note that collecting UNIX credential information from sockets in high-traffic environments can be resource intensive, therefore pass-unix-credentials() can be disabled globally, or separately for each source.

perm()

Accepted values:	permission value
Default:	-1

Description: The default permission for output files. If set, syslog-ng changes the permissions of accessed files (for example, /dev/null) to this value, and the onwer to the value set in the owner() option.

Starting with version 7.0.9, the default value of this option is -1, so syslog-ng PE does not change the permissions, unless explicitly configured to do so.

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 Timezones and daylight saving and 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.

reset-license-counter() (DEPRECATED)

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 Timezones and daylight saving.

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.

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.

stats-freq()

Accepted values:	number
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.

Note that these messages are sent from the internal() source of syslog-ng PE and are unstructured. If you want to select which counters you want to monitor, and format the messages, use the monitoring() source. For details on how you can monitor syslog-ng PE statistics and metrics, see Monitoring statistics and metrics of syslog-ng.

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 Monitoring statistics and metrics of syslog-ng.

stats-max-dynamics()

Accepted values:	number
Default:	N/A

Description: To avoid performance issues or even overloading syslog-ng PE (for example, if a script starts to send logs from different IP addresses to syslog-ng PE), you might want to limit the number of registered dynamic counters in the message statistics. For details on message statistics, see Monitoring statistics and metrics of syslog-ng.

• Unlimited dynamic counters:

  If you do not use this option, dynamic counters will not be limited. This can be useful in cases where you are extremely interested in dynamic counters, and use these statistics extensively.

  Caution: In some cases, there might be even millions of dynamic counters

• Limited dynamic counter clusters

  To limit dynamic counters, enter a number, and only a maximum of <number> counters will be registered in the statistics.

  In practice, this means dynamic counter clusters. A program name produces one dynamic counter cluster, that can include several counters, such as processed, stamp, and so on.

  Example: Limiting dynamic counter clusters 1

  If you set stats-max-dynamics() to 1, and 2 programs send messages, only one of these programs will be tracked in the dynamic counters, but it will have more than one counters.

  Example: Limiting dynamic counter clusters 2

  If you have 500 clients, and set stats-max-dynamics() to 1000, you will have enough number of counters reserved for these clients, but at the same time, you limit the use of your resources and therefore protect your system from being overloaded.

• No dynamic counters

  To disable dynamic counters completely, set the value of this option to 0. This is the recommended value if you do not use statistics, or if you are not interested in dynamic counters in particular (for example, the number of logs arriving from programs).

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

trim-large-messages()

Accepted values:	yes|no
Default:	no

Description: Determines what syslog-ng PE does with incoming log messages that are received using the IETF-syslog protocol using the syslog() driver, and are longer than the value of log-msg-size(). Other drivers ignore the trim-large-messages() option.

• If set to no, syslog-ng PE drops the incoming log message.

• If set to yes, syslog-ng PE trims the incoming log message to the size set in log-msg-size(), and adds the trimmed tag to the message. The rest of the message is dropped. You can use the tag to filter on such messages.

  filter f_trimmed {
      tags("trimmed");
  };

  If syslog-ng PE trims a log message, it sends a debug-level log message to its internal() source.

  As a result of trimming, a parser could fail to parse the trimmed message. For example, a trimmed JSON or XML message will not be valid JSON or XML.

Available in syslog-ng PE version 7.0.14 and later.

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 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 frac-digits().

use-rcptid() (DEPRECATED)

Accepted values:	yes | no
Default:	no

Description: When the use-rcptid global option is set to yes, syslog-ng PE automatically assigns a unique reception ID to every received message. You can access this ID and use it in templates via the ${RCPTID} macro. The reception ID is a monotonously increasing 48-bit integer number, that can never be zero (if the counter overflows, it restarts with 1).

This option is deprecated, use the use-uniqid() option instead.

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 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 RCPTID