The following options can be specified in the options statement, as described in the section called “Configuring global syslog-ng options”.
Accepted values: | regular expression |
Default: | no |
Description: A regexp containing hostnames which should not be handled as hostnames.
Accepted values: | yes | no |
Default: | no |
Description: Enable or disable the chained hostname format. If a client sends the log message directly to the syslog-ng PE server, the chain-hostnames()
option is enabled on the server, and the client sends a hostname in the message that is different from its DNS hostname (as resolved from DNS by the syslog-ng PE server), then the server can append the resolved hostname to the hostname in the message (separated with a /
character) when the message is written to the destination.
For example, consider a client-server scenario with the following hostnames: client-hostname-from-the-message
, client-hostname-resolved-on-the-server
, server-hostname
. The hostname of the log message written to the destination depends on the keep-hostname()
and the chain-hostnames()
options. How keep-hostname()
and chain-hostnames()
options are related is described in the following table.
keep-hostname() setting on the server | |||
---|---|---|---|
yes | no | ||
chain-hostnames() setting on the server | yes | client-hostname-from-the-message | client-hostname-from-the-message / client-hostname-resolved-on-the-server |
no | client-hostname-from-the-message | client-hostname-resolved-on-the-server |
If the log message is forwarded to the syslog-ng PE server via a syslog-ng PE relay, the hostname depends on the settings of the keep-hostname()
and the chain-hostnames()
options both on the syslog-ng PE relay and the syslog-ng PE server.
For example, consider a client-relay-server scenario with the following hostnames: client-hostname-from-the-message
, client-hostname-resolved-on-the-relay
, client-hostname-resolved-on-the-server
, relay-hostname-resolved-on-the-server
. How keep-hostname()
and chain-hostnames()
options are related is described in the following table.
chain-hostnames() setting on the server | |||||||
---|---|---|---|---|---|---|---|
yes | no | ||||||
keep-hostname() setting on the server | keep-hostname() setting on the server | ||||||
yes | no | yes | no | ||||
chain- hostnames() setting on the relay | yes | keep- hostname() setting on the relay | yes | client-hostname- from-the-message | client-hostname- from-the-message / relay-hostname- resolved-on-the- server | client-hostname- from-the-message | relay-hostname- resolved-on-the- server |
no | client-hostname- from-the-message / client-hostname- resolved-on-the- relay | client-hostname- from-the-message / client-hostname- resolved-on-the- relay / relay- hostname-resolved- on-the-server | client-hostname- from-the-message / client-hostname- resolved-on-the- relay | ||||
no | keep- hostname() setting on the relay | yes | client-hostname- from-the-message | client-hostname- from-the-message / relay-hostname- resolved-on-the- server | client-hostname- from-the-message | ||
no | client-hostname- resolved-on-the- relay | client-hostname- resolved-on-the- relay / relay- hostname-resolved- on-the-server | client-hostname- resolved-on-the- relay |
The chain-hostnames()
option of syslog-ng can interfere with the way syslog-ng PE counts the log source hosts, causing syslog-ng to think there are more hosts logging to the central server, especially if the clients sends a hostname in the message that is different from its real hostname (as resolved from DNS). Disable the chain-hostnames()
option on your log sources to avoid any problems related to license counting.
Accepted values: | yes | no |
Default: | no |
Description: Enable or disable checking whether the hostname contains valid characters.
Accepted values: | yes | no |
Default: | no |
Description: Enable or disable directory creation for destination files.
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 FQDN. This option affects every outgoing message: eventlog sources, file sources, MARK messages and internal messages of syslog-ng PE.
-
If the hostname is a short hostname, the custom domain name is appended after the hostname (for example
mypc
becomesmypc.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 iscustomcompany.local
, the hostname in the outgoing message becomesmypc.customcompany.local
).
Accepted values: | groupid |
Default: | root |
Description: The default group for newly created directories.
Accepted values: | permission value |
Default: | 0700 |
Description: The permission mask of directories created by syslog-ng. Log directories are only created if a file after macro expansion refers to a non-existing directory, and directory creation is enabled (see also the create-dirs()
option). For octal numbers prefix the number with 0
, for example use 0755
for rwxr-xr-x
.
To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-perm()
. Note that when creating a new directory without specifying attributes for dir-perm()
, the default permission of the directories is masked with the umask of the parent process (typically 0022
).
Accepted values: | number (seconds) |
Default: | 3600 |
Description: Number of seconds while a successful lookup is cached.
Accepted values: | number (seconds) |
Default: | 60 |
Description: Number of seconds while a failed lookup is cached.
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.
Accepted values: | number of hostnames |
Default: | 1007 |
Description: Number of hostnames in the DNS cache.
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); };
Accepted values: | number (messages) |
Default: | 1 |
Description: Specifies how many lines are flushed to a destination at a time. The syslog-ng PE application waits for this number of lines to accumulate and sends them off in a single batch. Setting this number high increases throughput as fully filled frames are sent to the network, but also increases message latency.
Accepted values: | time in milliseconds |
Default: | 10000 |
Description: This is an obsolete option. Specifies the time syslog-ng waits for lines to accumulate in its output buffer. For details, see the flush-lines()
option.
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.
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.
Type: | yes or no |
Default: | no |
Description: Enable or disable hostname rewriting.
-
If enabled (
keep-hostname(yes)
), syslog-ng PE assumes that the incoming log message was sent by the host specified in theHOST
field of the message. -
If disabled (
keep-hostname(no)
), syslog-ng PE rewrites theHOST
field of the message, either to the IP address (if theuse-dns()
parameter is set tono
), or to the hostname (if theuse-dns()
parameter is set toyes
and the IP address can be resolved to a hostname) of the host sending the message to syslog-ng PE. For details on using name resolution in syslog-ng PE, see the section called “Using name resolution in syslog-ng”.
This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
|
NOTE:
When relaying messages, enable this option on the syslog-ng PE server and also on every relay, otherwise syslog-ng PE will treat incoming messages as if they were sent by the last relay. |
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.
Accepted values: | number (messages) |
Default: | 10000 |
Description: The number of messages that the output queue can store.
Accepted values: | number (bytes) |
Default: | 65535 |
Description: Maximum length of a message in bytes. This length includes the entire message (the data structure and individual fields). The maximal value that can be set is 268435456 bytes (256MB). For messages using the IETF-syslog message format (RFC5424), the maximal size of the value of an SDATA field is 64kB.
Type: | number (bytes) |
Default: | 536870912 |
Description: If the size of memory (in bytes) required by journal files increases above this value, syslog-ng PE maps only a single block of every logstore journal into the memory. Default value: 536870912
(512 MB).
If the memory required for the journal files exceeds the logstore-journal-shmem-threshold()
limit, syslog-ng PE will store only a single journal block of every journal file in the memory, and — if more blocks are needed for a journal — store the additional blocks on the hard disk. Opening new logstore files means allocating memory for one new journal block for every new file. In extreme situations involving large traffic, this can lead to syslog-ng PE consuming the entire memory of the system. Adjust the journal-block-size()
and your file-naming conventions as needed to avoid such situations. For details on logstore journals, see the section called “Journal files”.
Example 9.2. Calculating memory usage of logstore journals
If you are using the default settings (4 journal blocks for every logstore journal, one block is 1MB, logstore-journal-shmem-threshold()
is 512MB), this means that syslog-ng PE will allocate 4MB memory for every open logstore file, up to 512MB if you have 128 open logstore files. Opening a new logstore file would require 4 more megabytes of memory for journaling, bringing the total required memory to 516MB, which is above the logstore-journal-shmem-threshold()
. In this case, syslog-ng PE switches to storing only a single journal block in the memory, lowering the memory requirements of journaling to 129MB. However, opening more and more logstore files will require more and more memory, and this is not limited, except when syslog-ng PE reaches the maximum number of files that can be open (as set in the --fd-limit
command-line option).
Example 9.3. Limiting the memory use of journal files
The following example causes syslog-ng PE to map only a single journal block into the host's memory if the total memory range used by logstore journals would be higher than 32 MB.
options { logstore-journal-shmem-threshold(33554432); }; destination d_messages { logstore("/var/log/messages_logstore.lgs" journal-block-size(19660800) journal-block-count(5) ); };
Accepted values: | number (seconds) |
Default: | 1200 |
Description: The mark-freq()
option is an alias for the deprecated mark()
option. This is retained for compatibility with syslog-ng version 1.6.x.
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).
Accepted values: | internal | dst-idle | host-idle | periodical | none | global |
Default: |
|
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
: SendsMARK
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
: SendsMARK
signal if there was NO local message on destination drivers. For exampleMARK
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
: SendsMARK
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 allMARK
messages. If an explicit mark-mode() is not given to the drivers wherenone
is the default value, thennone
will be used. -
global
: Destination driver uses the globalmark-mode()
setting. The syslog-ng interprets syntax error if the globalmark-mode()
is global.
|
NOTE:
In case of |
Available in syslog-ng PE 4 LTS and later.
Accepted values: | yes | no |
Default: | no |
Description: If enabled (normalize-hostnames(yes)
), syslog-ng PE converts the hostnames to lowercase.
Accepted values: | drop-message|drop-property|fallback-to-string|silently-drop-message|silently-drop-property|silently-fallback-to-string |
Default: | drop-message |
Description: Controls what happens when type-casting fails and syslog-ng PE cannot convert some data to the specified type. By default, syslog-ng PE drops the entire message and logs the error. Currently the value-pairs()
option uses the settings of on-error()
.
-
drop-message
: Drop the entire message and log an error message to theinternal()
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 theinternal()
source. -
fallback-to-string
: Convert the property to string and log an error message to theinternal()
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.
Accepted values: | userid |
Default: | root |
Description: The default owner of output files. By default, syslog-ng changes the privileges of accessed files (for example /dev/null
) to root.root 0600
. To disable modifying privileges, use this option with the -1
value.
Accepted values: | permission value |
Default: | 0600 |
Description: The default permission for output files. By default, syslog-ng changes the privileges of accessed files (for example /dev/null
) to root.root 0600
. To disable modifying privileges, use this option with the -1
value.
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); };
Accepted values: | name of the timezone, or the timezone offset |
Default: | local timezone |
Description: Specifies the time zone associated with the incoming messages, if not specified otherwise in the message or in the source driver. For details, see also the section called “Timezones and daylight saving” and the section called “A note on timezones and timestamps”.
The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")
), or as the timezone offset in +/-HH:MM format (for example +01:00
). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo
directory.
Accepted values: | name of the timezone, or the timezone offset |
Default: | local timezone |
Description: Specifies the time zone associated with the messages sent by syslog-ng, if not specified otherwise in the message or in the destination driver. For details, see the section called “Timezones and daylight saving”.
The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")
), or as the timezone offset in +/-HH:MM format (for example +01:00
). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo
directory.
The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")
), or as the timezone offset in +/-HH:MM format (for example +01:00
). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo
directory.
Accepted values: | number (seconds) |
Default: | 600 |
Description: The period between two STATS messages in seconds. STATS are log messages sent by syslog-ng, containing statistics about dropped log messages. Set to 0
to disable the STATS messages.
Accepted values: | 0 | 1 | 2 | 3 |
Default: | 0 |
Description: Specifies the detail of statistics syslog-ng collects about the processed messages.
-
Level 0 collects only statistics about the sources and destinations
-
Level 1 contains details about the different connections and log files, but has a slight memory overhead
-
Level 2 contains detailed statistics based on the hostname.
-
Level 3 contains detailed statistics based on various message parameters like facility, severity, or tags.
Note that level 2 and 3 increase the memory requirements and CPU load. For details on message statistics, see Chapter 17, Statistics and metrics of syslog-ng.
Accepted values: | yes|no |
Default: | yes |
Description: Enable syslog-ng PE to run in multithreaded mode and use multiple CPUs. Available only in syslog-ng Premium Edition 4 F1 and later. See Chapter 18, Multithreading and scaling in syslog-ng PE for details.
Accepted values: | number (seconds) |
Default: | 60 |
Description: The time to wait in seconds before an idle destination file is closed. Note that only destination files having macros in their filenames are closed automatically.
Accepted values: | number (seconds) |
Default: | 60 |
Description: The time to wait in seconds before a dead connection is reestablished.
Accepted values: | number (milliseconds) |
Default: | 0 |
Description: The time to wait in milliseconds between each invocation of the poll()
iteration.
Type: | number (seconds) |
Default: | 0 |
Description: The minimum time (in seconds) that should expire between two timestamping requests. When syslog-ng closes a chunk, it checks how much time has expired since the last timestamping request: if it is higher than the value set in the timestamp-freq()
parameter, it requests a new timestamp from the authority set in the timestamp-url()
parameter.
By default, timestamping is disabled: the timestamp-freq()
global option is set to 0. To enable timestamping, set it to a positive value.
Accepted values: | string |
Default: |
Description: The URL of the Timestamping Authority used to request timestamps to sign logstore chunks. Note that syslog-ng PE currently supports only Timestamping Authorities that conform to RFC3161 Internet X.509 Public Key Infrastructure Time-Stamp Protocol, other protocols like Microsoft Authenticode Timestamping are not supported.
Accepted values: | string |
Default: |
Description: If the Timestamping Server has timestamping policies configured, specify the OID of the policy to use into the Timestamping policy field. syslog-ng PE will include this ID in the timestamping requests sent to the TSA. This option is available in syslog-ng PE 3.1 and later.
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.
Accepted values: | rfc3164 | bsd | rfc3339 | iso |
Default: | rfc3164 |
Description: Specifies the timestamp format used when syslog-ng itself formats a timestamp and nothing else specifies a format (for example: STAMP
macros, internal messages, messages without original timestamps). For details, see also the section called “A note on timezones and timestamps”.
By default, timestamps include only seconds. To include fractions of a second (for example, milliseconds) use the frac-digits()
option. For details, see the section called “frac-digits()”.
|
NOTE:
This option applies only to file and file-like destinations. Destinations that use specific protocols (for example, |
Type: | yes, no, persist_only |
Default: | yes |
Description: Enable or disable DNS usage. The persist_only
option attempts to resolve hostnames locally from file (for example from /etc/hosts
). The syslog-ng PE application blocks on DNS queries, so enabling DNS may lead to a Denial of Service attack. To prevent DoS, protect your syslog-ng network endpoint with firewall rules, and make sure that all hosts which may get to syslog-ng are resolvable. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
|
NOTE:
This option has no effect if the |
Type: | yes or no |
Default: | no |
Description: Add Fully Qualified Domain Name instead of short hostname. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.
TIP: Set use-fqdn() to yes if you want to use the custom-domain() global option.
Accepted values: | yes | no |
Default: | no |
Description: The receipt ID function is disabled by default due to performance issues. For details, see also the section called “RCPTID”. This function is now deprecated. Use the use-uniqid()
option instead, for details, see the section called “use-uniqid()”.
Accepted values: | yes | no |
Default: | no |
Description: This option controls how the time related macros are expanded in filename and content templates. If set to yes, then the non-prefixed versions of the time related macros (for example: HOUR
instead of R_HOUR
and S_HOUR
) refer to the time when the message was received, otherwise it refers to the timestamp which is in the message.
|
NOTE:
The timestamps in the messages are generated by the originating host and might not be accurate. |
This option is deprecated as many users assumed that it controls the timestamp as it is written to logfiles/destinations, which is not the case. To change how messages are formatted, specify a content-template referring to the appropriate prefixed (S_
or R_
) time macro.
Accepted values: | yes | no |
Default: | no |
Description: This option enables generating a globally unique ID. It is generated from the HOSTID and the RCPTID in the format of HOSTID@RCPTID. It has a fixed length: 16+@+8 characters. You can include the unique ID in the message by using the macro. For details, see the section called “UNIQID”.
Enabling this option automatically generates the HOSTID. The HOSTID is a persistent, 32-bits-long cryptographically secure pseudo random number, that belongs to the host that the syslog-ng is running on. If the persist file is damaged, the HOSTID might change.
Enabling this option automatically enables the RCPTID functionality. For details, see the section called “RCPTID”