Chat now with support
Chat with Support

syslog-ng Open Source Edition 3.38 - Administration Guide

Preface Introduction to syslog-ng The concepts of syslog-ng Installing syslog-ng The syslog-ng OSE quick-start guide The syslog-ng OSE configuration file source: Read, receive, and collect log messages
How sources work default-network-drivers: Receive and parse common syslog messages internal: Collecting internal messages file: Collecting messages from text files wildcard-file: Collecting messages from multiple text files kubernetes: Collecting and parsing the Kubernetes CRI (Container Runtime Interface) format linux-audit: Collecting messages from Linux audit logs mqtt: receiving messages from an MQTT broker network: Collecting messages using the RFC3164 protocol (network() driver) nodejs: Receiving JSON messages from nodejs applications mbox: Converting local email messages to log messages osquery: Collect and parse osquery result logs pipe: Collecting messages from named pipes pacct: Collecting process accounting logs on Linux program: Receiving messages from external applications python: writing server-style Python sources python-fetcher: writing fetcher-style Python sources snmptrap: Read Net-SNMP traps sun-streams: Collecting messages on Sun Solaris syslog: Collecting messages using the IETF syslog protocol (syslog() driver) system: Collecting the system-specific log messages of a platform systemd-journal: Collecting messages from the systemd-journal system log storage systemd-syslog: Collecting systemd messages using a socket tcp, tcp6, udp, udp6: Collecting messages from remote hosts using the BSD syslog protocol— OBSOLETE unix-stream, unix-dgram: Collecting messages from UNIX domain sockets stdin: Collecting messages from the standard input stream
destination: Forward, send, and store log messages
amqp: Publishing messages using AMQP collectd: sending metrics to collectd discord: Sending alerts and notifications to Discord elasticsearch2: Sending messages directly to Elasticsearch version 2.0 or higher (DEPRECATED) elasticsearch-http: Sending messages to Elasticsearch HTTP Bulk API file: Storing messages in plain-text files graphite: Sending metrics to Graphite Sending logs to Graylog hdfs: Storing messages on the Hadoop Distributed File System (HDFS) Posting messages over HTTP http: Posting messages over HTTP without Java kafka: Publishing messages to Apache Kafka (Java implementation) kafka-c(): Publishing messages to Apache Kafka using the librdkafka client (C implementation) loggly: Using Loggly logmatic: Using Logmatic.io mongodb(): Storing messages in a MongoDB database mqtt() destination: sending messages from a local network to an MQTT broker network: Sending messages to a remote log server using the RFC3164 protocol (network() driver) osquery: Sending log messages to osquery's syslog table pipe: Sending messages to named pipes program: Sending messages to external applications pseudofile() python: writing custom Python destinations redis: Storing name-value pairs in Redis riemann: Monitoring your data with Riemann slack: Sending alerts and notifications to a Slack channel smtp: Generating SMTP messages (email) from logs snmp: Sending SNMP traps Splunk: Sending log messages to Splunk sql: Storing messages in an SQL database stomp: Publishing messages using STOMP Sumo Logic destinations: sumologic-http() and sumologic-syslog() syslog: Sending messages to a remote logserver using the IETF-syslog protocol syslog-ng(): Forward logs to another syslog-ng node tcp, tcp6, udp, udp6: Sending messages to a remote log server using the legacy BSD-syslog protocol (tcp(), udp() drivers) Telegram: Sending messages to Telegram unix-stream, unix-dgram: Sending messages to UNIX domain sockets usertty: Sending messages to a user terminal: usertty() destination Write your own custom destination in Java or Python Client-side failover
log: Filter and route log messages using log paths, flags, and filters Global options of syslog-ng OSE TLS-encrypted message transfer template and rewrite: Format, modify, and manipulate log messages parser: Parse and segment structured messages
Parsing syslog messages Parsing messages with comma-separated and similar values Parsing key=value pairs JSON parser XML parser Parsing dates and timestamps Python parser Parsing tags Apache access log parser Linux audit parser Cisco parser Parsing enterprise-wide message model (EWMM) messages iptables parser Netskope parser panos-parser(): parsing PAN-OS log messages Sudo parser MariaDB parser Websense parser Fortigate parser Check Point Log Exporter parser Regular expression (regexp) parser db-parser: Process message content with a pattern database (patterndb)
Correlating log messages Enriching log messages with external data Statistics of syslog-ng Multithreading and scaling in syslog-ng OSE Troubleshooting syslog-ng Best practices and examples The syslog-ng manual pages Creative Commons Attribution Non-commercial No Derivatives (by-nc-nd) License The syslog-ng Open Source Edition Documentation License Glossary

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 options statement to the syslog-ng configuration file using the following syntax:

options { option1(params); option2(params); ... };
Example: 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 Global options. For important global options and recommendations on their use, see Best practices and examples.

Global options

The following options can be specified in the options statement, as described in 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 OSE 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 OSE 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 OSE server via a syslog-ng OSE relay, the hostname depends on the settings of the keep-hostname() and the chain-hostnames() options both on the syslog-ng OSE relay and the syslog-ng OSE 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 can interfere with the way syslog-ng OSE counts the log source hosts. As a result, syslog-ng OSE falsely perceives several 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()

NOTE: This global option works only if the use-fqdn() global option is set to yes.

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

  • 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 3.16, the default value of this option is -1, so syslog-ng OSE 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.

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
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 OSE 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 OSE 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 OSE or in case of network sources, the connection with the client is closed, syslog-ng OSE automatically sends the unsent messages to the destination.

frac-digits()
Type: number
Default: 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: The syslog-ng OSE application can add the fractions to non-ISO8601 timestamps as well.

NOTE: As syslog-ng OSE is precise up to the microsecond, when the frac-digits() option is set to a value higher than 6, syslog-ng OSE will truncate the fraction seconds in the timestamps after 6 digits.

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 OSE configuration file.

For example:

jvm-options("-Xss1M -XX:+TraceClassLoading")
keep-hostname()
Type: yes or no
Default: no

Description: Enable or disable hostname rewriting.

  • If enabled (keep-hostname(yes)), syslog-ng OSE 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 OSE 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 OSE. For details on using name resolution in syslog-ng OSE, see Using name resolution in syslog-ng.

    s

NOTE: If the log message does not contain a hostname in its HOST field, syslog-ng OSE 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 OSE 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 OSE server and also on every relay, otherwise syslog-ng OSE 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 OSE).

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 an incoming 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 (256 MiB).

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

NOTE: In most cases, log-msg-size() does not need to be set higher than 10 MiB.

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, seeNotes about the configuration syntax.

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.

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 OSE 3.3 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. Note that setting the global mark-mode() to global causes a syntax error in syslog-ng OSE.

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 OSE 3.4 and later.

normalize-hostnames()
Accepted values: yes | no
Default: no

Description: If enabled (normalize-hostnames(yes)), syslog-ng OSE 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 OSE cannot convert some data to the specified type. By default, syslog-ng OSE 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 OSE.

  • 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 3.16, the default value of this option is -1, so syslog-ng OSE does not change the ownership, unless explicitly configured to do so.

pass-unix-credentials()
Accepted values: yes|no
Default: yes

Description: Enable syslog-ng OSE 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 Open Source Edition 3.7 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: 0600

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 3.16, the default value of this option is -1, so syslog-ng OSE 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 by using the name, 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 Timezones and daylight saving.

The timezone can be specified by using the name, 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 by using the name, 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.

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 Statistics of syslog-ng.

stats-max-dynamics()
Accepted values: number
Default: N/A

Description: To avoid performance issues or even overloading syslog-ng OSE (for example, if a script starts to send logs from different IP addresses to syslog-ng OSE), you might want to limit the number of registered dynamic counters in the message statistics. For details on message statistics, see Statistics 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).

NOTE: If you set a lower value to stats-max-dynamics() (or, any limiting value, if this option has not been configured before) and restart syslog-ng OSE, the changes will only be applied after stats-freq() time has passed. That is, the previously allocated dynamic clusters will only be removed after this time.

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 OSE to run in multithreaded mode and use multiple CPUs. Available only in syslog-ng Open Source Edition 3.3 and later. Note that setting threaded(no) does not mean that syslog-ng OSE will use only a single thread. For details, see Multithreading and scaling in syslog-ng OSE.

time-reap()
Accepted values: number (seconds)
Default: 60 or 0, see description for details

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

Starting with version 3.23, the way how time-reap() works is the following.

  1. If the time-reap() option of the destination is set, that value is used, for example:

    destination d_fifo {
        pipe(
            "/tmp/test.fifo",
            time-reap(30)  # sets time-reap() for this destination only
        );
    };
  2. If the time-reap() option of the destination is not set, and the destination does not use a template or macro in its filename or path, time-reap() is automatically set to 0. For example:

    destination d_fifo {
        pipe(
            "/tmp/test.fifo",
        );
    };
  3. Otherwise, the value of the global time-reap() option is used, which defaults to 60 seconds.

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.

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 Date-related macros.

The timezone can be specified by using the name, 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.

trim-large-messages()
Accepted values: yes|no
Default: no

Description: Determines what syslog-ng OSE 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 OSE drops the incoming log message.

  • If set to yes, syslog-ng OSE 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 OSE 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 OSE version 3.21 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.

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 OSE 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: Use this option to add a Fully Qualified Domain Name (FQDN) instead of a short hostname. You can specify this option either globally or per-source. The local setting of the source overrides the global option if available.

TIP: Set use-fqdn() to yes if you want to use the custom-domain() global option.

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

use-rcptid()
Accepted values: yes | no
Default: no

Description: When the use-rcptid global option is set to yes, syslog-ng OSE 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).

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

TLS-encrypted message transfer

Secure logging using TLS

The syslog-ng application can send and receive log messages securely over the network using the Transport Layer Security (TLS) protocol using the network() and syslog() drivers.

NOTE: This chapter describes how to use TLS encryption when using the standard syslog protocols, that is, the network() and syslog() drivers, for example, to forward log messages between two syslog-ng nodes, or to send log data to syslog-ng Store Box or another log server. Other destinations that support TLS-encryption are not discussed in this chapter (for example, http()).

TLS uses certificates to authenticate and encrypt the communication, as illustrated on the following figure:

Figure 19: Certificate-based authentication

The client authenticates the server by requesting its certificate and public key. Optionally, the server can also request a certificate from the client, thus mutual authentication is also possible.

In order to use TLS encryption in syslog-ng, the following elements are required:

  • A certificate on the syslog-ng server that identifies the syslog-ng server.

  • The certificate of the Certificate Authority that issued the certificate of the syslog-ng server (or the self-signed certificate of the syslog-ng server) must be available on the syslog-ng client.

When using mutual authentication to verify the identity of the clients, the following elements are required:

  • A certificate must be available on the syslog-ng client. This certificate identifies the syslog-ng client.

  • The certificate of the Certificate Authority that issued the certificate of the syslog-ng client must be available on the syslog-ng server.

Mutual authentication ensures that the syslog-ng server accepts log messages only from authorized clients.

For more information about configuring TLS communication in syslog-ng, see Encrypting log messages with TLS.

For more information about TLS-related error messages, see Error messages.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating