Chat now with support
Chat with Support

syslog-ng Premium Edition 6.0.23 - 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 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

Chapter 7. Sending and storing log messages — destinations and destination drivers

A destination is where a log message is sent if the filtering rules match. Similarly to sources, destinations consist of one or more drivers, each defining where and how messages are sent.

TIP:

If no drivers are defined for a destination, all messages sent to the destination are discarded. This is equivalent to omitting the destination from the log statement.

To define a destination, add a destination statement to the syslog-ng configuration file using the following syntax:

destination <identifier> {
                destination-driver(params); destination-driver(params); ... };

Example 7.1. A simple destination statement

The following destination statement sends messages to the TCP port 1999 of the 10.1.2.3 host.

destination d_demo_tcp { network("10.1.2.3" port(1999)); };

If name resolution is configured, you can use the hostname of the target server as well.

destination d_tcp { network("target_host" port(1999)); };

Caution:
  • Do not define the same drivers with the same parameters more than once, because it will cause problems. For example, do not open the same file in multiple destinations.

  • Do not use the same destination in different log paths, because it can cause problems with most destination types. Instead, use filters and log paths to avoid such situations.

  • Sources and destinations are initialized only when they are used in a log statement. For example, syslog-ng PE starts listening on a port or starts polling a file only if the source is used in a log statement. For details on creating log statements, see Chapter 8, Routing messages: log paths, reliability, and filters.

  • Hazard of data loss! If your log files are on an NFS-mounted network file system, see the section called “NFS file system for log files”.

The following table lists the destination drivers available in syslog-ng PE.

Table 7.1. Destination drivers available in syslog-ng

Name Description
elasticsearch and elasticsearch2 Sends messages to an Elasticsearch server. The elasticsearch2 driver supports Elasticsearch version 2.0-2.4.6.
file() Writes messages to the specified file.
hdfs Sends messages into a file on a Hadoop Distributed File System (HDFS) node.
kafka Publishes log messages to the Apache Kafka message bus, where subscribers can access them.
logstore() Writes messages to the specified binary logstore file.
mongodb() Sends messages to a MongoDB database.
network() Sends messages to a remote host using the BSD-syslog protocol over IPv4 and IPv6. Supports the TCP, UDP,RLTP™, and TLS network protocols.
pipe() Writes messages to the specified named pipe.
program() Forks and launches the specified program, and sends messages to its standard input.
smtp() Sends messages send mail to trusted recipients, through a controlled channel using the SMTP protocol.
snmp() Sends messages to the specified remote host using the SNMP v2c or v3 protocol.
sql() Sends messages into an SQL database. In addition to the standard syslog-ng packages, the sql() destination requires database-specific packages to be installed. Refer to the section appropriate for your platform in Chapter 3, Installing syslog-ng.
syslog() Sends messages to the specified remote host using the IETF-syslog protocol. The IETF standard supports message transport using the UDP, TCP, and TLS networking protocols.
unix-dgram() Sends messages to the specified unix socket in SOCK_DGRAM style (BSD).
unix-stream() Sends messages to the specified unix socket in SOCK_STREAM style (Linux).
usertty() Sends messages to the terminal of the specified user, if the user is logged in.

Sending messages directly to Elasticsearch version 2.0 or higher

Sending messages directly to Elasticsearch version 2.0-2.4.6

Starting with version 5.6 of syslog-ng PE can directly send log messages to Elasticsearch, allowing you to search and analyze your data in real time, and visualize it with Kibana.

NOTE:

In order to use this destination, syslog-ng Premium Edition must run in server mode. Typically, only the central syslog-ng Premium Edition server uses this destination. For details on the server mode, see the section called “Server mode”.

Note the following limitations when using the syslog-ng PEelasticsearch2 destination:

  • This destination is only supported on the Linux platforms that use the linux glibc2.11 installer, including: Red Hat ES 7, Ubuntu 14.04 (Trusty Tahr).

  • Since syslog-ng PE uses the official Java Elasticsearch libraries, the elasticsearch2 destination has significant memory usage.

  • The log messages of the underlying client libraries are available in the internal() source of syslog-ng PE.

Declaration: 

@module mod-java
@include "scl.conf"

elasticsearch2(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
    cluster("syslog-ng")
);

Example 7.5. Sending log data to Elasticsearch version 2.0-2.4.6

The following example defines an elasticsearch2 destination that sends messages in transport mode to an Elasticsearch server running on the localhost, using only the required parameters.

@module mod-java
@include "scl.conf"

destination d_elastic {
  elasticsearch2(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
  );
};

The following example sends 10000 messages in a batch, in node mode, and includes a custom unique ID for each message.

@module mod-java
@include "scl.conf"

options {
  threaded(yes);
  use_uniqid(yes);
};

source s_syslog {
  syslog();
};

destination d_elastic {
  elasticsearch2(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
    cluster("syslog-ng")
    client_mode("node")
    custom_id("${UNIQID}")
    flush-limit("10000")
  );
};

log {
  source(s_syslog);
  destination(d_elastic);
  flags(flow-control);
};

Procedure 7.2. Prerequisites

To send messages from syslog-ng PE to Elasticsearch, complete the following steps.

Steps: 

  1. Download and install the Java Runtime Environment (JRE), 2.x (or newer). The syslog-ng PEelasticsearch2 destination is tested and supported when using the Oracle implementation of Java. Other implementations are untested and unsupported, they may or may not work as expected.

  2. Download the Elasticsearch libraries (version 2.0-2.4.6) from https://www.elastic.co/downloads/elasticsearch.One Identity tests the destination using Elasticsearch version 2.4..

  3. Extract the Elasticsearch libraries into a temporary directory, then collect the various .jar files into a single directory (for example, /opt/elasticsearch/lib/) where syslog-ng PE can access them. You must specify this directory in the syslog-ng PE configuration file. The files are located in the lib directory and its subdirectories of the Elasticsearch release package.

How syslog-ng PE interacts with Elasticsearch

The syslog-ng PE application sends the log messages to the official Elasticsearch client library, which forwards the data to the Elasticsearch nodes. The way how syslog-ng PE interacts with Elasticsearch is described in the following steps.

  • After syslog-ng PE is started and the first message arrives to the elasticsearch2 destination, the elasticsearch2 destination tries to connect to the Elasticsearch server or cluster. If the connection fails, syslog-ng PE will repeatedly attempt to connect again after the period set in time-reopen() expires.

  • If the connection is established, syslog-ng PE sends JSON-formatted messages to Elasticsearch.

    • If flush_limit is set to 1: syslog-ng PE sends the message reliably: it sends a message to Elasticsearch, then waits for a reply from Elasticsearch. In case of failure, syslog-ng PE repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, syslog-ng PE drops the message.

      This method ensures reliable message transfer, but is slow.

    • If flush_limit is higher than 1: syslog-ng PE sends messages in a batch, and receives the response asynchronously. In case of a problem, syslog-ng PE cannot resend the messages.

      This method is relatively fast (depending on the size of flush_limit), but the transfer is not reliable. In transport mode, several messages can be lost before syslog-ng PE recognizes the error. Node mode is more reliable in this sense, because the message loss rate is significantly lower.

    • If concurrent-requests is higher than 1, syslog-ng PE can send multiple batches simultaneously, increasing performance (and also the number of messages that can be lost in case of an error). For details, see the section called “concurrent_requests()”.

Client modes

The syslog-ng PE application can interact with Elasticsearch in transport mode or node mode.

  • Transport mode. The syslog-ng PE application uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the syslog-ng PE configuration file.

  • Node mode. The syslog-ng PE application acts as an Elasticsearch node (client no-data), using the node client API of Elasticsearch. Further options for the node can be describe in an Elasticsearch configuration file specified in the resource() option.

    NOTE:

    In Node mode, it is required to define the home of the elasticsearch installation with the path.home paramter in the .yml file. For example: path.home: /usr/share/elasticsearch.

  • Shield mode. This mode is available only from syslog-ng PE version 5.6. In this mode, syslog-ng PE uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the syslog-ng PE configuration file, but with Shield (X-Pack security) support. For more details about Shield, see: https://www.elastic.co/products/x-pack/security.

Elasticsearch destination options

The elasticsearch2 destination can directly send log messages to Elasticsearch, allowing you to search and analyze your data in real time, and visualize it with Kibana. The elasticsearch2 destination has the following options.

Required options: 

The following options are required: index(), type(). In node mode, either the cluster() or the resource() option is required as well. Note that to use elasticsearch2, you must add the following lines to the beginning of your syslog-ng PE configuration:

@module mod-java
@include "scl.conf"
client_lib_dir()
Type: string
Default: N/A

Description: Include the path to the directory where you copied the required libraries (see Procedure 7.2, “Prerequisites”), for example, client_lib_dir(/user/share/elasticsearch-2.2.0/lib).

client_mode()
Type: transport | node | shield
Default: node

Description: Specifies the client mode used to connect to the Elasticsearch server, for example, client_mode("node").

  • Transport mode. The syslog-ng PE application uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the syslog-ng PE configuration file.

  • Node mode. The syslog-ng PE application acts as an Elasticsearch node (client no-data), using the node client API of Elasticsearch. Further options for the node can be describe in an Elasticsearch configuration file specified in the resource() option.

    NOTE:

    In Node mode, it is required to define the home of the elasticsearch installation with the path.home paramter in the .yml file. For example: path.home: /usr/share/elasticsearch.

  • Shield mode. This mode is available only from syslog-ng PE version 5.6. In this mode, syslog-ng PE uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the syslog-ng PE configuration file, but with Shield (X-Pack security) support. For more details about Shield, see: https://www.elastic.co/products/x-pack/security.

  • To use this mode, add the Shield .jar file (shield-x.x.x.jar) to the same directory where your Elasticsearch .jar files are located. You can download the Shield distribution and extract the .jar file manually, or you can get it from the Elasticsearch Maven repository.

    It inherits the Transport mode options, but the Shield-related options must be configured in the .yml file (see the resource() option of syslog-ng PE). For more details about the possible options, see: https://www.elastic.co/guide/en/shield/current/reference.html#ref-ssl-tls-settings.

    Example 7.6. Example for the .yml file

    shield.user: es_admin:********
    shield.transport.ssl: true
    shield.ssl.keystore.path: /usr/share/elasticsearch/node.jks
    shield.ssl.keystore.password: mypassword
    

cluster()
Type: string
Default: N/A

Description: Specifies the name or the Elasticsearch cluster, for example, cluster("my-elasticsearch-cluster"). Optionally, you can specify the name of the cluster in the Elasticsearch resource file. For details, see the section called “resource()”.

concurrent_requests()
Type: number
Default: 0

Description: The number of concurrent (simultaneous) requests that syslog-ng PE sends to the Elasticsearch server. Set this option to 1 or higher to increase performance. When using the concurrent_requests() option, make sure that the flush-limit() option is higher than one, otherwise it will not have any noticeable effect. For details, see the section called “flush_limit()”.

Caution:

Hazard of data loss! Using the concurrent-requests() option increases the number of messages lost in case the Elasticsearch server becomes unaccessible.

custom_id()
Type: template or template function
Default: N/A

Description: Use this option to specify a custom ID for the records inserted into Elasticsearch. If this option is not set, the Elasticsearch server automatically generates and ID for the message. For example: custom_id(${UNIQID}) (Note that to use the ${UNIQID} macro, the use-uniqid() global option must be enabled. For details, see the section called “use-uniqid()”.)

disk-buffer()

Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:

reliable()
Type: yes|no
Default: no

Description: If set to yes, syslog-ng PE cannot 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. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.

Caution:

Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.

dir()
Type: string
Default: N/A

Description: Defines the folder where the disk-buffer files are stored. This option has priority over --qdisk-dir=.

Caution:

When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file, or at least remove the relevant persist-entry.

syslog-ng PE creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file or the relevant entry is not deleted after modifying the dir() option, then following a restart, syslog-ng PE will look for or create disk-buffer files in their old location. To ensure that syslog-ng PE uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.

disk-buf-size()
Type: number (bytes)
Default:
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
mem-buf-length()
Type: number (messages)
Default: 10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
mem-buf-size()
Type: number (bytes)
Default: 163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
quot-size()
Type: number (messages)
Default: 64
Description: The number of messages stored in the output buffer of the destination.

Options reliable() and disk-buf-size() are required options.

Example 7.7. Examples for using disk-buffer()

In the following case reliable disk-buffer() is used.

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

In the following case normal disk-buffer() is used.

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

flush_limit()
Type: number
Default: 5000

Description: The number of messages that syslog-ng PE sends to the Elasticsearch server in a single batch.

  • If flush_limit is set to 1: syslog-ng PE sends the message reliably: it sends a message to Elasticsearch, then waits for a reply from Elasticsearch. In case of failure, syslog-ng PE repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, syslog-ng PE drops the message.

    This method ensures reliable message transfer, but is slow.

  • If flush_limit is higher than 1: syslog-ng PE sends messages in a batch, and receives the response asynchronously. In case of a problem, syslog-ng PE cannot resend the messages.

    This method is relatively fast (depending on the size of flush_limit), but the transfer is not reliable. In transport mode, several messages can be lost before syslog-ng PE recognizes the error. Node mode is more reliable in this sense, because the message loss rate is significantly lower.

  • If concurrent-requests is higher than 1, syslog-ng PE can send multiple batches simultaneously, increasing performance (and also the number of messages that can be lost in case of an error). For details, see the section called “concurrent_requests()”.

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.

index()
Type: string
Default: N/A

Description: Name of the Elasticsearch index to store the log messages. You can use macros and templates as well. For example, index("syslog-ng_${YEAR}.${MONTH}.${DAY}").

log-fifo-size()
Type: number (messages)
Default: Use global setting.

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

on-error()
Accepted values: drop-message|drop-property|fallback-to-string|silently-drop-message|silently-drop-property|silently-fallback-to-string
Default: Use the global setting (which defaults to 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.

port()
Type: number
Default: 9300

Description: The port number of the Elasticsearch server. This option is used only in transport mode: client_mode("transport")

retries()
Type: number (of attempts)
Default: 3

Description: The number of times syslog-ng PE attempts to send a message to this destination. If syslog-ng PE could not send a message, it will try again until the number of attempts reaches retries, then drops the message.

resource()
Type: string
Default: N/A

Description: The list of Elasticsearch resources to load, separated by semicolons. For example, resource("/home/user/elasticsearch/elasticsearch.yml;/home/user/elasticsearch/elasticsearch2.yml").

server()
Type: list of hostnames
Default: 127.0.0.1

Description: Specifies the hostname or IP address of the Elasticsearch server. When specifying an IP address, IPv4 (for example, 192.168.0.1) or IPv6 (for example, [::1]) can be used as well. When specifying multiple addresses, use space to separate the addresses, for example, server("127.0.0.1 remote-server-hostname1 remote-server-hostname2")

This option is used only in transport mode: client_mode("transport")

template()
Type: template or template function
Default: $(format-json --scope rfc5424 --exclude DATE --key ISODATE @timestamp=${ISODATE})

Description: The message as sent to the Elasticsearch server. Typically, you will want to use the command-line notation of the format-json template function.

To add a @timestamp field to the message, for example, to use with Kibana, include the @timestamp=${ISODATE} expression in the template. For example: template($(format-json --scope rfc5424 --exclude DATE --key ISODATE @timestamp=${ISODATE}))

For details on formatting messages in JSON format, see the section called “format-json”.

throttle()
Type: number (messages per second)
Default: 0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

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

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.

ts-format()
Type: rfc3164, bsd, rfc3339, iso
Default: Use the global option (which defaults to rfc3164)

Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see the section called “A note on timezones and timestamps”.

type()
Type: string
Default: N/A

Description: The type of the index. For example, type("test").

Storing messages in plain-text files

The file driver is one of the most important destination drivers in syslog-ng. It allows to output messages to the specified text file, or to a set of files.

The destination filename may include macros which get expanded when the message is written, thus a simple file() driver may create several files: for example, syslog-ng PE can store the messages of client hosts in a separate file for each host. For more information on available macros see the section called “Macros of syslog-ng PE”.

If the expanded filename refers to a directory which does not exist, it will be created depending on the create-dirs() setting (both global and a per destination option).

The file() has a single required parameter that specifies the filename that stores the log messages. For the list of available optional parameters, see the section called “file() destination options”.

Declaration: 

file(filename options());

Example 7.8. Using the file() driver

destination d_file { file("/var/log/messages"); };

Example 7.9. Using the file() driver with macros in the file name and a template for the message

destination d_file {
        file("/var/log/${YEAR}.${MONTH}.${DAY}/messages"
             template("${HOUR}:${MIN}:${SEC} ${TZ} ${HOST} [${LEVEL}] ${MSG}\n")
             template-escape(no));
};

NOTE:

When using this destination, update the configuration of your log rotation program to rotate these files. Otherwise, the log files can become very large.

Also, after rotating the log files, reload syslog-ng PE using the syslog-ng-ctl reload command, or use another method to send a SIGHUP to syslog-ng PE.

Caution:

Since the state of each created file must be tracked by syslog-ng, it consumes some memory for each file. If no new messages are written to a file within 60 seconds (controlled by the time-reap() global option), it is closed, and its state is freed.

Exploiting this, a DoS attack can be mounted against the system. If the number of possible destination files and its needed memory is more than the amount available on the syslog-ng server.

The most suspicious macro is ${PROGRAM}, where the number of possible variations is rather high. Do not use the ${PROGRAM} macro in insecure environments.

file() destination options

The file() driver outputs messages to the specified text file, or to a set of files. The file() destination has the following options:

Caution:

When creating several thousands separate log files, syslog-ng might not be able to open the required number of files. This might happen for example when using the ${HOST} macro in the filename while receiving messages from a large number of hosts. To overcome this problem, adjust the --fd-limit command-line parameter of syslog-ng or the global ulimit parameter of your host. For setting the --fd-limit command-line parameter of syslog-ng see the syslog-ng(8) manual page. For setting the ulimit parameter of the host, see the documentation of your operating system.

create-dirs()
Type: yes or no
Default: no

Description: Enable creating non-existing directories.

dir-group()
Type: string
Default: Use the global settings

Description: The group of the directories created by syslog-ng. To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-group().

dir-owner()
Type: string
Default: Use the global settings

Description: The owner of the directories created by syslog-ng. To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-owner().

dir-perm()
Type: number (octal notation)
Default: Use the global settings

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

flags()
Type: no-multi-line, syslog-protocol, threaded
Default: empty set

Description: Flags influence the behavior of the destination driver.

  • no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.

  • syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.

  • threaded: The threaded flag enables multithreading for the destination. For details on multithreading, see Chapter 18, Multithreading and scaling in syslog-ng PE.

    NOTE:

    The file destination uses multiple threads only if the destination filename contains macros.

flush-lines()
Type: number (messages)
Default: Use global setting.

Description: Specifies how many lines are sent 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 destination, but also increases message latency.

For optimal performance when sending messages to an syslog-ng PE server, make sure that the flush-lines() is smaller than the window size set using the log-iw-size() option in the source of your server.

flush-timeout() (OBSOLETE)
Type: time in milliseconds
Default: Use global setting.

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.

fsync()
Type: yes or no
Default: no

Description: Forces an fsync() call on the destination fd after each write. Note: enabling this option may seriously degrade performance.

group()
Type: string
Default: Use the global settings

Description: Set the group of the created file to the one specified. To preserve the original properties of an existing file, use the option without specifying an attribute: group().

local-time-zone()
Type: name of the timezone, or the timezone offset
Default: The local timezone.

Description: Sets the timezone used when expanding filename and tablename templates.

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.

log-fifo-size()
Type: number (messages)
Default: Use global setting.

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

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()
Accepted values: internal | dst-idle | host-idle | periodical | none | global
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.

overwrite-if-older()
Type: number (seconds)
Default: 0

Description: If set to a value higher than 0, syslog-ng PE checks when the file was last modified before starting to write into the file. If the file is older than the specified amount of time (in seconds), then syslog-ng removes the existing file and opens a new file with the same name. In combination with for example the ${WEEKDAY} macro, this can be used for simple log rotation, in case not all history has to be kept. (Note that in this weekly log rotation example if its Monday 00:01, then the file from last Monday is not seven days old, because it was probably last modified shortly before 23:59 last Monday, so it is actually not even six days old. So in this case, set the overwrite-if-older() parameter to a-bit-less-than-six-days, for example, to 518000 seconds.

owner()
Type: string
Default: Use the global settings

Description: Set the owner of the created file to the one specified. To preserve the original properties of an existing file, use the option without specifying an attribute: owner().

pad-size()
Type: number (bytes)
Default: 0

Description: If set, syslog-ng PE will pad output messages to the specified size (in bytes). Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes).

Caution:

Hazard of data loss! If the size of the incoming message is larger than the previously set pad-size() value, syslog-ng will truncate the message to the specified size. Therefore, all message content above that size will be lost.

perm()
Type: number (octal notation)
Default: Use the global settings

Description: The permission mask of the file if it is created by syslog-ng. For octal numbers prefix the number with 0, for example use 0755 for rwxr-xr-x.

To preserve the original properties of an existing file, use the option without specifying an attribute: perm().

suppress()
Type: seconds
Default: 0 (disabled)

Description: If several identical log messages would be sent to the destination without any other messages between the identical messages (for example, an application repeated an error message ten times), syslog-ng can suppress the repeated messages and send the message only once, followed by the Last message repeated n times. message. The parameter of this option specifies the number of seconds syslog-ng waits for identical messages.

template()
Type: string
Default: A format conforming to the default logfile format.

Description: Specifies a template defining the logformat to be used in the destination. Macros are described in the section called “Macros of syslog-ng PE”. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.

template-escape()
Type: yes or no
Default: no

Description: Turns on escaping for the ', ", and backspace characters in templated output files. This is useful for generating SQL statements and quoting string contents so that parts of the log message are not interpreted as commands to the SQL server.

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

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.

ts-format()
Type: rfc3164, bsd, rfc3339, iso
Default: Use the global option (which defaults to rfc3164)

Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see the section called “A note on timezones and timestamps”.

Storing messages in encrypted files

The syslog-ng PE application can store log messages securely in encrypted, compressed and timestamped binary files. Timestamps can be requested from an external Timestamping Authority (TSA).

Logstore files consist of individual chunks, every chunk can be encrypted, compressed, and timestamped separately. Chunks contain compressed log messages and header information needed for retrieving messages from the logstore file.

The syslog-ng PE application generates an SHA-1 hash for every chunk to verify the integrity of the chunk. The hashes of the chunks are chained together to prevent injecting chunks into the logstore file. The syslog-ng PE application can encrypt the logstore using various algorithms, using the aes128 encryption algorithm in CBC mode and the hmac-sha1 hashing (HMAC) algorithm as default. For other algorithms, see the section called “cipher()” and the section called “digest()”.

The destination filename may include macros which get expanded when the message is written, thus a simple logstore() driver may create several files. For more information on available macros see the section called “Macros of syslog-ng PE”.

If the expanded filename refers to a directory which does not exist, it will be created depending on the create-dirs() setting (both global and a per destination option).

The logstore() has a single required parameter that specifies the filename that stores the log messages. For the list of available optional parameters, see the section called “logstore() destination options”.

Caution:

Hazard of data loss! If your log files are on an NFS-mounted network file system, see the section called “NFS file system for log files”.

Declaration: 

logstore(filename options());

Example 7.15. Using the logstore() driver

A simple example saving and compressing log messages.

destination d_logstore { logstore("/var/log/messages.lgs" compress(5) ); };

A more detailed example that encrypts messages, modifies the parameters for closing chunks, and sets file privileges.

destination d_logstore { logstore("/var/log/messages-logstore.lgs"
encrypt-certificate("/opt/syslog-ng/etc/syslog-ng/keys/10-100-20-40/public-certificate-of-the-server.pem")
owner("balabit")
group("balabit")
perm(0777)
); };

The URL to the Timestamping Authority and if needed, the OID of the timestamping policy can be set as global options, or also per logstore destination. The following example specifies the URL and the OID as global options:

options {
        timestamp-url("http://10.50.50.50:8080/");
        timestamp-policy("0.4.0.2023.1.1");
};

NOTE:

When using the logstore() destination, update the configuration of your log rotation program to rotate these files. Otherwise, the log files can become very large.

Caution:

Since the state of each created file must be tracked by syslog-ng, it consumes some memory for each file. If no new messages are written to a file within 60 seconds (controlled by the time-reap() global option), it is closed, and its state is freed.

Exploiting this, a DoS attack can be mounted against the system. If the number of possible destination files and its needed memory is more than the amount available on the syslog-ng server.

The most suspicious macro is ${PROGRAM}, where the number of possible variations is rather high. Do not use the ${PROGRAM} macro in insecure environments.

Displaying the contents of logstore files

To display the contents of a logstore file, use the lgstool (formerly called logcat) command supplied with syslog-ng, for example lgstool cat /var/log/messages.lgs. Log messages available in the journal file of the logstore (but not yet written to the logstore file itself) are displayed as well.

To display the contents of encrypted log files, specify the private key of the certificate used to encrypt the file, for example lgstool cat -k private.key /var/log/messages.lgs. The contents of the file are sent to the standard output, so it is possible to use grep and other tools to find particular log messages, for example lgstool cat /var/log/messages.lgs |grep 192.168.1.1. For further details, see lgstool(1).

TIP:

The lgstool utility is available for Microsoft Windows operating systems at the syslog-ng Downloads page.

Caution:

For files that are in use by syslog-ng, the last chunk that is open cannot be read.

Journal files

Starting with syslog-ng Premium Edition 3.2, syslog-ng PE processes log messages into a journal file before writing them to the logstore file. That way logstore files are consistent even if syslog-ng PE crashes unexpectedly, avoiding losing messages. Note that this does not protect against losing messages if the operating system crashes.

A journal file is automatically created for every logstore file that syslog-ng PE opens. A journal file consists of journal blocks which store the log messages. When a journal block fills up with messages, syslog-ng PE writes the entire block into the logstore file and starts to reuse the journal block (one journal block becomes one chunk in the logstore file). If the messages cannot be written to the logstore file (for example, because the disk becomes unaccessible, or file operations are slow), messages are put to the next journal block (syslog-ng PE uses four blocks by default). When all journal blocks become full, syslog-ng PE will stop processing incoming traffic. syslog-ng PE starts accepting messages to the logstore file again when the first journal block is successfully written to the logstore file. If syslog-ng PE receives a HUP or STOP signal, or no new message arrives into the logstore for the period set in the time-reap() parameter, it writes every journal block to the logstore.

When syslog-ng PE is restarted, it automatically processes the journal files to the logstore files, unless a particular logstore file is not part of configuration of syslog-ng PE. Such orphaned journal files can be processed with the lgstool recover command. For details on processing orphaned journal files, see the section called “The recover command”.

Caution:
  • If a particular logstore destination receives messages at a constant but very low message rate (for example, a 100-byte message every 30 seconds), messages do not get written to the logstore file for a long time, because the journal block does not get full, and messages are more frequent than the time-reap() time. This becomes a problem when using logrotate to rotate the logstore files, because log messages will not be in the files they are expected. To avoid this situation, either use time-based macros in the filenames of the logstore files, or send a HUP signal to syslog-ng PE right before rotating the logstore files.

  • When every block of a journal becomes full and syslog-ng PE stops processing incoming traffic, it will not read new messages at all until a block is successfully written to the related logstore file. This is in contrast with flow-control, where only messages from the source related to the particular destination are not processed.

  • The messages in the journal file are in plain-text format: they are neither encrypted nor compressed. The journal file has the same permission as the logstore, by default, root privileges are required to access them. Make sure you consider this if you change the permissions of the journal file (owner, group, perm) in the syslog-ng PE configuration file.

NOTE:

Journal files are located in the same folder as the logstore file. The name of the journal file is the same as the logstore file with .jor suffix added. For example, the journal file for messages.lgs is messages.lgs.jor.

The syslog-ng PE application uses a separate journal file for every logstore file. Every journal file is processed by a separate thread. The journal files are mapped into the memory. The journal of an individual logstore file uses up to journal-block-size()*journal-block-count() memory address, which is 4MB by default. However, if you have several logstore files open in parallel (for example, you are collecting log messages from 500 hosts and storing them in separate files for every host, and the hosts are continuously sending messages) the memory requirements for journaling rise quickly (to ~2GB for the 500 hosts). To limit the memory use of journals, adjust the logstore-journal-shmem-threshold() global option (by default, it is 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”.

Caution:

If you have a large amount of open logstore files in parrallel (for example, you are using the ${HOST} or ${PROGRAM} macros in your filenames) consider lowering the journal-block-size() to avoid syslog-ng PE consuming the entire memory of the system.

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


logstore() destination options

The logstore driver stores log messages in binary files that can be encrypted, compressed, checked for integrity, and timestamped by an external Timestamping Authority (TSA). Otherwise, it is very similar to the file() destination.

Caution:

When creating several thousands separate log files, syslog-ng might not be able to open the required number of files. This might happen for example when using the ${HOST} macro in the filename while receiving messages from a large number of hosts. To overcome this problem, adjust the --fd-limit command-line parameter of syslog-ng or the global ulimit parameter of your host. For setting the --fd-limit command-line parameter of syslog-ng see the syslog-ng(8) manual page. For setting the ulimit parameter of the host, see the documentation of your operating system.

NOTE:

When using this destination, update the configuration of your log rotation program to rotate these files. Otherwise, the log files can become very large.

Also, after rotating the log files, reload syslog-ng PE using the syslog-ng-ctl reload command, or use another method to send a SIGHUP to syslog-ng PE.

The logstore() has a single required parameter that specifies the filename that stores the log messages.

Declaration: 

logstore(filename options());

The logstore() destination has the following options:

cipher()
Type: string
Default: aes-128-cbc

Description: Set the cipher method used to encrypt the logstore. The following cipher methods are available: aes-128-cbc, aes-128-cfb, aes-128-cfb1, aes-128-cfb8, aes-128-ecb, aes-128-ofb , aes-192-cbc, aes-192-cfb, aes-192-cfb1, aes-192-cfb8, aes-192-ecb, aes-192-ofb , aes-256-cbc, aes-256-cfb, aes-256-cfb1, aes-256-cfb8, aes-256-ecb, aes-256-ofb , aes128 , aes192 , aes256, bf , bf-cbc , bf-cfb, bf-ecb , bf-ofb , blowfish, cast , cast-cbc , cast5-cbc , cast5-cfb, cast5-ecb, cast5-ofb , des, des-cbc, des-cfb , des-cfb1 , des-cfb8 , des-ecb , des-ede, des-ede-cbc, des-ede-cfb , des-ede-ofb, des-ede3 , des-ede3-cbc, des-ede3-cfb, des-ede3-ofb, des-ofb , des3 , desx , desx-cbc, rc2, rc2-40-cbc , rc2-64-cbc, rc2-cbc, rc2-cfb, rc2-ecb , rc2-ofb, rc4, and rc4-40. By default, syslog-ng PE uses the aes-128-cbc method.

Note that the size of the digest hash must be equal to or larger than the key size of the cipher method. For example, to use the aes-256-cbc cipher method, the digest method must be at least SHA-256. This option is available in syslog-ng PE 3.1 and later.

chunk-size()
Type: number (kilobytes)
Default: 128

Description: This option is obsolete. Use the journal-block-size() option instead.

Size of a logstore chunk in kilobytes. Note that this size refers to the compressed size of the chunk. Also, the gzip library used for compressing the messages has a 32k long buffer, so messages may not appear in the actual logfile until this buffer is not filled. Logstore chunks are closed when they reach the specified size, or when the time limit set in chunk-time() expires.

chunk-time()
Type: number (seconds)
Default: 5

Description: This option is obsolete.

Time limit in seconds: syslog-ng PE closes the chunk if no new messages arrive until the time limit expires. Logstore chunks are closed when the time limit expires, or when they reach the size specified in the chunk-size() parameter. If the time limit set in the time-reap() parameter expires, the entire file is closed.

compress()
Type: number (between 0-9)
Default: 3

Description: Compression level. 0 means uncompressed files, while 1-9 is the compression level used by gzip (9 means the highest but slowest compression, 3 is usually a good compromise).

create-dirs()
Type: yes or no
Default: no

Description: Enable creating non-existing directories.

digest()
Type: string
Default: SHA1

Description: Set the digest method to use. The following digest methods are available: MD4, MD5, SHA0 (SHA), SHA1, RIPEMD160, SHA224, SHA256, SHA384, and SHA512. By default, syslog-ng PE uses the SHA1 method.

Note that the size of the digest hash must be equal to or larger than the key size of the cipher method. For example, to use the aes-256-cbc cipher method, the digest method must be at least SHA256. This option is available in syslog-ng PE 3.1 and later.

dir-group()
Type: string
Default: Use the global settings

Description: The group of the directories created by syslog-ng. To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-group().

dir-owner()
Type: string
Default: Use the global settings

Description: The owner of the directories created by syslog-ng. To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-owner().

dir-perm()
Type: number (octal notation)
Default: Use the global settings

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

encrypt-certificate()
Type: filename
Default: none

Description: Name of a file, that contains an X.509 certificate (and the public key) in PEM format. The syslog-ng PE application uses this certificate to encrypt the logstore files which can be decrypted using the private key of the certificate.

flags()
Type: serialized
Default: empty set

Description: Flags influence the behavior of the destination driver.

  • The serialized flag instructs the driver to store the log messages in a serialized format. When using the lgstool utility to display messages from the logstore, the messages can be reformatted with a template only if the serialized flag has been enabled on the logstore.

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()
Type: string
Default: Use the global settings

Description: Set the group of the created file to the one specified. To preserve the original properties of an existing file, use the option without specifying an attribute: group().

log-fifo-size()
Type: number (messages)
Default: Use global setting.

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

journal-block-count()
Type: number (1-255)
Default: 4

Description: The number of blocks in the journal file. If set to 0, syslog-ng will set it to the default value (4). The maximal value is 255. If journal-block-count() is set higher than 255, syslog-ng will use the maximum value.

NOTE:

By default, journal files are mapped into the memory of the host. To influence the amount of memory addresses used by journal files, see the logstore-journal-shmem-threshold() global option.

Example 7.17. Setting journal block number and size

The following example sets the size of a journal block to 512KB and increases the number of blocks to 5.

destination d_logstore {
     logstore("/var/log/messages-logstore.lgs"
        encrypt-certificate ("/opt/syslog-ng/etc/syslog-ng/keys/public-server-certificate.pem")
        journal-block-size(524288)
        journal-block-count(5));
};

journal-block-size()
Type: number (bytes)
Default: 1048576

Description: The size of blocks (in bytes) in the journal file. The size of the block must be a multiple of the page size: if not, syslog-ng PE automatically increases it to the next multiple of the page size. The maximum size of a journal block is 32MB, the minimum size is 256KB. If the value specified as journal-block-size() is lower than minimum size or higher than the maximum size, syslog-ng PE will use the minimum or maximum size, respectively.

NOTE:
  • At least one journal block for every logstore file open is mapped into the memory. For details on logstore journals, see the section called “Journal files”.

  • The size of the journal block is not equal with the size of logstore chunks, because the records in the logstore file can be encrypted or compressed.

Example 7.18. Setting journal block number and size

The following example sets the size of a journal block to 512KB and increases the number of blocks to 5.

destination d_logstore {
     logstore("/var/log/messages-logstore.lgs"
        encrypt-certificate ("/opt/syslog-ng/etc/syslog-ng/keys/public-server-certificate.pem")
        journal-block-size(524288)
        journal-block-count(5));
};

owner()
Type: string
Default: Use the global settings

Description: Set the owner of the created file to the one specified. To preserve the original properties of an existing file, use the option without specifying an attribute: owner().

perm()
Type: number (octal notation)
Default: Use the global settings

Description: The permission mask of the file if it is created by syslog-ng. For octal numbers prefix the number with 0, for example use 0755 for rwxr-xr-x.

To preserve the original properties of an existing file, use the option without specifying an attribute: perm().

template()
Type: string
Default: A format conforming to the default logfile format.

Description: Specifies a template defining the logformat to be used in the destination. Macros are described in the section called “Macros of syslog-ng PE”. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.

throttle()
Type: number (messages per second)
Default: 0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

timestamp-freq()
Type: number (seconds)
Default: Use global setting.

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-policy()
Type: string
Default:

Description: If the Timestamping Server has timestamping policies configured, specify the OID of the policy to use with this parameter. 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.

timestamp-url()
Type: string
Default: Use global setting.

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.

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

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.

ts-format()
Type: rfc3164, bsd, rfc3339, iso
Default: Use the global option (which defaults to rfc3164)

Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see the section called “A note on timezones and timestamps”.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating