# Global options reference
The following options can be specified in the options statement, as described in [Configuring global options](../../docs/axosyslog-core/chapter-global-options/options/index.md).
## 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 AxoSyslog 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 AxoSyslog 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 AxoSyslog server via a AxoSyslog relay, the hostname depends on the settings of the `keep-hostname()` and the `chain-hostnames()` options both on the AxoSyslog relay and the AxoSyslog 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 AxoSyslog counts the log source hosts. As a result, AxoSyslog 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:_
When receiving messages, AxoSyslog can check whether the hostname contains valid characters.
Valid characters are:
* alphanumeric characters (A-Z, a-z, 0-9)
* the dash (`-`) and underscore (`_`) characters
* the dot (`.`) and the colon (`:`) characters
* the `@` and slash (`/`)
If the hostname contains invalid characters, AxoSyslog sets the `syslog.invalid_hostname` tag for the message, and doesn’t parse the `${HOST}` field from the message.
The `check-hostname()` global option applies to the following sources: [`file()`](../../docs/axosyslog-core/chapter-sources/configuring-sources-file/index.md), [`network()`](../../docs/axosyslog-core/chapter-sources/configuring-sources-network/index.md), [`pipe()`](../../docs/axosyslog-core/chapter-sources/source-pipe/index.md), [`program()`](../../docs/axosyslog-core/chapter-sources/source-program/index.md), [`stdin()`](../../docs/axosyslog-core/chapter-sources/configuring-sources-stdin/index.md), [`syslog()`](../../docs/axosyslog-core/chapter-sources/source-syslog/index.md), [`systemd-syslog()`](../../docs/axosyslog-core/chapter-sources/source-system/index.md), [`unix-dgram()`](../../docs/axosyslog-core/chapter-sources/source-unixstream/index.md), [`unix-stream()`](../../docs/axosyslog-core/chapter-sources/source-unixstream/index.md), [`wildcard-file()`](../../docs/axosyslog-core/chapter-sources/configuring-sources-wildcard-file/index.md). Instead of using the global option, you can also set the `check-hostname()` option for the specific source.
For the [`python()`](../../docs/axosyslog-core/chapter-sources/python-source/index.md) and [`python-fetcher()`](../../docs/axosyslog-core/chapter-sources/python-fetcher-source/index.md) sources and the [`syslog-parser()`](../../docs/axosyslog-core/chapter-parsers/parser-syslog/index.md) parser you can enable this option as a flag.
## check-program()
|
---|---
Accepted values: | `yes`, `no`
Default: | `no`
Available in version 4.10 and later.
If the `check-program` flag is enabled, AxoSyslog validates the `${PROGRAM}` field for RFC3164-formatted messages. Valid program names meet the following criteria:
* Contain only these characters: `[a-zA-Z0-9-_/().]`
* Include at least one alphabetical character.
If the program name fails validation, it’s considered to be part of the log message.
You can also enable this behavior per source using the `check-program` source flag.
## 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 AxoSyslog.
* 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 AxoSyslog does not change the ownership, unless explicitly configured to do so.
## disk-buffer()
_Description:_ Sets default values for the disk-buffer sub-options listed below. Each destination that uses `disk-buffer()` inherits these defaults unless the destination overrides them. Other `disk-buffer()` sub-options (for example, `capacity-bytes()`, `dir()`, `reliable()`) must be set on the destination itself — see [Using disk-based and memory buffering](../../docs/axosyslog-core/chapter-routing-filters/concepts-diskbuffer/index.md).
```
options {
disk-buffer(
prealloc(no)
truncate-size-ratio(0.1)
stats(freq(60))
);
};
```
### prealloc()
Type: | yes/no
---|---
Default: | no
Available in AxoSyslog 4.0 and later.
_Description:_
By default, AxoSyslog doesn’t reserve the disk space for the disk-buffer file, since in a properly configured and sized environment the disk-buffer is practically empty, so a large preallocated disk-buffer file is just a waste of disk space. But a preallocated buffer can prevent other data from using the intended buffer space (and elicit a warning from the OS if disk space is low), preventing message loss if the buffer is actually needed. To avoid this problem, when using AxoSyslog 4.0 or later, you can preallocate the space for your disk-buffer files by setting `prealloc(yes)`.
In addition to making sure that the required disk space is available when needed, preallocated disk-buffer files provide radically better (3-4x) performance as well: in case of an outage the amount of messages stored in the disk-buffer is continuously growing, and using large continuous files is faster, than constantly waiting on a file to change its size.
If you are running AxoSyslog on a dedicated host (always recommended for any high-volume settings), use `prealloc(yes)`.
### stats(freq())
|
---|---
Accepted values: | number (seconds)
Default: | 0 (disabled)
_Description:_ The frequency (in seconds) at which AxoSyslog emits disk-buffer metrics to the internal statistics. `0` disables periodic reporting. Disk-buffer metrics remain available through [`syslog-ng-ctl stats`](../../docs/axosyslog-core/app-man-syslog-ng/syslog-ng-ctl.1/index.md) regardless of this setting.
### truncate-size-ratio()
Type: | number (between 0 and 1)
---|---
Default: | 1 (do not truncate)
_Description:_ Limits the truncation of disk-buffer files. Truncation can slow down disk I/O operations but saves disk space. AxoSyslog only truncates a disk-buffer file if the possible disk gain is more than `truncate-size-ratio()` times `capacity-bytes()`. For details and trade-offs, see [`truncate-size-ratio()`](../../docs/axosyslog-core/chapter-routing-filters/concepts-diskbuffer/index.md) on the destination-level disk-buffer page.
## 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 AxoSyslog 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 AxoSyslog application flushes the messages if it has sent `flush-lines()` number of messages, or the queue became empty. If you stop or reload AxoSyslog or in case of network sources, the connection with the client is closed, AxoSyslog automatically sends the unsent messages to the destination.
## flush-timeout()
|
---|---
Type: | time in milliseconds
Default: | 10000 [milliseconds]
_Description:_ Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends flushes to the destinations evenly. The timer starts when the first message arrives to the buffer, so if only few messages arrive, AxoSyslog sends messages to the destination at most once every `flush-timeout()` seconds.
You can also set this option per destination.
## frac-digits()
|
---|---
Type: | number
Default: | 0
_Description:_ The AxoSyslog 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 AxoSyslog application can add the fractions to non-ISO8601 timestamps as well.
Note As AxoSyslog is precise up to the microsecond, when the `frac-digits()` option is set to a value higher than 6, AxoSyslog 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 AxoSyslog 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)`), AxoSyslog assumes that the incoming log message was sent by the host specified in the `HOST` field of the message.
* If disabled (`keep-hostname(no)`), AxoSyslog 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 AxoSyslog. For details on using name resolution in AxoSyslog, see [Using name resolution in syslog-ng](../../docs/axosyslog-core/chapter-examples/examples-dns/index.md).
Note
If the log message does not contain a hostname in its `HOST` field, AxoSyslog 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, AxoSyslog 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 AxoSyslog server and also on every relay, otherwise AxoSyslog will treat incoming messages as if they were sent by the last relay.
## keep-timestamp()
|
---|---
Type: | yes or no
Default: | yes
_Description:_ Specifies whether AxoSyslog 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.
Warning To use the `S_` macros, the `keep-timestamp()` option must be enabled (this is the default behavior of AxoSyslog).
## 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 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.
You can also set this option per destination.
## log-fetch-limit()
|
---|---
Type: | number
Default: | 100
_Description:_ The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if `log-fetch-limit()` is too high.
## log-fifo-size()
|
---|---
Accepted values: | number (messages)
Default: | 10000
_Description:_ The number of messages that the output queue can store.
## log-flow-control()
|
---|---
Accepted values: | `yes`, `no`
Default: | `no`
Available in AxoSyslog 4.12 and later.
_Description:_ Enables flow control for all log paths. When set to yes, flow control is globally enabled, but you can selectively disable it for individual log paths using the [`no-flow-control`](../../docs/axosyslog-core/chapter-routing-filters/logpath/reference-logflags/index.md#no-flow-control) flag. For example:
```
options {
log-flow-control(yes);
};
log {
source { system(); };
destination { network("server" port(5555)); };
flags(no-flow-control);
};
log { ... };
```
**CAUTION:**
Enabling global flow control can cause the `system()` source to block. As a result, if messages accumulate at the destination, applications that log through the system may become completely stalled, potentially halting their operation. We don’t recommend enabling flow control in log paths that include the `system()` source.
## log-iw-size()
|
---|---
Type: | number
Default: | 100
_Description:_ Specifies the source window size - the maximum number of in-flight messages permitted by the source before flow control is enforced. This only applies when `flow-control` is enabled.
Warning
```
If you change the value of log-iw-size() and keep-alive() is enabled, the change will affect only new connections, the log-iw-size() of kept-alive connections will not change. To apply the new log-iw-size() value to every connection, restart the syslog-ng service. A simple configuration reload is NOT sufficient.
```
If the source is receiving data using the UDP protocol, always [restart the `syslog-ng` service](../../docs/axosyslog-core/quickstart/managing-and-checking-linux/index.md#restart-axosyslog) after changing the value of `log-iw-size()` for the changes to take effect.
Note that when using `disk-buffer()`, the messages stored on disk are not included in the window size calculation. For details about the effects of this parameter, see [Managing incoming and outgoing messages with flow-control](../../docs/axosyslog-core/chapter-routing-filters/concepts-flow-control/index.md).
You can also set this option per source.
## log-level()
|
---|---
Accepted values: | `default`, `verbose`, `debug`, `trace`
Default: | `default`
_Description:_ Controls AxoSyslog’s own internal log level. Corresponds to setting the internal log level using `syslog-ng-ctl` or the command line options of `syslog-ng` (the `-d`, `-v`, and `-t` ). Setting the log level in the configuration makes it easier to control logging in containerized environments where changing command line options is more problematic.
Available in AxoSyslog 4.0 and later.
Higher log-levels automatically include messages from lower log-levels:
* `default`: Just normal log messages.
* `verbose`: Normal and verbose log messages.
* `debug`: Include debug messages of AxoSyslog.
* `trace`: Include trace messages of how messages are processed.
```
options {
log-level(debug);
};
```
## 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](../../docs/axosyslog-core/chapter-concepts/concepts-message-representation/index.md).
You can use human-readable units when setting configuration options. For details, see[Notes about the configuration syntax](../../docs/axosyslog-core/chapter-configuration-file/configuration-syntax-notes/index.md).
## long-hostnames()
Obsolete alias for [`chain-hostnames()`](../../docs/axosyslog-core/chapter-global-options/reference-options/index.md#global-options-chain-hostnames).
## 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 AxoSyslog version 1.6.x.
## mark-freq()
|
---|---
Accepted values: | number [seconds]
Default: | 1200
_Description:_ An alias for the obsolete `mark()` option, retained for compatibility with 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 AxoSyslog 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 AxoSyslog.
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 AxoSyslog 3.4 and later.
## min-iw-size-per-reader()
|
---|---
Accepted values: | number
Default: | 100
_Description:_ Sets the minimum initial window size allocated to each reader when multiple readers (for example, in a `wildcard-file()` source) share the same `log-iw-size()` budget. The effective per-reader window is `max(log-iw-size() / number-of-readers, min-iw-size-per-reader())`. For details on flow control, see [Managing incoming and outgoing messages with flow-control](../../docs/axosyslog-core/chapter-routing-filters/concepts-flow-control/index.md).
## normalize-hostnames()
|
---|---
Accepted values: | `yes`, `no`
Default: | `no`
_Description:_ If enabled (`normalize-hostnames(yes)`), AxoSyslog 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 AxoSyslog cannot convert some data to the specified type. By default, AxoSyslog 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 AxoSyslog.
* `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 AxoSyslog does not change the ownership, unless explicitly configured to do so.
## pass-unix-credentials()
|
---|---
Accepted values: | `yes
Default: | yes
_Description:_ Enable AxoSyslog 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 AxoSyslog 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 AxoSyslog 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](../../docs/axosyslog-core/chapter-concepts/timezone-handling/index.md) and [A note on timezones and timestamps](../../docs/axosyslog-core/chapter-concepts/timezone-handling/example-timezones/index.md).
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](../../docs/axosyslog-core/chapter-concepts/timezone-handling/index.md).
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()
Available in AxoSyslog 4.1 and later.
_Description:_ The `stats()` option is a collection of statistics-related options.
```
options {
stats(
freq(1)
level(1)
lifetime(1000)
max-dynamics(10000)
syslog-stats(yes)
);
};
```
### freq()
|
---|---
Accepted values: | number
Default: | 0 (seconds)
_Description:_ The period between two STATS messages in seconds. STATS are log messages sent by `syslog-ng`, containing statistics about dropped log messages. `0` disables the STATS messages.
Note
Starting with AxoSyslog version 4.12, the default value of this option is `0`, disabling STATS messages. We recommend accessing metrics using the [`syslog-ng-ctl stats`](../../docs/axosyslog-core/app-man-syslog-ng/syslog-ng-ctl.1/index.md#syslog-ng-ctl-stats) interface for monitoring and observability, for example, by using `syslog-ng-ctl stats prometheus`.
In earlier versions, the default was `600` (ten minutes).
### healthcheck-freq()
|
---|---
Accepted values: | number (seconds)
Default: | 300 (5 minutes)
_Description:_ Controls how frequently AxoSyslog publishes health-check results as metrics. Health checks verify that the internal processing pipeline responds in a timely manner. For the list of emitted metrics and how to inspect them, see [`syslog-ng-ctl`](../../docs/axosyslog-core/app-man-syslog-ng/syslog-ng-ctl.1/index.md).
### level()
|
---|---
Accepted values: | `0`, `1`, `2`, `3`
Default: | `0`
_Description:_ Specifies the detail of metrics and statistics AxoSyslog 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, see [Statistics and metrics of AxoSyslog](../../docs/axosyslog-core/chapter-log-statistics/index.md).
### lifetime()
|
---|---
Accepted values: | number (seconds)
Default: | `N/A`
_Description:_ Dynamic counters in metrics are pruned after `lifetime` expires. Note that orphaned counters are not pruned (you can prune them by running `syslog-ng-ctl stats --remove-orphans`).
### max-dynamics()
|
---|---
Accepted values: | number
Default: | `N/A`
Available in AxoSyslog 4.1 and later.
_Description:_ To avoid performance issues or even overloading AxoSyslog (for example, if a script starts to send logs from different IP addresses to AxoSyslog), you might want to limit the number of registered dynamic counters in the message statistics. For details on message statistics, see [Statistics and metrics of AxoSyslog](../../docs/axosyslog-core/chapter-log-statistics/index.md).
* 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.
Warning 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 `` 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 don’t use statistics, or if you aren’t 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 hasn’t been configured before) and restart AxoSyslog, 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.
### syslog-stats()
|
---|---
Accepted values: | `yes`, `no`, `auto`
Default: | `auto`
Available in AxoSyslog 4.1 and later.
_Description:_ Changes the behavior of counting messages based on different syslog fields, like `SEVERITY`, `FACILITY`, `HOST`.
Possible values:
* `yes`: Enable syslog stats.
* `no`: Disable syslog stats.
* `auto`: Use the setting of the old [`stats(level())` option](../../docs/axosyslog-core/chapter-global-options/reference-options/index.md#global-option-stats-level).
## stats-freq()
Deprecated legacy option. Use [`stats(freq())`](../../docs/axosyslog-core/chapter-global-options/reference-options/index.md#global-option-stats-freq) instead.
## stats-level()
Deprecated legacy option. Use [`stats(level())`](../../docs/axosyslog-core/chapter-global-options/reference-options/index.md#global-option-stats-level) instead.
## stats-lifetime()
Deprecated legacy option. Use [`stats(lifetime())`](../../docs/axosyslog-core/chapter-global-options/reference-options/index.md#global-option-stats-lifetime) instead.
## stats-max-dynamics()
Deprecated legacy option. Use [`stats(max-dynamics())`](../../docs/axosyslog-core/chapter-global-options/reference-options/index.md#global-option-stats-max-dynamics) instead.
## 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), AxoSyslog 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 AxoSyslog waits for identical messages.
You can also set this option per destination.
## sync() or sync-freq() (DEPRECATED)
|
---|---
Accepted values: | number (messages)
Default: | 0
_Description:_ Obsolete aliases for `flush-lines()`
## 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.
> Note: Starting with AxoSyslog version 4.5, `template-escape(yes)` escapes the top-level template function in case of nested template functions.
You can also set this option per destination.
## threaded()
|
---|---
Accepted values: | `yes
Default: | yes
_Description:_ Enable AxoSyslog to run in multithreaded mode and use multiple CPUs. Available only in AxoSyslog 3.3 and later. Note that setting `threaded(no)` does not mean that AxoSyslog will use only a single thread. For details, see [Multithreading and scaling](../../docs/axosyslog-core/chapter-multithreading/index.md).
## 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](../../docs/axosyslog-core/chapter-manipulating-messages/customizing-message-format/date-macros/index.md).
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
Default: | no
_Description:_ Determines what AxoSyslog 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`, AxoSyslog drops the incoming log message.
* If set to `yes`, AxoSyslog 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 AxoSyslog 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 AxoSyslog version 3.21 and later.
## ts-format()
|
---|---
Accepted values: | `rfc3164`
Default: | `rfc3164`
_Description:_ Specifies the timestamp format used when AxoSyslog 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](../../docs/axosyslog-core/chapter-concepts/timezone-handling/example-timezones/index.md).
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](../../docs/axosyslog-core/chapter-global-options/reference-options/index.md) 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 AxoSyslog application blocks on DNS queries, so enabling DNS may lead to a Denial of Service attack. To prevent DoS, protect your AxoSyslog network endpoint with firewall rules, and make sure that all hosts which may get to AxoSyslog 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.
Note 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` or `no`
Default: | `no`
_Description:_ When the `use-rcptid` global option is set to `yes`, AxoSyslog 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 64-bit integer number, that can never be zero (if the counter overflows, it restarts with 1).
This option is deprecated, use the `use-uniqid()` option instead.
## use-uniqid()
|
---|---
Accepted values: | `yes`, `no`
Default: | `no`
_Description:_ This option enables generating a globally unique ID. It is generated from the HOSTID and the RCPTID in the format of HOSTID@RCPTID. It has a fixed length: 16+@+8 characters. You can include the unique ID in the message by using the macro. For details, see [UNIQID](../../docs/axosyslog-core/chapter-manipulating-messages/customizing-message-format/reference-macros/index.md).
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 AxoSyslog 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](../../docs/axosyslog-core/chapter-manipulating-messages/customizing-message-format/reference-macros/index.md)
Last modified April 24, 2026: [Adds missing global options (cdeaad4)]()