A destination is where a log message is sent if the filtering rules match. Similarly to sources, destinations consist of one or more drivers, each defining where and how messages are sent.
Note
If no drivers are defined for a destination, all messages sent to the destination are discarded. This is equivalent to omitting the destination from the log statement.
To define a destination, add a destination statement to the syslog-ng.conf configuration file using the following syntax:
Do not define the same drivers with the same parameters more than once, because it will cause problems. For example, do not open the same file in multiple destinations.
Do not use the same destination in different log paths, because it can cause problems with most destination types. Instead, use filters and log paths to avoid such situations.
Sources and destinations are initialized only when they are used in a log statement. For example, AxoSyslog starts listening on a port or starts polling a file only if the source is used in a log statement. For details on creating log statements, see log: Filter and route log messages using log paths, flags, and filters.
The following table lists the destination drivers available in AxoSyslog. If these destinations do not satisfy your needs, you can extend AxoSyslog and write your own destination, for example, in C, Java, or Python. For details, see Write your own custom destination in Java or Python.
The following destination driver groups are available in AxoSyslog:
1 - amqp: Publish messages using AMQP
The amqp() driver publishes messages using the AMQP (Advanced Message Queuing Protocol). AxoSyslog supports AMQP versions 0.9.1 and 1.0. The AxoSyslog amqp() driver supports persistence, and every available exchange types.
The name-value pairs selected with the value-pairs() option will be sent as AMQP headers, while the body of the AMQP message is empty by default (but you can add custom content using the body() option). Publishing the name-value pairs as headers makes it possible to use the Headers exchange-type and subscribe only to interesting log streams. This solution is more flexible than using the routing-key() option.
The amqp() driver publishes messages using the AMQP (Advanced Message Queuing Protocol).
The amqp() destination has the following options:
auth-method()
Accepted values:
plain
Default:
plain
Description: The amqp() driver supports the following types of authentication:
plain: Authentication happens using username and password. This is the default.
external: Authentication happens using an out-of-band mechanism, for example, x509 certificate peer verification, client IP address range, or similar. For more information, see the RabbitMQ documentation.
batch-bytes()
Accepted values:
number [bytes]
Default:
none
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Available in AxoSyslog version 3.19 and later.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
body()
Type:
string
Default:
empty string
Description: The body of the AMQP message. You can also use macros and templates.
ca-file()
Type:
string
Default:
N/A
Description: Name of a file, that contains the trusted CA certificate in PEM format. For example: ca-file("/home/certs/syslog-ng/tls/cacert.pem"). The AxoSyslog application uses this CA certificate to validate the certificate of the peer.
An alternative way to specify this option is to put into a tls() block and specify it there, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-file(), cert-file(), key-file(), and peer-verify()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
cert-file()
Accepted values:
Filename
Default:
none
Description: Name of a file, that contains an X.509 certificate (or a certificate chain) in PEM format, suitable as a TLS certificate, matching the private key set in the key-file() option. The AxoSyslog application uses this certificate to authenticate the AxoSyslog client on the destination server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.
An alternative way to specify this option is to put into a tls() block and specify it there, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-file(), cert-file(), key-file(), and peer-verify()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: The name of the AMQP exchange where AxoSyslog sends the message. Exchanges take a message and route it into zero or more queues.
exchange-declare()
Type:
yes
Default:
no
Description: By default, AxoSyslog does not create non-existing exchanges. Use the exchange-declare(yes) option to automatically create exchanges.
exchange-type()
Type:
direct
Default:
fanout
Description: The type of the AMQP exchange.
frame-size()
Type:
integer
Default:
Description: Sets maximal frame size (the frame-max option described in the AMQP Reference Guide.
heartbeat()
Type:
number [seconds]
Default:
0 (disabled)
Description: If enabled, the AxoSyslog amqp destination sends heartbeat messages to the server periodically. During negotiation, both the amqp server and the client provide a heartbeat parameter, and the smaller is chosen for heartbeat interval. For example:
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The hostname or IP address of the AMQP server.
key-file()
Accepted values:
Filename
Default:
none
Description: The name of a file that contains an unencrypted private key in PEM format, suitable as a TLS key. If properly configured, the AxoSyslog application uses this private key and the matching certificate (set in the cert-file() option) to authenticate the AxoSyslog client on the destination server.
max-channel()
Type:
integer
Default:
Description: Sets maximal number of channels (the channel-max option described in the AMQP Reference Guide.
An alternative way to specify this option is to put into a tls() block and specify it there, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-file(), cert-file(), key-file(), and peer-verify()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
password()
Type:
string
Default:
n/a
Description: The password used to authenticate on the AMQP server.
peer-verify()
Accepted values:
`yes
Default:
yes
Description: Verification method of the peer. The following table summarizes the possible options and their results depending on the certificate of the peer.
The remote peer has:
no certificate
invalid certificate
valid certificate
Local peer-verify() setting
no (optional-untrusted)
TLS-encryption
TLS-encryption
TLS-encryption
yes (required-trusted)
rejected connection
rejected connection
TLS-encryption
For untrusted certificates only the existence of the certificate is checked, but it does not have to be valid — AxoSyslog accepts the certificate even if it is expired, signed by an unknown CA, or its CN and the name of the machine mismatches.
Warning
When validating a certificate, the entire certificate chain must be valid, including the CA certificate. If any certificate of the chain is invalid, AxoSyslog will reject the connection.
An alternative way to specify this option is to put into a tls() block and specify it there, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-file(), cert-file(), key-file(), and peer-verify()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
persistent()
Type:
yes
Default:
yes
Description: If this option is enabled, the AMQP server or broker will store the messages on its hard disk. That way, the messages will be retained if the AMQP server is restarted, if the message queue is set to be durable on the AMQP server.
port()
Type:
number
Default:
5672
Description: The port number of the AMQP server.
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
routing-key()
Type:
string
Default:
empty string
Description: Specifies a routing key for the exchange. The routing key selects certain messages published to an exchange to be routed to the bound queue. In other words, the routing key acts like a filter. The routing key can include macros and templates.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
username()
Type:
string
Default:
empty string
Description: The username used to authenticate on the AMQP server.
value-pairs()
Type:
parameter list of the value-pairs() option
Default:
scope("selected-macros" "nv-pairs")
Description: The value-pairs() option creates structured name-value pairs from the data and metadata of the log message. For details on using value-pairs(), see Structuring macros, metadata, and other value-pairs.
Note
Empty keys are not logged.
vhost()
Type:
string
Default:
/
Description: The name of the AMQP virtual host to send the messages to.
For authentication, the destination uses GoogleDefaultCredentials, which covers everything listed as ADC. In a production environment, use a service account and Workload Identity.
By default, the messages are sent with one worker, one message per batch, and without compression.
Options
The bigquery() destination has the following options.
batch-bytes()
Accepted values:
number [bytes]
Default:
none
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Available in AxoSyslog version 3.19 and later.
By default, the batch-bytes() option of the bigquery() destination is 10 MB. This is an upper limit for the bigquery() destination. Note that due to a framework limitation, the batch might be at most 1 message larger than the set limit.
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
channel-args()
Type:
See description
Default:
-
Description: The channel-args() option is available in gRPC-based drivers. It accepts name-value pairs and sets channel arguments defined in the GRPC Core library documentation. For example:
Description: Enables compression in gRPC requests. Although gRPC supports various compression methods, currently only deflate is supported (which is basically the same as gzip).
dataset()
Type:
string
Default:
-
Description: The name of the dataset where AxoSyslog sends the data.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Flags influence the behavior of the destination driver.
no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.
syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.
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.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The maximum number of gRPC pings that can be sent when there is no data/header frame to be sent. AxoSyslog won’t send any pings after this limit. Set it to 0 disable this restriction and keep sending pings.
time()
Type:
number [milliseconds]
Default:
Description: The period (in milliseconds) after which AxoSyslog sends a gRPC keepalive ping.
timeout()
Type:
number [milliseconds]
Default:
10
Description: The time (in milliseconds) AxoSyslog waits for an acknowledgement.
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.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
on-error()
Type:
One of: drop-message, drop-property, fallback-to-string, silently-drop-message, silently-drop-property, silently-fallback-to-string
Default:
Use the global setting (which defaults to drop-message)
Description: Controls what happens when type-casting fails and 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.
persist-name()
Type:
string
Default:
N/A
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
project()
Type:
string
Default:
-
Description: The ID of the Google Cloud project where AxoSyslog sends the data.
protobuf-schema()
Type:
See the description
Default:
-
Description: Sets the schema of the BigQuery table from a protobuf schema file.
Alternatively, you can set the schema with the schema() option.
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
schema()
Type:
See the description
Default:
-
Description: Sets the schema of the BigQuery table. On the left side of the arrow, set the name of the column and its type. On the right side, set any AxoSyslog template or macro, which gets evaluated on each log that is routed to the bigquery() destination. The available column types are: STRING, BYTES, INTEGER, FLOAT, BOOLEAN, TIMESTAMP, DATE, TIME, DATETIME, JSON, NUMERIC, BIGNUMERIC, GEOGRAPHY, RECORD, INTERVAL. For example:
Alternatively, you can set the schema with the protobuf-schema() option.
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.
table()
Type:
string
Default:
-
Description: The name of the Google BigQuery table where AxoSyslog sends the data.
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.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
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.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
url()
Type:
string
Default:
bigquerystorage.googleapis.com
Description: The URL of the Google BigQuery where the logs are sent.
worker-partition-key()
Type:
template
Default:
Description: The worker-partition-key() option specifies a template: messages that expand the template to the same value are mapped to the same partition. When batching is enabled and multiple workers are configured, it’s important to add only those messages to a batch which generate identical URLs. To achieve this, set the worker-partition-key() option with a template that contains all the templates used in the url() option, otherwise messages will be mixed.
For example, you can partition messages based on the destination host:
worker-partition-key("$HOST")
workers()
Type:
integer
Default:
1
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
The following example uses the name of the application sending the log message as the plugin name, and the value of the ${SEQNUM} macro as the value of the metric sent to collectd.
To use the collectd() driver, the scl.conf file must be included in your AxoSyslog configuration:
@include "scl.conf"
The collectd() driver is actually a reusable configuration snippet configured to send log messages using the unix-stream() driver. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of this configuration snippet on GitHub.
3.1 - collectd() destination options
The collectd() destination has the following options. The plugin() and type() options are required options. You can also set other options of the underlying unix-stream() driver (for example, socket buffer size).
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Use global setting (exception: for http() destination, the default is 1).
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.
For optimal performance when sending messages to an AxoSyslog server, make sure that the value of flush-lines() is smaller than the window size set in the log-iw-size() option in the source of your server.
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.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The hostname that is passed to collectd. By default, AxoSyslog uses the host from the log message as the hostname.
type("gauge"),
interval()
Type:
integer
Default:
60
Description: The interval in which the data is collected.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
keep-alive()
Type:
yes or no
Default:
yes
Description: Specifies whether connections to destinations should be closed when syslog-ng is reloaded. Note that this applies to the client (destination) side of the connections, server-side (source) connections are always reopened after receiving a HUP signal unless the keep-alive option is enabled for the source.
plugin()
Type:
string
Default:
Description: The name of the plugin that submits the data to collectd. For example:
plugin("${PROGRAM}"),
plugin-instance()
Type:
string
Default:
Description: The name of the plugin-instance that submits the data to collectd.
Description: This option controls the SO_BROADCAST socket option required to make AxoSyslog send messages to a broadcast address. For details, see the socket(7) manual page.
so-keepalive()
Type:
yes or no
Default:
no
Description: Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. For details, see the socket(7) manual page.
so-rcvbuf()
Type:
number
Default:
0
Description: Specifies the size of the socket receive buffer in bytes. For details, see the socket(7) manual page.
so-sndbuf()
Type:
number
Default:
0
Description: Specifies the size of the socket send buffer in bytes. For details, see the socket(7) manual page.
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.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
type()
Type:
string or template
Default:
Description: Identifies the type and number of values passed to collectd. For details, see the types.db manual page. For example:
type("gauge"),
type-instance()
Type:
string
Default:
Description: For example:
type-instance("seqnum"),
values()
Type:
string, macro,or template
Default:
U
Description: Colon-separated list of the values to send to collectd. For example:
values("${SEQNUM}"),
4 - discord: Send alerts and notifications to Discord
The discord() destination driver sends messages to Discord using Discord Webhook. For the list of available optional parameters, see Discord destination options.
By default the message sending is throttled to 5 message/sec, see Discord: Rate Limits. To change this, use the throttle() option.
To use this destination, the scl.conf file must be included in your AxoSyslog configuration:
@include "scl.conf"
The discord() driver is actually a reusable configuration snippet configured to send log messages using the http() driver. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of this configuration snippet on GitHub.
The discord() destination of AxoSyslog can directly post log messages to web services using the HTTP protocol. The discord() destination has the following options.
avatar-url()
Type:
URL
Default:
N/A
Description: A hyperlink for icon of the author to be displayed in Discord. For details, see the avatar_url option in the Discord documentation.
batch-bytes()
Accepted values:
number [bytes]
Default:
none
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Name of a file, that contains an X.509 certificate (or a certificate chain) in PEM format, suitable as a TLS certificate, matching the private key set in the key-file() option. The AxoSyslog application uses this certificate to authenticate the AxoSyslog client on the destination server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Depends on the OpenSSL version that AxoSyslog uses
Description: Specifies the cipher, hash, and key-exchange algorithms used for the encryption, for example, ECDHE-ECDSA-AES256-SHA384. The list of available algorithms depends on the version of OpenSSL used to compile AxoSyslog. To specify multiple ciphers, separate the cipher names with a colon, and enclose the list between double-quotes, for example:
For a list of available algorithms, execute the openssl ciphers -v command. The first column of the output contains the name of the algorithms to use in the cipher-suite() option, the second column specifies which encryption protocol uses the algorithm (for example, TLSv1.2). That way, the cipher-suite() also determines the encryption protocol used in the connection: to disable SSLv3, use an algorithm that is available only in TLSv1.2, and that both the client and the server supports. You can also specify the encryption protocols using ssl-options().
You can also use the following command to automatically list only ciphers permitted in a specific encryption protocol, for example, TLSv1.2:
echo"cipher-suite(\"$(openssl ciphers -v | grep TLSv1.2 | awk '{print $1}'| xargs echo -n | sed 's/ /:/g'| sed -e 's/:$//')\")"
Note that starting with version 3.10, when AxoSyslog receives TLS-encrypted connections, the order of ciphers set on the AxoSyslog server takes precedence over the client settings.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The number of messages that the output queue can store.
key-file()
Accepted values:
Filename
Default:
none
Description: The name of a file that contains an unencrypted private key in PEM format, suitable as a TLS key. If properly configured, the AxoSyslog application uses this private key and the matching certificate (set in the cert-file() option) to authenticate the AxoSyslog client on the destination server.
The http() destination supports only unencrypted key files (that is, the private key cannot be password-protected).
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Removes every character above the set limit. For details, see the content option in the Discord documentation.
peer-verify()
Accepted values:
`yes
Default:
yes
Description: Verification method of the peer. The following table summarizes the possible options and their results depending on the certificate of the peer.
The remote peer has:
no certificate
invalid certificate
valid certificate
Local peer-verify() setting
no (optional-untrusted)
TLS-encryption
TLS-encryption
TLS-encryption
yes (required-trusted)
rejected connection
rejected connection
TLS-encryption
For untrusted certificates only the existence of the certificate is checked, but it does not have to be valid — AxoSyslog accepts the certificate even if it is expired, signed by an unknown CA, or its CN and the name of the machine mismatches.
Warning
When validating a certificate, the entire certificate chain must be valid, including the CA certificate. If any certificate of the chain is invalid, AxoSyslog will reject the connection.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
persist-name()
Type:
string
Default:
N/A
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
proxy()
Type:
The proxy server address, in `proxy("PROXY_IP:PORT")` format.
For example, `proxy("http://myproxy:3128")`
Default:
None
Description:
You can use the proxy() option to configure the HTTP driver in all HTTP-based destinations to use a specific HTTP proxy that is independent from the proxy configured for the system.
Alternatively, you can leave the HTTP as-is, in which case the driver leaves the default http_proxy and https_proxy environment variables unmodified.
Note
Configuring the <code>proxy()</code> option overwrites the default <code>http_proxy</code> and <code>https_proxy</code> environment variables.
Example: the proxy() option in configuration
The following example illustrates including the proxy() option in your configuration.
Description: Specifies what AxoSyslog does with the log message, based on the response code received from the HTTP server. If the server returns a status code beginning with 2 (for example, 200), AxoSyslog assumes the message was successfully sent. Otherwise, the action listed in the following table is applied. For status codes not listed in the following table, if the status code begins with 2 (for example, 299), AxoSyslog assumes the message was successfully sent. For other status codes, AxoSyslog disconnects. The following actions are possible:
disconnect: Keep trying to resend the message indefinitely.
drop: Drop the message without trying to resend it.
retry: Retry sending the message for a maximum of retries() times (3 by default).
success: Assume the message was successfully sent.
|------+-----------------------------------+------------|| code | explanation | action ||------+-----------------------------------+------------||100|"Continue"| disconnect ||101|"Switching Protocols"| disconnect ||102|"Processing"| retry ||103|"Early Hints"| retry ||200|"OK"| success ||201|"Created"| success ||202|"Accepted"| success ||203|"Non-Authoritative Information"| success ||204|"No Content"| success ||205|"Reset Content"| success ||206|"Partial Content"| success ||300|"Multiple Choices"| disconnect ||301|"Moved Permanently"| disconnect ||302|"Found"| disconnect ||303|"See Other"| disconnect ||304|"Not Modified"| retry ||307|"Temporary Redirect"| disconnect ||308|"Permanent Redirect"| disconnect ||400|"Bad Request"| disconnect ||401|"Unauthorized"| disconnect ||402|"Payment Required"| disconnect ||403|"Forbidden"| disconnect ||404|"Not Found"| disconnect ||405|"Method Not Allowed"| disconnect ||406|"Not Acceptable"| disconnect ||407|"Proxy Authentication Required"| disconnect ||408|"Request Timeout"| disconnect ||409|"Conflict"| disconnect ||410|"Gone"| drop ||411|"Length Required"| disconnect ||412|"Precondition Failed"| disconnect ||413|"Payload Too Large"| disconnect ||414|"URI Too Long"| disconnect ||415|"Unsupported Media Type"| disconnect ||416|"Range Not Satisfiable"| drop ||417|"Expectation Failed"| disconnect ||418|"I'm a teapot"| disconnect ||421|"Misdirected Request"| disconnect ||422|"Unprocessable Entity"| drop ||423|"Locked"| disconnect ||424|"Failed Dependency"| drop ||425|"Too Early"| drop ||426|"Upgrade Required"| disconnect ||428|"Precondition Required"| retry ||429|"Too Many Requests"| disconnect ||431|"Request Header Fields Too Large"| disconnect ||451|"Unavailable For Legal Reasons"| drop ||500|"Internal Server Error"| disconnect ||501|"Not Implemented"| disconnect ||502|"Bad Gateway"| disconnect ||503|"Service Unavailable"| disconnect ||504|"Gateway Timeout"| retry ||505|"HTTP Version Not Supported"| disconnect ||506|"Variant Also Negotiates"| disconnect ||507|"Insufficient Storage"| disconnect ||508|"Loop Detected"| drop ||510|"Not Extended"| disconnect ||511|"Network Authentication Required"| disconnect ||------+-----------------------------------+------------|
To customize the action to take for a particular response code, use the following format: response-action(<response-code> => <action>. To customize multiple response code-action pairs, separate them with a comma, for example:
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
To handle HTTP error responses, if the HTTP server returns 5xx codes, AxoSyslog will attempt to resend messages until the number of attempts reaches retries. If the HTTP server returns 4xx codes, AxoSyslog will drop the messages.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
Warning
Hazard of data loss! Make sure to include a fallback value, as if the template gets resolved to an empty string, Discord rejects the message.
throttle()
Type:
number
Default:
5
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
Description: The value (in seconds) to wait for an operation to complete, and attempt to reconnect the server if exceeded. By default, the timeout value is 0, meaning that there is no timeout. Available in version 3.11 and later.
tts()
Type:
`true
Default:
false
Description: Enables TTS (Text-To-Speech) mode. For more information, see the tts option in the Discord documentation.
url()
Type:
URL
Default:
N/A
Description: The webhook URL of the Discord server/channel. For more information, see Discord: Intro to Webhooks.
user-agent()
Type:
string
Default:
syslog-ng [version]'/libcurl[version]`
Description: The value of the USER-AGENT header in the messages sent to the server.
username()
Type:
string
Default:
N/A
Description: Overrides the default username of the webhook. For details, see the username option in the Discord documentation.
use-system-cert-store()
Type:
`yes
Default:
no
Description: Use the certificate store of the system for verifying HTTPS certificates. For details, see the curl documentation.
workers()
Type:
integer
Default:
1
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
If you are using load-balancing (that is, you have configured multiple servers in the url() option), increase the number of worker threads at least to the number of servers. For example, if you have set three URLs (url("site1", "site2", "site3")), set the workers() option to 3 or more.
5 - elasticsearch2: DEPRECATED - Send messages directly to Elasticsearch version 2.0 or higher
Starting with version 3.7 of AxoSyslog can directly send log messages to Elasticsearch, allowing you to search and analyze your data in real time, and visualize it with Kibana.
Note the following limitations when using the AxoSyslog elasticsearch2 destination:
Since AxoSyslog uses Java libraries, the elasticsearch2 destination has significant memory usage.
Example: Sending log data to Elasticsearch version 2.x and above
The following example defines an elasticsearch2 destination that sends messages in transport mode to an Elasticsearch server running on the localhost, using only the required parameters.
Verify the certificate of the Elasticsearch server and perform certificate authentication (this is actually a mutual, certificate-based authentication between the AxoSyslog client and the Elasticsearch server):
The elasticsearch2() driver is actually a reusable configuration snippet configured to receive log messages using the Java language-binding of AxoSyslog. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of the elasticsearch configuration snippet on GitHub. For details on extending AxoSyslog in Java, see the Getting started with syslog-ng development guide.
Note
If you delete all Java destinations from your configuration and reload syslog-ng, the JVM is not used anymore, but it is still running. If you want to stop JVM, stop syslog-ng and then start syslog-ng again.
5.1 - Prerequisites
To send messages from AxoSyslog to Elasticsearch, complete the following steps.
Steps:
Download and install the Java Runtime Environment (JRE), 2.x (or newer). The AxoSyslogelasticsearch2 destination is tested and supported when using the Oracle implementation of Java. Other implementations are untested and unsupported, they may or may not work as expected.
Note
This step is only required if you use the elasticsearch2 destination in node mode or transport mode.
This step is only required if you use the elasticsearch2 destination in node mode or transport mode.
Extract the Elasticsearch libraries into a temporary directory, then collect the various .jar files into a single directory (for example, /opt/elasticsearch/lib/) where AxoSyslog can access them. You must specify this directory in the AxoSyslog configuration file. The files are located in the lib directory and its subdirectories of the Elasticsearch release package.
5.2 - How AxoSyslog interacts with Elasticsearch
The AxoSyslog application sends the log messages to the official Elasticsearch client library, which forwards the data to the Elasticsearch nodes. The way AxoSyslog interacts with Elasticsearch is described in the following steps.
After AxoSyslog is started and the first message arrives to the elasticsearch2 destination, the elasticsearch2 destination tries to connect to the Elasticsearch server or cluster. If the connection fails, AxoSyslog will repeatedly attempt to connect again after the period set in time-reopen() expires.
If the connection is established, AxoSyslog sends JSON-formatted messages to Elasticsearch.
If flush-limit is set to 1: AxoSyslog sends the message reliably: it sends a message to Elasticsearch, then waits for a reply from Elasticsearch. In case of failure, AxoSyslog repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, AxoSyslog drops the message.
This method ensures reliable message transfer, but is slow (about 1000 messages/second).
If flush-limit is higher than 1: AxoSyslog sends messages in a batch, and receives the response asynchronously. In case of a problem, AxoSyslog cannot resend the messages.
This method is relatively fast (depending on the size of flush-limit, about 8000 messages/second), but the transfer is not reliable. In transport mode, over 5000-30000 messages can be lost before AxoSyslog recognizes the error. In node mode, about 1000 messages can be lost.
If concurrent-requests is higher than 1, AxoSyslog can send multiple batches simultaneously, increasing performance (and also the number of messages that can be lost in case of an error).
Version 3.10 and newer of AxoSyslog automatically converts the timestamp (date) of the message to UTC, as needed by Elasticsearch and Kibana.
5.3 - Client modes
The AxoSyslog application can interact with Elasticsearch in the following modes of operation: http, https, node, searchguard, and transport.
HTTP mode
The AxoSyslog application sends messages over HTTP using the REST API of Elasticsearch, and uses the cluster-url() and cluster() options from the AxoSyslog configuration file. In HTTP mode, AxoSyslogelasticsearch2 driver can send log messages to every Elasticsearch version, including 1.x-6.x. Note that HTTP mode is available in AxoSyslog version 3.8 and newer.
In version 3.10 and newer, you can list multiple servers in HTTP and HTTPS mode in the cluster-url() and server() options. The AxoSyslog application will use these destination servers in load-balancing fashion. Note that load-balancing is handled by an external library (Jest), AxoSyslog does not have any direct influence on it.
HTTPS mode
The AxoSyslog application sends messages over an encrypted and optionally authenticated HTTPS channel using the REST API of Elasticsearch, and uses the cluster-url() and cluster() options from the AxoSyslog configuration file. In HTTPS mode, AxoSyslogelasticsearch2 driver can send log messages to every Elasticsearch version, including 1.x-6.x. Note that HTTPS mode is available in AxoSyslog version 3.10 and newer.
This mode supports password-based and certificate-based authentication of the client, and can verify the certificate of the server as well.
In version 3.10 and newer, you can list multiple servers in HTTP and HTTPS mode in the cluster-url() and server() options. The AxoSyslog application will use these destination servers in load-balancing fashion. Note that load-balancing is handled by an external library (Jest), AxoSyslog does not have any direct influence on it.
Transport mode
The AxoSyslog application uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the AxoSyslog configuration file.
Node mode
The AxoSyslog application acts as an Elasticsearch node (client no-data), using the node client API of Elasticsearch. Further options for the node can be describe in an Elasticsearch configuration file specified in the resource() option.
Note
In Node mode, it is required to define the home of the elasticsearch installation with the <code>path.home</code> parameter in the <code>.yml</code> file. For example: <code>path.home: /usr/share/elasticsearch</code>.
Search Guard mode
Use the Search Guard Elasticsearch plugin to encrypt and authenticate your connections from AxoSyslog to Elasticsearch 2.x. For Elasticsearch versions 5.x and newer, use HTTPS mode. For details on configuring Search Guard mode, see Search Guard.
5.4 - Search Guard
Purpose:
Version 3.9 and later supports the Search Guard Elasticsearch plugin (version 2.4.1.16 and newer) to encrypt and authenticate your connections to from AxoSyslog to Elasticsearch 2 and newer. To configure AxoSyslog to send messages to an Elasticsearch 2.x cluster that uses Search Guard, complete the following steps.
To connect to an Elasticsearch 5.x or newer cluster, use HTTPS mode.
Steps:
Install the Search Guard plugin on your AxoSyslog host. Use the plugin version that matches the version of your Elasticsearch installation.
Create a certificate for your AxoSyslog host, and add the certificate to the SYSLOG_NG-NODE_NAME-keystore.jks file. You can configure the location of this file in the Elasticsearch resources file under the path.conf parameter. For details, see the Search Guard documentation.
Configure an Elasticsearch destination in AxoSyslog that uses the searchguard client mode. For example:
Configure the Elasticsearch resource file (for example, /etc/syslog-ng/elasticsearch.yml) as needed for your environment. Note the searchguard: section.
The elasticsearch2 destination can directly send log messages to Elasticsearch, allowing you to search and analyze your data in real time, and visualize it with Kibana. The elasticsearch2 destination has the following options.
Required options:
The following options are required: index(), type(). In node mode, either the cluster() or the resource() option is required as well. Note that to use elasticsearch2, you must add the following lines to the beginning of your AxoSyslog configuration:
@include "scl.conf"
client-lib-dir()
Type:
string
Default:
The AxoSyslog module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/
Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your AxoSyslog configuration (for example, because you have multiple Java-based destinations), AxoSyslog will merge every available paths to a single list.
Description: Include the path to the directory where you copied the required libraries (see Prerequisites), for example, client-lib-dir(/user/share/elasticsearch-2.2.0/lib).
client-mode()
Type:
http
Default:
node
Description: Specifies the client mode used to connect to the Elasticsearch server, for example, client-mode("node").
HTTP mode
The AxoSyslog application sends messages over HTTP using the REST API of Elasticsearch, and uses the cluster-url() and cluster() options from the AxoSyslog configuration file. In HTTP mode, AxoSyslogelasticsearch2 driver can send log messages to every Elasticsearch version, including 1.x-6.x. Note that HTTP mode is available in AxoSyslog version 3.8 and newer.
In version 3.10 and newer, you can list multiple servers in HTTP and HTTPS mode in the cluster-url() and server() options. The AxoSyslog application will use these destination servers in load-balancing fashion. Note that load-balancing is handled by an external library (Jest), AxoSyslog does not have any direct influence on it.
HTTPS mode
The AxoSyslog application sends messages over an encrypted and optionally authenticated HTTPS channel using the REST API of Elasticsearch, and uses the cluster-url() and cluster() options from the AxoSyslog configuration file. In HTTPS mode, AxoSyslogelasticsearch2 driver can send log messages to every Elasticsearch version, including 1.x-6.x. Note that HTTPS mode is available in AxoSyslog version 3.10 and newer.
This mode supports password-based and certificate-based authentication of the client, and can verify the certificate of the server as well.
In version 3.10 and newer, you can list multiple servers in HTTP and HTTPS mode in the cluster-url() and server() options. The AxoSyslog application will use these destination servers in load-balancing fashion. Note that load-balancing is handled by an external library (Jest), AxoSyslog does not have any direct influence on it.
Transport mode
The AxoSyslog application uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the AxoSyslog configuration file.
Node mode
The AxoSyslog application acts as an Elasticsearch node (client no-data), using the node client API of Elasticsearch. Further options for the node can be describe in an Elasticsearch configuration file specified in the resource() option.
Note
In Node mode, it is required to define the home of the elasticsearch installation with the <code>path.home</code> parameter in the <code>.yml</code> file. For example: <code>path.home: /usr/share/elasticsearch</code>.
Search Guard mode
Use the Search Guard Elasticsearch plugin to encrypt and authenticate your connections from AxoSyslog to Elasticsearch 2.x. For Elasticsearch versions 5.x and newer, use HTTPS mode. For details on configuring Search Guard mode, see Search Guard.
cluster()
Type:
string
Default:
N/A
Description: Specifies the name or the Elasticsearch cluster, for example, cluster("my-elasticsearch-cluster"). Optionally, you can specify the name of the cluster in the Elasticsearch resource file. For details, see resource().
cluster-url()
Type:
string
Default:
N/A
Description: Specifies the URL or the Elasticsearch cluster, for example, cluster-url("http://192.168.10.10:9200")").
In version 3.10 and newer, you can list multiple servers in HTTP and HTTPS mode in the cluster-url() and server() options. The AxoSyslog application will use these destination servers in load-balancing fashion. Note that load-balancing is handled by an external library (Jest), AxoSyslog does not have any direct influence on it.
Description: The number of concurrent (simultaneous) requests that AxoSyslog sends to the Elasticsearch server. Set this option to 1 or higher to increase performance. When using the concurrent-requests() option, make sure that the flush-limit() option is higher than one, otherwise it will not have any noticeable effect. For details, see flush-limit().
Warning
Hazard of data loss! Using the concurrent-requests() option increases the number of messages lost in case the Elasticsearch server becomes unaccessible.
custom-id()
Type:
template or template function
Default:
N/A
Description: Use this option to specify a custom ID for the records inserted into Elasticsearch. If this option is not set, the Elasticsearch server automatically generates and ID for the message. For example: custom-id(${UNIQID}) (Note that to use the ${UNIQID} macro, the use-uniqid() global option must be enabled. For details, see use-uniqid().)
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: The number of messages that AxoSyslog sends to the Elasticsearch server in a single batch.
If flush-limit is set to 1: AxoSyslog sends the message reliably: it sends a message to Elasticsearch, then waits for a reply from Elasticsearch. In case of failure, AxoSyslog repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, AxoSyslog drops the message.
This method ensures reliable message transfer, but is slow (about 1000 messages/second).
If flush-limit is higher than 1: AxoSyslog sends messages in a batch, and receives the response asynchronously. In case of a problem, AxoSyslog cannot resend the messages.
This method is relatively fast (depending on the size of flush-limit, about 8000 messages/second), but the transfer is not reliable. In transport mode, over 5000-30000 messages can be lost before AxoSyslog recognizes the error. In node mode, about 1000 messages can be lost.
If concurrent-requests is higher than 1, AxoSyslog can send multiple batches simultaneously, increasing performance (and also the number of messages that can be lost in case of an error).
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.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Determines how AxoSyslog authenticates to the Elasticsearch server. Depending on the value of this option, you might have to set other options as well. Possible values:
none: Connect to the Elasticsearch server without authentication.
Verify the certificate of the Elasticsearch server and perform certificate authentication (this is actually a mutual, certificate-based authentication between the AxoSyslog client and the Elasticsearch server):
Description: The password to use for password-authentication on the Elasticsearch server. You must also set the http-auth-type-basic-username option.
This option is used only in HTTPS mode with basic authentication: client-mode("https") and http-auth-type("basic"), and is available in AxoSyslog version 3.10 and newer.
Description: The username to use for password-authentication on the Elasticsearch server. You must also set the http-auth-type-basic-password option.
This option is used only in HTTPS mode with basic authentication: client-mode("https") and http-auth-type("basic"), and is available in AxoSyslog version 3.10 and newer.
Description: Name of the Elasticsearch index to store the log messages. You can use macros and templates as well.
java-keystore-filepath()
Type:
string
Default:
N/A
Description: Path to the Java keystore file that stores the certificate that AxoSyslog uses to authenticate on the Elasticsearch server. You must also set the java-keystore-password option.
To import a certificate into a Java keystore, use the appropriate tool of your Java implementation. For example, on Oracle Java, you can use the keytool utility:
keytool -import -alias ca -file <certificate-to-import> -keystore <keystore-to-import> -storepass <password-to-the-keystore>
This option is used only in HTTPS mode with basic authentication: client-mode("https") and http-auth-type("clientcert"), and is available in AxoSyslog version 3.10 and newer.
Verify the certificate of the Elasticsearch server and perform certificate authentication (this is actually a mutual, certificate-based authentication between the AxoSyslog client and the Elasticsearch server):
Description: The password of the Java keystore file set in the java-keystore-filepath option.
To import a certificate into a Java keystore, use the appropriate tool of your Java implementation. For example, on Oracle Java, you can use the keytool utility:
keytool -import -alias ca -file <certificate-to-import> -keystore <keystore-to-import> -storepass <password-to-the-keystore>
This option is used only in HTTPS mode with basic authentication: client-mode("https") and http-auth-type("clientcert"), and is available in AxoSyslog version 3.10 and newer.
Verify the certificate of the Elasticsearch server and perform certificate authentication (this is actually a mutual, certificate-based authentication between the AxoSyslog client and the Elasticsearch server):
Description: Path to the Java keystore file that stores the CA certificate that AxoSyslog uses to verify the certificate of the Elasticsearch server. You must also set the java-truststore-password option.
If you do not set the java-truststore-filepath option, AxoSyslog does accepts any certificate that the Elasticsearch server shows. In this case, the identity of the server is not verified, only the connection is encrypted.
To import a certificate into a Java keystore, use the appropriate tool of your Java implementation. For example, on Oracle Java, you can use the keytool utility:
keytool -import -alias ca -file <certificate-to-import> -keystore <keystore-to-import> -storepass <password-to-the-keystore>
This option is used only in HTTPS mode: client-mode("https"), and is available in AxoSyslog version 3.10 and newer.
Verify the certificate of the Elasticsearch server without authentication:
Verify the certificate of the Elasticsearch server and perform certificate authentication (this is actually a mutual, certificate-based authentication between the AxoSyslog client and the Elasticsearch server):
Description: The password of the Java truststore file set in the java-truststore-filepath option.
To import a certificate into a Java keystore, use the appropriate tool of your Java implementation. For example, on Oracle Java, you can use the keytool utility:
keytool -import -alias ca -file <certificate-to-import> -keystore <keystore-to-import> -storepass <password-to-the-keystore>
This option is used only in HTTPS mode: client-mode("https"), and is available in AxoSyslog version 3.10 and newer.
Verify the certificate of the Elasticsearch server without authentication:
Verify the certificate of the Elasticsearch server and perform certificate authentication (this is actually a mutual, certificate-based authentication between the AxoSyslog client and the Elasticsearch server):
Description: Specify the Java Virtual Machine (JVM) settings of your Java destination from the AxoSyslog configuration file.
For example:
jvm-options("-Xss1M -XX:+TraceClassLoading")
You can set this option only as a global option, by adding it to the options statement of the syslog-ng.conf configuration file.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
on-error()
Type:
One of: drop-message, drop-property, fallback-to-string, silently-drop-message, silently-drop-property, silently-fallback-to-string
Default:
Use the global setting (which defaults to drop-message)
Description: Controls what happens when type-casting fails and 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.
port()
Type:
number
Default:
9300
Description: The port number of the Elasticsearch server. This option is used only in transport mode: client-mode("transport")
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
resource()
Type:
string
Default:
N/A
Description: The list of Elasticsearch resources to load, separated by semicolons. For example, resource("/home/user/elasticsearch/elasticsearch.yml;/home/user/elasticsearch/elasticsearch2.yml").
server()
Type:
list of hostnames
Default:
127.0.0.1
Description: Specifies the hostname or IP address of the Elasticsearch server. When specifying an IP address, IPv4 (for example, 192.168.0.1) or IPv6 (for example, [::1]) can be used as well. When specifying multiple addresses, use space to separate the addresses, for example, server("127.0.0.1 remote-server-hostname1 remote-server-hostname2")
This option is used only in transport mode: client-mode("transport")
In version 3.10 and newer, you can list multiple servers in HTTP and HTTPS mode in the cluster-url() and server() options. The AxoSyslog application will use these destination servers in load-balancing fashion. Note that load-balancing is handled by an external library (Jest), AxoSyslog does not have any direct influence on it.
Description: By default, when connecting to an Elasticsearch cluster, AxoSyslog checks the state of the cluster. If the primary shards of the cluster are not active, AxoSyslog will not send messages, but wait for them to become active. To disable this health check and send the messages to Elasticsearch anyway, use the skip-cluster-health-check(yes) option in your configuration.
template()
Type:
template or template function
Default:
$(format-json --scope rfc5424 --exclude DATE --key ISODATE @timestamp=${ISODATE})
Description: The message as sent to the Elasticsearch server. Typically, you will want to use the command-line notation of the format-json template function.
To add a @timestamp field to the message, for example, to use with Kibana, include the @timestamp=${ISODATE} expression in the template. For example: template($(format-json --scope rfc5424 --exclude DATE --key ISODATE @timestamp=${ISODATE}))
For details on formatting messages in JSON format, see format-json.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-zone()
Type:
name of the timezone, or the timezone offset
Default:
unspecified
Description: Convert timestamps to the timezone specified by this option. If this option is not set, then the original timezone information in the message is used. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see 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.
Version 3.10 and newer of AxoSyslog automatically converts the timestamp (date) of the message to UTC, as needed by Elasticsearch and Kibana.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
type()
Type:
string
Default:
N/A
Description: The type of the index. For example, type("test").
6 - elasticsearch-http: Send messages to Elasticsearch HTTP Bulk API
Version 3.21 of AxoSyslog can directly post log messages to an Elasticsearch deployment using the Elasticsearch Bulk API over the HTTP and Secure HTTP (HTTPS) protocols.
HTTPS connection, as well as password- and certificate-based authentication is supported. The content of the events is sent in JSON format.
Use an empty string to omit the type from the index: type(""). For example, you need to do that when using Elasticsearch 7 or newer, and you use a mapping in Elasticsearch to modify the type of the data.
You can use the proxy() option to configure the HTTP driver in all HTTP-based destinations to use a specific HTTP proxy that is independent from the proxy configured for the system.
Alternatively, you can leave the HTTP as-is, in which case the driver leaves the default http_proxy and https_proxy environment variables unmodified.
This driver is actually a reusable configuration snippet configured to send log messages using the tcp() driver using a template. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of this configuration snippet on GitHub.
6.1 - Batch mode and load balancing
The elasticsearch-http() destination automatically sends multiple log messages in a single HTTP request, increasing the rate of messages that your Elasticsearch deployment can consume. For details on adjusting and fine-tuning the batch mode of the elasticsearch-http() destination, see the following section.
Batch size
The batch-bytes(), batch-lines(), and batch-timeout() options of the destination determine how many log messages AxoSyslog sends in a batch. The batch-lines() option determines the maximum number of messages AxoSyslog puts in a batch in. This can be limited based on size and time:
AxoSyslog sends a batch every batch-timeout() milliseconds, even if the number of messages in the batch is less than batch-lines(). That way the destination receives every message in a timely manner even if suddenly there are no more messages.
AxoSyslog sends the batch if the total size of the messages in the batch reaches batch-bytes() bytes.
To increase the performance of the destination, increase the number of worker threads for the destination using the workers() option, or adjust the batch-bytes(), batch-lines(), batch-timeout() options.
Example: HTTP batch mode
In the following example, a batch consists of 100 messages, or a maximum of 512 kilobytes, and is sent every 20 seconds (20000 milliseconds).
Load balancing between multiple Elasticsearch indexers
Starting with version 3.19, you can specify multiple URLs, for example, url("site1" "site2"). In this case, AxoSyslog sends log messages to the specified URLs in a load-balance fashion. This means that AxoSyslog sends each message to only one URL. For example, you can use this to send the messages to a set of ingestion nodes or indexers of your SIEM solution if a single node cannot handle the load. Note that the order of the messages as they arrive on the servers can differ from the order AxoSyslog has received them, so use load-balancing only if your server can use the timestamp from the messages. If the server uses the timestamp when it receives the messages, the order of the messages will be incorrect.
Warning
If you set multiple URLs in the url() option, set the persist-name() option as well to avoid data loss.
Starting with version AxoSyslog version 3.22, you can use any of the following formats to specify multiple URLs:
url("server1", "server2", "server3");# comma-separated strings url("server1""server2""server3");# space-separated strings url("server1 server2 server3");# space-separated within a single string
Example: HTTP load balancing
The following destination sends log messages to 3 different Elasticsearch indexer nodes. Each node is assigned a separate worker thread. A batch consists of 100 messages, or a maximum of 512 kilobytes, and is sent every 20 seconds (20000 milliseconds).
If you are using load-balancing (that is, you have configured multiple servers in the url() option), increase the number of worker threads at least to the number of servers. For example, if you have set three URLs (url("site1", "site2", "site3")), set the workers() option to 3 or more.
6.2 - elasticsearch-http() destination options
The elasticsearch-http destination of AxoSyslog can directly post log messages to an Elasticsearch deployment using the Elasticsearch Bulk API over the HTTP and Secure HTTP (HTTPS) protocols. The elasticsearch-http destination has the following options. The required options are: index(), type(), and url().
This destination is available in AxoSyslog version 3.21 and later.
batch-bytes()
Accepted values:
number [bytes]
Default:
none
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Name of a file that contains an X.509 CA certificate (or a certificate chain) in PEM format. The AxoSyslog application uses this certificate to validate the certificate of the HTTPS server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Name of a file, that contains an X.509 certificate (or a certificate chain) in PEM format, suitable as a TLS certificate, matching the private key set in the key-file() option. The AxoSyslog application uses this certificate to authenticate the AxoSyslog client on the destination server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Depends on the OpenSSL version that AxoSyslog uses
Description: Specifies the cipher, hash, and key-exchange algorithms used for the encryption, for example, ECDHE-ECDSA-AES256-SHA384. The list of available algorithms depends on the version of OpenSSL used to compile AxoSyslog. To specify multiple ciphers, separate the cipher names with a colon, and enclose the list between double-quotes, for example:
For a list of available algorithms, execute the openssl ciphers -v command. The first column of the output contains the name of the algorithms to use in the cipher-suite() option, the second column specifies which encryption protocol uses the algorithm (for example, TLSv1.2). That way, the cipher-suite() also determines the encryption protocol used in the connection: to disable SSLv3, use an algorithm that is available only in TLSv1.2, and that both the client and the server supports. You can also specify the encryption protocols using ssl-options().
You can also use the following command to automatically list only ciphers permitted in a specific encryption protocol, for example, TLSv1.2:
echo"cipher-suite(\"$(openssl ciphers -v | grep TLSv1.2 | awk '{print $1}'| xargs echo -n | sed 's/ /:/g'| sed -e 's/:$//')\")"
Note that starting with version 3.10, when AxoSyslog receives TLS-encrypted connections, the order of ciphers set on the AxoSyslog server takes precedence over the client settings.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Sets the specified value as the ID of the Elasticsearch index (_id).
delimiter()
Accepted values:
string
Default:
newline character
Description: By default, AxoSyslog separates the log messages of the batch with a newline character. You can specify a different delimiter by using the delimiter() option.
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The name of the Elasticsearch index where Elasticsearch will store the messages received from AxoSyslog. This option is mandatory for this destination.
You can use macros and template functions, but you must ensure that the resolved template contains only characters that Elasticsearch permits in the name of the index. The AxoSyslog application does not validate the name of the index. For details on the characters permitted in the name of Elasticsearch indices, see the documentation of Elasticsearch.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
key-file()
Accepted values:
Filename
Default:
none
Description: The name of a file that contains an unencrypted private key in PEM format, suitable as a TLS key. If properly configured, the AxoSyslog application uses this private key and the matching certificate (set in the cert-file() option) to authenticate the AxoSyslog client on the destination server.
This destination supports only unencrypted key files (that is, the private key cannot be password-protected).
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: The password that AxoSyslog uses to authenticate on the server where it sends the messages.
peer-verify()
Accepted values:
`yes
Default:
yes
Description: Verification method of the peer. The following table summarizes the possible options and their results depending on the certificate of the peer.
The remote peer has:
no certificate
invalid certificate
valid certificate
Local peer-verify() setting
no (optional-untrusted)
TLS-encryption
TLS-encryption
TLS-encryption
yes (required-trusted)
rejected connection
rejected connection
TLS-encryption
For untrusted certificates only the existence of the certificate is checked, but it does not have to be valid — AxoSyslog accepts the certificate even if it is expired, signed by an unknown CA, or its CN and the name of the machine mismatches.
Warning
When validating a certificate, the entire certificate chain must be valid, including the CA certificate. If any certificate of the chain is invalid, AxoSyslog will reject the connection.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
To handle HTTP error responses, if the HTTP server returns 5xx codes, AxoSyslog will attempt to resend messages until the number of attempts reaches retries. If the HTTP server returns 4xx codes, AxoSyslog will drop the messages.
ssl-version()
Type:
string
Default:
None, uses the libcurl default
Description: Specifies the permitted SSL/TLS version. Possible values: sslv2, sslv3, tlsv1, tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
type()
Type:
string or template
Default:
N/A
Description: The type of the Elasticsearch index.
Use an empty string to omit the type from the index: type(""). For example, you need to do that when using Elasticsearch 7 or newer, and you use a mapping in Elasticsearch to modify the type of the data.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
timeout()
Type:
number [seconds]
Default:
10
Description: The value (in seconds) to wait for an operation to complete, and attempt to reconnect the server if exceeded.
url()
Type:
URL or list of URLs, for example, url(“site1” “site2”)
Default:
N/A
Description: Specifies the hostname or IP address and optionally the port number of the Elasticsearch indexer. Use a colon (:) after the address to specify the port number of the server. For example: http://your-elasticsearch-indexer.server:8088/_bulk
This option is mandatory for this destination.
Make sure that the URL ends with _bulk, this is the Elasticsearch API endpoint that properly parses the messages sent by AxoSyslog.
In case the server on the specified URL returns a redirect request, AxoSyslog automatically follows maximum 3 redirects. Only HTTP and HTTPS based redirections are supported.
Starting with version 3.19, you can specify multiple URLs, for example, url("site1" "site2"). In this case, AxoSyslog sends log messages to the specified URLs in a load-balance fashion. This means that AxoSyslog sends each message to only one URL. For example, you can use this to send the messages to a set of ingestion nodes or indexers of your SIEM solution if a single node cannot handle the load. Note that the order of the messages as they arrive on the servers can differ from the order AxoSyslog has received them, so use load-balancing only if your server can use the timestamp from the messages. If the server uses the timestamp when it receives the messages, the order of the messages will be incorrect.
Warning
If you set multiple URLs in the url() option, set the persist-name() option as well to avoid data loss.
Starting with version AxoSyslog version 3.22, you can use any of the following formats to specify multiple URLs:
url("server1", "server2", "server3");# comma-separated strings url("server1""server2""server3");# space-separated strings url("server1 server2 server3");# space-separated within a single string
user()
Type:
string
Default:
Description: The username that AxoSyslog uses to authenticate on the server where it sends the messages.
use-system-cert-store()
Type:
`yes
Default:
no
Description: Use the certificate store of the system for verifying HTTPS certificates. For details, see the curl documentation.
workers()
Type:
integer
Default:
4
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
If you are using load-balancing (that is, you have configured multiple servers in the url() option), increase the number of worker threads at least to the number of servers. For example, if you have set three URLs (url("site1", "site2", "site3")), set the workers() option to 3 or more.
7 - file: Store messages in plain-text files
The file driver is one of the most important destination drivers. It allows to output messages to the specified text file, or to a set of files.
The destination filename may include macros which get expanded when the message is written, thus a simple file() driver may create several files: for example, AxoSyslog can store the messages of client hosts in a separate file for each host. For more information on available macros see Macros of AxoSyslog.
If the expanded filename refers to a directory which does not exist, it will be created depending on the create-dirs() setting (both global and a per destination option).
The file() has a single required parameter that specifies the filename that stores the log messages. For the list of available optional parameters, see file() destination options.
Declaration:
file(filename options());
Example: Using the file() driver
destination d_file { file("/var/log/messages");};
Example: Using the file() driver with macros in the file name and a template for the message
When using this destination, update the configuration of your log rotation program to rotate these files. Otherwise, the log files can become very large.
Also, after rotating the log files, reload AxoSyslog using the syslog-ng-ctl reload command, or use another method to send a SIGHUP to AxoSyslog.
Warning
Since the state of each created file must be tracked by syslog-ng, it consumes some memory for each file. If no new messages are written to a file within 60 seconds (controlled by the time-reap() global option), it is closed, and its state is freed.
Exploiting this, a DoS attack can be mounted against the system. If the number of possible destination files and its needed memory is more than the amount available on the AxoSyslog server.
The most suspicious macro is ${PROGRAM}, where the number of possible variations is rather high. Do not use the ${PROGRAM} macro in insecure environments.
7.1 - file() destination options
The file() driver outputs messages to the specified text file, or to a set of files. The file() destination has the following options:
Warning
When creating several thousands separate log files, AxoSyslog might not be able to open the required number of files. This might happen for example, when using the ${HOST} macro in the filename while receiving messages from a large number of hosts. To overcome this problem, adjust the --fd-limit command-line parameter of AxoSyslog or the global ulimit parameter of your host. For setting the --fd-limit command-line parameter ofAxoSyslog see the The syslog-ng manual page. For setting the ulimit parameter of the host, see the documentation of your operating system.
create-dirs()
Type:
yes or no
Default:
no
Description: Enable creating non-existing directories when creating files or socket files.
dir-group()
Type:
string
Default:
Use the global settings
Description: The group of the directories created by syslog-ng. To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-group().
dir-owner()
Type:
string
Default:
Use the global settings
Description: The owner of the directories created by syslog-ng. To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-owner().
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.
dir-perm()
Type:
number
Default:
Use the global settings
Description: The permission mask of directories created by syslog-ng. Log directories are only created if a file after macro expansion refers to a non-existing directory, and directory creation is enabled (see also the create-dirs() option). For octal numbers prefix the number with 0, for example, use 0755 for rwxr-xr-x.
To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-perm(). Note that when creating a new directory without specifying attributes for dir-perm(), the default permission of the directories is masked with the umask of the parent process (typically 0022).
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Flags influence the behavior of the destination driver.
no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.
syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.
threaded: The threaded flag enables multithreading for the destination. For details on multithreading, see Multithreading and scaling.
Note
The file destination uses multiple threads only if the destination filename contains macros.
flush-lines()
Type:
number
Default:
Use global setting (exception: for http() destination, the default is 1).
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.
For optimal performance when sending messages to an AxoSyslog server, make sure that the value of flush-lines() is smaller than the window size set in the log-iw-size() option in the source of your server.
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.
fsync()
Type:
yes or no
Default:
no
Description: Forces an fsync() call on the destination fd after each write.
Note
Enabling this option may seriously degrade performance.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Set the group of the created file to the one specified. To preserve the original properties of an existing file, use the option without specifying an attribute: group().
local-time-zone()
Type:
name of the timezone, or the timezone offset
Default:
The local timezone.
Description: Sets the timezone used when expanding filename and tablename templates.
The timezone can be specified 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.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
mark-freq()
Accepted values:
number [seconds]
Default:
1200
Description: An alias for the obsolete mark() option, retained for compatibility with 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).
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:
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.
overwrite-if-older()
Type:
number (seconds)
Default:
0
Description: If set to a value higher than 0, AxoSyslog checks when the file was last modified before starting to write into the file. If the file is older than the specified amount of time (in seconds), then AxoSyslog removes the existing file and opens a new file with the same name. In combination with for example, the ${WEEKDAY} macro, this can be used for simple log rotation, in case not all history has to be kept. (Note that in this weekly log rotation example if its Monday 00:01, then the file from last Monday is not seven days old, because it was probably last modified shortly before 23:59 last Monday, so it is actually not even six days old. So in this case, set the overwrite-if-older() parameter to a-bit-less-than-six-days, for example, to 518000 seconds.
owner()
Type:
string
Default:
Use the global settings
Description: Set the owner of the created file to the one specified. To preserve the original properties of an existing file, use the option without specifying an attribute: owner().
pad-size()
Type:
number
Default:
0
Description: If set, AxoSyslog will pad output messages to the specified size (in bytes). Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes).
Warning
Hazard of data loss! If the size of the incoming message is larger than the previously set pad-size() value, AxoSyslog will truncate the message to the specified size. Therefore, all message content above that size will be lost.
perm()
Type:
number
Default:
Use the global settings
Description: The permission mask of the file if it is created by syslog-ng. For octal numbers prefix the number with 0, for example, use 0755 for rwxr-xr-x.
To preserve the original properties of an existing file, use the option without specifying an attribute: perm().
suppress()
Type:
seconds
Default:
0 (disabled)
Description: If several identical log messages would be sent to the destination without any other messages between the identical messages (for example, an application repeated an error message ten times), 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.
symlink-as()
Type:
Filename
Default:
N/A
Description: The configured file name will be used as a symbolic link to the last created file by file destination.
In this case the /var/log/cron should point to the current month.
Note
The symlink uses the same permissions as the file destination.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
template-escape()
Type:
yes or no
Default:
no
Description: Turns on escaping for the ', ", and backspace characters in templated output files. This is useful for generating SQL statements and quoting string contents so that parts of the log message are not interpreted as commands to the SQL server.
Note: Starting with AxoSyslog version 4.5, template-escape(yes) escapes the top-level template function in case of nested template functions.
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.
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);};
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",
);};
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-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.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
This driver is actually a reusable configuration snippet configured to send log messages using the http() driver using a template. You can find the source of this configuration snippet on GitHub.
Options
The following options are specific to the google-pubsub() destination. But since this destination is based on the http() destination, you can use the options of the http() destination as well if needed.
Note: The google-pubsub() destination automatically configures some of these http() destination options as required by the Google Pub/Sub API.
attributes()
Type:
string
Default:
"--scope rfc5424,all-nv-pairs --exclude MESSAGE"
Description: A JSON object representing key-value pairs for the Pub/Sub Event, formatted as AxoSyslog value-pairs. By default, the google-pubsub() destination sends the RFC5424 fields as attributes. If you want to send different fields, override the default template. By default, the message part is sent in the data() option.
Description: The template to use as the data part of the Google Pub/Sub message.
project()
Type:
string
Default:
-
Description: The ID of the Google Cloud project where AxoSyslog sends the data. The Pub/Sub API must be enabled for the project.
topic()
Type:
string
Default:
-
Description: The name of the Google Pub/Sub topic where AxoSyslog sends the data.
9 - graphite: Send metrics to Graphite
The graphite() destination can send metrics to a Graphite server to store numeric time-series data. There are many ways to feed the Graphite template function with name value pairs. The AxoSyslog CSV and PatternDB parsers (for details, see Using pattern parsers) can parse log messages and generate name value pairs based on message content. The CSV parser (for details, see Parsing messages with comma-separated and similar values) can be used for logs that have a constant field based structure, like the Apache web server access logs. The [patterndb() parser] can parse information and can extract important fields from free form log messages, as long as patterns describing the log messages are available. Another way is to send JSON-based log messages (for details, see JSON parser) to AxoSyslog, like running a simple shell script collecting metrics and running it from cron regularly.
To use the graphite() destination, the only mandatory parameter is payload, which specifies the value pairs to send to graphite. In the following example any value pairs starting with “monitor." are forwarded to graphite.
The graphite() destination is only a wrapper around the network() destination and the graphite-output template function. If you want to fine-tune the TCP parameters, use the network() destination instead, as described in graphite-output.
9.1 - graphite() destination options
The graphite() destination has the following options:
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The hostname or IP address of the Graphite server.
port()
Type:
number
Default:
2003
Description: The port number of the Graphite server.
payload()
Type:
parameter list of the payload() option
Default:
empty string
Description: The payload() option allows you to select which value pairs to forward to graphite.
The syntax of payload is different from the syntax of value-pairs(): use the command-line syntax used in the format-json template function. For details on using the payload() option, see graphite-output.
Note
If left empty, there is no data to be forwarded to Graphite.
10 - graylog2: Send logs to Graylog
graylog2(): Sending logs to Graylog
You can use the graylog2() destination and a Graylog Extended Log Format (GELF) template to send syslog messages to Graylog.
You can forward simple name-value pairs where the name starts with a dot or underscore. If names of your name-value pairs include dots other than the first character, you should use JSON formatting directly instead of the GELF template and send logs to a raw TCP port in Graylog, which can then extract fields from nested JSON. Version 3.21 and later also supports TLS-encrypted connection to the Graylog server.
Declaration:
graylog2();
Example: Using the graylog2() driver
You can send syslog messages to Graylog using the graylog2() destination. The graylog2() destination uses the GELF template, the native data format of Graylog.
On the Graylog side, configure a GELF TCP input. For more information, see the relevant Graylog documentation.
On the AxoSyslog side, configure the name or IP address of the host running Graylog.
If you parsed your messages using syslog-ng, the template also forwards any name-value pairs where the name starts with a dot or underscore.
Note
If there is a dot in a field name other than the first character, AxoSyslog creates nested JSON while formatting the message. Nested JSON is not automatically parsed in GELF messages.
Sending nested JSON to Graylog
While sending nested JSON inside GELF is possible, it is not convenient. If you use parsing and normalization and dot notation in field names, use pure JSON instead of GELF to forward your messages.
On the Graylog side, create a new raw TCP input.
Still in Graylog, once the raw TCP input is ready, add a JSON extractor to it.
On the AxoSyslog side, use a network destination combined with a template utilizing format-json as shown in the example below:
The graylog2() destination has the following options:
ca-dir()
Accepted values:
Directory name
Default:
none
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
ca-file()
Accepted values:
File name
Default:
empty
Description: Optional. The name of a file that contains a set of trusted CA certificates in PEM format. The AxoSyslog application uses the CA certificates in this file to validate the certificate of the peer.
Example format in configuration:
ca-file("/etc/pki/tls/certs/ca-bundle.crt")
Note
The ca-file() option can be used together with the ca-dir() option, and it is relevant when peer-verify() is set to other than no or optional-untrusted.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see TLS options.
transport()
Type:
udp, tcp, or tls
Default:
tcp
Description: Specifies the protocol used to send messages to the destination server.
If you use the udp transport, AxoSyslog automatically sends multicast packets if a multicast destination address is specified. The tcp transport does not support multicasting.
11 - hdfs: Store messages on the Hadoop Distributed File System (HDFS)
Starting with version 3.7, AxoSyslog can send plain-text log files to the Hadoop Distributed File System (HDFS), allowing you to store your log data on a distributed, scalable file system. This is especially useful if you have huge amounts of log messages that would be difficult to store otherwise, or if you want to process your messages using Hadoop tools (for example, Apache Pig).
Note the following limitations when using the AxoSyslog hdfs destination:
Since AxoSyslog uses the official Java HDFS client, the hdfs destination has significant memory usage (about 400MB).
You cannot set when log messages are flushed. Hadoop performs this action automatically, depending on its configured block size, and the amount of data received. There is no way for the AxoSyslog application to influence when the messages are actually written to disk. This means that AxoSyslog cannot guarantee that a message sent to HDFS is actually written to disk. When using flow-control, AxoSyslog acknowledges a message as written to disk when it passes the message to the HDFS client. This method is as reliable as your HDFS environment.
The hdfs() driver is actually a reusable configuration snippet configured to receive log messages using the Java language-binding of AxoSyslog. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of the hdfs configuration snippet on GitHub. For details on extending AxoSyslog in Java, see the Getting started with syslog-ng development guide.
Note
If you delete all Java destinations from your configuration and reload syslog-ng, the JVM is not used anymore, but it is still running. If you want to stop JVM, stop syslog-ng and then start syslog-ng again.
11.1 - Prerequisites
To send messages from AxoSyslog to HDFS, complete the following steps.
Steps:
If you want to use the Java-based modules of AxoSyslog (for example, the Elasticsearch, HDFS, or Kafka destinations), you must compile AxoSyslog with Java support.
Download and install the Java Runtime Environment (JRE), 1.7 (or newer). You can use OpenJDK or Oracle JDK, other implementations are not tested.
Set LD_LIBRARY_PATH to include the libjvm.so file, for example:LD_LIBRARY_PATH=/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/amd64/server:$LD_LIBRARY_PATH
Note that many platforms have a simplified links for Java libraries. Use the simplified path if available. If you use a startup script to start AxoSyslog set LD_LIBRARY_PATH in the script as well.
If you are behind an HTTP proxy, create a gradle.properties under the modules/java-modules/ directory. Set the proxy parameters in the file. For details, see The Gradle User Guide.
Extract the HDFS libraries into a temporary directory, then collect the various .jar files into a single directory (for example, /opt/hadoop/lib/) where AxoSyslog can access them. You must specify this directory in the AxoSyslog configuration file. The files are located in the various lib directories under the share/ directory of the Hadoop release package. (For example, in Hadoop 2.7, required files are common/hadoop-common-2.7.0.jar, common/libs/\*.jar, hdfs/hadoop-hdfs-2.7.0.jar, hdfs/lib/\*, but this may change between Hadoop releases, so it is easier to copy every .jar file into a single directory.
11.2 - How AxoSyslog interacts with HDFS
The AxoSyslog application sends the log messages to the official HDFS client library, which forwards the data to the HDFS nodes. The way AxoSyslog interacts with HDFS is described in the following steps.
After AxoSyslog is started and the first message arrives to the hdfs destination, the hdfs destination tries to connect to the HDFS NameNode. If the connection fails, AxoSyslog will repeatedly attempt to connect again after the period set in time-reopen() expires.
AxoSyslog checks if the path to the logfile exists. If a directory does not exist AxoSyslog automatically creates it. AxoSyslog creates the destination file (using the filename set in the AxoSyslog configuration file, with a UUID suffix to make it unique, for example, /usr/hadoop/logfile.txt.3dc1c59e-ab3b-4b71-9e81-93db477ed9d9) and writes the message into the file. After the file is created, AxoSyslog will write all incoming messages into the hdfs destination.
Note
When the hdfs-append-enabled() option is set to true, AxoSyslog will not assign a new UUID suffix to an existing file, because it is then possible to open a closed file and append data to that.
Note
You cannot set when log messages are flushed. Hadoop performs this action automatically, depending on its configured block size, and the amount of data received. There is no way for the AxoSyslog application to influence when the messages are actually written to disk. This means that AxoSyslog cannot guarantee that a message sent to HDFS is actually written to disk. When using flow-control, AxoSyslog acknowledges a message as written to disk when it passes the message to the HDFS client. This method is as reliable as your HDFS environment.
If the HDFS client returns an error, AxoSyslog attempts to close the file, then opens a new file and repeats sending the message (trying to connect to HDFS and send the message), as set in the retries() parameter. If sending the message fails for retries() times, AxoSyslog drops the message.
The AxoSyslog application closes the destination file in the following cases:
AxoSyslog is reloaded
AxoSyslog is restarted
The HDFS client returns an error.
If the file is closed and you have set an archive directory, AxoSyslog moves the file to this directory. If AxoSyslog cannot move the file for some reason (for example, AxoSyslog cannot connect to the HDFS NameNode), the file remains at its original location, AxoSyslog will not try to move it again.
11.3 - Storing messages with MapR-FS
The AxoSyslog application is also compatible with MapR File System (MapR-FS). MapR-FS provides better performance, reliability, efficiency, maintainability, and ease of use compared to the default Hadoop Distributed Files System (HDFS). To use MapR-FS with AxoSyslog, complete the following steps:
Install MapR libraries. Instead of the official Apache HDFS libraries, MapR uses different libraries. The supported version is MapR 4.x.
Download the libraries from the Maven Repository and Artifacts for MapR or get it from an already existing MapR installation.
Install MapR. If you do not know how to install MapR, follow the instructions on the MapR website.
In a default MapR installation, the required libraries are installed in the following path: /opt/mapr/lib.
Enter the path where MapR was installed in the class-path option of the hdfs destination, for example:
class-path("/opt/mapr/lib/")
If the libraries were downloaded from the Maven Repository, the following additional libraries will be requiered. Note that the version numbers in the filenames can be different in the various Hadoop releases:commons-collections-3.2.1.jar, commons-logging-1.1.3.jar, hadoop-auth-2.5.1.jar, log4j-1.2.15.jar, slf4j-api-1.7.5.jar, commons-configuration-1.6.jar, guava-13.0.1.jar, hadoop-common-2.5.1.jar, maprfs-4.0.2-mapr.jar, slf4j-log4j12-1.7.5.jar, commons-lang-2.5.jar, hadoop-0.20.2-dev-core.jar, json-20080701.jar, protobuf-java-2.5.0.jar, zookeeper-3.4.5-mapr-1406.jar.
Configure the hdfs destination in AxoSyslog.
Example: Storing logfiles with MapR-FS
The following example defines an hdfs destination for MapR-FS using only the required parameters.
11.4 - Kerberos authentication with the hdfs() destination
Version 3.10 and later supports Kerberos authentication to authenticate the connection to your Hadoop cluster. AxoSyslog assumes that you already have a Hadoop and Kerberos infrastructure.
Note
If you configure Kerberos authentication for a hdfs() destination, it affects all hdfs() destinations. Kerberos and non-Kerberos hdfs() destinations cannot be mixed in a AxoSyslog configuration. This means that if one hdfs() destination uses Kerberos authentication, you have to configure all other hdfs() destinations to use Kerberos authentication too.
Failing to do so results in non-Kerberos hdfs() destinations being unable to authenticate to the HDFS server.
Note
If you want to configure your hdfs() destination to stop using Kerberos authentication, namely, to remove Kerberos-related options from the hdfs() destination configuration, make sure to restart AxoSyslog for the changes to take effect.
Prerequisites:
You have configured your Hadoop infrastructure to use Kerberos authentication.
You have a keytab file and a principal for the host running AxoSyslog. For details, see the Kerberos documentation.
You have installed and configured the Kerberos client packages on the host running AxoSyslog. (That is, Kerberos authentication works for the host, for example, from the command line using the kinit user@REALM -k -t <keytab_file> command.)
The hdfs destination stores the log messages in files on the Hadoop Distributed File System (HDFS). The hdfs destination has the following options.
The following options are required: hdfs-file(), hdfs-uri(). Note that to use hdfs, you must add the following line to the beginning of your AxoSyslog configuration:
@include "scl.conf"
client-lib-dir()
Type:
string
Default:
The AxoSyslog module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/
Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your AxoSyslog configuration (for example, because you have multiple Java-based destinations), AxoSyslog will merge every available paths to a single list.
For the hdfs destination, include the path to the directory where you copied the required libraries (see Prerequisites), for example, client-lib-dir("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/hadoop/libs/").
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
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.
hdfs-append-enabled()
Type:
`true
Default:
false
Description: When hdfs-append-enabled is set to true, AxoSyslog will append new data to the end of an already existing HDFS file. Note that in this case, archiving is automatically disabled, and AxoSyslog will ignore the hdfs-archive-dir option.
When hdfs-append-enabled is set to false, the AxoSyslog application always creates a new file if the previous has been closed. In that case, appending data to existing files is not supported.
When you choose to write data into an existing file, AxoSyslog does not extend the filename with a UUID suffix because there is no need to open a new file (a new unique ID would mean opening a new file and writing data into that).
Warning
Before enabling the hdfs-append-enabled option, ensure that your HDFS server supports the append operation and that it is enabled. Otherwise AxoSyslog will not be able to append data into an existing file, resulting in an error log.
hdfs-archive-dir()
Type:
string
Default:
N/A
Description: The path where AxoSyslog will move the closed log files. If AxoSyslog cannot move the file for some reason (for example, AxoSyslog cannot connect to the HDFS NameNode), the file remains at its original location. For example, hdfs-archive-dir("/usr/hdfs/archive/").
Note
When hdfs-append-enabled is set to true, archiving is automatically disabled, and AxoSyslog will ignore the hdfs-archive-dir option.
hdfs-file()
Type:
string
Default:
N/A
Description: The path and name of the log file. For example, hdfs-file("/usr/hdfs/mylogfile.txt"). AxoSyslog checks if the path to the logfile exists. If a directory does not exist AxoSyslog automatically creates it.
hdfs-file() supports the usage of macros. This means that AxoSyslog can create files on HDFS dynamically, using macros in the file (or directory) name.
Note
When a filename resolved from the macros contains a character that HDFS does not support, AxoSyslog will not be able to create the file. Make sure that you use macros that do not contain unsupported characters.
Example: Using macros in filenames
In the following example, a /var/testdb_working_dir/$DAY-$HOUR.txt file will be created (with a UUID suffix):
As an example, if it is the 31st day of the month and it is 12 o’clock, then the name of the file will be 31-12.txt.
hdfs-max-filename-length()
Type:
number
Default:
255
Description: The maximum length of the filename. This filename (including the UUID that AxoSyslog appends to it) cannot be longer than what the file system permits. If the filename is longer than the value of hdfs-max-filename-length, AxoSyslog will automatically truncate the filename. For example, hdfs-max-filename-length("255").
hdfs-resources()
Type:
string
Default:
N/A
Description: The list of Hadoop resources to load, separated by semicolons. For example, hdfs-resources("/home/user/hadoop/core-site.xml;/home/user/hadoop/hdfs-site.xml").
hdfs-uri()
Type:
string
Default:
N/A
Description: The URI of the HDFS NameNode is in hdfs://IPaddress:port or hdfs://hostname:port format. When using MapR-FS, the URI of the MapR-FS NameNode is in maprfs://IPaddress or maprfs://hostname format, for example: maprfs://10.140.32.80. The IP address of the node can be IPv4 or IPv6. For example, hdfs-uri("hdfs://10.140.32.80:8020"). The IPv6 address must be enclosed in square brackets ([]) as specified by RFC 2732, for example, hdfs-uri("hdfs://[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:8020").
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Specify the Java Virtual Machine (JVM) settings of your Java destination from the AxoSyslog configuration file.
For example:
jvm-options("-Xss1M -XX:+TraceClassLoading")
You can set this option only as a global option, by adding it to the options statement of the syslog-ng.conf configuration file.
kerberos-keytab-file()
Type:
string
Default:
N/A
Description: The path to the Kerberos keytab file that you received from your Kerberos administrator. For example, kerberos-keytab-file("/opt/syslog-ng/etc/hdfs.headless.keytab"). This option is needed only if you want to authenticate using Kerberos in Hadoop. You also have to set the hdfs-option-kerberos-principal() option. For details on the using Kerberos authentication with the hdfs() destination, see Kerberos authentication with the hdfs() destination.
Description: The Kerberos principal you want to authenticate with. For example, kerberos-principal("hdfs-user@MYREALM"). This option is needed only if you want to authenticate using Kerberos in Hadoop. You also have to set the hdfs-option-kerberos-keytab-file() option. For details on the using Kerberos authentication with the hdfs() destination, see Kerberos authentication with the hdfs() destination.
Description: The number of messages that the output queue can store.
on-error()
Type:
One of: drop-message, drop-property, fallback-to-string, silently-drop-message, silently-drop-property, silently-fallback-to-string
Default:
Use the global setting (which defaults to drop-message)
Description: Controls what happens when type-casting fails and 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.
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reap()
Accepted values:
number (seconds)
Default:
0 (disabled)
Description: The time to wait in seconds before an idle destination file is closed. Note that if hdfs-archive-dir option is set and time-reap expires, archiving is triggered for the affected file.
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.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
12 - java: Post messages over HTTP using Java
Version 3.7 of AxoSyslog can directly post log messages to web services using the HTTP protocol. Error and status messages received from the HTTP server are forwarded to the internal logs of AxoSyslog. The current implementation has the following limitations:
Only HTTP connections are supported, HTTPS is not.
If you delete all Java destinations from your configuration and reload syslog-ng, the JVM is not used anymore, but it is still running. If you want to stop JVM, stop syslog-ng and then start syslog-ng again.
12.1 - HTTP destination options
The http destination of AxoSyslog can directly post log messages to web services using the HTTP protocol. The http destination has the following options. Some of these options are directly used by the Java code underlying the http destination, therefore these options must be specified in the following format:
option("<option-name>", "<option-value>")
For example, option("url", "http://<server-address>:<port-number>"). The exact format to use is indicated in the description of the option.
Required options
The following options are required: url().
ca-dir()
Accepted values:
Directory name
Default:
none
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
ca-file()
Accepted values:
File name
Default:
empty
Description: Optional. The name of a file that contains a set of trusted CA certificates in PEM format. The AxoSyslog application uses the CA certificates in this file to validate the certificate of the peer.
Example format in configuration:
ca-file("/etc/pki/tls/certs/ca-bundle.crt")
Note
The ca-file() option can be used together with the ca-dir() option, and it is relevant when peer-verify() is set to other than no or optional-untrusted.
class-name()
Type:
string
Default:
N/A
Description: The name of the class (including the name of the package) that includes the destination driver to use.
For the http destination, use this option as class-name("org.syslog_ng.http.HTTPDestination").
client-lib-dir()
Type:
string
Default:
The AxoSyslog module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/
Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your AxoSyslog configuration (for example, because you have multiple Java-based destinations), AxoSyslog will merge every available paths to a single list.
For the http destination, include the path to the java modules of AxoSyslog, for example, class-path("/syslog-ng/install_dir/lib/syslog-ng/java-modules/\*.jar").
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Specify the Java Virtual Machine (JVM) settings of your Java destination from the AxoSyslog configuration file.
For example:
jvm-options("-Xss1M -XX:+TraceClassLoading")
You can set this option only as a global option, by adding it to the options statement of the syslog-ng.conf configuration file.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
method()
Type:
DELETE
Default:
PUT
Description: Specifies the HTTP method to use when sending the message to the server. Available in AxoSyslog version 3.7.2 and newer.
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
url()
Type:
URL
Default:
Description: Specifies the hostname or IP address and optionally the port number of the web service that can receive log data via HTTP. Use a colon (:) after the address to specify the port number of the server. You can also use macros, templates, and template functions in the URL, for example: http://host.example.com:8080/${MACRO1}/${MACRO2}/script")
13 - http: Post messages over HTTP without Java
Version 3.8 of AxoSyslog can directly post log messages to web services using the HTTP protocol, without having to use Java. The current implementation has the following limitations:
Only the PUT and the POST methods are supported.
HTTPS connection, as well as password- and certificate-based authentication is supported.
If the server returns a status code beginning with 2 (for example, 200), AxoSyslog assumes the message was successfully sent. For other response codes, see HTTP destination options. You can override the behavior of AxoSyslog using the response-action() option.
Example: Client certificate authentication with HTTPS
You can use the proxy() option to configure the HTTP driver in all HTTP-based destinations to use a specific HTTP proxy that is independent from the proxy configured for the system.
Alternatively, you can leave the HTTP as-is, in which case the driver leaves the default http_proxy and https_proxy environment variables unmodified.
Starting with version 3.18, you can send multiple log messages in a single HTTP request if the destination HTTP server supports that.
Batch size
The batch-bytes(), batch-lines(), and batch-timeout() options of the destination determine how many log messages AxoSyslog sends in a batch. The batch-lines() option determines the maximum number of messages AxoSyslog puts in a batch in. This can be limited based on size and time:
AxoSyslog sends a batch every batch-timeout() milliseconds, even if the number of messages in the batch is less than batch-lines(). That way the destination receives every message in a timely manner even if suddenly there are no more messages.
AxoSyslog sends the batch if the total size of the messages in the batch reaches batch-bytes() bytes.
To increase the performance of the destination, increase the number of worker threads for the destination using the workers() option, or adjust the batch-bytes(), batch-lines(), batch-timeout() options.
Formatting the batch
By default, AxoSyslog separates the log messages of the batch with a newline character. You can specify a different delimiter by using the delimiter() option.
If the target application or server requires a special beginning or ending to recognize batches, use the body-prefix() and body-suffix() options to add a beginning and ending to the batch. For example, you can use these options to create JSON-encoded arrays as POST payloads, which is required by a number of REST APIs. The body of a batch HTTP request looks like this:
value of body-prefix() option
log-line-1 (as formatted in the body() option) log-line-2 (as formatted in the body() option) ....
log-line-n (the number of log lines is batch-lines(), or less if batch-timeout() has elapsed or the batch would be longer than batch-bytes()) value of body-suffix() option
Starting with version 3.19, you can specify multiple URLs, for example, url("site1" "site2"). In this case, AxoSyslog sends log messages to the specified URLs in a load-balance fashion. This means that AxoSyslog sends each message to only one URL. For example, you can use this to send the messages to a set of ingestion nodes or indexers of your SIEM solution if a single node cannot handle the load. Note that the order of the messages as they arrive on the servers can differ from the order AxoSyslog has received them, so use load-balancing only if your server can use the timestamp from the messages. If the server uses the timestamp when it receives the messages, the order of the messages will be incorrect.
Warning
If you set multiple URLs in the url() option, set the persist-name() option as well to avoid data loss.
Starting with version AxoSyslog version 3.22, you can use any of the following formats to specify multiple URLs:
url("server1", "server2", "server3");# comma-separated strings url("server1""server2""server3");# space-separated strings url("server1 server2 server3");# space-separated within a single string
Example: HTTP load balancing
The following destination sends log messages to an Elasticsearch server using the bulk API, to 3 different ingest nodes. Each node is assigned a separate worker thread. A batch consists of 100 messages, or a maximum of 512 kilobytes, and is sent every 10 seconds (10000 milliseconds).
If you are using load-balancing (that is, you have configured multiple servers in the url() option), increase the number of worker threads at least to the number of servers. For example, if you have set three URLs (url("site1", "site2", "site3")), set the workers() option to 3 or more.
Templates in the url()
Available in AxoSyslog version 4.5.0 and later.
In AxoSyslog, a template can only be resolved on a single message, because the same template might have different resolutions on different messages. As a batch consists of multiple messages, it’s not trivial to decide which message should be used for the resolution.
When batching is enabled and multiple workers are configured, it’s important to add only those messages to a batch which generate identical URLs. To achieve this, set the worker-partition-key() option with a template that contains all the templates used in the url() option, otherwise messages will be mixed.
For security reasons, all the templated contents in the url() option are URL-encoded automatically. The following parts of the URL cannot be templated:
scheme
host
port
user
password
13.2 - HTTP destination options
The http destination of AxoSyslog can directly post log messages to web services using the HTTP protocol. The http destination has the following options.
accept-encoding()
Type:
"identity", "gzip", "deflate", "all"
Default:
Description: Use accept-encoding() to request the server to compress the HTTP responses. (AxoSyslog doesn’t currently use them, but they still contribute to network traffic.) To compress the messages sent by AxoSyslog, see the content-compression() option.
Use "identity" for no compression.
If you want to accept multiple compression types, list them separated by commas inside the quotation mark.
To enable all available compression types, use "all".
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
Description: The body of the HTTP request, for example, body("${ISODATE} ${MESSAGE}"). You can use strings, macros, and template functions in the body. If not set, it will contain the message received from the source by default.
body-prefix()
Accepted values:
string
Default:
none
Description: The string AxoSyslog puts at the beginning of the body of the HTTP request, before the log message. Available in AxoSyslog version 3.18 and later.
Description: The string AxoSyslog puts to the end of the body of the HTTP request, after the log message. Available in AxoSyslog version 3.18 and later.
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Name of a file that contains an X.509 CA certificate (or a certificate chain) in PEM format. The AxoSyslog application uses this certificate to validate the certificate of the HTTPS server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Name of a file, that contains an X.509 certificate (or a certificate chain) in PEM format, suitable as a TLS certificate, matching the private key set in the key-file() option. The AxoSyslog application uses this certificate to authenticate the AxoSyslog client on the destination server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Depends on the OpenSSL version that AxoSyslog uses
Description: Specifies the cipher, hash, and key-exchange algorithms used for the encryption, for example, ECDHE-ECDSA-AES256-SHA384. The list of available algorithms depends on the version of OpenSSL used to compile AxoSyslog. To specify multiple ciphers, separate the cipher names with a colon, and enclose the list between double-quotes, for example:
For a list of available algorithms, execute the openssl ciphers -v command. The first column of the output contains the name of the algorithms to use in the cipher-suite() option, the second column specifies which encryption protocol uses the algorithm (for example, TLSv1.2). That way, the cipher-suite() also determines the encryption protocol used in the connection: to disable SSLv3, use an algorithm that is available only in TLSv1.2, and that both the client and the server supports. You can also specify the encryption protocols using ssl-options().
You can also use the following command to automatically list only ciphers permitted in a specific encryption protocol, for example, TLSv1.2:
echo"cipher-suite(\"$(openssl ciphers -v | grep TLSv1.2 | awk '{print $1}'| xargs echo -n | sed 's/ /:/g'| sed -e 's/:$//')\")"
Note that starting with version 3.10, when AxoSyslog receives TLS-encrypted connections, the order of ciphers set on the AxoSyslog server takes precedence over the client settings.
content-compression()
Type:
"identity", "gzip", "deflate", "all"
Default:
Description: Use content-compression() to compress the messages sent by AxoSyslog. To accept compressed responses from the server, see the accept-encoding() option.
Use "identity" for no compression.
If you want to accept multiple compression types, list them separated by commas inside the quotation mark.
To enable all available compression types, use "all".
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: By default, AxoSyslog separates the log messages of the batch with a newline character. You can specify a different delimiter by using the delimiter() option. Available in AxoSyslog version 3.18 and later.
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Use global setting (exception: for http() destination, the default is 1).
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.
For optimal performance when sending messages to an AxoSyslog server, make sure that the value of flush-lines() is smaller than the window size set in the log-iw-size() option in the source of your server.
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.
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.
headers()
Type:
string list
Default:
Description: Custom HTTP headers to include in the request, for example, headers("HEADER1: header1", "HEADER2: header2"). If not set, only the default headers are included, but no custom headers.
The following headers are included by default:
X-Syslog-Host: <host>
X-Syslog-Program: <program>
X-Syslog-Facility: <facility>
X-Syslog-Level: <loglevel/priority>
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The name of a file that contains an unencrypted private key in PEM format, suitable as a TLS key. If properly configured, the AxoSyslog application uses this private key and the matching certificate (set in the cert-file() option) to authenticate the AxoSyslog client on the destination server.
The http() destination supports only unencrypted key files (that is, the private key cannot be password-protected).
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
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.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
method()
Type:
POST or PUT
Default:
POST
Description: Specifies the HTTP method to use when sending the message to the server.
ocsp-stapling-verify
Accepted values:
yes, no
Default:
no
Available in AxoSyslog 4.0 and later.
Description: When OCSP stapling verification is enabled, AxoSyslog requests the server to send back its OCSP status. AxoSyslog verifies this status response using the trust store you have configured using the ca-file(), ca-dir(), or the pkcs12-file() options.
Note
RFC 6961 multi-stapling and TLS 1.3-provided multiple responses are currently not validated, only the peer certificate is verified.
One of: drop-message, drop-property, fallback-to-string, silently-drop-message, silently-drop-property, silently-fallback-to-string
Default:
Use the global setting (which defaults to drop-message)
Description: Controls what happens when type-casting fails and 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.
password()
Type:
string
Default:
Description: The password that AxoSyslog uses to authenticate on the server where it sends the messages.
peer-verify()
Accepted values:
`yes
Default:
yes
Description: Verification method of the peer. The following table summarizes the possible options and their results depending on the certificate of the peer.
The remote peer has:
no certificate
invalid certificate
valid certificate
Local peer-verify() setting
no (optional-untrusted)
TLS-encryption
TLS-encryption
TLS-encryption
yes (required-trusted)
rejected connection
rejected connection
TLS-encryption
For untrusted certificates only the existence of the certificate is checked, but it does not have to be valid — AxoSyslog accepts the certificate even if it is expired, signed by an unknown CA, or its CN and the name of the machine mismatches.
Warning
When validating a certificate, the entire certificate chain must be valid, including the CA certificate. If any certificate of the chain is invalid, AxoSyslog will reject the connection.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
persist-name()
Type:
string
Default:
N/A
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
proxy()
Type:
The proxy server address, in `proxy("PROXY_IP:PORT")` format.
For example, `proxy("http://myproxy:3128")`
Default:
None
Description:
You can use the proxy() option to configure the HTTP driver in all HTTP-based destinations to use a specific HTTP proxy that is independent from the proxy configured for the system.
Alternatively, you can leave the HTTP as-is, in which case the driver leaves the default http_proxy and https_proxy environment variables unmodified.
Note
Configuring the <code>proxy()</code> option overwrites the default <code>http_proxy</code> and <code>https_proxy</code> environment variables.
Example: the proxy() option in configuration
The following example illustrates including the proxy() option in your configuration.
Description: Specifies what AxoSyslog does with the log message, based on the response code received from the HTTP server. If the server returns a status code beginning with 2 (for example, 200), AxoSyslog assumes the message was successfully sent. Otherwise, the action listed in the following table is applied. For status codes not listed in the following table, if the status code begins with 2 (for example, 299), AxoSyslog assumes the message was successfully sent. For other status codes, AxoSyslog disconnects. The following actions are possible:
disconnect: Keep trying to resend the message indefinitely.
drop: Drop the message without trying to resend it.
retry: Retry sending the message for a maximum of retries() times (3 by default).
success: Assume the message was successfully sent.
|------+-----------------------------------+------------|| code | explanation | action ||------+-----------------------------------+------------||100|"Continue"| disconnect ||101|"Switching Protocols"| disconnect ||102|"Processing"| retry ||103|"Early Hints"| retry ||200|"OK"| success ||201|"Created"| success ||202|"Accepted"| success ||203|"Non-Authoritative Information"| success ||204|"No Content"| success ||205|"Reset Content"| success ||206|"Partial Content"| success ||300|"Multiple Choices"| disconnect ||301|"Moved Permanently"| disconnect ||302|"Found"| disconnect ||303|"See Other"| disconnect ||304|"Not Modified"| retry ||307|"Temporary Redirect"| disconnect ||308|"Permanent Redirect"| disconnect ||400|"Bad Request"| disconnect ||401|"Unauthorized"| disconnect ||402|"Payment Required"| disconnect ||403|"Forbidden"| disconnect ||404|"Not Found"| disconnect ||405|"Method Not Allowed"| disconnect ||406|"Not Acceptable"| disconnect ||407|"Proxy Authentication Required"| disconnect ||408|"Request Timeout"| disconnect ||409|"Conflict"| disconnect ||410|"Gone"| drop ||411|"Length Required"| disconnect ||412|"Precondition Failed"| disconnect ||413|"Payload Too Large"| disconnect ||414|"URI Too Long"| disconnect ||415|"Unsupported Media Type"| disconnect ||416|"Range Not Satisfiable"| drop ||417|"Expectation Failed"| disconnect ||418|"I'm a teapot"| disconnect ||421|"Misdirected Request"| disconnect ||422|"Unprocessable Entity"| drop ||423|"Locked"| disconnect ||424|"Failed Dependency"| drop ||425|"Too Early"| drop ||426|"Upgrade Required"| disconnect ||428|"Precondition Required"| retry ||429|"Too Many Requests"| disconnect ||431|"Request Header Fields Too Large"| disconnect ||451|"Unavailable For Legal Reasons"| drop ||500|"Internal Server Error"| disconnect ||501|"Not Implemented"| disconnect ||502|"Bad Gateway"| disconnect ||503|"Service Unavailable"| disconnect ||504|"Gateway Timeout"| retry ||505|"HTTP Version Not Supported"| disconnect ||506|"Variant Also Negotiates"| disconnect ||507|"Insufficient Storage"| disconnect ||508|"Loop Detected"| drop ||510|"Not Extended"| disconnect ||511|"Network Authentication Required"| disconnect ||------+-----------------------------------+------------|
To customize the action to take for a particular response code, use the following format: response-action(<response-code> => <action>. To customize multiple response code-action pairs, separate them with a comma, for example:
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
To handle HTTP error responses, if the HTTP server returns 5xx codes, AxoSyslog will attempt to resend messages until the number of attempts reaches retries. If the HTTP server returns 4xx codes, AxoSyslog will drop the messages.
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.
ssl-version()
Type:
string
Default:
None, uses the libcurl default
Description: Specifies the permitted SSL/TLS version. Possible values: sslv2, sslv3, tlsv1, tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
timeout()
Type:
number [seconds]
Default:
0
Description: The value (in seconds) to wait for an operation to complete, and attempt to reconnect the server if exceeded. By default, the timeout value is 0, meaning that there is no timeout. Available in version 3.11 and later.
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.
url()
Type:
URL or list of URLs
Default:
http://localhost/
Description: Specifies the hostname or IP address and optionally the port number of the web service that can receive log data via HTTP. Use a colon (:) after the address to specify the port number of the server. For example: http://127.0.0.1:8000
In case the server on the specified URL returns a redirect request, AxoSyslog automatically follows maximum 3 redirects. Only HTTP and HTTPS based redirections are supported.
Templates in the URL
Starting with AxoSyslog version 4.5, you can use templates in the url() option of the http() driver, but note the following points.
Templates and batching: A template can only be resolved for a single message, because the template might have different resolutions on different messages. When batching is enabled and the destination uses multiple workers, it’s important to only batch messages which generate identical URLs. In this case, set the worker-partition-key() option with a template that contains all the templates used in the url() option, otherwise messages will be mixed.
For security reasons, AxoSyslog automatically URL-encodes the templated content of the url() option. The following parts of the URL cannot be templated:
scheme
host
port
user
password
Load balancing
Starting with version 3.19, you can specify multiple URLs, for example, url("site1" "site2"). In this case, AxoSyslog sends log messages to the specified URLs in a load-balance fashion. This means that AxoSyslog sends each message to only one URL. For example, you can use this to send the messages to a set of ingestion nodes or indexers of your SIEM solution if a single node cannot handle the load. Note that the order of the messages as they arrive on the servers can differ from the order AxoSyslog has received them, so use load-balancing only if your server can use the timestamp from the messages. If the server uses the timestamp when it receives the messages, the order of the messages will be incorrect.
Warning
If you set multiple URLs in the url() option, set the persist-name() option as well to avoid data loss.
Starting with version AxoSyslog version 3.22, you can use any of the following formats to specify multiple URLs:
url("server1", "server2", "server3");# comma-separated strings url("server1""server2""server3");# space-separated strings url("server1 server2 server3");# space-separated within a single string
Templates in the url()
Available in AxoSyslog version 4.5.0 and later.
In AxoSyslog, a template can only be resolved on a single message, because the same template might have different resolutions on different messages. As a batch consists of multiple messages, it’s not trivial to decide which message should be used for the resolution.
When batching is enabled and multiple workers are configured, it’s important to add only those messages to a batch which generate identical URLs. To achieve this, set the worker-partition-key() option with a template that contains all the templates used in the url() option, otherwise messages will be mixed.
For security reasons, all the templated contents in the url() option are URL-encoded automatically. The following parts of the URL cannot be templated:
scheme
host
port
user
password
user-agent()
Type:
string
Default:
syslog-ng [version]'/libcurl[version]`
Description: The value of the USER-AGENT header in the messages sent to the server.
user()
Type:
string
Default:
Description: The username that AxoSyslog uses to authenticate on the server where it sends the messages.
use-system-cert-store()
Type:
`yes
Default:
no
Description: Use the certificate store of the system for verifying HTTPS certificates. For details, see the curl documentation.
worker-partition-key()
Type:
template
Default:
Description: The worker-partition-key() option specifies a template: messages that expand the template to the same value are mapped to the same partition. When batching is enabled and multiple workers are configured, it’s important to add only those messages to a batch which generate identical URLs. To achieve this, set the worker-partition-key() option with a template that contains all the templates used in the url() option, otherwise messages will be mixed.
For example, you can partition messages based on the destination host:
worker-partition-key("$HOST")
workers()
Type:
integer
Default:
1
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
If you are using load-balancing (that is, you have configured multiple servers in the url() option), increase the number of worker threads at least to the number of servers. For example, if you have set three URLs (url("site1", "site2", "site3")), set the workers() option to 3 or more.
13.3 - The Azure auth header plugin
This section describes the AxoSyslog application’s Azure auth header plugin.
For more information about modules in AxoSyslog, see Using modules.
The Azure auth header plugin
The Azure auth header plugin is a signal-slot mechanism-based AxoSyslog module that generates authorization headers for applications that connect to Microsoft Azure.
Defining the Azure auth header plugin
You can define the Azure auth header plugin by the following:
All these options are mandatory. They are used as input for the method that calculates the authorization header.
13.4 - The Python HTTP header plugin
This section describes the AxoSyslog application’s Python HTTP header plugin.
For more information about modules in AxoSyslog, see Using modules.
The Python HTTP header plugin
The AxoSyslog application supports adding custom headers to HTTP requests using the Python programming language.
Prerequisites
Note
Before you use the python-http-header plugin, make sure that your AxoSyslog appliance was compiled with Python support. If you installed AxoSyslog from a package, make sure that the subpackage containing Python support is also installed.
class: Mandatory option. It refers to the user’s Python class that implements the python-http-header interface. It can be mymodule.MyClass if the class MyClass is put into a mymodule.py module, or simply MyClass if the user’s code is provided inline in the configuration, using the python { ... }; keyword.
Note
If you put the class implementation into its own module, it should be put into a standard location, or made available with the PYTHONPATH environment variable.
options("key" "value"): Optional option. Multiple options can be specified at the same time. The AxoSyslog application will build a Python dictionary, which will be available in the __init__ method.
mark-errors-as-critical(yes|no): Optional option. Its default value is yes. In case there is a Python error, this parameter decides if the HTTP destination will still try to send the request with the failed headers, or disconnect instead.
Defining the python-http-header() interface
You can define the Python interface with the following:
By default, when the signal_http_header_request is emitted by the HTTP module, the connected slot automatically executes the Python code.
Note
If the plugin fails, the HTTP module does not send the HTTP request without the header items by default. If you want the HTTP module to try sending the request without the header items, disable the mark-errors-as-critical function.
Methods used in the configuration:
__init__(self, options): Optional method. The options specified in the AxoSyslog configuration can be stored in the instance using this method.
get_headers(self, body, headers): Mandatory method. Returns a list of strings of form ["header: value", …]. The returned headers will be set for the outgoing HTTP request. The body contains the body of the HTTP request. The headers contain the current headers that the HTTP destination has already added to the request.
on_http_response_received(self, http_code): Optional method. If specified, AxoSyslog inserts the http_code of the previous response. This can be used to handle error (for example, for recreating auth headers, or dropping cache).
Example configuration for using the Python HTTP header plugin
The following example can be copy-pasted and used as a template for using the Python HTTP header plugin in your configuration.
python { from syslogng import Logger
logger= Logger() class TestCounter():
def __init__(self, options):
self.header = options["header"] self.counter = int(options["counter"]) logger.debug(f"TestCounter class instantiated; options={options}") def get_headers(self, body, headers):
logger.debug(f"get_headers() called, received body={body}, headers={headers}")response=["{}: {}".format(self.header, self.counter)] self.counter +=1return response
def on_http_response_received(self, http_code):
self.counter += http_code
logger.debug("HTTP response code received: {}".format(http_code)) def __del__(self):
logger.debug("Deleting TestCounter class instance")};source s_network { network(port(5555));}; destination d_http { http( python_http_header( class("TestCounter") options("header", "X-Test-Python-Counter") options("counter", 11)# this means that syslog-ng will keep trying to send the http request even when this module fails mark-errors-as-critical(no)) url("http://127.0.0.1:8888"));}; log { source(s_network); destination(d_http); flags(flow-control);};
Warning
Although it is possible to configure multiple HTTP workers for AxoSyslog, the AxoSyslog application can only embed a single Python interpreter at the same time. As a result, if you configure more than one HTTP workers on your AxoSyslog application, the Python code will run in concurrent mode. To protect the state of the object, you may need to use locks.
The kafka() driver is actually a reusable configuration snippet configured to receive log messages using the Java language-binding of AxoSyslog. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of the kafka configuration snippet on GitHub. For details on extending AxoSyslog in Java, see the Getting started with syslog-ng development guide.
Note
If you delete all Java destinations from your configuration and reload syslog-ng, the JVM is not used anymore, but it is still running. If you want to stop JVM, stop syslog-ng and then start syslog-ng again.
14.1 - Prerequisites
To publish messages from AxoSyslog to Apache Kafka, complete the following steps.
Steps:
If you want to use the Java-based modules of AxoSyslog (for example, the Elasticsearch, HDFS, or Kafka destinations), you must compile AxoSyslog with Java support.
Download and install the Java Runtime Environment (JRE), 1.7 (or newer). You can use OpenJDK or Oracle JDK, other implementations are not tested.
Set LD_LIBRARY_PATH to include the libjvm.so file, for example:LD_LIBRARY_PATH=/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/amd64/server:$LD_LIBRARY_PATH
Note that many platforms have a simplified links for Java libraries. Use the simplified path if available. If you use a startup script to start AxoSyslog set LD_LIBRARY_PATH in the script as well.
If you are behind an HTTP proxy, create a gradle.properties under the modules/java-modules/ directory. Set the proxy parameters in the file. For details, see The Gradle User Guide.
Extract the Apache Kafka libraries into a single directory. If needed, collect the various .jar files into a single directory (for example, /opt/kafka/lib/) where AxoSyslog can access them. You must specify this directory in the AxoSyslog configuration file.
Check if the following files in the Kafka libraries have the same version number: slf4j-api-<version-number>.jar, slf4j-log4j12-<version-number>.jar. If the version number of these files is different, complete the following steps:
Delete one of the files (for example, slf4j-log4j12-<version-number>.jar).
Download a version that matches the version number of the other file (for example, 1.7.6) from the official SLF4J distribution.
Copy the downloaded file into the directory of your Kafka library files (for example, /opt/kafka/lib/).
14.2 - How AxoSyslog interacts with Apache Kafka
When stopping the AxoSyslog application, AxoSyslog will not stop until all Java threads are finished, including the threads started by the Kafka Producer. There is no way (except for the kill -9 command) to stop AxoSyslog before the Kafka Producer stops. To change this behavior set the properties of the Kafka Producer in its properties file, and reference the file in the properties-file option.
The AxoSyslog kafka destination tries to reconnect to the brokers in a tight loop. This can look as spinning, because of a lot of similar debug messages. To decrease the amount of such messages, set a bigger timeout using the following properties:
The kafka destination of AxoSyslog can directly publish log messages to the Apache Kafka message bus, where subscribers can access them. The kafka destination has the following options.
Required options:
The following options are required: kafka-bootstrap-servers(), topic(). Note that to use kafka, you must add the following lines to the beginning of your AxoSyslog configuration:
@include "scl.conf"
client-lib-dir()
Type:
string
Default:
The AxoSyslog module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/
Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your AxoSyslog configuration (for example, because you have multiple Java-based destinations), AxoSyslog will merge every available paths to a single list.
For the kafka destination, include the path to the directory where you copied the required libraries (see Prerequisites), for example, client-lib-dir("/opt/syslog-ng/lib/syslog-ng/java-modules/KafkaDestination.jar:/usr/share/kafka/lib/\*.jar").
kafka-bootstrap-servers()
Type:
list of hostnames
Default:
Description: Specifies the hostname or IP address of the Kafka server. When specifying an IP address, IPv4 (for example, 192.168.0.1) or IPv6 (for example, [::1]) can be used as well. Use a colon (:) after the address to specify the port number of the server. When specifying multiple addresses, use a comma to separate the addresses, for example, kafka-bootstrap-servers("127.0.0.1:2525,remote-server-hostname:6464")
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.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Specify the Java Virtual Machine (JVM) settings of your Java destination from the AxoSyslog configuration file.
For example:
jvm-options("-Xss1M -XX:+TraceClassLoading")
You can set this option only as a global option, by adding it to the options statement of the syslog-ng.conf configuration file.
on-error()
Type:
One of: drop-message, drop-property, fallback-to-string, silently-drop-message, silently-drop-property, silently-fallback-to-string
Default:
Use the global setting (which defaults to drop-message)
Description: Controls what happens when type-casting fails and 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.
key()
Type:
template
Default:
N/A
Description: The key of the partition under which the message is published. You can use templates to change the topic dynamically based on the source or the content of the message, for example, key("${PROGRAM}").
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
properties-file()
Type:
string (absolute path)
Default:
N/A
Description: The absolute path and filename of the Kafka properties file to load. For example, properties-file("/opt/syslog-ng/etc/kafka_dest.properties"). The AxoSyslog application reads this file and passes the properties to the Kafka Producer. If a property is defined both in the AxoSyslog configuration file (syslog-ng.conf) and in the properties file, then AxoSyslog uses the definition from the AxoSyslog configuration file.
The AxoSyslog kafka destination supports all properties of the official Kafka producer. For details, see the Apache Kafka documentation.
The kafka-bootstrap-servers option is translated to the bootstrap.servers property.
For example, the following properties file defines the acknowledgment method and compression:
acks=all
compression.type=snappy
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
sync-send()
Type:
`true
Default:
false
Description: When sync-send is set to true, AxoSyslog sends the message reliably: it sends a message to the Kafka server, then waits for a reply. In case of failure, AxoSyslog repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, AxoSyslog drops the message.
This method ensures reliable message transfer, but is very slow.
When sync-send() is set to false, AxoSyslog sends messages asynchronously, and receives the response asynchronously. In case of a problem, AxoSyslog cannot resend the messages.
This method is fast, but the transfer is not reliable. Several thousands of messages can be lost before AxoSyslog recognizes the error.
template()
Type:
template or template function
Default:
$ISODATE $HOST $MSGHDR$MSG\\n
Description: The message as published to Apache Kafka. You can use templates and template functions (for example, format-json()) to format the message, for example, template("$(format-json --scope rfc5424 --exclude DATE --key ISODATE)").
For details on formatting messages in JSON format, see format-json.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
topic()
Type:
template
Default:
N/A
Description: The Kafka topic under which the message is published. You can use templates to change the topic dynamically based on the source or the content of the message, for example, topic("${HOST}").
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.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
15 - kafka-c(): Publish messages to Apache Kafka (C implementation)
Starting with version 3.21, AxoSyslog can directly publish log messages to the Apache Kafka message bus, where subscribers can access them.
As of AxoSyslog version 3.21, the new C implementation of the kafka destination is available. The new implementation uses the librdkafka client and has several advantages, such as scalability, more efficient memory usage and simpler setup. The options of this implementation are compatible with those of the old Java implementation.
15.1 - Shifting from Java implementation to C implementation
If you were using the Java implementation of the kafka destination and want to shift to its C implementation, the following changes to the configuration file and considerations are necessary.
Unlike the old one, the new topic() option can not handle templates. It must be a string.
The template() option has been renamed message().
The kafka-bootstrap-servers() option has been renamed bootstrap-servers().
The properties-file() is a Java properties file with options that are similar to, but not identical with, the options in the old, Java implementation’s properties-file(). For more information, click here.
The sync-send() option has been deprecated. Remove it from the configuration file.
The client_lib_dir() option has been deprecated. Remove it from the configuration file.
The old implementation’s option() option has been removed and replaced by the config() option, which has a different syntax.
This section describes the prerequisites and restrictions for using the kafka destination in the new C implementation, and important information about the declaration of the destination.
Prerequisites and restrictions
Since the new C implementation uses the librdkafka client library, the kafka destination has less memory usage than the previous Java implementation (which uses the official Java Kafka producer).
A AxoSyslog destination recognizes a message as sent when the message has been sent to the Kafka client, not when the Kafka server confirms its delivery.
If the Kafka client collects too many unsent messages, it will not accept any more messages from AxoSyslog. The AxoSyslog application detects this and stops sending messages to the Kafka client. Also, AxoSyslog’s flow control starts functioning in the direction of the sources (for example, AxoSyslog will not read from the sources in that specific logpath).
You can specify a “high water mark” limit for the Kafka client in the properties-file().
For more information about how the C implementation of the kafka() destination works with AxoSyslog, click here.
15.4 - Options of the kafka() destination's C implementation
The C implementation of the kafka() destination of AxoSyslog can directly publish log messages to the Apache Kafka message bus, where subscribers can access them. The C implementation of the kafka() destination has the following options.
Required options:
The following options are required: bootstrap-servers(), topic(). Note that to use the C implementation of the kafka() destination, you must add the following lines to the beginning of your AxoSyslog configuration:
@define kafka-implementation kafka-c
Note
At least one of the config() and the properties_file() options is mandatory. While you can specify everything in the config() option if you want, the properties-file() is optional. If you have an option in both the config() and the properties-file() specified, the option specified later in the AxoSyslog configuration file will prevail.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
Note
The AxoSyslog configuration accepts batch-lines() with sync-send() set to both "yes" or "no", but the option will only take effect if you set sync-send() to "yes".
Note
If you set sync-send() to "yes", the number you specify for batch-lines() affects how many messages AxoSyslog packs into once transaction.
Note
When setting batch-timeout(), consider the value of the transaction.timeout.ms Kafka property. If in case of timeout (that is, if AxoSyslog does not receive batch-lines() amount of messages) the value of batch-timeout() exceeds the value of transaction.timeout.ms, AxoSyslog will not send out messages in time.
For more information about the default values of the transaction.timeout.ms Kafka property, see the librdkafka documentation.
bootstrap-servers()
Type:
string
Default:
Description: Specifies the hostname or IP address of the Kafka server. When specifying an IP address, IPv4 (for example, 192.168.0.1) or IPv6 (for example, [::1]) can be used as well. Use a colon (:) after the address to specify the port number of the server. When specifying multiple addresses, use a comma to separate the addresses, for example, bootstrap-servers("127.0.0.1:2525,remote-server-hostname:6464")
client-lib-dir()
Type:
string
Default:
The AxoSyslog module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/
Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your AxoSyslog configuration (for example, because you have multiple Java-based destinations), AxoSyslog will merge every available paths to a single list.
For the kafka destination, include the path to the directory where you copied the required libraries (see Prerequisites), for example, client-lib-dir("/opt/syslog-ng/lib/syslog-ng/java-modules/KafkaDestination.jar:/usr/share/kafka/lib/\*.jar").
Note
Unlike in the Java implementation, the client-lib-dir() option has no significant role in the C implementation of the kafka() destination. The programming language accepts this option for better compatibility.
config()
Description: You can use this option to expand or override the options of the properties-file().
Note
At least one of the config() and the properties_file() options is mandatory. While you can specify everything in the config() option if you want, the properties-file() is optional. If you have an option in both the config() and the properties-file() specified, the option specified later in the AxoSyslog configuration file will prevail.
The AxoSyslogkafka destination supports all properties of the official Kafka producer. For details, see the librdkafka documentation.
The syntax of the config() option is the following:
config( “key1” => “value1”
“key2” => “value2”
)
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
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.
flush-timeout-on-reload()
Type:
integer in msec
Default:
1000
Description: When AxoSyslog reloads, the Kafka client will also reload. The flush-timeout-on-reload() option specifies the number of milliseconds AxoSyslog waits for the Kafka client to send the unsent messages. The unsent messages will be retained in syslog-ng’s own queue and AxoSyslog will continue sending them after reload. This works without disk-buffering, too.
flush-timeout-on-shutdown()
Type:
integer in msec
Default:
60000
Description: When AxoSyslog shuts down, the Kafka client will also shut down. The flush-timeout-on-shutdown() option specifies the number of milliseconds AxoSyslog waits for the Kafka client to send the unsent messages. Any messages not sent after the specified time will be lost. To avoid losing messages, we recommend you use the disk-buffer option.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The key of the partition under which the message is published. You can use templates to change the topic dynamically based on the source or the content of the message, for example, key("${PROGRAM}").
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
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.
on-error()
Type:
One of: drop-message, drop-property, fallback-to-string, silently-drop-message, silently-drop-property, silently-fallback-to-string
Default:
Use the global setting (which defaults to drop-message)
Description: Controls what happens when type-casting fails and 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.
persist-name()
Type:
string
Default:
N/A
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
poll-timeout()
Type:
integer in msec
Default:
1000
Description: Specifies the frequency your AxoSyslog queries the Kafka client about the amount of messages sent since the last poll-timeout (). In case of multithreading, the first AxoSyslog worker is responsible for poll-timeout().
properties-file()
Type:
string (absolute path)
Default:
N/A
Description: The absolute path and filename of the Kafka properties file to load. For example, properties-file("/opt/syslog-ng/etc/kafka_dest.properties"). The AxoSyslog application reads this file and passes the properties to the Kafka Producer.
The AxoSyslogkafka destination supports all properties of the official Kafka producer. For details, see the librdkafka documentation.
The bootstrap-servers option is translated to the bootstrap.servers property.
For example, the following properties file defines the acknowledgment method and compression:
example
`acks=all
compression.type=snappy`.
Note
At least one of the config() and the properties_file() options is mandatory. While you can specify everything in the config() option if you want, the properties-file() is optional. If you have an option in both the config() and the properties-file() specified, the option specified later in the AxoSyslog configuration file will prevail.
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
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.
sync-send()
Type:
`true
Default:
false
Description: When sync-send is set to true, AxoSyslog sends the message reliably: it sends a message to the Kafka server, then waits for a reply. In case of failure, AxoSyslog repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, AxoSyslog drops the message.
This method ensures reliable message transfer, but is very slow.
When sync-send() is set to false, AxoSyslog sends messages asynchronously, and receives the response asynchronously. In case of a problem, AxoSyslog cannot resend the messages.
This method is fast, but the transfer is not reliable. Several thousands of messages can be lost before AxoSyslog recognizes the error.
Note
If you want to use the sync-send() option set to "yes", Axoflow recommends that you use librdkafka version 1.4.0 or higher, and a Kafka server with version number 0.11.0 or higher.
template()
Type:
template or template function
Default:
$ISODATE $HOST $MSGHDR$MSG\\n
Description: The message as published to Apache Kafka. You can use templates and template functions (for example, format-json()) to format the message, for example, template("$(format-json --scope rfc5424 --exclude DATE --key ISODATE)").
For details on formatting messages in JSON format, see format-json.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-zone()
Type:
name of the timezone, or the timezone offset
Default:
unspecified
Description: Convert timestamps to the timezone specified by this option. If this option is not set, then the original timezone information in the message is used. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see 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.
topic()
Type:
string
Default:
N/A
Description: The Kafka topic under which the message is published.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
workers()
Type:
integer
Default:
1
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
Note
The workers are only responsible for formatting the messages that need to be delivered to the Kafka clients. Configure this option only if your Kafka clients have many threads and they do not receive enough messages.
Note
Kafka clients have their own threadpool, entirely independent from any AxoSyslog settings. The workers() option has no effect on this threadpool.
16 - loggly: Send logs to Loggly
The loggly() destination sends log messages to the Loggly Logging-as-a-Service provider. You can send log messages over TCP, or encrypted with TLS.
Declaration:
loggly(token());
Example: Using the loggly() driver
To use the loggly() destination, the only mandatory parameter is your user token. The following example sends every log from the system() source to your Loggly account.
The following example uses TLS encryption. Before using it, download the CA certificate of Loggly and copy it to your hosts (for example, into the /etc/ssl/certs/ directory.
To use the loggly() driver, the scl.conf file must be included in your AxoSyslog configuration:
@include "scl.conf"
The loggly() driver is actually a reusable configuration snippet configured to send log messages using the tcp() driver using a template. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of this configuration snippet on GitHub.
16.1 - loggly() destination options
The loggly() destination has the following options. You can also set other options of the underlying tcp() driver (for example, port number or TLS-encryption).
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see TLS options.
token()
Type:
string
Default:
Description: Your Customer Token that you received from Loggly.
transport()
Type:
udp, tcp, or tls
Default:
tcp
Description: Specifies the protocol used to send messages to the destination server.
If you use the udp transport, AxoSyslog automatically sends multicast packets if a multicast destination address is specified. The tcp transport does not support multicasting.
17 - logmatic: Send logs to Logmatic.io
The logmatic() destination sends log messages to the Logmatic.io Logging-as-a-Service provider. You can send log messages over TCP, or encrypted with TLS.
Declaration:
logmatic(token());
Example: Using the logmatic() driver
To use the logmatic() destination, the only mandatory parameter is your user token. The following example sends every log from the system() source to your Logmatic.io account.
The following example uses TLS encryption. Before using it, download the CA certificate of Logmatic.io and copy it to your hosts (for example, into the /etc/ssl/certs/ directory.
To use the logmatic() driver, the scl.conf file must be included in your AxoSyslog configuration:
@include "scl.conf"
The logmatic() driver is actually a reusable configuration snippet configured to send log messages using the tcp() driver using a template. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of this configuration snippet on GitHub.
17.1 - logmatic() destination options
The logmatic() destination has the following options. You can also set other options of the underlying tcp() driver (for example, port number or TLS-encryption).
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Your API Key that you received from Logmatic.io.
18 - Send messages to Falcon LogScale
Starting with version 4.3.0, AxoSyslog can send messages to Falcon LogScale using its Ingest Structured Data API. That way you don’t have to parse the data on Falcon LogScale, because AxoSyslog already sends it in a structured format that LogScale understands and can show in a structured manner as separate columns. For a tutorial on using this destination in Kubernetes, see the From syslog-ng to LogScale: structured logs from any source blog post.
Prerequisites
Create an Ingest token for AxoSyslog to use in the token() option of the destination. This token is specific to a LogScale repository.
This driver is actually a reusable configuration snippet configured to send log messages using the http() driver using a template. You can find the source of this configuration snippet on GitHub.
Options
The following options are specific to the logscale() destination. But since this destination is based on the http() destination, you can use the options of the http() destination as well if needed.
attributes()
Type:
string
Default:
"--scope rfc5424 --exclude MESSAGE --exclude DATE --leave-initial-dot"
Description: A JSON object representing key-value pairs for the LogScale Event, formatted as AxoSyslog value-pairs. By default, the logscale() destination sends the RFC5424 fields as attributes. If you want to send different fields, override the default template.
content-type()
Type:
string
Default:
"application/json"
Description: The content-type of the HTTP request.
extra-headers()
Type:
string
Default:
Description: Extra headers for the HTTP request.
rawstring()
Type:
template
Default:
${MESSAGE}
Description: Accepts a template that you can use to format the LogScale event.
Application Layer Transport Security (ALTS) is a simple to use authentication, only available within Google’s infrastructure. It accepts the target-service-account() option, where you can list service accounts to match against when authenticating the server.
tls(peer-verify()) is not available for the opentelemetry() and loki() destination.
The gRPC-based drivers (opentelemetry() and loki()) have a different tls() block implementation from the network() or http() drivers. Most features are the same.
batch-lines()
Type:
number
Default:
0
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
channel-args()
Type:
See description
Default:
-
Description: The channel-args() option is available in gRPC-based drivers. It accepts name-value pairs and sets channel arguments defined in the GRPC Core library documentation. For example:
Description: The maximum number of gRPC pings that can be sent when there is no data/header frame to be sent. AxoSyslog won’t send any pings after this limit. Set it to 0 disable this restriction and keep sending pings.
time()
Type:
number [milliseconds]
Default:
Description: The period (in milliseconds) after which AxoSyslog sends a gRPC keepalive ping.
timeout()
Type:
number [milliseconds]
Default:
10
Description: The time (in milliseconds) AxoSyslog waits for an acknowledgement.
labels()
Type:
Default:
See the description
The labels applied to the message as they are sent to the destination. Use the following format:
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. For details on template functions, see Template functions of AxoSyslog.
tenant-id()
Type:
string
Default:
-
Description: Available in version 4.7 and newer. Sets the tenant ID for multi-tenant scenarios. For example:
Description: Sets the timestamp to use for the messages sent to Loki. This is important because Loki accepts data only if their timestamp is monotonously increasing, out of order messages are rejected. The possible values for this option are:
current: Use the timestamp when AxoSyslog processes the message in the output. This guarantees that the timestamp is monotonously increasing, but in some cases can significantly differ from the time when the message was generated.
msg: Use the original timestamp of the message.
received: Use the timestamp when AxoSyslog has received the message.
url()
Type:
string
Default:
localhost:9095
Description: The URL of the Loki endpoint.
workers()
Type:
integer
Default:
1
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
20 - mongodb(): Store messages in a MongoDB database
The mongodb() driver sends messages to a MongoDB database. MongoDB is a schema-free, document-oriented database. For the list of available optional parameters, see mongodb() destination options.
Declaration
mongodb(parameters);
The mongodb() driver does not support creating indexes, as that can be a very complex operation in MongoDB. If needed, the administrator of the MongoDB database must ensure that indexes are created on the collections.
The mongodb() driver does not add the _id field to the message: the MongoDB server will do that automatically, if none is present. If you want to override this field from AxoSyslog, use the key() parameter of the value-pairs() option.
The AxoSyslog mongodb() driver is compatible with MongoDB server version 1.4 and newer.
Note
Prior to version 4.0, AxoSyslog handled every data as strings, and allowed you to convert the strings into other types of data that only certain destinations data formats supported.
Starting with AxoSyslog 4.0, each name-value pair is a (name, type, value) triplet, and several components of AxoSyslog have typing support. For details, see Components that support data types.
Example: Using the mongodb() driver
The following example creates a mongodb() destination using only default values.
destination d_mongodb { mongodb();};
The following example displays the default values.
The following example shows the same setup using the deprecated libmongo-client syntax (as used in AxoSyslog version 3.7), and is equivalent with the previous example.
When AxoSyslog connects the MongoDB server during startup, it completes the following steps.
The AxoSyslog application connects the first address listed in the servers() option.
If the server is accessible and it is a master MongoDB server, AxoSyslog authenticates on the server (if needed), then starts sending the log messages to the server.
If the server is not accessible, or it is not a master server in a MongoDB replicaset and it does not send the address of the master server, AxoSyslog connects the next address listed in the servers() option.
If the server is not a master server in a MongoDB replicaset, but it sends the address of the master server, AxoSyslog connects the received address.
When AxoSyslog connects the master MongoDB server, it retrieves the list of replicas (from the replSet option of the server), and appends this list to the servers() option.
Warning
This means that AxoSyslog can send log messages to addresses that are not listed in its configuration.
Make sure to include the address of your master server in your AxoSyslog configuration file, otherwise you risk losing log messages if all the addresses listed in the AxoSyslog configuration are offline.
Addresses retrieved from the MongoDB servers are not stored, and can be lost when AxoSyslog is restarted. The retrieved addresses are not lost if the server() option of the destination was not changed in the configuration file since the last restart.
The failover mechanism used in the mongodb() driver is different from the client-side failover used in other drivers.
The AxoSyslog application attempts to connect another server if the servers() list contains at least two addresses, and one of the following events happens:
The safe-mode() option is set to no, and the MongoDB server becomes unreachable.
The safe-mode() option is set to yes, and AxoSyslog cannot insert a log message into the database because of an error.
In this case, AxoSyslog starts to connect the addresses in from the servers() list (starting from the first address) to find the new master server, authenticates on the new server (if needed), then continues to send the log messages to the new master server.
During this failover step, one message can be lost if the safe-mode() option is disabled.
If the original master becomes accessible again, AxoSyslog will automatically connect to the original master.
20.2 - mongodb() destination options
The mongodb() driver sends messages to a MongoDB database. MongoDB is a schema-free, document-oriented database.
The mongodb() destination has the following options:
bulk()
Type:
yes, no
Default:
yes
Available in AxoSyslog version 4.3.0 and newer.
Description: Enables bulk insert mode. If disabled, each messages is inserted individually.
Note: Bulk sending is only efficient if you use a constant collection (without templates), or the used template does not lead to too many collections switching within a reasonable time range.
Description: The name of the MongoDB collection where the log messages are stored (collections are similar to SQL tables). You can use templates to change the collection dynamically based on the source or the content of the message, for example, collection("${HOST}").
Warning
Hazard of data loss! The AxoSyslog application does not verify that the specified collection name does not contain invalid characters. If you specify a collection with an invalid name, the log messages sent to the MongoDB database will be irrevocably lost without any warning.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Available in AxoSyslog version 3.19 and later.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
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.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
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.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
on-error()
Type:
One of: drop-message, drop-property, fallback-to-string, silently-drop-message, silently-drop-property, silently-fallback-to-string
Default:
Use the global setting (which defaults to drop-message)
Description: Controls what happens when type-casting fails and 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.
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
For MongoDB operations, AxoSyslog uses a one-minute timeout: if an operation times out, AxoSyslog assumes the operation has failed.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
Description: The value-pairs() option creates structured name-value pairs from the data and metadata of the log message. For details on using value-pairs(), see Structuring macros, metadata, and other value-pairs.
Note
Empty keys are not logged.
Note
Prior to version 4.0, AxoSyslog handled every data as strings, and allowed you to convert the strings into other types of data that only certain destinations data formats supported.
Starting with AxoSyslog 4.0, each name-value pair is a (name, type, value) triplet, and several components of AxoSyslog have typing support. For details, see Components that support data types.
workers()
Type:
integer
Default:
1
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
The rest of this chapter and its sections build on your familiarity with the MQTT protocol, the concept of client and broker entities, and how these entities function within an MQTT system.
Example: Using the mqtt() destination in your configuration
The following example illustrates a mqtt() destination configured to fetch messages from the localhost:4444 address, and send them to the broker running on localhost:4445, using the mqtt test/test topic.
21.1 - Prerequisites to using the mqtt() destination
Using the current implementation of the mqtt() destination has the following prerequisites:
Installing the eclipse-paho-mqtt-c library.
Note
The default package manager for some Linux operating systems contains the eclipse-paho-mqtt-c library, but depending on your OS, you may have to install the library manually. For more information about how you can download and install the eclipse-paho-mqtt-c library, see Eclipse Paho on the Eclipse Foundation website.
Having a broker entity in a functional MQTT system.
Note
In your configuration, you will specify the broker entity of your MQTT system in the address() option of your mqtt() source.
21.2 - Limitations to using the mqtt() destination
Using the mqtt() destination of AxoSyslog has the following limitations:
You can only use the mqtt() destination with AxoSyslog version 3.33 or higher.
You cannot use the mqtt() destination without installing the the eclipse-paho-mqtt-c library.
For more information about how you can download and install the eclipse-paho-mqtt-c library, see Eclipse Paho on the Eclipse Foundation website.
The current implementation of the mqtt() destination supports versions 3.1 and 3.1.1 of the MQTT protocol.
21.3 - Options of the mqtt() destination
The mqtt() destination has the following options.
Required options: address(), fallback-topic(), and topic().
address()
Type:
string
Default:
tcp://localhost:1883
Required:
yes
Description: Specifies the hostname or IP address, and the port number of the MQTT broker to which AxoSyslog will send the log messages.
Syntax: <protocol type>://<host>:<port>
Supported protocol types: TCP, WS, SSL andWSS.
client-id()
Type:
string
Default:
syslog-ng-source-{topic option}
Required:
no
Description: The client-id() is used to identify the client to the MQTT server, which stores session data for each client. The session data can contains information regarding which message has been sent, received. It is not possible to set the client-id() to an empty string. To always start a new session see the cleansession() option.
cleansession()
Type:
`yes
Default:
no
Description: This option instruments the MQTT broker to clean the session data when connecting. The session data contains information about which message was processed.
fallback-topic()
Type:
string
Default:
N/A
Description: Required option when using templates in the topic() option.
If the resolved topic() template is not a valid topic, AxoSyslog will use the fallback-topic() option to send messages.
Note
If instead of strings, you use actual templates (that is, a macro like ${MESSAGE}, or a template function like $(format-json)) in the topic() option, configuring the fallback-topic() option is required.
Note
Occasionally, the reason why AxoSyslog cannot post messages to the configured topic() is that the topic contains invalid characters that originate from templates.
http-proxy()
Type:
URL
Default:
N/A
Description: Specifies HTTP/HTTPS proxy for WebSocket connections.
keep-alive()
Type:
positive integer number (in seconds)
Default:
60
Description: Specifies the number of seconds that AxoSyslog keeps the connection between the broker and clients open in case there is no message traffic. When keep-alive() number of seconds pass, the connection is terminated, and you have to reconnect.
On the MQTT side, the keep alive function provides a workaround method to access connections that are still open.
password()
Type:
string
Default:
N/A
Description: The password used to authenticate on the MQTT broker.
qos()
Type:
number
Default:
`0`
Possible values:
`0` - at most once (the fastest option)
`1` - at least once (a much slower option than `0`)
`2` - exactly once (the slowest option)
Description: The Quality of Service (QoS) level in MQTT messaging is an agreement between sender and receiver on the guarantee of delivering a message.
template()
Type:
string
Default:
$ISODATE $HOST $MSGHDR$MSG
Description: Specifies the message template that AxoSyslog sends to the MQTT broker.
Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see TLS options.
The following options are relevant for the mqtt()tls() block: ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), ssl-version(), use-system-cert-store().
topic()
Type:
string or template
Default:
N/A
Description: Required option. Specifies the MQTT topic.
Note
The current implementation of the mqtt() destination does not support using the following characters for topic names:
$
+
#
username()
Type:
string
Default:
N/A
Description: The username used to authenticate on the MQTT broker.
21.4 - Possible error messages you may encounter while using the mqtt() destination
While using the mqtt() destination, you may encounter issues and corresponding error messages originating from the MQTT system. The following table contains the error messages you may encounter, the possible reasons behind them, and potential workaround methods.
Complete error message
Possible reason(s)
Possible solution(s)
ERROR, while init threaded dest.
The AxoSyslog application will not start.
You can try the following methods:
Restart AxoSyslog.
Stop some of the programs running on your computer.
Restart your computer, and then restart AxoSyslog.
mqtt: the topic() argument is required for mqtt destinations.
The topic() option is not set in your configuration. The AxoSyslog application will not start.
Set the missing topic() option in your configuration, then restart .
The mqtt destination does not support the batching of messages, ...
Your configuration may contain the batch-timeout() and / or batch-lines() options, which are not supported by the mqtt() destination. The AxoSyslog application will not start.
If your configuration contains the batch-timeout() and / or batch-lines() options, remove them from your configuration, and restart .
Disconnected during publish!
The AxoSyslog application can not send the message, because AxoSyslog disconnected from the broker. By default, AxoSyslog attempts to reconnect to the broker and send the messages 3 times.
If AxoSyslog fails all 3 attempts to reconnect to the broker and send the messages, you can try checking your configuration or restarting your MQTT system with AxoSyslog as a client.
Max message inflight! (publish)
The AxoSyslog application can not send the message due to the max message inflight broker response code (which signals that the broker has received too many messages, and it needs more time to process them). The AxoSyslog application will attempt to resend the message.
Wait until the broker can process the in-flight messages and AxoSyslog can attempt to resend the message.
Failure during publishing!
The AxoSyslog application can not send the message due to the failure broker response code. The AxoSyslog application will attempt to resend the message.
N/A
Error during publish!
The AxoSyslog application can not send the message, and drops it.
Possible reason: bad_utf8_string (topic), NULL parameter`.
That is, the most probable reasons behind this issue are either that the topic name in your configuration is not correct, or that the message field is empty.
You can try the following methods:
Modify the name of the topic() option in your configuration.
Make sure that the message field is not empty.
Disconnected while waiting the response!
The AxoSyslog application has sent the message, but the client disconnected from the broker before AxoSyslog received the response. The AxoSyslog application will attempt to reconnect, or to resend the message.
The AxoSyslog application will attempt to reconnect to the broker and send the in-flight message. If the reconnect attempt fails, AxoSyslog will resend the message.
"Error while waiting the response!"
The AxoSyslog application can not get any response from the broker, due to the failure broker response code. The AxoSyslog will attempt to resend the message.
In this case, you will receive a further error message, depending on what the problem is. Wait for the second error message for more information about how you can proceed.
"Error constructing topic ..."
Due to an issue with the configured topic template, the mqtt() destination will use the fallback-topic() option instead.
N/A
mqtt dest: topic name is illegal, it can't be empty
This error message is related to the "Error constructing topic ..." error message.
In this case, the topic template returns a 0 length string. As a result, the mqtt() destination will use the fallback-topic() option instead.
N/A
Error connecting mqtt client ...
The AxoSyslog application can not connect to broker, and it will attempt to reconnect later.
If the issue persists, you can try the following:
Update your eclipse-paho-mqtt-c library.
Restart AxoSyslog.
Error creat mqtt client ...
The AxoSyslog application encountered an error while creating the MQTT client, and it will attempt to create it later.
Possible reasons:
There is a wrong address() set in your configuration.
The broker is not running.
You can try the following methods:
Check the address() option in your configuration, and modify if necessary.
Check if the specified broker is running by connecting to it manually, and then sending the broker a message.
22 - network: Send messages to a remote log server using the RFC3164 protocol (network() driver)
The network() destination driver can send syslog messages conforming to RFC3164 from the network using the TCP, TLS, and UDP networking protocols.
UDP is a simple datagram oriented protocol, which provides “best effort service” to transfer messages between hosts. It may lose messages, and no attempt is made to retransmit lost messages. The BSD-syslog protocol traditionally uses UDP.
Use UDP only if you have no other choice.
TCP provides connection-oriented service: the client and the server establish a connection, each message is acknowledged, and lost packets are resent. TCP can detect lost connections, and messages are lost, only if the TCP connection breaks. When a TCP connection is broken, messages that the client has sent but were not yet received on the server are lost.
The AxoSyslog application supports TLS (Transport Layer Security, also known as SSL) over TCP. For details, see Encrypting log messages with TLS.
Declaration:
network("<destination-address>"[options]);
The network() destination has a single required parameter that specifies the destination host address where messages should be sent. If name resolution is configured, you can use the hostname of the target server. By default, AxoSyslog sends messages using the TCP protocol to port 514.
Example: Using the network() driver
TCP destination that sends messages to 10.1.2.3, port 1999:
To send messages using the IETF-syslog message format without using the IETF-syslog protocol, enable the syslog-protocol flag. (For details on how to use the IETF-syslog protocol, see syslog() destination options.)
The network() driver sends messages to a remote host (for example, a server or relay) on the local intranet or internet using the RFC3164 syslog protocol (for details about the protocol, see BSD-syslog or legacy-syslog messages). The network() driver supports sending messages using the UDP, TCP or the encrypted TLS networking protocols.
These destinations have the following options:
ca-dir()
Accepted values:
Directory name
Default:
none
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
ca-file()
Accepted values:
File name
Default:
empty
Description: Optional. The name of a file that contains a set of trusted CA certificates in PEM format. The AxoSyslog application uses the CA certificates in this file to validate the certificate of the peer.
Example format in configuration:
ca-file("/etc/pki/tls/certs/ca-bundle.crt")
Note
The ca-file() option can be used together with the ca-dir() option, and it is relevant when peer-verify() is set to other than no or optional-untrusted.
close-on-input()
Type:
yes
Default:
yes
Description: By default, AxoSyslog closes destination sockets if it receives any input from the socket (for example, a reply). If this option is set to no, AxoSyslog just ignores the input, but does not close the socket.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Available only in AxoSyslog version 3.17 and later. For details about how client-side failover works, see Client-side failover.
servers()
Type:
list of IP addresses and fully-qualified domain names
Default:
empty
Description: Specifies a secondary destination server where log messages are sent if the primary server becomes inaccessible. To list several failover servers, separate the address of the servers with comma. By default, AxoSyslog waits for the a server before switching to the next failover server is set in the time-reopen() option.
If failback() is not set, AxoSyslog does not attempt to return to the primary server even if it becomes available. In case the failover server fails, AxoSyslog attempts to connect the next failover server in the list in round-robin fashion.
Warning
The failover servers must be accessible on the same port as the primary server.
failback()
Description: Available only in AxoSyslog version 3.17 and later.
When AxoSyslog starts up, it always connects to the primary server first. In the failover() option there is a possibility to customize the failover modes.
Depending on how you set the failback() option, AxoSyslog behaves as follows:
round-robin mode: If failback() is not set, AxoSyslog does not attempt to return to the primary server even if it becomes available. In case the failover server fails, AxoSyslog attempts to connect the next failover server in the list in round-robin fashion.
In the following example AxoSyslog handles the logservers in round-robin fashion if the primary logserver becomes inaccessible (therefore failback() option is not set).
failback mode: If failback() is set, AxoSyslog attempts to return to the primary server.
After AxoSyslog connects a secondary server during a failover, it sends a probe every tcp-probe-interval() seconds towards the primary server. If the primary logserver responds with a TCP ACK packet, the probe is successful. When the number of successful probes reaches the value set in the successful-probes-required() option, AxoSyslog tries to connect the primary server using the last probe.
Note
AxoSyslog always waits for the result of the last probe before sending the next message. So if one connection attempt takes longer than the configured interval, that is, it waits for connection time out, you may experience longer intervals between actual probes.
In the following example AxoSyslog attempts to return to the primary logserver, as set in the failback() option: it will check if the server is accessible every tcp-probe-interval() seconds, and reconnect to the primary logserver after three successful connection attempts.
Default value for tcp-probe-interval(): 60 seconds
Default value for successful-probes-required(): 3
Example: Configuring failover servers
In the following example AxoSyslog handles the logservers in round-robin fashion if the primary logserver becomes uneccassible (therefore failback() option is not set).
In the following example AxoSyslog attempts to return to the primary logserver, as set in the failback() option: it will check if the server is accessible every tcp-probe-interval() seconds, and reconnect to the primary logserver after three successful connection attempts.
This option is not available for the connection-less UDP protocol, because in this case the client does not detect that the destination becomes inaccessible.
flags()
Type:
no-multi-line, syslog-protocol
Default:
empty set
Description: Flags influence the behavior of the destination driver.
no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.
syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.
flush-lines()
Type:
number
Default:
Use global setting (exception: for http() destination, the default is 1).
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.
For optimal performance when sending messages to an AxoSyslog server, make sure that the value of flush-lines() is smaller than the window size set in the log-iw-size() option in the source of your server.
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.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Determines the internet protocol version of the given driver (network() or syslog()). The possible values are 4 and 6, corresponding to IPv4 and IPv6. The default value is ip-protocol(4).
Note that listening on a port using IPv6 automatically means that you are also listening on that port using IPv4. That is, if you want to have receive messages on an IP-address/port pair using both IPv4 and IPv6, create a source that uses the ip-protocol(6). You cannot have two sources with the same IP-address/port pair, but with different ip-protocol() settings (it causes an Address already in use error).
For example, the following source receives messages on TCP, using the network() driver, on every available interface of the host on both IPv4 and IPv6.
Description: Specifies the Type-of-Service value of outgoing packets.
ip-ttl()
Type:
number
Default:
0
Description: Specifies the Time-To-Live value of outgoing packets.
keep-alive()
Type:
yes or no
Default:
yes
Description: Specifies whether connections to destinations should be closed when syslog-ng is reloaded. Note that this applies to the client (destination) side of the connections, server-side (source) connections are always reopened after receiving a HUP signal unless the keep-alive option is enabled for the source.
localip()
Type:
string
Default:
0.0.0.0
Description: The IP address to bind to before connecting to target.
localport()
Type:
number
Default:
0
Description: The port number to bind to. Messages are sent from this port.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
mark-freq()
Accepted values:
number [seconds]
Default:
1200
Description: An alias for the obsolete mark() option, retained for compatibility with 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).
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:
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.
port() or destport()
Type:
number
Default:
601
Description: The port number to connect to. Note that the default port numbers used by AxoSyslog do not comply with the latest RFC which was published after the release of AxoSyslog 3.0.2, therefore the default port numbers will change in the future releases.
so-broadcast()
Type:
yes or no
Default:
no
Description: This option controls the SO_BROADCAST socket option required to make AxoSyslog send messages to a broadcast address. For details, see the socket(7) manual page.
so-keepalive()
Type:
yes or no
Default:
no
Description: Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. For details, see the socket(7) manual page.
so-rcvbuf()
Type:
number
Default:
0
Description: Specifies the size of the socket receive buffer in bytes. For details, see the socket(7) manual page.
so-sndbuf()
Type:
number
Default:
0
Description: Specifies the size of the socket send buffer in bytes. For details, see the socket(7) manual page.
spoof-source()
Type:
yes or no
Default:
no
Description: Enables source address spoofing. This means that the host running AxoSyslog generates UDP packets with the source IP address matching the original sender of the message. It is useful when you want to perform some kind of preprocessing using AxoSyslog then forward messages to your central log management solution with the source address of the original sender. This option only works for UDP destinations though the original message can be received by TCP as well. This option is only available if syslog-ng was compiled using the --enable-spoof-source configuration option.
The maximum size of spoofed datagrams in udp() destinations is set to 1024 bytes by default. To change the maximum size, use the spoof-source-max-msglen() option.
Note
Anything above the size of the maximum transmission unit (MTU), which is 1500 bytes by default, is not recommended because of fragmentation.
The maximum datagram in IP protocols (both IPv4 and IPv6) is 65535 bytes including the IP and UDP headers. The minimum size of the IPv4 header is 20 bytes, the IPv6 is 40 bytes, and the UDP is 8 bytes.
Warning
To use spoofing on Microsoft Windows platforms, you must also set the spoof-interface() option as well.
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.
tcp-keepalive-intvl()
Type:
number [seconds]
Default:
0
Description: Specifies the interval (number of seconds) between subsequential keepalive probes, regardless of the traffic exchanged in the connection. This option is equivalent to /proc/sys/net/ipv4/tcp_keepalive_intvl. The default value is 0, which means using the kernel default.
Warning
The tcp-keepalive-time(), tcp-keepalive-probes(), and tcp-keepalive-intvl() options only work on platforms which support the TCP_KEEPCNT, TCP_KEEPIDLE,and TCP_KEEPINTVL setsockopts. Currently, this is Linux.
A connection that has no traffic is closed after tcp-keepalive-time() + tcp-keepalive-intvl() \* tcp-keepalive-probes() seconds.
Available in AxoSyslog version 3.4 and later.
tcp-keepalive-probes()
Type:
number
Default:
0
Description: Specifies the number of unacknowledged probes to send before considering the connection dead. This option is equivalent to /proc/sys/net/ipv4/tcp_keepalive_probes. The default value is 0, which means using the kernel default.
Warning
The tcp-keepalive-time(), tcp-keepalive-probes(), and tcp-keepalive-intvl() options only work on platforms which support the TCP_KEEPCNT, TCP_KEEPIDLE,and TCP_KEEPINTVL setsockopts. Currently, this is Linux.
A connection that has no traffic is closed after tcp-keepalive-time() + tcp-keepalive-intvl() \* tcp-keepalive-probes() seconds.
Available in AxoSyslog version 3.4 and later.
tcp-keepalive-time()
Type:
number [seconds]
Default:
0
Description: Specifies the interval (in seconds) between the last data packet sent and the first keepalive probe. This option is equivalent to /proc/sys/net/ipv4/tcp_keepalive_time. The default value is 0, which means using the kernel default.
Warning
<p>The <code>tcp-keepalive-time()</code>, <code>tcp-keepalive-probes()</code>, and <code>tcp-keepalive-intvl()</code> options only work on platforms which support the <code>TCP_KEEPCNT</code>, <code>TCP_KEEPIDLE</code>,and <code>TCP_KEEPINTVL</code> setsockopts. Currently, this is Linux.</p>
A connection that has no traffic is closed after tcp-keepalive-time() + tcp-keepalive-intvl() \* tcp-keepalive-probes() seconds.
Available in AxoSyslog version 3.4 and later.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
Note
If a message uses the IETF-syslog format (RFC5424), only the text of the message can be customized (that is, the $MESSAGE part of the log), the structure of the header is fixed.
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.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-zone()
Type:
name of the timezone, or the timezone offset
Default:
unspecified
Description: Convert timestamps to the timezone specified by this option. If this option is not set, then the original timezone information in the message is used. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see 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.
tls()
Type:
tls options
Default:
n/a
Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see TLS options.
transport()
Type:
udp, tcp, or tls
Default:
tcp
Description: Specifies the protocol used to send messages to the destination server.
If you use the udp transport, AxoSyslog automatically sends multicast packets if a multicast destination address is specified. The tcp transport does not support multicasting.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
23 - Send messages to OpenObserve
Starting with version 4.5.0, AxoSyslog can send messages to OpenObserve using its Logs Ingestion - JSON API. This API accepts multiple records in batch in JSON format.
To configure AxoSyslog, you’ll need the username, password, the name of your organization, and the name of the OpenObserve stream where you want to send your data.
This driver is actually a reusable configuration snippet configured to send log messages using the http() driver using a template. You can find the source of this configuration snippet on GitHub.
Options
The following options are specific to the openobserve-log() destination. But since this destination is based on the http() destination, you can use the options of the http() destination as well if needed.
Note: The openobserve-log() destination automatically configures some of these http() destination options as required by the OpenObserve Ingest API.
Description: The password for the username specified in the user() option.
port()
Type:
integer
Default:
5080
Description: The port number of the server.
record()
Type:
string
Default:
"--scope rfc5424 --exclude DATE --key ISODATE @timestamp=${ISODATE}"
Description: A JSON object representing key-value pairs sent to OpenObserve, formatted as AxoSyslog value-pairs. By default, the openobserve-log() destination sends the RFC5424 fields as attributes. If you want to send different fields, override the default content of the record() field.
stream()
Type:
string
Default:
"default"
Description: The OpenObserve stream where AxoSyslog sends the data, for example, your-example-stream.
user()
Type:
string
Default:
-
Description: The username of the account, for example, [email protected].
url()
Type:
string
Default:
-
Description: The base URL of the OpenObserve Ingest API. The actual URL is constructed from the base URL and some other options of the destination: url():port()/api/organization()/stream()/_json
24 - opensearch: Send messages to OpenSearch
Available in AxoSyslog version 4.4 and later.
The opensearch() destination can directly post log messages to OpenSearch using its HTTP endpoint.
HTTPS connection, as well as password- and certificate-based authentication is supported. The content of the events is sent in JSON format.
This driver is actually a reusable configuration snippet configured to send log messages using the http() driver using a template. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of this configuration snippet on GitHub.
24.1 - Batch mode and load balancing
The opensearch() destination automatically sends multiple log messages in a single HTTP request, increasing the rate of messages that your Elasticsearch deployment can consume. For details on adjusting and fine-tuning the batch mode, see the following section.
Batch size
The batch-bytes(), batch-lines(), and batch-timeout() options of the destination determine how many log messages AxoSyslog sends in a batch. The batch-lines() option determines the maximum number of messages AxoSyslog puts in a batch in. This can be limited based on size and time:
AxoSyslog sends a batch every batch-timeout() milliseconds, even if the number of messages in the batch is less than batch-lines(). That way the destination receives every message in a timely manner even if suddenly there are no more messages.
AxoSyslog sends the batch if the total size of the messages in the batch reaches batch-bytes() bytes.
To increase the performance of the destination, increase the number of worker threads for the destination using the workers() option, or adjust the batch-bytes(), batch-lines(), batch-timeout() options.
Example: HTTP batch mode
In the following example, a batch consists of 100 messages, or a maximum of 512 kilobytes, and is sent every 20 seconds (20000 milliseconds).
Starting with version 3.19, you can specify multiple URLs, for example, url("site1" "site2"). In this case, AxoSyslog sends log messages to the specified URLs in a load-balance fashion. This means that AxoSyslog sends each message to only one URL. For example, you can use this to send the messages to a set of ingestion nodes or indexers of your SIEM solution if a single node cannot handle the load. Note that the order of the messages as they arrive on the servers can differ from the order AxoSyslog has received them, so use load-balancing only if your server can use the timestamp from the messages. If the server uses the timestamp when it receives the messages, the order of the messages will be incorrect.
Warning
If you set multiple URLs in the url() option, set the persist-name() option as well to avoid data loss.
Starting with version AxoSyslog version 3.22, you can use any of the following formats to specify multiple URLs:
url("server1", "server2", "server3");# comma-separated strings url("server1""server2""server3");# space-separated strings url("server1 server2 server3");# space-separated within a single string
Example: HTTP load balancing
The following destination sends log messages to 3 different indexer nodes. Each node is assigned a separate worker thread. A batch consists of 100 messages, or a maximum of 512 kilobytes, and is sent every 20 seconds (20000 milliseconds).
If you are using load-balancing (that is, you have configured multiple servers in the url() option), increase the number of worker threads at least to the number of servers. For example, if you have set three URLs (url("site1", "site2", "site3")), set the workers() option to 3 or more.
24.2 - opensearch() destination options
The opensearch destination of AxoSyslog can directly post log messages to an OpenSearch deployment using the OpenSearch Bulk API over the HTTP and Secure HTTP (HTTPS) protocols. The opensearch destination has the following options. The required options are: index() and url().
This destination is available in AxoSyslog version 4.4 and later.
batch-bytes()
Accepted values:
number [bytes]
Default:
none
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Name of a file that contains an X.509 CA certificate (or a certificate chain) in PEM format. The AxoSyslog application uses this certificate to validate the certificate of the HTTPS server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Name of a file, that contains an X.509 certificate (or a certificate chain) in PEM format, suitable as a TLS certificate, matching the private key set in the key-file() option. The AxoSyslog application uses this certificate to authenticate the AxoSyslog client on the destination server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Depends on the OpenSSL version that AxoSyslog uses
Description: Specifies the cipher, hash, and key-exchange algorithms used for the encryption, for example, ECDHE-ECDSA-AES256-SHA384. The list of available algorithms depends on the version of OpenSSL used to compile AxoSyslog. To specify multiple ciphers, separate the cipher names with a colon, and enclose the list between double-quotes, for example:
For a list of available algorithms, execute the openssl ciphers -v command. The first column of the output contains the name of the algorithms to use in the cipher-suite() option, the second column specifies which encryption protocol uses the algorithm (for example, TLSv1.2). That way, the cipher-suite() also determines the encryption protocol used in the connection: to disable SSLv3, use an algorithm that is available only in TLSv1.2, and that both the client and the server supports. You can also specify the encryption protocols using ssl-options().
You can also use the following command to automatically list only ciphers permitted in a specific encryption protocol, for example, TLSv1.2:
echo"cipher-suite(\"$(openssl ciphers -v | grep TLSv1.2 | awk '{print $1}'| xargs echo -n | sed 's/ /:/g'| sed -e 's/:$//')\")"
Note that starting with version 3.10, when AxoSyslog receives TLS-encrypted connections, the order of ciphers set on the AxoSyslog server takes precedence over the client settings.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Sets the specified value as the ID of the OpenSearch index (_id).
delimiter()
Accepted values:
string
Default:
newline character
Description: By default, AxoSyslog separates the log messages of the batch with a newline character. You can specify a different delimiter by using the delimiter() option.
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The name of the OpenSearch index where OpenSearch will store the messages received from AxoSyslog. This option is mandatory for this destination.
You can use macros and template functions, but you must ensure that the resolved template contains only characters that OpenSearch permits in the name of the index. The AxoSyslog application does not validate the name of the index. For details on the characters permitted in the name of OpenSearch indices, see the documentation of OpenSearch.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
key-file()
Accepted values:
Filename
Default:
none
Description: The name of a file that contains an unencrypted private key in PEM format, suitable as a TLS key. If properly configured, the AxoSyslog application uses this private key and the matching certificate (set in the cert-file() option) to authenticate the AxoSyslog client on the destination server.
This destination supports only unencrypted key files (that is, the private key cannot be password-protected).
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: The password that AxoSyslog uses to authenticate on the server where it sends the messages.
peer-verify()
Accepted values:
`yes
Default:
yes
Description: Verification method of the peer. The following table summarizes the possible options and their results depending on the certificate of the peer.
The remote peer has:
no certificate
invalid certificate
valid certificate
Local peer-verify() setting
no (optional-untrusted)
TLS-encryption
TLS-encryption
TLS-encryption
yes (required-trusted)
rejected connection
rejected connection
TLS-encryption
For untrusted certificates only the existence of the certificate is checked, but it does not have to be valid — AxoSyslog accepts the certificate even if it is expired, signed by an unknown CA, or its CN and the name of the machine mismatches.
Warning
When validating a certificate, the entire certificate chain must be valid, including the CA certificate. If any certificate of the chain is invalid, AxoSyslog will reject the connection.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
proxy()
Type:
The proxy server address, in `proxy("PROXY_IP:PORT")` format.
For example, `proxy("http://myproxy:3128")`
Default:
None
Description:
You can use the proxy() option to configure the HTTP driver in all HTTP-based destinations to use a specific HTTP proxy that is independent from the proxy configured for the system.
Alternatively, you can leave the HTTP as-is, in which case the driver leaves the default http_proxy and https_proxy environment variables unmodified.
Note
Configuring the proxy() option overwrites the default http_proxy and https_proxy environment variables.
Example: the proxy() option in configuration
The following example illustrates including the proxy() option in your configuration.
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
To handle HTTP error responses, if the HTTP server returns 5xx codes, AxoSyslog will attempt to resend messages until the number of attempts reaches retries. If the HTTP server returns 4xx codes, AxoSyslog will drop the messages.
ssl-version()
Type:
string
Default:
None, uses the libcurl default
Description: Specifies the permitted SSL/TLS version. Possible values: sslv2, sslv3, tlsv1, tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
timeout()
Type:
number [seconds]
Default:
10
Description: The value (in seconds) to wait for an operation to complete, and attempt to reconnect the server if exceeded.
url()
Type:
URL or list of URLs, for example, url(“site1” “site2”)
Default:
N/A
Description: Specifies the hostname or IP address and optionally the port number of the OpenSearch indexer. Use a colon (:) after the address to specify the port number of the server. For example: http://your-opensearch-indexer.server:8088/_bulk
This option is mandatory for this destination.
Make sure that the URL ends with _bulk, this is the OpenSearch API endpoint that properly parses the messages sent by AxoSyslog.
In case the server on the specified URL returns a redirect request, AxoSyslog automatically follows maximum 3 redirects. Only HTTP and HTTPS based redirections are supported.
Starting with version 3.19, you can specify multiple URLs, for example, url("site1" "site2"). In this case, AxoSyslog sends log messages to the specified URLs in a load-balance fashion. This means that AxoSyslog sends each message to only one URL. For example, you can use this to send the messages to a set of ingestion nodes or indexers of your SIEM solution if a single node cannot handle the load. Note that the order of the messages as they arrive on the servers can differ from the order AxoSyslog has received them, so use load-balancing only if your server can use the timestamp from the messages. If the server uses the timestamp when it receives the messages, the order of the messages will be incorrect.
Warning
If you set multiple URLs in the url() option, set the persist-name() option as well to avoid data loss.
Starting with version AxoSyslog version 3.22, you can use any of the following formats to specify multiple URLs:
url("server1", "server2", "server3");# comma-separated strings url("server1""server2""server3");# space-separated strings url("server1 server2 server3");# space-separated within a single string
user()
Type:
string
Default:
Description: The username that AxoSyslog uses to authenticate on the server where it sends the messages.
use-system-cert-store()
Type:
`yes
Default:
no
Description: Use the certificate store of the system for verifying HTTPS certificates. For details, see the curl documentation.
workers()
Type:
integer
Default:
4
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
If you are using load-balancing (that is, you have configured multiple servers in the url() option), increase the number of worker threads at least to the number of servers. For example, if you have set three URLs (url("site1", "site2", "site3")), set the workers() option to 3 or more.
25 - osquery: Send log messages to osquery's syslog table
The osquery() driver sends log messages to osquery’s syslog table.
The syslog table contains logs forwarded over a named pipe from syslog-ng. When an osquery process that supports the syslog table starts up, it creates (and properly sets permissions for) a named pipe for AxoSyslog to write to.
The osquery() destination has the following options:
file()
Type:
string
Default:
N/A
Description: Specifies a path to the file where log messages are stored, for example, for debug purposes.
Specifying this option is optional. However, when you start losing logs for some reason, then it is recommended to write outgoing log messages to a specified file, in the same format that messages are written to the pipe. You can also use a template() function called t_osquery, which re-formats messages so they comply with the text-based protocol that osquery accepts.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Specifies a custom path to the named pipe that acts as the interface between osquery and syslog-ng. (The default path is set in the SCL file.)
Specifying this option is optional.
26 - Send logs, metrics, and traces to OpenTelemetry
Application Layer Transport Security (ALTS) is a simple to use authentication, only available within Google’s infrastructure. It accepts the target-service-account() option, where you can list service accounts to match against when authenticating the server.
tls(peer-verify()) is not available for the opentelemetry() and loki() destination.
The gRPC-based drivers (opentelemetry() and loki()) have a different tls() block implementation from the network() or http() drivers. Most features are the same.
batch-bytes()
Accepted values:
number [bytes]
Default:
4MB
Available in AxoSyslog version 4.6 and later.
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option. The batch might be at most 1 message larger than the set limit.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
OTLP has a default 4 MiB batch limit, therefore the default value for batch-bytes() is 4 MB, which is a bit below 4 MiB.
The batch size is calculated before compression, which is the same as the limit is calculated on the server.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
channel-args()
Type:
See description
Default:
-
Description: The channel-args() option is available in gRPC-based drivers. It accepts name-value pairs and sets channel arguments defined in the GRPC Core library documentation. For example:
Description: Enables compression in gRPC requests. Although gRPC supports various compression methods, currently only deflate is supported (which is basically the same as gzip).
workers()
Type:
integer
Default:
1
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
27 - pipe: Send messages to named pipes
The pipe() driver sends messages to a named pipe like /dev/xconsole.
The pipe driver has a single required parameter, specifying the filename of the pipe to open. The filename can include macros. For the list of available optional parameters, see pipe() destination options.
Declaration:
pipe(filename);
Warning
Starting with AxoSyslog 3.0.2, pipes are created automatically. In earlier versions, you had to create the pipe using the mkfifo(1) command.
Example: Using the pipe() driver
destination d_pipe { pipe("/dev/xconsole");};
27.1 - pipe() destination options
This driver sends messages to a named pipe like /dev/xconsole.
The pipe() destination has the following options:
create-dirs()
Type:
yes or no
Default:
no
Description: Enable creating non-existing directories when creating files or socket files.
flags()
Type:
no-multi-line, syslog-protocol
Default:
empty set
Description: Flags influence the behavior of the destination driver.
no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.
syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.
flush-lines()
Type:
number
Default:
Use global setting (exception: for http() destination, the default is 1).
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.
For optimal performance when sending messages to an AxoSyslog server, make sure that the value of flush-lines() is smaller than the window size set in the log-iw-size() option in the source of your server.
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()
Type:
string
Default:
Use the global settings
Description: Set the group of the created file to the one specified. To preserve the original properties of an existing file, use the option without specifying an attribute: group().
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The number of messages that the output queue can store.
mark-freq()
Accepted values:
number [seconds]
Default:
1200
Description: An alias for the obsolete mark() option, retained for compatibility with 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).
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:
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.
owner()
Type:
string
Default:
Use the global settings
Description: Set the owner of the created file to the one specified. To preserve the original properties of an existing file, use the option without specifying an attribute: owner().
pad-size()
Type:
number
Default:
0
Description: If set, AxoSyslog will pad output messages to the specified size (in bytes). Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes).
Warning
Hazard of data loss! If the size of the incoming message is larger than the previously set pad-size() value, AxoSyslog will truncate the message to the specified size. Therefore, all message content above that size will be lost.
perm()
Type:
number (octal notation)
Default:
0600
Description: The permission mask of the pipe. For octal numbers prefix the number with ‘0’, for example: use 0755 for rwxr-xr-x.
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.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
template-escape()
Type:
yes or no
Default:
no
Description: Turns on escaping for the ', ", and backspace characters in templated output files. This is useful for generating SQL statements and quoting string contents so that parts of the log message are not interpreted as commands to the SQL server.
Note: Starting with AxoSyslog version 4.5, template-escape(yes) escapes the top-level template function in case of nested template functions.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-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.
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);};
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",
);};
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-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.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
28 - program: Send messages to external applications
The program() driver starts an external application or script and sends the log messages to its standard input (stdin). Usually, every message is a single line (ending with a newline character), which your script can process. Make sure that your script runs in a loop and keeps reading the standard input — it should not exit. (If your script exits, AxoSyslog tries to restart it.)
The program() driver has a single required parameter, specifying a program name to start. The program is executed with the help of the current shell, so the command may include both file patterns and I/O redirections. For the list of available optional parameters, see program() destination options.
Declaration:
program(command_to_run);
When using the program() driver, consider the following:
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor, you might have to modify your AppArmor configuration to enable AxoSyslog to execute external applications.
The AxoSyslog application executes program destinations through the standard system shell. If the system shell is not bash and you experience problems with the program destination, try changing the /bin/sh link to /bin/bash.
If the external program exits, the AxoSyslog application automatically restarts it. However it is not recommended to launch programs for single messages, because if the message rate is high, launching several instances of an application might overload the system, resulting in Denial of Service.
When the AxoSyslog application stops, it will automatically stop the external program. To avoid restarting the application when AxoSyslog is only reloaded, enable the keep-alive() option in the program destination.
Certain external applications buffer the log messages, which might cause unexpected latency and other problems. For example, if you send the log messages to an external Perl script, Perl uses a line buffer for terminal output and block buffer otherwise. You might want to disable buffering in the external application.
Example: Using the program() destination driver
The message format does not include the priority and facility values by default. To add these values, specify a template for the program destination, as shown in the following example. Make sure to end your template with a newline character (\n).
The following shell script writes the incoming messages into the /tmp/testlog file.
#!/bin/bashwhileread line ;doecho$line >> /tmp/testlog
done
28.1 - program() destination options
This driver starts an external application or script and sends the log messages to its standard input (stdin).
The program() destination has the following options:
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Flags influence the behavior of the destination driver.
no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.
syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.
flush-lines()
Type:
number
Default:
Use global setting (exception: for http() destination, the default is 1).
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.
For optimal performance when sending messages to an AxoSyslog server, make sure that the value of flush-lines() is smaller than the window size set in the log-iw-size() option in the source of your server.
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.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The number of messages that the output queue can store.
inherit-environment()
Type:
yes
Default:
yes
Description: By default, when program() starts an external application or script, it inherits the entire environment of the parent process (that is, AxoSyslog). Use inherit-environment(no) to prevent this.
keep-alive()
Type:
yes or no
Default:
no
Description: Specifies whether the external program should be closed when AxoSyslog is reloaded.
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).
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:
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.
Note that in earlier versions of AxoSyslog, the default for the mark-mode of the program destination was none. Now it defaults to the global setting, so the program destination will emit a MARK message every mark-freq interval. To avoid such messages, set the mark-mode() option of the destination to none.
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.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
Make sure to end your template with a newline character (\n).
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.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
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.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
29 - pseudofile()
The pseudofile() destination driver is a very simple driver, aimed at delivering messages to special files such as files in the /proc, /dev or /sys directories. It opens and closes the file after each write operation, instead of keeping it open. It does not append further data. It does not support templates in the filename, and does not have a queue, processing is performed immediately as read by the source. Therefore, no loss is possible, but it takes CPU time from the source, so it is not adequate in high-traffic situations.
Declaration:
pseudofile(filename options());
29.1 - pseudofile() destination options
The pseudofile() destination has the following options:
file()
Type:
filename with path
Default:
Description: The file to write messages to, including the path.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
30 - python: Write custom Python destinations
The Python destination allows you to write your own destination in Python. You can import external Python modules to process the messages, and send them to other services or servers. Since many services have a Python library, the Python destination makes integrating AxoSyslog very easy and quick.
The following points apply to using Python blocks in AxoSyslog in general:
Python parsers and template functions are available in AxoSyslog version 3.10 and later.
Python destinations and sources are available in AxoSyslog version 3.18 and later.
Supported Python versions: 2.7 and 3.4+ (if you are using pre-built binaries, check the dependencies of the package to find out which Python version it was compiled with).
The Python block must be a top-level block in the AxoSyslog configuration file.
If you store the Python code in a separate Python file and only include it in the AxoSyslog configuration file, make sure that the PYTHONPATH environment variable includes the path to the Python file, and export the PYTHON_PATH environment variable. For example, if you start AxoSyslog manually from a terminal and you store your Python files in the /opt/syslog-ng/etc directory, use the following command: export PYTHONPATH=/opt/syslog-ng/etc.
In production, when AxoSyslog starts on boot, you must configure your startup script to include the Python path. The exact method depends on your operating system. For recent Red Hat Enterprise Linux, Fedora, and CentOS distributions that use systemd, the systemctl command sources the /etc/sysconfig/syslog-ng file before starting AxoSyslog. (On openSUSE and SLES, /etc/sysconfig/syslog file.) Append the following line to the end of this file: PYTHONPATH="<path-to-your-python-file>", for example, PYTHONPATH="/opt/syslog-ng/etc".
The Python object is initiated every time when AxoSyslog is started or reloaded.
Warning
If you reload AxoSyslog, existing Python objects are destroyed, therefore the context and state information of Python blocks is lost. Log rotation and updating the configuration of AxoSyslog typically involves a reload.
The Python block can contain multiple Python functions.
Using Python code in AxoSyslog can significantly decrease the performance of AxoSyslog, especially if the Python code is slow. In general, the features of AxoSyslog are implemented in C, and are faster than implementations of the same or similar features in Python.
Validate and lint the Python code before using it. The AxoSyslog application does not do any of this.
Python error messages are available in the internal() source of AxoSyslog.
You can access the name-value pairs of AxoSyslog directly through a message object or a dictionary.
To help debugging and troubleshooting your Python code, you can send log messages to the internal() source of AxoSyslog. For details, see Logging from your Python code.
Note
Starting with 3.26, AxoSyslog assigns a persist name to Python sources and destinations. The persist name is generated from the class name. If you want to use the same Python class multiple times in your AxoSyslog configuration, add a unique persist-name() to each source or destination, otherwise AxoSyslog will not start. For example:
Alternatively, you can include the following line in the Python package: @staticmethod generate_persist_name. For example:
from syslogng import LogSource
class PyNetworSource(LogSource):
@staticmethod
def generate_persist_name(options):
return options["port"] def run(self):
pass
def request_exit(self):
pass
Declaration:
Python destinations consist of two parts. The first is a AxoSyslog destination object that you define in your AxoSyslog configuration and use in the log path. This object references a Python class, which is the second part of the Python destination. The Python class processes the log messages it receives, and can do virtually anything that you can code in Python. You can either embed the Python class into your AxoSyslog configuration file, or store it in an external Python file.
destination <name_of_the_python_destination>{ python( class("<name_of_the_python_class_executed_by_the_destination>"));}; python { class <name_of_the_python_class_executed_by_the_destination>(object):
def open(self):
"""Open a connection to the target service
Should return False if opening fails"""return True
def close(self):
"""Close the connection to the target service""" pass
def is_opened(self):
"""Check if the connection to the target is able to receive messages"""return True
def init(self, options):
"""This method is called at initialization time
Should return false if initialization fails"""return True
def deinit(self):
"""This method is called at deinitialization time""" pass
def send(self, msg):
"""Send a message to the target service
It should return True to indicate success. False will suspend the
destination for a period specified by the time-reopen() option."""return True
def flush(self):
"""Flush the queued messages""" pass
};
The AxoSyslog application initializes Python objects every time when it is started or reloaded. The init method is executed as part of the initialization. You can perform any initialization steps that are necessary for your source to work.
Warning
If you reload AxoSyslog, existing Python objects are destroyed, therefore the context and state information of Python blocks is lost. Log rotation and updating the configuration of AxoSyslog typically involves a reload.
When this method returns with False, AxoSyslog does not start. It can be used to check options and return False when they prevent the successful start of the source.
options: This optional argument contains the contents of the options() parameter of the AxoSyslog configuration object as a Python dictionary.
The open(self) method opens the resources required for the destination, for example, it initiates a connection to the target service. It is called after init() when AxoSyslog is started or reloaded. If send() returns with an error, AxoSyslog calls close() and open() before trying to send again.
If open() fails, it should return the False value. In this case, AxoSyslog retries it every time-reopen() seconds. By default, this is 1 second for Python sources and destinations, the value of time-reopen() is not inherited from the global option. For details, see Error handling in the python() destination.
send(self, message) method (mandatory)
The send method sends a message to the target service. It should return True to indicate success, or self.QUEUED when using batch mode. For other possible return values, see the description of the flush() method. Note that for batch mode, the flush() method must be implemented as well.
This is the only mandatory method of the destination.
If a message cannot be delivered after the number of times set in retries() (by default: 3), AxoSyslog drops the message and continues with the next message. For details, see Error handling in the python() destination.
The method can return True, False, or one of the following constants:
self.DROP: The message is dropped immediately.
self.ERROR: Corresponds to boolean False. The message is put back to the queue, and sending the message is attempted (up to the number of the retries() option). The destination is suspended for time-reopen() seconds.
self.SUCCESS: Corresponds to boolean True. The message was sent successfully.
self.QUEUED: The send() method should return this value when using batch mode, if it has successfully added the message to the batch. Message acknowledgment of batches is controlled by the flush() method.
self.NOT_CONNECTED: The message is put back to the queue, and the destination is suspended. The open() method will be called, and the sending the messages will be continued with the same message/batch.
self.RETRY: The message is put back to the queue, and sending the message is attempted (up to the number of the retries() option). If sending the message has failed retries() times, self.NOT_CONNECTED is returned.
flush(self) method (optional)
Send the messages in a batch. You can use this method to implement batch-mode message sending instead of sending messages one-by-one. When using batch mode, the send() method adds the messages to a batch (for example, a list), and the flush() method sends the messages as configured in the batch-bytes(), batch-lines(), or batch-timeout() options.
The method can return True, False, or one of the following constants:
self.DROP: The messages cannot be sent and the entire batch is dropped immediately.
self.ERROR: Corresponds to boolean False. The message is put back to the queue, and sending the message is attempted (up to the number of the retries() option). The destination is suspended for time-reopen() seconds.
self.SUCCESS: Corresponds to boolean True. The message was sent successfully.
self.NOT_CONNECTED: The message is put back to the queue, and the destination is suspended. The open() method will be called, and the sending the messages will be continued with the same message/batch.
self.RETRY: The message is put back to the queue, and sending the message is attempted (up to the number of the retries() option). If sending the message has failed retries() times, self.NOT_CONNECTED is returned.
close(self) method (optional)
Close the connection to the target service. Usually it is called right before deinit() when stopping or reloading AxoSyslog. It is also called when send() fails.
The deinit(self) method (optional)
This method is executed when AxoSyslog is stopped or reloaded. This method does not return a value.
Warning
If you reload AxoSyslog, existing Python objects are destroyed, therefore the context and state information of Python blocks is lost. Log rotation and updating the configuration of AxoSyslog typically involves a reload.
Error handling in the python() destination
The Python destination handles errors as follows.
Currently AxoSyslog ignores every error from the open method until the first log message arrives to the Python destination. If the fist message has arrived and there was an error in the open method, AxoSyslog starts calling the open method every time-reopen() second, until opening the destination succeeds.
If the open method returns without error, AxoSyslog calls the send method to send the first message.
If the send method returns with an error, AxoSyslog calls the is_opened method.
If the is_opened method returns an error, AxoSyslog starts calling the open method every time-reopen() second, until opening the destination succeeds.
Otherwise, AxoSyslog calls the send method again.
If the send method has returned with an error retries() times and the is_opened method has not returned any errors, AxoSyslog drops the message and attempts to process the next message.
Example: Write logs into a file
The purpose of this example is only to demonstrate the basics of the Python destination, if you really want to write log messages into text files, use the file destination instead.
The following sample code writes the body of log messages into the /tmp/example.txt file. Only the send() method is implemented, meaning that AxoSyslog opens and closes the file for every message.
The Python destination allows you to write your own destination in Python. The python() destination has the following options. The class() option is mandatory. For details on writing destinations in Python, see python: Write custom Python destinations.
batch-bytes()
Accepted values:
number [bytes]
Default:
none
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Available in AxoSyslog version 3.19 and later.
This option does not have any effect unless the flush() method is implemented in the destination.
batch-lines()
Type:
number
Default:
25
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
This option does not have any effect unless the flush() method is implemented in the destination.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
This option does not have any effect unless the flush() method is implemented in the destination.
class()
Type:
string
Default:
N/A
Description: The name of the Python class that implements the destination, for example:
python( class("MyPythonDestination"));
If you want to store the Python code in an external Python file, the class() option must include the name of the Python file containing the class, without the path and the .py extension, for example:
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
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.
loaders()
Type:
list of python modules
Default:
empty list
Description: The AxoSyslog application imports Python modules specified in this option, before importing the code of the Python class. This option has effect only when the Python class is provided in an external Python file. This option has no effect when the Python class is provided within the AxoSyslog configuration file (in a python{} block). You can use the loaders() option to modify the import mechanism that imports Python class. For example, that way you can use hy in your Python class.
python(class(usermodule.HyParser) loaders(hy))
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
on-error()
Type:
One of: drop-message, drop-property, fallback-to-string, silently-drop-message, silently-drop-property, silently-fallback-to-string
Default:
Use the global setting (which defaults to drop-message)
Description: Controls what happens when type-casting fails and 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.
options()
Type:
string
Default:
N/A
Description: This option allows you to pass custom values from the configuration file to the Python code. Enclose both the option names and their values in double-quotes. The Python code will receive these values during initialization as the options dictionary. For example, you can use this to set the IP address of the server from the configuration file, so it is not hard-coded in the Python object.
For example, you can refer to the value of the host field in the Python code as options["host"]. Note that the Python code receives the values as strings, so you might have to cast them to the type required, for example: int(options["port"])
Note
From version 3.27, AxoSyslog supports the arrow syntax for declaring custom Java and Python options. You can alternatively declare them using a similar syntax:
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
Note
Starting with 3.26, AxoSyslog assigns a persist name to Python sources and destinations. The persist name is generated from the class name. If you want to use the same Python class multiple times in your AxoSyslog configuration, add a unique persist-name() to each source or destination, otherwise AxoSyslog will not start. For example:
Alternatively, you can include the following line in the Python package: @staticmethod generate_persist_name. For example:
from syslogng import LogSource
class PyNetworSource(LogSource):
@staticmethod
def generate_persist_name(options):
return options["port"] def run(self):
pass
def request_exit(self):
pass
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
1
Description: The time to wait in seconds before a dead connection is reestablished.
value-pairs()
Type:
parameter list of the value-pairs() option
Default:
scope("selected-macros" "nv-pairs")
Description: The value-pairs() option creates structured name-value pairs from the data and metadata of the log message. For details on using value-pairs(), see Structuring macros, metadata, and other value-pairs.
Note
Empty keys are not logged.
You can use this option to limit which name-value pairs are passed to the Python code for each message. Note that if you use the value-pairs() option, the Python code receives the specified value-pairs as a Python dict. Otherwise, it receives the message object. In the following example, only the text of the log message is passed to Python.
Starting with version 3.34, you can send multiple log messages with the help of Redis’s pipelining feature.
Batch size
The batch-lines(), batch-lines(), and batch-timeout() options of the destination determine how many log messages AxoSyslog sends in a batch. The batch-lines() option determines the maximum number of messages AxoSyslog puts in a batch in. This can be limited based on size and time:
AxoSyslog sends a batch every batch-timeout() milliseconds, even if the number of messages in the batch is less than batch-lines(). That way the destination receives every message in a timely manner even if suddenly there are no more messages.
To increase the performance of the destination, increase the number of worker threads for the destination using the workers() option, or adjust the batch-lines() and/or batch-timeout() options.
Example: Redis batch mode
The following destination sends log messages to a Redis server using the pipelining feature. A batch consists of 100 messages and is sent every 10 seconds (10000 milliseconds) if there is less than 100 messages are in the queue.
The redis() driver sends messages as name-value pairs to a Redis key-value store.
The redis() destination has the following options:
auth()
Type:
hostname or IP address
Default:
N/A
Description: The password used for authentication on a password-protected Redis server. Available in AxoSyslog version 3.10 and later.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
command()
Type:
comma-separated list of strings ("", “«”, “<s<o<-command-parameter>”, “<th<d-”)
Default:
empty string
Description: The Redis command to execute, for example, LPUSH, INCR, or HINCRBY. Using the HINCRBY command with an increment value of 1 allows you to create various statistics. For example, the command("HINCRBY" "${HOST}/programs" "${PROGRAM}" "1") command counts the number of log messages on each host for each program.
Note the following points when using the redis() destination:
You can use macros and templates in the parameters of the Redis command.
Currently you can use only one command in a redis() destination.
The AxoSyslog application ignores the return value of the command. If the Redis server returns an error, AxoSyslog closes the connection.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Available in AxoSyslog version 3.19 and later.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The hostname or IP address of the Redis server.
port()
Type:
number
Default:
6379
Description: The port number of the Redis server.
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
workers()
Type:
integer
Default:
1
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
32 - riemann: Monitor your data with Riemann
The riemann() driver sends your data (for example, metrics or events) to a Riemann monitoring system.
The riemann() driver sends metrics or events to a Riemann monitoring system.
The riemann() destination has the following options:
attributes()
Type:
parameter list of the value-pairs() option
Default:
Description: The attributes() option adds extra metadata to the Riemann event, that can be displayed on the Riemann dashboard. To specify the metadata to add, use the syntax of the value-pairs() option. For details on using value-pairs(), see Structuring macros, metadata, and other value-pairs.
description()
Type:
template, macro, or string
Default:
Description: The value to add as the description field of the Riemann event.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Instead of the arrival time into Riemann, AxoSyslog can also send its own timestamp value.
This can be useful if Riemann is inaccessible for a while, and the messages are collected in the disk buffer until Riemann is accessible again. In this case, it would be difficult to differentiate between messages based on the arrival time only, because this would mean that there would be hundreds of messages with the same arrival time. This issue can be solved by using this option.
The event-time() option takes an optional parameter specifying whether the time format is in seconds or microseconds. For example:
In case the parameter is omitted, AxoSyslog defaults to the seconds version. In case the event-time() option is omitted altogether, AxoSyslog defaults to the seconds version with $UNIXTIME.
Note that the time format parameter requires:
riemann-c-client 1.10.0 or newer
In older versions of riemann-c-client, the microseconds option is not available.
In case your distribution does not contain a recent enough version of riemann-c-client and you wish to use microseconds, install a new version from .
If you installed the new version in a custom location (instead of the default one), make sure that you append the directory of the pkg-config file (.pc file) to the environment variable export PKG_CONFIG_PATH=....
After calling configure, you should see the following message in the case of successful installation:
Older versions of Riemann cannot handle microseconds. No error will be indicated, however, the time of the event will be set to the timestamp when the message arrived to Riemann.
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Available in AxoSyslog version 3.19 and later.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
If an error occurs while sending the messages to the server, AxoSyslog will try to resend every message from the batch. If it does not succeed (you can set the number of retry attempts in the retries() option), AxoSyslog drops every message in the batch.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The value to add as the host field of the Riemann event.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
metric()
Type:
template, macro, or string
Default:
Description: The numeric value to add as the metric field of the Riemann event. If possible, include type-hinting as well, otherwise the Riemann server will interpret the value as a floating-point number. The following example specifies the SEQNUM macro as an integer.
metric(int("$SEQNUM"))
port()
Type:
number
Default:
5555
Description: The port number of the Riemann server.
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
server()
Type:
hostname or IP address
Default:
127.0.0.1
Description: The hostname or IP address of the Riemann server.
service()
Type:
template, macro, or string
Default:
${PROGRAM}
Description: The value to add as the service field of the Riemann event.
state()
Type:
template, macro, or string
Default:
Description: The value to add as the state field of the Riemann event.
tags()
Type:
string list
Default:
the tags already assigned to the message
Description: The list of tags to add as the tags field of the Riemann event. If not specified AxoSyslog automatically adds the tags already assigned to the message. If you set the tags() option, only the tags you specify will be added to the event.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
timeout()
Type:
number [seconds]
Default:
Description: The value (in seconds) to wait for an operation to complete, and attempt to reconnect the Riemann server if exceeded. By default, the timeout is disabled.
ttl()
Type:
template, macro, or number
Default:
Description: The value (in seconds) to add as the ttl (time-to-live) field of the Riemann event.
type()
Type:
tcp
Default:
tcp
Description: The type of the network connection to the Riemann server: TCP, TLS, or UDP. For TLS connections, set the ca-file() option to authenticate the Riemann server, and the cert-file() and key-file() options if the Riemann server requires authentication from its clients.
Make sure that you specify TLS options either using type() or using the tls() block. Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
ca-file()
Type:
path to a CA certificate in PEM format
Default:
Description: Path to the CA certificate in PEM format that signed the certificate of the Riemann server. When establishing TLS connection, AxoSyslog verifies the certificate of the Riemann server using this CA.
This option was called cacert() up until (and including) AxoSyslog version 3.12.
cert-file()
Type:
path to a CA certificate in PEM format
Default:
Description: Path to the a certificate file in PEM format. When establishing TLS connection, AxoSyslog authenticates on the Riemann server using this certificate and the matching private key set in the key-file() option.
Note that you have to set the cert-file() and key-file() options only if the Riemann server requires authentication from the clients.
This option was called cert() in AxoSyslog version 3.7.
key-file()
Type:
path to a private key file
Default:
Description: Path to the private key of the certificate file set in the cert-file() option. When establishing TLS connection, AxoSyslog authenticates on the Riemann server using this private key and the matching certificate set in the cert-file() option.
Note that you have to set the cert-file() and key-file() options only if the Riemann server requires authentication from the clients.
This option was called key() in AxoSyslog version 3.7.
33 - s3: Amazon S3
Available in AxoSyslog version 4.4 and later.
The s3() destination sends log messages to the Amazon Simple Storage Service (Amazon S3) object storage service. Messages are normally sent encrypted with TLS (HTTPS), but you can specify a custom unencrypted HTTP endpoint.
Prerequisites
An existing S3 bucket configured for programmatic access, and the related ACCESS_KEY and SECRET_KEY of a user that can access it.
If you are not using the venv (/usr/bin/syslog-ng-update-virtualenv) created by AxoSyslog, you must install the boto3 and/or botocore Python dependencies.
To use the s3() driver, the scl.conf file must be included in your AxoSyslog configuration:
@include "scl.conf"
The s3() driver is actually a reusable configuration snippet. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of this configuration snippet on GitHub.
AxoSyslog can create a new object based on the following strategies:
Based on object size: The max-object-size() option configures AxoSyslog to finish an object if it reaches a certain size. AxoSyslog appends an index ("-1", “-2”, …) to the end of the object key, then starts a new object.
Based on timestamp: The object-key-timestamp() option can be used to set a datetime-related template, which is appended to the end of the object, for example: "${R_MONTH_ABBREV}${R_DAY}". When a log message arrives with a newer timestamp template resolution, the previous timestamped object gets finished and a new one is started with the new timestamp. If an older message arrives, it doesn`t reopen the old object, but starts a new object with the key having an index appended to the old object.
Based on timeout: The flush-grace-period() option sets the number of minutes to wait for new messages to arrive after the last one. If the timeout expires, AxoSyslog closes the object, and opens a new object (with an appended index) when a new message arrives.
All of these strategies can be used individually, or together.
Upload options
AxoSyslog uploads objects using the multipart upload API. AxoSyslog composes chunks locally. When a chunk reaches the size set in chunk-size() (by default 5 MiB), the chunk is uploaded. When an object is finished, the multipart upload is completed and S3 merges the chunks.
The following options are specific to the s3() destination.
access-key()
Type:
string
Default:
N/A
Description: The ACCESS_KEY of the service account used to access the S3 bucket. (Together with secret-key().)
Starting with version 4.7, you can use the AWS_... environment variables or credentials files from the ~/.aws/ directory instead of this option. For details, see the official documentation.
bucket()
Type:
string
Default:
Description: The name of the S3 bucket, for example, my-bucket. Note that the bucket must already exist.
canned-acl()
Type:
string
Default:
empty
Description: The ACL assigned to the object, if specified, for example, bucket-owner-read. The following values are valid:
If you configure an invalid value, the default is used.
chunk-size()
Type:
string
Default:
5MiB
Description: The size of log messages that AxoSyslog writes to the S3 object in a batch. If compression is enabled, the chunk-size() refers to the compressed size.
compression()
Type:
boolean
Default:
no
Description: Setting compression(yes) enables gzip compression, and implicitly adds a .gz suffix to the created object’s key. You can set the level of the compression using the compresslevel() option (0-9).
compresslevel()
Type:
integer (0-9)
Default:
9
Description: Only has effect if compression() is set to yes. You can set the level of the compression using the compresslevel() option (0-9).
flush-grace-period()
Type:
integer [minutes]
Default:
60
Description: After the grace period expires and no new messages are routed to the destination, AxoSyslog flushes the contents of the buffer to the S3 object even if the volume of the messages in the buffer is lower than chunk-size().
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
max-object-size()
Type:
string
Default:
5120GiB
Description: The maximal size of the S3 object. If an object reaches this size, AxoSyslog appends an index ("-1", “-2”, …) to the end of the object key and starts a new object after rotation.
max-pending-uploads()
Type:
integer
Default:
32
Description: The max-pending-uploads() and upload-threads() options configure the upload of the chunks. Uploading happens in multiple threads to minimize network overhead.
upload-threads() limits the maximum number of parallel uploads.
max-pending-uploads() limits the number of chunks that are waiting in the work queue of the upload threads to get uploaded.
object-key()
Type:
template
Default:
N/A
Description: The object key (or key name), which uniquely identifies the object in an Amazon S3 bucket. Note that a suffix may be appended to this object key depending on the naming strategies used. Example: my-logs/${HOSTNAME}/.
object-key-timestamp()
Type:
template
Default:
Description: The object-key-timestamp() option can be used to set a datetime-related template, which is appended to the end of the object key, for example: "${R_MONTH_ABBREV}${R_DAY}". When a log message arrives with a newer timestamp template resolution, the previous timestamped object gets finished and a new one is started with the new timestamp. If an older message arrives, it doesn`t reopen the old object, but starts a new object with the key having an index appended to the old object.
persist-name()
Type:
string
Default:
N/A
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
region()
Type:
string
Default:
Description: The AWS region to use when writing the bucket. This should normally be the same region where the bucket is created. This option implies an API endpoint url(). For providers other than AWS, or for custom API endpoints, use the url() option.
secret-key()
Type:
string
Default:
N/A
Description: The SECRET_KEY of the service account used to access the S3 bucket. (Together with access-key().)
Starting with version 4.7, you can use the AWS_... environment variables or credentials files from the ~/.aws/ directory instead of this option. For details, see the official documentation.
storage-class()
Type:
string
Default:
STANDARD
Description: The storage class of the object, for example, REDUCED_REDUNDANCY. The following values are valid:
If you configure an invalid value, the default is used.
upload-threads()
Type:
integer
Default:
8
Description: The number of AxoSyslog worker threads that are used to upload data to S3 from this destination.
template()
Type:
template or template function
Default:
${MESSAGE}\n
Description: The message as written to the Amazon S3 object. You can use templates and template functions to format the message.
url()
Type:
string
Default:
N/A
Description: The API endpoint URL for writing to the S3 bucket, for example https://s3.us-west-2.amazonaws.com, http://minio.local:9000, or https://storage.googleapis.com.
34 - slack: Send alerts and notifications to a Slack channel
The slack() destination driver sends messages to a Slack channel using the Slack Web API. For the list of available optional parameters, see Slack destination options. This destination is available in version 3.19 and later.
The driver allows you to modify nearly every field of the HTTP request. For details, see the Slack API documentation.
You can use the proxy() option to configure the HTTP driver in all HTTP-based destinations to use a specific HTTP proxy that is independent from the proxy configured for the system.
By default, the throttle() option is set to 1, because Slack has a 1 message/second limit on Webhooks. It can allow more message in short bursts, so you can set it to 0, if you only expect messages in a short period of time. For details, see the Web API rate limiting in the Slack documentation.
To use this destination, the scl.conf file must be included in your AxoSyslog configuration:
@include "scl.conf"
The slack() driver is actually a reusable configuration snippet configured to send log messages using the http() driver. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of this configuration snippet on GitHub.
Prerequisites
To send messages and notifications from AxoSyslog to Slack, you must create a Slack app and a Webhook that AxoSyslog can use. For details, see the Slack documentation.
Example: Using the slack() driver
The following example sets the colors and the author of the message.
The slack destination of AxoSyslog can directly post log messages and notifications to Slack channels. The slack destination has the following options.
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
ca-file()
Accepted values:
Filename
Default:
none
Description: Name of a file that contains an X.509 CA certificate (or a certificate chain) in PEM format. The AxoSyslog application uses this certificate to validate the certificate of the HTTPS server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
cipher-suite()
Accepted values:
Name of a cipher, or a colon-separated list
Default:
Depends on the OpenSSL version that AxoSyslog uses
Description: Specifies the cipher, hash, and key-exchange algorithms used for the encryption, for example, ECDHE-ECDSA-AES256-SHA384. The list of available algorithms depends on the version of OpenSSL used to compile AxoSyslog. To specify multiple ciphers, separate the cipher names with a colon, and enclose the list between double-quotes, for example:
For a list of available algorithms, execute the openssl ciphers -v command. The first column of the output contains the name of the algorithms to use in the cipher-suite() option, the second column specifies which encryption protocol uses the algorithm (for example, TLSv1.2). That way, the cipher-suite() also determines the encryption protocol used in the connection: to disable SSLv3, use an algorithm that is available only in TLSv1.2, and that both the client and the server supports. You can also specify the encryption protocols using ssl-options().
You can also use the following command to automatically list only ciphers permitted in a specific encryption protocol, for example, TLSv1.2:
echo"cipher-suite(\"$(openssl ciphers -v | grep TLSv1.2 | awk '{print $1}'| xargs echo -n | sed 's/ /:/g'| sed -e 's/:$//')\")"
Note that starting with version 3.10, when AxoSyslog receives TLS-encrypted connections, the order of ciphers set on the AxoSyslog server takes precedence over the client settings.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
Description: The colors to be assigned to the messages of different importance levels.
color-chooser()
Type:
integer or template
Default:
‘${LEVEL_NUM}’
Description: An integer that assigns a color to the message from the list of colors set in the colors() option.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The Webhook URL for the Incoming Webhook of your Slack app. This URL must also include the authentication token that AxoSyslog uses to authenticate to Slack. For example: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
Description: The number of messages that the output queue can store.
persist-name()
Type:
string
Default:
N/A
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
To handle HTTP error responses, if the HTTP server returns 5xx codes, AxoSyslog will attempt to resend messages until the number of attempts reaches retries. If the HTTP server returns 4xx codes, AxoSyslog will drop the messages.
ssl-version()
Type:
string
Default:
None, uses the libcurl default
Description: Specifies the permitted SSL/TLS version. Possible values: sslv2, sslv3, tlsv1, tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3.
An alternative way to specify this option is to put it into a tls() block, together with any other TLS options. This allows you to separate these options and ensure better readability.
Make sure that you specify TLS options either using their own dedicated option (ca-dir(), ca-file(), cert-file(), cipher-suite(), key-file(), peer-verify(), and ssl-version()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
By default, the throttle() option is set to 1, because Slack has a 1 message/second limit on Webhooks. It can allow more message in short bursts, so you can set it to 0, if you only expect messages in a short period of time. For details, see the Web API rate limiting in the Slack documentation.
Description: The value (in seconds) to wait for an operation to complete, and attempt to reconnect the server if exceeded. By default, the timeout value is 0, meaning that there is no timeout. Available in version 3.11 and later.
Description: The value of the USER-AGENT header in the messages sent to the server.
use-system-cert-store()
Type:
`yes
Default:
no
Description: Use the certificate store of the system for verifying HTTPS certificates. For details, see the curl documentation.
workers()
Type:
integer
Default:
1
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
If you are using load-balancing (that is, you have configured multiple servers in the url() option), increase the number of worker threads at least to the number of servers. For example, if you have set three URLs (url("site1", "site2", "site3")), set the workers() option to 3 or more.
35 - smtp: Generate SMTP messages (emails) from logs
The destination is aimed at a fully controlled local, or near-local, trusted SMTP server. The goal is to send mail to trusted recipients, through a controlled channel. It hands mails over to an SMTP server, and that is all it does, therefore the resulting solution is as reliable as sending an email in general. For example, AxoSyslog does not verify whether the recipient exists.
The smtp() driver sends email messages triggered by log messages. The smtp() driver uses SMTP, without needing external applications. You can customize the main fields of the email, add extra headers, send the email to multiple recipients, and so on.
The subject(), body(), and header() fields may include macros which get expanded in the email. For more information on available macros see Macros of AxoSyslog.
The smtp() driver has the following required parameters: host(), port(), from(), to(), subject(), and body(). For the list of available optional parameters, see smtp() destination options.
Note
The smtp() destination driver is available only in AxoSyslog 3.4 and later.
The following example defines an smtp() destination using only the required parameters.
destination d_smtp { smtp( host("localhost") port(25) from("alert service""[email protected]") to("Admin #1""[email protected]") subject("[ALERT] Important log message of $LEVEL condition received from $HOST/$PROGRAM!") body("Hi!\nThe alerting service detected the following important log message:\n $MSG\n-- \n"));};
The following example sets some optional parameters as well.
destination d_smtp { smtp( host("localhost") port(25) from("syslog-ng alert service""[email protected]") to("Admin #1""[email protected]") to("Admin #2""[email protected]") cc("Admin BOSS""[email protected]") bcc("Blind CC""[email protected]") subject("[ALERT] Important log message of $LEVEL condition received from $HOST/$PROGRAM!") body("Hi!\nThe syslog-ng alerting service detected the following important log message:\n $MSG\n-- \nsyslog-ng\n") header("X-Program", "$PROGRAM"));};
Example: Simple email alerting with the smtp() driver
The following example sends an email alert if the eth0 network interface of the host is down.
filter f_linkdown { match("eth0: link down" value("MESSAGE"));}; destination d_alert { smtp( host("localhost") port(25) from("syslog-ng alert service""syslog@localhost") reply-to("Admins""root@localhost") to("Ennekem""me@localhost") subject("[SYSLOG ALERT]: eth0 link down") body("Syslog received an alert:\n$MSG"));}; log { source(s_local); filter(f_linkdown); destination(d_alert);};
35.1 - smtp() destination options
The smtp() sends email messages using SMTP, without needing external applications. The smtp() destination has the following options:
body()
Type:
string
Default:
n/a
Description: The BODY field of the email. You can also use macros in the string. Use \\n to start a new line. For example:
body("AxoSyslog received the following alert from $HOST:\n$MSG")
bcc()
Type:
string
Default:
n/a
Description: The BCC recipient of the email (contents of the BCC field). You can specify the email address, or the name and the email address. Set the bcc option multiple times to send the email to multiple recipients. For example: bcc("[email protected]") or bcc("Admin" "[email protected]") or >bcc("Admin" "[email protected]") bcc("Admin2" "[email protected]")
You can also use macros to set the value of this parameter.
cc()
Type:
string
Default:
n/a
Description: The CC recipient of the email (contents of the CC field). You can specify the email address, or the name and the email address. Set the cc option multiple times to send the email to multiple recipients. For example: cc("[email protected]") or cc("Admin" "[email protected]") or cc("Admin" "[email protected]") cc("Admin2" "[email protected]"
You can also use macros to set the value of this parameter.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Available in AxoSyslog version 3.19 and later.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
from()
Type:
string
Default:
n/a
Description: The sender of the email (contents of the FROM field). You can specify the email address, or the name and the email address. For example:
If you specify the from() option multiple times, the last value will be used. Instead of the from() option, you can also use sender(), which is just an alias of the from() option.
You can also use macros to set the value of this parameter.
header()
Type:
string
Default:
n/a
Description: Adds an extra header to the email with the specified name and content. The first parameter sets the name of the header, the second one its value. The value of the header can contain macros. Set the header option multiple times to add multiple headers. For example:
header("X-Program", "$PROGRAM")
When using the header option, note the following points:
Do not use the header() option to set the values of headers that have dedicated options. Use it only to add extra headers.
If you set the same custom header multiple times, only the first will be added to the email, other occurrences will be ignored.
It is not possible to set the DATE, Return-Path, Original-Recipient, Content-*, MIME-*, Resent-*, Received headers.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Hostname or IP address of the SMTP server.
Note
If you specify host="localhost", AxoSyslog will use a socket to connect to the local SMTP server. Use host="127.0.0.1" to force TCP communication between AxoSyslog and the local SMTP server.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
port()
Type:
number
Default:
25
Description: The port number of the SMTP server.
reply-to()
Type:
string
Default:
n/a
Description: Replies of the recipient will be sent to this address (contents of the REPLY-TO field). You can specify the email address, or the name and the email address. Set the reply-to() option multiple times to send the email to multiple recipients. For example: reply-to("[email protected]") or reply-to("Admin" "[email protected]") or reply-to("Admin" "[email protected]") reply-to("Admin2" "[email protected]")
You can also use macros to set the value of this parameter.
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
subject()
Type:
string
Default:
n/a
Description: The SUBJECT field of the email. You can also use macros. For example:
subject("[SYSLOG ALERT]: Critical error message received from $HOST")
If you specify the subject() option multiple times, the last value will be used.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
to()
Type:
string
Default:
localhost
Description: The recipient of the email (contents of the TO field). You can specify the email address, or the name and the email address. Set the to() option multiple times to send the email to multiple recipients. For example: to("[email protected]") or to("Admin" "[email protected]") or to("Admin" "[email protected]") to("Admin2" "[email protected]")
You can also use macros to set the value of this parameter.
36 - snmp: Send SNMP traps
The snmp() driver sends SNMP traps using the Simple Network Management Protocol version 2c or version 3. Incoming log messages can be converted to SNMP traps, as the fields of the SNMP messages can be customized using AxoSyslog macros.
The snmp() driver is available in AxoSyslog version 3.22 and later.
Note
The snmp destination driver currently supports sending SNMP traps only using the UDP transport protocol.
The snmp() driver requires the host(), trap-obj(), and snmp-obj() options to be set, as well as the engine-id() and version() options when using the SNMPv3 protocol. For the list of available optional parameters, see snmp() destination options.
If AxoSyslog cannot resolve the destination hostname during startup, it will try to resolve the hostname again when the next message to be sent as an SNMP trap is received. However, if this name resolution fails, the trap will be dropped.
Note
The snmp() destination driver does not generate MARK signals itself, but can receive and forward MARK signals.
Example: Using the snmp() destination driver
The following example defines an SNMP destination that uses the SNMPv2c protocol.
36.1 - Converting Cisco syslog messages to clogMessageGenerated SNMP traps
The AxoSyslog application can convert the syslog messages sent by Cisco devices to Cisco-specific SNMP traps defined by the CISCO-SYSLOG-MIB (enterprises.cisco.ciscoMgmt.ciscoCiscoMIB) is also supported (such traps are also referred to as clogMessageGenerated notifications). That way, the incoming log messages can be forwarded to devices used to process and analyze Cisco-specific SNMP traps. For this to work correctly, the following requirements must be met:
The Source Configuration Library (SCL) must be included in the AxoSyslog configuration file:
To accomplish this, AxoSyslog has to use a special pattern database to parse the Cisco-specific syslog messages, because these messages do not comply with the standard syslog formats.
For details on the Cisco-specific SNMP trap format, see CISCO-SYSLOG-MIB on the Cisco website.
Parsing Cisco-specific message fields with patterndb
The ${PROGRAM} part of the syslog messages sent by Cisco devices contain not only the program name, but other important protocol information part as well. The ${PROGRAM} of these messages contains the Facility, Severity, and the Mnemonic (the Cisco name) of the message. The following pattern database parses these values and makes them available as the .cisco.Facility, .cisco.Severity, and .cisco.MsgName, respectively. The actual log message is available as .cisco.MsgText.
<patterndb version="4"pub_date="2011-05-03">
<ruleset name="cisco snmp ruleset1" xml:id="480de478-d4a6-4a7f-bea4-0c0245d361e3">
<description>Pattern for Cisco messages having BSD timestamps, for example: Jul 012010 00:32:59: %SYS-5-CONFIG_I: Configured from console by console</description>
<pattern>%@ESTRING:.cisco.Facility:-@@ESTRING:.cisco.Severity:-@@ANYSTRING:.cisco.MsgName@</pattern>
<rules>
<rule xml:id="09944c71-95eb-4bc0-8575-936931d85713"provider="oneidentity"class="system">
<patterns>
<pattern> @ANYSTRING:.cisco.MsgText@</pattern>
</patterns>
</rule>
</rules>
</ruleset>
<ruleset name="cisco snmp ruleset2" xml:id="480de478-d4a6-4a7f-bea4-0c0245d361e3">
<description>Pattern for Cisco messages having cisco-specific timestamps, for example: 18: Jan 22 10:45:44.543: %SYS-5-CONFIG_I: Configured from console by console</description>
<rules>
<rule xml:id="09944c71-95eb-4bc0-8575-936931d85714"provider="oneidentity"class="system">
<patterns>
<pattern>%@ESTRING:.cisco.Facility:-@@ESTRING:.cisco.Severity:-@@ESTRING:.cisco.MsgName::@ @ANYSTRING:.cisco.MsgText@</pattern>
</patterns>
</rule>
</rules>
</ruleset>
</patterndb>
Sending clogMessageGenerated SNMP traps
To send out clogMessageGenerated SNMP traps, use the cisco_snmp() destination driver. The cisco-snmp() destination is actually a modified version of the snmp() destination driver.
Note
The cisco-snmp() driver is actually a reusable configuration snippet. For details on using or writing SCLs, see Reusing configuration blocks.
The cisco-snmp() driver has the same requirements and options as the snmp() destination driver, but automatically fills the clogMessageGenerated-specific fields with the data received from parsing the Cisco-specific syslog messages using the pattern database. For details on the , see the <INSTALLDIR>/ share/include/scl/snmp/plugin.conf file.
This driver sends SNMP traps using the SNMP v2c or v3 protocol.
The snmp() destination has the following options:
auth-algorithm()
Type:
SHA
Default:
SHA
Description: The authentication method to use. Lowercase values (for example, sha) can be used as well.
This option is used with the SNMPv3 protocol.
auth-password()
Type:
string
Default:
empty string
Description: The password used for authentication. If the auth-username() option is set but the auth-password() is empty, AxoSyslog will try to authenticate with an empty password.
This option is used with the SNMPv3 protocol.
auth-username()
Type:
string
Default:
empty string
Description: The username used to authenticate on the SNMP server. If this parameter is set, AxoSyslog will try to authenticate on the SNMP server.
This option is used with the SNMPv3 protocol.
community()
Type:
string
Default:
public
Description: The community string used for SNMPv2c authentication.
This option is used with the SNMPv2c protocol.
enc-algorithm()
Type:
AES
Default:
AES
Description: The encryption method used to encrypt the SNMP traffic. Lowercase values (for example, aes) can be used as well.
This option is used with the SNMPv3 protocol.
enc-password()
Type:
string
Default:
Description: The password used for the encryption. Encryption is used only if the enc-password() is not empty.
This option is used with the SNMPv3 protocol.
engine-id()
Type:
number (hexadecimal number)
Default:
Description: The engine ID is a hexadecimal number at least 10 digits long, starting with 0x. for example, 0xABABABABAB.
This option is a required parameter when using the SNMPv3 protocol.
host()
Type:
hostname or IP address
Default:
n/a
Description: Hostname of the SNMP server.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
Description: The snmp-obj() option can be used to create custom SNMP trap elements. To create a trap element, specify the OID, type, and value of the element in the snmp-obj() option. To send SNMP traps, at least one snmp-obj() option must be defined. The snmp-obj() option requires the following parameters. Note that AxoSyslog does not validate the values of these elements.
<oid_of_the_object>: The object id of the SNMP object, for example, .1.3.6.1.4.1.18372.3.1.1.1.1.1`.
<type_of_the_object>: The type of the object specified as an ASN.1 primitive. One of: Integer, Timeticks, Octetstring, Counter32, Ipaddress, Objectid`. The type names are not case sensitive.
<value_of_the_object>: The value of the object as a string. The macros of AxoSyslog can be used to set these values, making it possible to transfer the content and other metadata from the the syslog message to the SNMP trap. Note that if the value of an Integer, Counter32orTimeticks` object is not a number (for example, is an empty string or other not-number string), AxoSyslog will automatically replace the value with 0. The values of other types of objects are not validated.
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.
Description: The trap-obj() is a specialized version of the snmp-obj() option that is used to identify the SNMP trap object. The type of the trap object is always Objectid. The <oid_of_the_object> and the <value_of_the_object»parameters are identical to the respective parameters of the snmp-obj() option. For details on these parameters, see snmp-obj().
Note
Using the trap-obj() object is equivalent to using the snmp-obj() with the Objectid type.
version()
Type:
v2c
Default:
v2c
Description: Specifies which version of the SNMP protocol to use.
Note
The AxoSyslog application will accept any valid option for the snmp() destination, but will only use the ones relevant to the selected protocol version, any other option will be ignored. For example, if the version("v2c") engine-id("0xABABABABAB") community("mycommunity") options are set, AxoSyslog will accept every option, but process only the community() option, because engine-id() applies only to SNMPv3.
37 - splunk-hec-event: Send messages to Splunk HEC
Starting with version 4.2.0, AxoSyslog can send messages to the Splunk HTTP Event Collector (HEC).
Prerequisites
Enable the HTTP Event Collector (HEC) on your Splunk deployment.
Create a token for AxoSyslog to use in the token() option of the destination. When creating the token, use the syslog source type.
event() accepts a template, which declares the content of the log message sent to Splunk. Default value: ${MSG}
index(), source(), host(), and time() accept templates, and declare the respective field of each log message based on the set template.
default-index(), default-source(), and default-sourcetype() accept literal strings, and are used as fallback values if a log message doesn’t set these fields. These values are passed to the URL as query parameters, so they don’t inflate the body of the HTTP request
for each message in the batch, which saves bandwidth.
fields() accepts template, which is passed as additional indexing metadata to Splunk.
extra-headers(), extra-queries(), and content-type() are additional HTTP request options.
HEC raw API
The splunk-hec-raw() destination feeds Splunk via the HEC raw API.
The options of the splunk-hec-raw() destination are similar to the splunk-hec-event() destination, but it has a mandatory option: channel(). The channel() option must be a globally unique channel identifier (GUID), this ID differentiates the data from different clients. Note that Splunk doesn’t generate this ID, you must create it for yourself. When Splunk sees a new channel identifier, it creates a new channel.
Use the template() option to set the content of the log message sent to Splunk (and not the event() option that is used in the splunk-hec-event() destination).
38 - sql: Store messages in an SQL database
The sql() driver sends messages into an SQL database. Currently the Microsoft SQL (MSSQL), MySQL, Oracle, PostgreSQL, and SQLite databases are supported. Starting with AxoSyslog 4.0, type information is automatically added to the stored columns if available. For details, see Specifying data types in value-pairs.
The AxoSyslog application requires read and write access to the SQL table, otherwise it cannot verify that the destination table exists.
Currently the AxoSyslog application has default schemas for the different databases and uses these defaults if the database schema (for example, columns and column types) is not defined in the configuration file. However, these schemas will be deprecated and specifying the exact database schema will be required in later versions.
Note
The sql() destination requires database-specific packages to be installed. These packages are automatically installed by the binary syslog-ng installer.
The table and value parameters can include macros to create tables and columns dynamically (for details, see Macros of AxoSyslog).
Warning
When using macros in table names, note that some databases limit the maximum allowed length of table names. Consult the documentation of the database for details.
Inserting the records into the database is performed by a separate thread. The AxoSyslog application automatically performs the escaping required to insert the messages into the database.
Example: Using the sql() driver
The following example sends the log messages into a PostgreSQL database running on the logserver host. The messages are inserted into the logs database, the name of the table includes the exact date and the name of the host sending the messages. The AxoSyslog application automatically creates the required tables and columns, if the user account used to connect to the database has the required privileges.
38.1 - Using the sql() driver with an Oracle database
The Oracle sql destination has some special aspects that are important to note.
The hostname of the database server is set in the tnsnames.ora file, not in the host parameter of the sql() destination.
If the tnsnames.ora file is not located in the /etc directory (or in the /var/opt/oracle directory on Solaris), set the following Oracle-related environment variables, so AxoSyslog will find the file: ORACLE_BASE, ORACLE_HOME, and ORACLE_SID. For details, see the documentation of the Oracle Instant Client.
You cannot use the same database() settings in more than one destination, because the database() option of the SQL driver is just a reference to the connection string of the tnsnames.ora file. To overcome this problem, you can duplicate the connections in the tnsnames.ora file under a different name, and use a different table in each Oracle destination in AxoSyslog.
As certain database versions limit the maximum length of table names, macros in the table names should be used with care.
In the current version of AxoSyslog, the types of database columns must be explicitly set for the Oracle destination. The column used to store the text part of the syslog messages should be able to store messages as long as the longest message permitted by syslog-ng, therefore it is usually recommended to use the varchar2 or clob column type. (The maximum length of the messages can be set using the log-msg-size() option.) For details, see the following example.
The Oracle Instant Client used by AxoSyslog supports only the following character sets:
Single-byte character sets: US7ASCII, WE8DEC, WE8MSWIN1252, and WE8ISO8859P1
Unicode character sets: UTF8, AL16UTF16, and AL32UTF8
Example: Using the sql() driver with an Oracle database
The following example sends the log messages into an Oracle database running on the logserver host, which must be set in the /etc/tnsnames.ora file. The messages are inserted into the LOGS database, the name of the table includes the exact date when the messages were sent. The AxoSyslog application automatically creates the required tables and columns, if the user account used to connect to the database has the required privileges.
The Oracle Instant Client retrieves the address of the database server from the /etc/tnsnames.ora file. Edit or create this file as needed for your configuration. A sample is provided below.
38.2 - Using the sql() driver with a Microsoft SQL database
The mssql database driver can access Microsoft SQL (MSSQL) destinations. This driver has some special aspects that are important to note.
The date format used by the MSSQL database must be explicitly set in the /etc/locales.conf file of the AxoSyslog server. For details, see the following example.
As certain database versions limit the maximum length of table names, macros in the table names should be used with care.
In the current version of AxoSyslog, the types of database columns must be explicitly set for the MSSQL destination.
Warning
The following column types cannot be used in MSSQL destinations: nchar, nvarchar, ntext, and xml.
The column used to store the text part of the syslog messages should be able to store messages as long as the longest message permitted by syslog-ng. The varchar column type can store maximum 4096 bytes-long messages. The maximum length of the messages can be set using the log-msg-size() option. For details, see the following example.
Remote access for SQL users must be explicitly enabled on the Microsoft Windows host running the Microsoft SQL Server.
Example: Using the sql() driver with an MSSQL database
The following example sends the log messages into an MSSQL database running on the logserver host. The messages are inserted into the syslogng database, the name of the table includes the exact date when the messages were sent. The AxoSyslog application automatically creates the required tables and columns, if the user account used to connect to the database has the required privileges.
The date format used by the MSSQL database must be explicitly set in the /etc/locales.conf file of the AxoSyslog server. Edit or create this file as needed for your configuration. A sample is provided below.
[default]date="%Y-%m-%d %H:%M:%S"
38.3 - Interacting with the database
SQL operations
Create table:
If the given table does not exist, AxoSyslog tries to create it with the given column types.
The AxoSyslog application automatically creates the required tables and columns, if the user account used to connect to the database has the required privileges.
If AxoSyslog cannot create or alter a table, it tries to do it again when it reaches the next time-reopen().
Alter table:
If the table structure is different from given structure in an existing table, AxoSyslog tries to add columns in this table but never will delete or modify an existing column.
If AxoSyslog cannot create or alter a table, it tries to do it again when reach the next time-reopen().
The AxoSyslog application requires read and write access to the SQL table, otherwise it cannot verify that the destination table exists.
Insert table:
Insert new records in a table.
Inserting the records into the database is performed by a separate thread.
The AxoSyslog application automatically performs the escaping required to insert the messages into the database.
If insert returns with error, AxoSyslog tries to insert the message +two times by default, then drops it. Retrying time is the value of time-reopen().
Encoding
The AxoSyslog application uses UTF-8 by default when writes logs into database.
Start/stop and reload
Start:
The AxoSyslog application will connect to database automatically after starting regardless existing incoming messages.
Stop:
The AxoSyslog application will close the connection to database before shutting down.
Possibility of losing logs:
The AxoSyslog application cannot lose logs during shutting down if disk buffer was given and it is not full yet.
The AxoSyslog application cannot lose logs during shutting down if disk buffer was not given.
Reload:
The AxoSyslog application will close the connection to database if it received SIGHUP signal (reload).
It will reconnect to the database when it tries to send a new message to this database again.
Macros:
The value of ${SEQNUM} macro will be overridden by sql driver regardless of local or relayed incoming message.
It will be grown continuously.
38.3.1 - MySQL-specific interaction methods
To specify the socket to use, set and export the MYSQL_UNIX_PORT environment variable, for example, MYSQL_UNIX_PORT=/var/lib/mysql/mysql.sock; export MYSQL_UNIX_PORT.
38.3.2 - MsSQL-specific interaction methods
In SQL Server 2005 this restriction is lifted - kind of. The total length of all key columns in an index cannot exceed 900 bytes.
If you are using null() in your configuration, be sure that the columns allow NULL to insert. Give the column as the following example: "datetime varchar(16) NULL".
The date format used by the MSSQL database must be explicitly set in the /etc/locales.conf file of the AxoSyslog server. [default] date = "%Y-%m-%d %H:%M:%S".
38.4 - sql() destination options
This driver sends messages into an SQL database. The sql() destination has the following options:
batch-bytes()
Accepted values:
number [bytes]
Default:
none
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Available in AxoSyslog version 3.19 and later.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
Description: Name of the columns storing the data in fieldname [dbtype] format. The [dbtype] parameter is optional, and specifies the type of the field. By default, AxoSyslog creates text columns. Note that not every database engine can index text fields.
Warning
The following column types cannot be used in MSSQL destinations: nchar, nvarchar, ntext, and xml.
create-statement-append()
Type:
string
Default:
empty string
Description: Specifies additional SQL options that are appended to the CREATE statement. That way you can customize what happens when AxoSyslog creates a new table in the database. Consult the documentation of your database server for details on the available options. Syntax:
create-statement-append(<options-to-append>)
For example, you can appends the ROW_FORMAT=COMPRESSED option to MySQL create table statements:
create-statement-append(ROW_FORMAT=COMPRESSED)
database()
Type:
string
Default:
logs
Description: Name of the database that stores the logs. Macros cannot be used in database name. Also, when using an Oracle database, you cannot use the same database() settings in more than one destination.
dbd-option()
Type:
string
Default:
empty string
Description: Specify database options that are set whenever AxoSyslog connects to the database server. Consult the documentation of your database server for details on the available options. Syntax:
dbd-option(OPTION_NAME VALUE)
OPTION_NAME is always a string, VALUE is a string or a number. For example:
Description: Defines an optional DBI driver location for DBD initialization.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Flags related to the sql() destination.
dont-create-tables: Enable this flag to prevent AxoSyslog from creating non-existing database tables automatically. The AxoSyslog application typically has to create tables if you use macros in the table names. Available in AxoSyslog version 3.2 and later.
explicit-commits: By default, AxoSyslog commits every log message to the target database individually. When the explicit-commits option is enabled, messages are committed in batches. This improves the performance, but results in some latency, as the messages are not immediately sent to the database. The size and frequency of batched commits can be set using the batch-lines() parameter. The explicit-commits option is available in AxoSyslog version 3.2 and later.
Example: Setting flags for SQL destinations
The following example sets the dont-create-tables and explicit-commits flags for an sql() destination.
flags(dont-create-tables,explicit-commits)
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.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Hostname of the database server. Note that Oracle destinations do not use this parameter, but retrieve the hostname from the /etc/tnsnames.ora file.
Note
If you specify host="localhost", AxoSyslog will use a socket to connect to the local database server. Use host="127.0.0.1" to force TCP communication between AxoSyslog and the local database server.
To specify the socket to use, set and export the MYSQL_UNIX_PORT environment variable, for example, MYSQL_UNIX_PORT=/var/lib/mysql/mysql.sock; export MYSQL_UNIX_PORT.
indexes()
Type:
string list
Default:
“date”, “facility”, “host”, “program”
Description: The list of columns that are indexed by the database to speed up searching. To disable indexing for the destination, include the empty indexes() parameter in the destination, simply omitting the indexes parameter will cause AxoSyslog to request indexing on the default columns.
The AxoSyslog application will create the name of indexes automaticaly with the following method:
In case of MsSQL, PostgreSQL, MySQL or SQLite or (Oracle but tablename < 30 characters): {table}_{column}_idx.
In case of Oracle and tablename > 30 characters: md5sum of {table}_{column}-1 and the first character will be replaced by “i” character and the md5sum will be truncated to 30 characters.
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.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
null()
Type:
string
Default:
Description: If the content of a column matches the string specified in the null() parameter, the contents of the column will be replaced with an SQL NULL value. If unset (by default), the option does not match on any string. For details, see the Example: Using SQL NULL values.
Example: Using SQL NULL values
The null() parameter of the SQL driver can be used to replace the contents of a column with a special SQL NULL value. To replace every column that contains an empty string with NULL, use the null("") option, for example
To replace only a specific column (for example, pid) if it is empty, assign a default value to the column, and use this default value in the null() parameter:
Ensure that the default value you use does not appear in the actual log messages, because other occurrences of this string will be replaced with NULL as well.
password()
Type:
string
Default:
n/a
Description: Password of the database user.
port()
Type:
number
Default:
1433 TCP for MSSQL, 3306 TCP for MySQL, 1521 for Oracle, and 5432 TCP for PostgreSQL
Description: The port number to connect to.
quote-char()
Type:
string
Default:
Available in AxoSyslog version 4.3.0 and newer.
Description: Set custom quoting for table and index names (for example, MySQL needs sometimes this for certain identifiers).
Note: Using a backtick character needs special formatting, because AxoSyslog uses backticks for configuration parameter names. To use backticks as quote character, set a double backtick: quote-char("``")
retries()
Type:
number (insertion attempts)
Default:
3
Description: The number of insertion attempts. If AxoSyslog could not insert a message into the database, it will repeat the attempt until the number of attempts reaches retries, then drops the connection to the database. For example, AxoSyslog will try to insert a message maximum three times by default (once for first insertion and twice if the first insertion was failed).
session-statements()
Type:
comma-separated list of SQL statements
Default:
empty string
Description: Specifies one or more SQL-like statement which is executed after AxoSyslog has successfully connected to the database. For example:
The AxoSyslog application does not validate or limit the contents of customized queries. Consequently, queries performed with a user with write-access can potentially modify or even harm the database. Use customized queries with care, and only for your own responsibility.
table()
Type:
string
Default:
messages
Description: Name of the database table to use (can include macros). When using macros, note that some databases limit the length of table names.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
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.
type()
Type:
mssql, mysql, oracle, pgsql, or sqlite3
Default:
mysql
Description: Specifies the type of the database, that is, the DBI database driver to use. Use the mssql option to send logs to an MSSQL database. For details, see the examples of the databases on the following sections.
Description: The parts of the message to store in the fields specified in the columns() parameter.
It is possible to give a special value calling: default (without quotation marks).It means that the value will be used that is the default of the column type of this value.
Description: Flags influence the behavior of the destination driver.
no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.
syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.
flush-lines()
Type:
number
Default:
Use global setting (exception: for http() destination, the default is 1).
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.
For optimal performance when sending messages to an AxoSyslog server, make sure that the value of flush-lines() is smaller than the window size set in the log-iw-size() option in the source of your server.
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.
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.
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.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
mark-freq()
Accepted values:
number [seconds]
Default:
1200
Description: An alias for the obsolete mark() option, retained for compatibility with 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).
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:
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.
pad-size()
Type:
number
Default:
0
Description: If set, AxoSyslog will pad output messages to the specified size (in bytes). Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes).
Warning
Hazard of data loss! If the size of the incoming message is larger than the previously set pad-size() value, AxoSyslog will truncate the message to the specified size. Therefore, all message content above that size will be lost.
persist-name()
Type:
string
Default:
N/A
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
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.
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.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
template-escape()
Type:
yes or no
Default:
no
Description: Turns on escaping for the ', ", and backspace characters in templated output files. This is useful for generating SQL statements and quoting string contents so that parts of the log message are not interpreted as commands to the SQL server.
Note: Starting with AxoSyslog version 4.5, template-escape(yes) escapes the top-level template function in case of nested template functions.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-zone()
Type:
name of the timezone, or the timezone offset
Default:
unspecified
Description: Convert timestamps to the timezone specified by this option. If this option is not set, then the original timezone information in the message is used. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see 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.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
40 - stomp: Publish messages using STOMP
The stomp() driver sends messages to servers (message brokers) using the Simple (or Streaming) Text Oriented Message Protocol (STOMP), formerly known as TTMP. AxoSyslog supports version 1.0 of the STOMP protocol. The AxoSyslog stomp() driver supports persistence.
The name-value pairs selected with the value-pairs() option will be sent as STOMP headers, while the body of the STOMP message is empty by default (but you can add custom content using the body() option). Publishing the name-value pairs as headers makes it possible to use the Headers exchange-type and subscribe only to interesting log streams.
The following example shows the default values of the available options.
destination d_stomp { stomp( host("localhost") port(61613) destination("/topic/syslog") body("")# optional, empty by default persistent(yes) ack(no) username("user")# optional, empty by default password("password")# optional, empty by default value-pairs(scope(selected-macros, nv-pairs, sdata)));};
40.1 - stomp() destination options
The stomp() driver publishes messages using the Simple (or Streaming) Text Oriented Message Protocol (STOMP).
The stomp() destination has the following options:
ack()
Type:
yes
Default:
no
Description: Request the STOMP server to acknowledge the receipt of the messages. If you enable this option, then after sending a message, AxoSyslog waits until the server confirms that it has received the message. This delay can seriously limit the performance of AxoSyslog if the message rate is high, and the server cannot acknowledge the messages fast enough.
body()
Type:
string
Default:
empty string
Description: The body of the STOMP message. You can also use macros and templates.
destination()
Type:
string
Default:
/topic/syslog
Description: The name of the destination (message queue) on the STOMP server. It can include macros and templates.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Available in AxoSyslog version 3.19 and later.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The hostname or IP address of the STOMP server.
password()
Type:
string
Default:
n/a
Description: The password used to authenticate on the STOMP server.
persistent()
Type:
yes
Default:
yes
Description: If this option is enabled, the STOMP server or broker will store the messages on its hard disk. That way, the messages will be retained if the STOMP server is restarted, if the message queue is set to be durable on the STOMP server.
port()
Type:
number
Default:
61613
Description: The port number of the STOMP server.
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
username()
Type:
string
Default:
empty string
Description: The username used to authenticate on the STOMP server.
value-pairs()
Type:
parameter list of the value-pairs() option
Default:
scope("selected-macros" "nv-pairs")
Description: The value-pairs() option creates structured name-value pairs from the data and metadata of the log message. For details on using value-pairs(), see Structuring macros, metadata, and other value-pairs.
Note
Empty keys are not logged.
41 - Sumo Logic destinations: sumologic-http() and sumologic-syslog()
From version 3.27.1, the AxoSyslog application can send log messages to Sumo Logic, a cloud-based log management and security analytics service, by using the sumologic-http() and sumologic-syslog() destinations.
Prerequisites
Currently, using the sumologic-http() and sumologic-syslog() destinations with AxoSyslog has the following prerequisites:
A Sumo Logic account.
If you do not yet have a Sumo Logic account, visit the official Sumo Logic website, and click Start free trial to create an account.
Note
A free trial version of the Sumo Logic account has limited functionalities and is only available for 90 days.
A verified connection and client configuration with the Sumo Logic service.
Warning
To avoid potential data loss, we strongly recommend that you verify your connection and client configuration with the Sumo Logic service before you start using the sumologic-http() or sumologic-syslog() destination with AxoSyslog in a production environment.
(Optional) For using the sumologic-http() destination, you need a HTTP Hosted Collector configured in the Sumo Logic service.
(Optional) For using the sumologic-http() destination, you need the unique HTTP collector code you receive while configuring your Host Collector for HTTP requests.
Limitations
Currently, using the sumologic-syslog() and sumologic-http() destinations with AxoSyslog has the following limitations:
The minimum required version of AxoSyslog is version 3.27.1.
Message format must be in RFC 5424-compliant form. Messages over 64KB in length are truncated.
For more information about the message format limitations, see the Message format section on the official Sumo Logic website.
64 characters long Sumo Logic tokens must be passed in the message body.
Note
Although RFC 5424 limits the structured data field (SD-ID) to 32 characters, Sumo Logic tokens are 64 characters long. If your logging client enforces the 32 characters length limit, you must pass the token in the message body.
To use the sumologic() driver, the scl.conf file must be included in your AxoSyslog configuration:
@include "scl.conf"
Note
The sumologic() driver is actually a reusable configuration snippet configured to send log messages using the network() and http() destination by using a template. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of this configuration snippet on GitHub.
41.1 - sumologic-http()
The sumologic-http() and sumologic-syslog() destinations send log messages to Sumo Logic, a cloud-based log management and security analytics service.
In addition, the sumologic-http() destination also has the following options.
batch-bytes()
Accepted values:
number [bytes]
Default:
none
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
Available in AxoSyslog version 3.19 and later.
batch-lines()
Type:
number
Default:
1
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
ca-dir()
Accepted values:
Directory name
Default:
none
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
ca-file()
Accepted values:
File name
Default:
empty
Description: Optional. The name of a file that contains a set of trusted CA certificates in PEM format. The AxoSyslog application uses the CA certificates in this file to validate the certificate of the peer.
Example format in configuration:
ca-file("/etc/pki/tls/certs/ca-bundle.crt")
Note
The ca-file() option can be used together with the ca-dir() option, and it is relevant when peer-verify() is set to other than no or optional-untrusted.
Description: Custom HTTP headers to include in the request, for example, headers("HEADER1: header1", "HEADER2: header2"). If not set, only the default headers are included, but no custom headers.
The following headers are included by default:
X-Syslog-Host:
X-Syslog-Program:
X-Syslog-Facility:
X-Syslog-Level: <loglevel/priority>
Note
The headers() option is a required option for the sumologic-http() destination.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
tls()
Type:
tls options
Default:
n/a
Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see TLS options.
In version 4.0 and newer, using the tls() option is optional, and Sumo Logic servers are verified using the system certificate store by default. In earlier versions, this was a required option.
In addition, the sumologic-syslog() destination also has the following options.
ca-dir()
Accepted values:
Directory name
Default:
none
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
ca-file()
Accepted values:
File name
Default:
empty
Description: Optional. The name of a file that contains a set of trusted CA certificates in PEM format. The AxoSyslog application uses the CA certificates in this file to validate the certificate of the peer.
Example format in configuration:
ca-file("/etc/pki/tls/certs/ca-bundle.crt")
Note
The ca-file() option can be used together with the ca-dir() option, and it is relevant when peer-verify() is set to other than no or optional-untrusted.
Description: Optional. This option sets the port number of the Sumo Logic server to connect to.
tag()
Type:
string list
Default:
“tag”
Description: Optional. This option specifies the list of tags to add as the tags fields of Sumo Logic messages. If not specified, AxoSyslog automatically adds the tags already assigned to the message. If you set the tag() option, only the tags you specify will be added to the messages.
tls()
Type:
tls options
Default:
n/a
Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see TLS options.
In version 4.0 and newer, using the tls() option is optional, and Sumo Logic servers are verified using the system certificate store by default. In earlier versions, this was a required option.
token()
Type:
string
Default:
Description: Required option. The Cloud Syslog Cloud Token that you received from the Sumo Logic service while configuring your cloud syslog source.
42 - syslog: Send messages to a remote logserver using the IETF-syslog protocol
The syslog() driver sends messages to a remote host (for example, a syslog-ng server or relay) on the local intranet or internet using the new standard syslog protocol developed by IETF (for details about the new protocol, see IETF-syslog messages). The protocol supports sending messages using the UDP, TCP, or the encrypted TLS networking protocols.
The required arguments of the driver are the address of the destination host (where messages should be sent). The transport method (networking protocol) is optional, syslog-ng uses the TCP protocol by default. For the list of available optional parameters, see syslog() destination options.
Declaration:
syslog(host transport [options]);
Note
Note that the syslog destination driver has required parameters, while the source driver defaults to the local bind address, and every parameter is optional.
The udp transport method automatically sends multicast packets if a multicast destination address is specified. The tcp and tls methods do not support multicasting.
Note
The default ports for the different transport protocols are as follows: UDP — 514, TCP — 514, TLS — 6514.
If a message uses the IETF-syslog format (RFC5424), only the text of the message can be customized (that is, the $MESSAGE part of the log), the structure of the header is fixed.
42.1 - syslog() destination options
The syslog() driver sends messages to a remote host (for example, an AxoSyslog server or relay) on the local intranet or internet using the RFC5424 syslog protocol developed by IETF (for details about the protocol, see IETF-syslog messages). The protocol supports sending messages using the UDP, TCP, or the encrypted TLS networking protocols.
These destinations have the following options:
ca-dir()
Accepted values:
Directory name
Default:
none
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
ca-file()
Accepted values:
File name
Default:
empty
Description: Optional. The name of a file that contains a set of trusted CA certificates in PEM format. The AxoSyslog application uses the CA certificates in this file to validate the certificate of the peer.
Example format in configuration:
ca-file("/etc/pki/tls/certs/ca-bundle.crt")
Note
The ca-file() option can be used together with the ca-dir() option, and it is relevant when peer-verify() is set to other than no or optional-untrusted.
close-on-input()
Type:
yes
Default:
yes
Description: By default, AxoSyslog closes destination sockets if it receives any input from the socket (for example, a reply). If this option is set to no, AxoSyslog just ignores the input, but does not close the socket.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the <code>unset()</code> rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a <code>LogMessage</code> will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop <code>unset</code> values, making the <code>LogMessage</code> representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
<p>When creating a new <code>dir()</code> option for a disk buffer, or modifying an existing one, make sure you delete the persist file.</p>
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the <code>dir()</code> path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of <code>reliable()</code> option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Axoflow does not recommend you to change <code>truncate-size-ratio()</code>. Only change its value if you understand the performance implications of doing so.
Example: Examples for using disk-buffer()
In the following case reliable disk-buffer() is used.
Description: Available only in AxoSyslog version 3.17 and later. For details about how client-side failover works, see Client-side failover.
servers()
Type:
list of IP addresses and fully-qualified domain names
Default:
empty
Description: Specifies a secondary destination server where log messages are sent if the primary server becomes inaccessible. To list several failover servers, separate the address of the servers with comma. By default, AxoSyslog waits for the a server before switching to the next failover server is set in the time-reopen() option.
If failback() is not set, AxoSyslog does not attempt to return to the primary server even if it becomes available. In case the failover server fails, AxoSyslog attempts to connect the next failover server in the list in round-robin fashion.
Warning
The failover servers must be accessible on the same port as the primary server.
failback()
Description: Available only in AxoSyslog version 3.17 and later.
When AxoSyslog starts up, it always connects to the primary server first. In the failover() option there is a possibility to customize the failover modes.
Depending on how you set the failback() option, AxoSyslog behaves as follows:
round-robin mode: If failback() is not set, AxoSyslog does not attempt to return to the primary server even if it becomes available. In case the failover server fails, AxoSyslog attempts to connect the next failover server in the list in round-robin fashion.
In the following example AxoSyslog handles the logservers in round-robin fashion if the primary logserver becomes inaccessible (therefore failback() option is not set).
failback mode: If failback() is set, AxoSyslog attempts to return to the primary server.
After AxoSyslog connects a secondary server during a failover, it sends a probe every tcp-probe-interval() seconds towards the primary server. If the primary logserver responds with a TCP ACK packet, the probe is successful. When the number of successful probes reaches the value set in the successful-probes-required() option, AxoSyslog tries to connect the primary server using the last probe.
Note
AxoSyslog always waits for the result of the last probe before sending the next message. So if one connection attempt takes longer than the configured interval, that is, it waits for connection time out, you may experience longer intervals between actual probes.
In the following example AxoSyslog attempts to return to the primary logserver, as set in the failback() option: it will check if the server is accessible every tcp-probe-interval() seconds, and reconnect to the primary logserver after three successful connection attempts.
Default value for tcp-probe-interval(): 60 seconds
Default value for successful-probes-required(): 3
Example: Configuring failover servers
In the following example AxoSyslog handles the logservers in round-robin fashion if the primary logserver becomes uneccassible (therefore failback() option is not set).
In the following example AxoSyslog attempts to return to the primary logserver, as set in the failback() option: it will check if the server is accessible every tcp-probe-interval() seconds, and reconnect to the primary logserver after three successful connection attempts.
This option is not available for the connection-less UDP protocol, because in this case the client does not detect that the destination becomes inaccessible.
flags()
Type:
no-multi-line, syslog-protocol
Default:
empty set
Description: Flags influence the behavior of the destination driver.
no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.
syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.
flush-lines()
Type:
number
Default:
Use global setting (exception: for http() destination, the default is 1).
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.
For optimal performance when sending messages to an AxoSyslog server, make sure that the value of flush-lines() is smaller than the window size set in the log-iw-size() option in the source of your server.
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 <code>frac-digits()</code> option is set to a value higher than 6, AxoSyslog will truncate the fraction seconds in the timestamps after 6 digits.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Determines the internet protocol version of the given driver (network() or syslog()). The possible values are 4 and 6, corresponding to IPv4 and IPv6. The default value is ip-protocol(4).
Note that listening on a port using IPv6 automatically means that you are also listening on that port using IPv4. That is, if you want to have receive messages on an IP-address/port pair using both IPv4 and IPv6, create a source that uses the ip-protocol(6). You cannot have two sources with the same IP-address/port pair, but with different ip-protocol() settings (it causes an Address already in use error).
For example, the following source receives messages on TCP, using the network() driver, on every available interface of the host on both IPv4 and IPv6.
Description: Specifies the Type-of-Service value of outgoing packets.
ip-ttl()
Type:
number
Default:
0
Description: Specifies the Time-To-Live value of outgoing packets.
keep-alive()
Type:
yes or no
Default:
yes
Description: Specifies whether connections to destinations should be closed when syslog-ng is reloaded. Note that this applies to the client (destination) side of the connections, server-side (source) connections are always reopened after receiving a HUP signal unless the keep-alive option is enabled for the source.
localip()
Type:
string
Default:
0.0.0.0
Description: The IP address to bind to before connecting to target.
localport()
Type:
number
Default:
0
Description: The port number to bind to. Messages are sent from this port.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
mark-freq()
Accepted values:
number [seconds]
Default:
1200
Description: An alias for the obsolete mark() option, retained for compatibility with 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).
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:
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 <code>dst-idle</code>, <code>host-idle</code> and <code>periodical</code>, the <code>MARK</code> message will not be written in the destination, if it is not open yet.
Available in AxoSyslog 3.4 and later.
port() or destport()
Type:
number
Default:
601
Description: The port number to connect to. Note that the default port numbers used by AxoSyslog do not comply with the latest RFC which was published after the release of AxoSyslog 3.0.2, therefore the default port numbers will change in the future releases.
so-broadcast()
Type:
yes or no
Default:
no
Description: This option controls the SO_BROADCAST socket option required to make AxoSyslog send messages to a broadcast address. For details, see the socket(7) manual page.
so-keepalive()
Type:
yes or no
Default:
no
Description: Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. For details, see the socket(7) manual page.
so-rcvbuf()
Type:
number
Default:
0
Description: Specifies the size of the socket receive buffer in bytes. For details, see the socket(7) manual page.
so-sndbuf()
Type:
number
Default:
0
Description: Specifies the size of the socket send buffer in bytes. For details, see the socket(7) manual page.
spoof-source()
Type:
yes or no
Default:
no
Description: Enables source address spoofing. This means that the host running AxoSyslog generates UDP packets with the source IP address matching the original sender of the message. It is useful when you want to perform some kind of preprocessing using AxoSyslog then forward messages to your central log management solution with the source address of the original sender. This option only works for UDP destinations though the original message can be received by TCP as well. This option is only available if syslog-ng was compiled using the --enable-spoof-source configuration option.
The maximum size of spoofed datagrams in udp() destinations is set to 1024 bytes by default. To change the maximum size, use the spoof-source-max-msglen() option.
Note
<p>Anything above the size of the maximum transmission unit (MTU), which is 1500 bytes by default, is not recommended because of fragmentation.</p>
The maximum datagram in IP protocols (both IPv4 and IPv6) is 65535 bytes including the IP and UDP headers. The minimum size of the IPv4 header is 20 bytes, the IPv6 is 40 bytes, and the UDP is 8 bytes.
Warning
To use spoofing on Microsoft Windows platforms, you must also set the <code>spoof-interface()</code> option as well.
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.
tcp-keepalive-intvl()
Type:
number [seconds]
Default:
0
Description: Specifies the interval (number of seconds) between subsequential keepalive probes, regardless of the traffic exchanged in the connection. This option is equivalent to /proc/sys/net/ipv4/tcp_keepalive_intvl. The default value is 0, which means using the kernel default.
Warning
<p>The <code>tcp-keepalive-time()</code>, <code>tcp-keepalive-probes()</code>, and <code>tcp-keepalive-intvl()</code> options only work on platforms which support the <code>TCP_KEEPCNT</code>, <code>TCP_KEEPIDLE</code>,and <code>TCP_KEEPINTVL</code> setsockopts. Currently, this is Linux.</p>
A connection that has no traffic is closed after tcp-keepalive-time() + tcp-keepalive-intvl() \* tcp-keepalive-probes() seconds.
Available in AxoSyslog version 3.4 and later.
tcp-keepalive-probes()
Type:
number
Default:
0
Description: Specifies the number of unacknowledged probes to send before considering the connection dead. This option is equivalent to /proc/sys/net/ipv4/tcp_keepalive_probes. The default value is 0, which means using the kernel default.
Warning
<p>The <code>tcp-keepalive-time()</code>, <code>tcp-keepalive-probes()</code>, and <code>tcp-keepalive-intvl()</code> options only work on platforms which support the <code>TCP_KEEPCNT</code>, <code>TCP_KEEPIDLE</code>,and <code>TCP_KEEPINTVL</code> setsockopts. Currently, this is Linux.</p>
A connection that has no traffic is closed after tcp-keepalive-time() + tcp-keepalive-intvl() \* tcp-keepalive-probes() seconds.
Available in AxoSyslog version 3.4 and later.
tcp-keepalive-time()
Type:
number [seconds]
Default:
0
Description: Specifies the interval (in seconds) between the last data packet sent and the first keepalive probe. This option is equivalent to /proc/sys/net/ipv4/tcp_keepalive_time. The default value is 0, which means using the kernel default.
Warning
<p>The <code>tcp-keepalive-time()</code>, <code>tcp-keepalive-probes()</code>, and <code>tcp-keepalive-intvl()</code> options only work on platforms which support the <code>TCP_KEEPCNT</code>, <code>TCP_KEEPIDLE</code>,and <code>TCP_KEEPINTVL</code> setsockopts. Currently, this is Linux.</p>
A connection that has no traffic is closed after tcp-keepalive-time() + tcp-keepalive-intvl() \* tcp-keepalive-probes() seconds.
Available in AxoSyslog version 3.4 and later.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
Note
If a message uses the IETF-syslog format (RFC5424), only the text of the message can be customized (that is, the $MESSAGE part of the log), the structure of the header is fixed.
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.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-zone()
Type:
name of the timezone, or the timezone offset
Default:
unspecified
Description: Convert timestamps to the timezone specified by this option. If this option is not set, then the original timezone information in the message is used. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see 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.
tls()
Type:
tls options
Default:
n/a
Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see TLS options.
transport()
Type:
udp, tcp, or tls
Default:
tcp
Description: Specifies the protocol used to send messages to the destination server.
If you use the udp transport, AxoSyslog automatically sends multicast packets if a multicast destination address is specified. The tcp transport does not support multicasting.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
Note
This option applies only to file and file-like destinations. Destinations that use specific protocols (for example, <code>network()</code>, or <code>syslog()</code>) ignore this option. For protocol-like destinations, use a template locally in the destination, or use the <a href="/docs/axosyslog-core/chapter-global-options/reference-options/">proto-template</a> option.
43 - syslog-ng(): Forward logs to another syslog-ng node
The syslog-ng() destination driver forwards log messages to another AxoSyslog node in EWMM format.
The Enterprise-wide message model or EWMM allows you to deliver structured messages from the initial receiving AxoSyslog component right up to the central log server, through any number of hops. It does not matter if you parse the messages on the client, on a relay, or on the central server, their structured results will be available where you store the messages. Optionally, you can also forward the original raw message as the first AxoSyslog component in your infrastructure has received it, which is important if you want to forward a message for example, to a SIEM system. To make use of the enterprise-wide message model, you have to use the syslog-ng() destination on the sender side, and the default-network-drivers() source on the receiver side.
The syslog-ng() destination driver is available in version 3.16 and later. The node that receives this message must use the default-network-drivers() source to properly handle the messages.
The following is a sample log message in EWMM format.
<13>1 2018-05-13T13:27:50.993+00:00 my-host @syslog-ng - - -
{"MESSAGE":"<34>Oct 11 22:14:15 mymachine su: 'su root' failed for username on
/dev/pts/8","HOST_FROM":"my-host","HOST":"my-host","FILE_NAME":"/tmp/in","._TAGS":".source.s_file"}
Note in this driver you have to set the address of the destination server using the server() parameter (in some other destinations, this parameter does not have an explicit name).
syslog-ng() destination options
The syslog-ng() destination is a special version of the network() destination driver: by default, it sends EWMM-formatted log messages to the TCP514 port of the server.
ca-dir()
Accepted values:
Directory name
Default:
none
Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.
This option can be used together with the optional ca-file() option.
ca-file()
Accepted values:
File name
Default:
empty
Description: Optional. The name of a file that contains a set of trusted CA certificates in PEM format. The AxoSyslog application uses the CA certificates in this file to validate the certificate of the peer.
Example format in configuration:
ca-file("/etc/pki/tls/certs/ca-bundle.crt")
Note
The ca-file() option can be used together with the ca-dir() option, and it is relevant when peer-verify() is set to other than no or optional-untrusted.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Available only in AxoSyslog version 3.17 and later. For details about how client-side failover works, see Client-side failover.
servers()
Type:
list of IP addresses and fully-qualified domain names
Default:
empty
Description: Specifies a secondary destination server where log messages are sent if the primary server becomes inaccessible. To list several failover servers, separate the address of the servers with comma. By default, AxoSyslog waits for the a server before switching to the next failover server is set in the time-reopen() option.
If failback() is not set, AxoSyslog does not attempt to return to the primary server even if it becomes available. In case the failover server fails, AxoSyslog attempts to connect the next failover server in the list in round-robin fashion.
Warning
The failover servers must be accessible on the same port as the primary server.
failback()
Description: Available only in AxoSyslog version 3.17 and later.
When AxoSyslog starts up, it always connects to the primary server first. In the failover() option there is a possibility to customize the failover modes.
Depending on how you set the failback() option, AxoSyslog behaves as follows:
round-robin mode: If failback() is not set, AxoSyslog does not attempt to return to the primary server even if it becomes available. In case the failover server fails, AxoSyslog attempts to connect the next failover server in the list in round-robin fashion.
In the following example AxoSyslog handles the logservers in round-robin fashion if the primary logserver becomes inaccessible (therefore failback() option is not set).
failback mode: If failback() is set, AxoSyslog attempts to return to the primary server.
After AxoSyslog connects a secondary server during a failover, it sends a probe every tcp-probe-interval() seconds towards the primary server. If the primary logserver responds with a TCP ACK packet, the probe is successful. When the number of successful probes reaches the value set in the successful-probes-required() option, AxoSyslog tries to connect the primary server using the last probe.
Note
AxoSyslog always waits for the result of the last probe before sending the next message. So if one connection attempt takes longer than the configured interval, that is, it waits for connection time out, you may experience longer intervals between actual probes.
In the following example AxoSyslog attempts to return to the primary logserver, as set in the failback() option: it will check if the server is accessible every tcp-probe-interval() seconds, and reconnect to the primary logserver after three successful connection attempts.
Default value for tcp-probe-interval(): 60 seconds
Default value for successful-probes-required(): 3
Example: Configuring failover servers
In the following example AxoSyslog handles the logservers in round-robin fashion if the primary logserver becomes uneccassible (therefore failback() option is not set).
In the following example AxoSyslog attempts to return to the primary logserver, as set in the failback() option: it will check if the server is accessible every tcp-probe-interval() seconds, and reconnect to the primary logserver after three successful connection attempts.
This option is not available for the connection-less UDP protocol, because in this case the client does not detect that the destination becomes inaccessible.
Example: Specifying failover servers for syslog() destinations
The following example specifies two failover servers for a simple syslog() destination.
Description: Flags influence the behavior of the destination driver.
no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.
syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.
flush-lines()
Type:
number
Default:
Use global setting (exception: for http() destination, the default is 1).
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.
For optimal performance when sending messages to an AxoSyslog server, make sure that the value of flush-lines() is smaller than the window size set in the log-iw-size() option in the source of your server.
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.
ip-protocol()
Type:
number
Default:
4
Description: Determines the internet protocol version of the given driver (network() or syslog()). The possible values are 4 and 6, corresponding to IPv4 and IPv6. The default value is ip-protocol(4).
Note that listening on a port using IPv6 automatically means that you are also listening on that port using IPv4. That is, if you want to have receive messages on an IP-address/port pair using both IPv4 and IPv6, create a source that uses the ip-protocol(6). You cannot have two sources with the same IP-address/port pair, but with different ip-protocol() settings (it causes an Address already in use error).
For example, the following source receives messages on TCP, using the network() driver, on every available interface of the host on both IPv4 and IPv6.
Description: Specifies the Type-of-Service value of outgoing packets.
ip-ttl()
Type:
number
Default:
0
Description: Specifies the Time-To-Live value of outgoing packets.
keep-alive()
Type:
yes or no
Default:
yes
Description: Specifies whether connections to destinations should be closed when syslog-ng is reloaded. Note that this applies to the client (destination) side of the connections, server-side (source) connections are always reopened after receiving a HUP signal unless the keep-alive option is enabled for the source.
localip()
Type:
string
Default:
0.0.0.0
Description: The IP address to bind to before connecting to target.
localport()
Type:
number
Default:
0
Description: The port number to bind to. Messages are sent from this port.
log-fifo-size()
Type:
number
Default:
Use global setting.
Description: The number of messages that the output queue can store.
mark-freq()
Accepted values:
number [seconds]
Default:
1200
Description: An alias for the obsolete mark() option, retained for compatibility with 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).
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:
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.
port() or destport()
Type:
number
Default:
601
Description: The port number to connect to. Note that the default port numbers used by AxoSyslog do not comply with the latest RFC which was published after the release of AxoSyslog 3.0.2, therefore the default port numbers will change in the future releases.
server()
Type:
hostname or IP address
Default:
127.0.0.1
Description: The hostname or IP address of the AxoSyslog server.
so-broadcast()
Type:
yes or no
Default:
no
Description: This option controls the SO_BROADCAST socket option required to make AxoSyslog send messages to a broadcast address. For details, see the socket(7) manual page.
so-keepalive()
Type:
yes or no
Default:
no
Description: Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. For details, see the socket(7) manual page.
so-rcvbuf()
Type:
number
Default:
0
Description: Specifies the size of the socket receive buffer in bytes. For details, see the socket(7) manual page.
so-sndbuf()
Type:
number
Default:
0
Description: Specifies the size of the socket send buffer in bytes. For details, see the socket(7) manual page.
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.
tcp-keepalive-intvl()
Type:
number [seconds]
Default:
0
Description: Specifies the interval (number of seconds) between subsequential keepalive probes, regardless of the traffic exchanged in the connection. This option is equivalent to /proc/sys/net/ipv4/tcp_keepalive_intvl. The default value is 0, which means using the kernel default.
Warning
The tcp-keepalive-time(), tcp-keepalive-probes(), and tcp-keepalive-intvl() options only work on platforms which support the TCP_KEEPCNT, TCP_KEEPIDLE,and TCP_KEEPINTVL setsockopts. Currently, this is Linux.
A connection that has no traffic is closed after tcp-keepalive-time() + tcp-keepalive-intvl() \* tcp-keepalive-probes() seconds.
Available in AxoSyslog version 3.4 and later.
tcp-keepalive-probes()
Type:
number
Default:
0
Description: Specifies the number of unacknowledged probes to send before considering the connection dead. This option is equivalent to /proc/sys/net/ipv4/tcp_keepalive_probes. The default value is 0, which means using the kernel default.
Warning
<p>The <code>tcp-keepalive-time()</code>, <code>tcp-keepalive-probes()</code>, and <code>tcp-keepalive-intvl()</code> options only work on platforms which support the <code>TCP_KEEPCNT</code>, <code>TCP_KEEPIDLE</code>,and <code>TCP_KEEPINTVL</code> setsockopts. Currently, this is Linux.</p>
A connection that has no traffic is closed after tcp-keepalive-time() + tcp-keepalive-intvl() \* tcp-keepalive-probes() seconds.
Available in AxoSyslog version 3.4 and later.
tcp-keepalive-time()
Type:
number [seconds]
Default:
0
Description: Specifies the interval (in seconds) between the last data packet sent and the first keepalive probe. This option is equivalent to /proc/sys/net/ipv4/tcp_keepalive_time. The default value is 0, which means using the kernel default.
Warning
<p>The <code>tcp-keepalive-time()</code>, <code>tcp-keepalive-probes()</code>, and <code>tcp-keepalive-intvl()</code> options only work on platforms which support the <code>TCP_KEEPCNT</code>, <code>TCP_KEEPIDLE</code>,and <code>TCP_KEEPINTVL</code> setsockopts. Currently, this is Linux.</p>
A connection that has no traffic is closed after tcp-keepalive-time() + tcp-keepalive-intvl() \* tcp-keepalive-probes() seconds.
Available in AxoSyslog version 3.4 and later.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
template-escape()
Type:
yes or no
Default:
no
Description: Turns on escaping for the ', ", and backspace characters in templated output files. This is useful for generating SQL statements and quoting string contents so that parts of the log message are not interpreted as commands to the SQL server.
Note: Starting with AxoSyslog version 4.5, template-escape(yes) escapes the top-level template function in case of nested template functions.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-zone()
Type:
name of the timezone, or the timezone offset
Default:
unspecified
Description: Convert timestamps to the timezone specified by this option. If this option is not set, then the original timezone information in the message is used. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see 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.
tls()
Type:
tls options
Default:
n/a
Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see TLS options.
transport()
Type:
udp, tcp, or tls
Default:
tcp
Description: Specifies the protocol used to send messages to the destination server.
If you use the udp transport, AxoSyslog automatically sends multicast packets if a multicast destination address is specified. The tcp transport does not support multicasting.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
44 - syslog-ng-otlp(): Forward logs to another node using OpenTelemetry
Available in AxoSyslog version 4.4 and later.
The syslog-ng-otlp() source and destination allows you to transfer the internal representation of log messages between AxoSyslog instances using the OpenTelemetry protocol. Unlike the traditional syslog-ng() drivers that rely on simple TCP connections, syslog-ng-otlp() leverages the OpenTelemetry protocol for efficient and reliable log message transmission.
The key benefits of the syslog-ng-otlp() drivers are:
scalability (via the workers() option),
built-in application layer acknowledgement,
support for Google service authentication (ADC or ALTS), and
improved load balancing capabilities.
To use it, configure a syslog-ng-otlp() destination on the sender node, and a syslog-ng-otlp() source on the receiver node, like this:
Application Layer Transport Security (ALTS) is a simple to use authentication, only available within Google’s infrastructure. It accepts the target-service-account() option, where you can list service accounts to match against when authenticating the server.
tls(peer-verify()) is not available for the opentelemetry() and loki() destination.
The gRPC-based drivers (opentelemetry() and loki()) have a different tls() block implementation from the network() or http() drivers. Most features are the same.
batch-bytes()
Accepted values:
number [bytes]
Default:
4MB
Available in AxoSyslog version 4.6 and later.
Description: Sets the maximum size of payload in a batch. If the size of the messages reaches this value, AxoSyslog sends the batch to the destination even if the number of messages is less than the value of the batch-lines() option. The batch might be at most 1 message larger than the set limit.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-bytes().
OTLP has a default 4 MiB batch limit, therefore the default value for batch-bytes() is 4 MB, which is a bit below 4 MiB.
The batch size is calculated before compression, which is the same as the limit is calculated on the server.
batch-lines()
Type:
number
Default:
0
Description: Specifies how many lines are flushed to a destination in one batch. 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.
For example, if you set batch-lines() to 100, AxoSyslog waits for 100 messages.
If the batch-timeout() option is disabled, the AxoSyslog application flushes the messages if it has sent batch-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.
Note that if the batch-timeout() option is enabled and the queue becomes empty, AxoSyslog flushes the messages only if batch-timeout() expires, or the batch reaches the limit set in batch-lines().
For optimal performance, make sure that the AxoSyslog source that feeds messages to this destination is configured properly: the value of the log-iw-size() option of the source must be higher than the batch-lines()*workers() of the destination. Otherwise, the size of the batches cannot reach the batch-lines() limit.
batch-timeout()
Type:
time in milliseconds
Default:
-1 (disabled)
Description: Specifies the time AxoSyslog waits for lines to accumulate in the output buffer. The AxoSyslog application sends batches 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 batch-timeout() milliseconds.
channel-args()
Type:
See description
Default:
-
Description: The channel-args() option is available in gRPC-based drivers. It accepts name-value pairs and sets channel arguments defined in the GRPC Core library documentation. For example:
Description: Enables compression in gRPC requests. Although gRPC supports various compression methods, currently only deflate is supported (which is basically the same as gzip).
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The number of messages that the output queue can store.
persist-name()
Type:
string
Default:
N/A
Description: If you receive the following error message during AxoSyslog startup, set the persist-name() option of the duplicate drivers:
Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down.
This error happens if you use identical drivers in multiple sources, for example, if you configure two file sources to read from the same file. In this case, set the persist-name() of the drivers to a custom string, for example, persist-name("example-persist-name1").
retries()
Type:
number (of attempts)
Default:
3
Description: If AxoSyslog cannot send a message, it will try again until the number of attempts reaches retries().
If the number of attempts reaches retries(), AxoSyslog will wait for time-reopen() time, then tries sending the message again.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
url()
Type:
string
Default:
localhost:9095
Description: The URL of the AxoSyslog receiver.
worker-partition-key()
Type:
template
Default:
Description: The worker-partition-key() option specifies a template: messages that expand the template to the same value are mapped to the same partition. When batching is enabled and multiple workers are configured, it’s important to add only those messages to a batch which generate identical URLs. To achieve this, set the worker-partition-key() option with a template that contains all the templates used in the url() option, otherwise messages will be mixed.
For example, you can partition messages based on the destination host:
worker-partition-key("$HOST")
workers()
Type:
integer
Default:
1
Description: Specifies the number of worker threads (at least 1) that AxoSyslog uses to send messages to the server. Increasing the number of worker threads can drastically improve the performance of the destination.
Warning
Hazard of data loss. When you use more than one worker threads together with disk-based buffering, AxoSyslog creates a separate disk buffer for each worker thread. This means that decreasing the number of workers can result in losing data currently stored in the disk buffer files. Do not decrease the number of workers when the disk buffer files are in use.
45 - tcp, tcp6, udp, udp6: OBSOLETE - Send messages to a remote log server using the legacy BSD-syslog protocol (tcp(), udp() drivers)
The tcp(), tcp6(), udp(), and udp6() drivers send messages to another host (for example, an AxoSyslog server or relay) on the local intranet or internet using the UDP or TCP protocol. The tcp6() and udp6() drivers use the IPv6 network protocol.
45.1 - tcp(), tcp6(), udp(), and udp6() destination options
45.1.1 - Change an old destination driver to the network() driver
To replace your existing tcp(), tcp6(), udp(), udp6() destinations with a network() destination, complete the following steps.
Replace the driver with network. For example, replace udp( with network(
Set the transport protocol.
If you used TLS-encryption, add the transport("tls") option, then continue with the next step.
If you used the tcp or tcp6 driver, add the transport("tcp") option.
If you used the udp or udp driver, add the transport("udp") option.
If you use IPv6 (that is, the udp6 or tcp6 driver), add the ip-protocol(6) option.
If you did not specify the port used in the old driver, check network() destination options and verify that your clients send the messages to the default port of the transport protocol you use. Otherwise, set the appropriate port number in your source using the port() option.
All other options are identical. Test your configuration with the syslog-ng --syntax-only command.
The following configuration shows a simple tcp destination.
The telegram() destination sends log messages to Telegram, which is a secure, cloud-based mobile and desktop messaging app.
Note that this destination automatically uses the certificate store of the system (for details, see the curl documentation).
Declaration:
telegram(parameters);
You can use the proxy() option to configure the HTTP driver in all HTTP-based destinations to use a specific HTTP proxy that is independent from the proxy configured for the system.
Example: Using the telegram() driver
The following example creates a telegram() destination.
Description: Disables link previews for links in the message. By default, the disable-web-page-preview value is true. From a security point of view, Axoflow recommends to leave it true, otherwise malicious messages can trick the telegram destination to generate traffic to any URL.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: Formats the message in a markdown-style or HTML-style formatting. By default, the parse-mode value is markdown, which means that the message is formatted in markdown style.
template()
Type:
string
Default:
${MESSAGE}
Description: Specifies the content of the message. The AxoSyslog application will automatically encode the content of this option using the url-encode() template function.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
47 - unix-stream, unix-dgram: Send messages to UNIX domain sockets
The unix-stream() and unix-dgram() drivers send messages to a UNIX domain socket in either SOCK_STREAM or SOCK_DGRAM mode.
47.1 - unix-stream() and unix-dgram() destination options
These drivers send messages to a unix socket in either SOCK_STREAM or SOCK_DGRAM mode. The unix-stream() and unix-dgram() destinations have the following options:
close-on-input()
Type:
yes
Default:
yes
Description: By default, AxoSyslog closes destination sockets if it receives any input from the socket (for example, a reply). If this option is set to no, AxoSyslog just ignores the input, but does not close the socket.
create-dirs()
Type:
yes or no
Default:
no
Description: Enable creating non-existing directories when creating files or socket files.
disk-buffer()
Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:
capacity-bytes()
Type:
number (bytes)
Default:
1MiB
Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
In AxoSyslog version 4.2 and earlier, this option was called disk-buf-size().
compaction()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog prunes the unused space in the LogMessage representation, making the disk queue size smaller at the cost of some CPU time. Setting the compaction() argument to yes is recommended when numerous name-value pairs are unset during processing, or when the same names are set multiple times.
Note
Simply unsetting these name-value pairs by using the unset() rewrite operation is not enough, as due to performance reasons that help when AxoSyslog is CPU bound, the internal representation of a LogMessage will not release the memory associated with these name-value pairs. In some cases, however, the size of this overhead becomes significant (the raw message size can grow up to four times its original size), which unnecessarily increases the disk queue file size. For these cases, the compaction will drop unset values, making the LogMessage representation smaller at the cost of some CPU time required to perform compaction.
dir()
Type:
string
Default:
N/A
Description: Defines the folder where the disk-buffer files are stored.
Warning
When creating a new dir() option for a disk buffer, or modifying an existing one, make sure you delete the persist file.
AxoSyslog creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, AxoSyslog will look for or create disk-buffer files in their old location. To ensure that AxoSyslog uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
Note
If the dir() path provided by the user does not exist, AxoSyslog creates the path with the same permission as the running instance.
flow-control-window-bytes()
Type:
number (bytes)
Default:
163840000
Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-size().
flow-control-window-size()
Type:
number(messages)
Default:
10000
Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
In AxoSyslog version 4.2 and earlier, this option was called mem-buf-length().
front-cache-size()
Type:
number(messages)
Default:
1000
Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer already exists, the change will take effect when the disk-buffer becomes empty.
Options reliable() and capacity-bytes() are required options.
In AxoSyslog version 4.2 and earlier, this option was called qout-size().
prealloc()
Type:
yes/no
Default:
no
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).
Available in AxoSyslog 4.0 and later.
reliable()
Type:
yes/no
Default:
no
Description: If set to yes, AxoSyslog cannot lose logs in case of reload/restart, unreachable destination or AxoSyslog crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.
Warning
Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
truncate-size-ratio()
Type:
number((between 0 and 1))
Default:
1 (do not truncate)
Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down the disk IO operations, but it saves disk space. By default, AxoSyslog version 4.0 and later doesn’t truncate disk-buffer files by default (truncate-size-ratio(1)). Earlier versions freed the disk-space when at least 10% of the disk-buffer file could be freed (truncate-size-ratio(0.1)).
AxoSyslog only truncates the file if the possible disk gain is more than truncate-size-ratio() times capacity-bytes().
Description: Flags influence the behavior of the destination driver.
no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.
syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.
flush-lines()
Type:
number
Default:
Use global setting (exception: for http() destination, the default is 1).
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.
For optimal performance when sending messages to an AxoSyslog server, make sure that the value of flush-lines() is smaller than the window size set in the log-iw-size() option in the source of your server.
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.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
Note
The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.
Using hook-commands() when AxoSyslog starts or stops
To execute an external program when AxoSyslog starts or stops, use the following options:
startup()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog starts.
shutdown()
Type:
string
Default:
N/A
Description: Defines the external program that is executed as AxoSyslog stops.
Using the hook-commands() when AxoSyslog reloads
To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:
setup()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.
teardown()
Type:
string
Default:
N/A
Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.
Description: The number of messages that the output queue can store.
keep-alive()
Type:
yes or no
Default:
yes
Description: Specifies whether connections to destinations should be closed when syslog-ng is reloaded. Note that this applies to the client (destination) side of the connections, server-side (source) connections are always reopened after receiving a HUP signal unless the keep-alive option is enabled for the source.
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).
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:
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.
so-broadcast()
Type:
yes or no
Default:
no
Description: This option controls the SO_BROADCAST socket option required to make AxoSyslog send messages to a broadcast address. For details, see the socket(7) manual page.
so-keepalive()
Type:
yes or no
Default:
no
Description: Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. For details, see the socket(7) manual page.
so-rcvbuf()
Type:
number
Default:
0
Description: Specifies the size of the socket receive buffer in bytes. For details, see the socket(7) manual page.
so-sndbuf()
Type:
number
Default:
0
Description: Specifies the size of the socket send buffer in bytes. For details, see the socket(7) manual page.
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.
template()
Type:
string
Default:
A format conforming to the default logfile format.
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Macros of AxoSyslog. Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.
template-escape()
Type:
yes or no
Default:
no
Description: Turns on escaping for the ', ", and backspace characters in templated output files. This is useful for generating SQL statements and quoting string contents so that parts of the log message are not interpreted as commands to the SQL server.
Note: Starting with AxoSyslog version 4.5, template-escape(yes) escapes the top-level template function in case of nested template functions.
throttle()
Type:
number
Default:
0
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
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.
ts-format()
Type:
rfc3164, bsd, rfc3339, iso
Default:
rfc3164
Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see ts-format().
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.
48 - usertty: Send messages to a user terminal
This driver writes messages to the terminal of a logged-in user.
The usertty() driver has a single required argument, specifying a username who should receive a copy of matching messages. Use the asterisk * to specify every user currently logged in to the system.
Declaration:
usertty(username);
The usertty() does not have any further options nor does it support templates.
Example: Using the usertty() driver
destination d_usertty { usertty("root");};
time-reopen()
Accepted values:
number [seconds]
Default:
60
Description: The time to wait in seconds before a dead connection is reestablished.
49 - Write your own custom destination in Java or Python
The AxoSyslog application is open source, so if you have the necessary programming skills, you can extend it if its features are not adequate for your particular environment or needs. You can write destinations and other extensions to AxoSyslog in C (the main language of AxoSyslog), or using its language bindings, for example, Java or Python. .
If you delete all Java destinations from your configuration and reload syslog-ng, the JVM is not used anymore, but it is still running. If you want to stop JVM, stop syslog-ng and then start syslog-ng again.
50 - Client-side failover
AxoSyslog can detect if the remote server of a network destination becomes inaccessible, and start sending messages to a secondary server. You can configure multiple failover servers, so if the secondary server becomes inaccessible as well, AxoSyslog switches to the third server in the list, and so on. If there are no more failover servers left, AxoSyslog returns to the beginning of a list and attempts to connect to the primary server.
The primary server is the address you provided in the destination driver configuration and it has a special role. AxoSyslog nominates this destination over the failover servers, and handles it as the primary address.
When AxoSyslog starts up, it always connects to the primary server first. In the failover() option there is a possibility to customize the failover modes.
Depending on how you set the failback() option, AxoSyslog behaves as follows:
round-robin mode: If failback() is not set, AxoSyslog does not attempt to return to the primary server even if it becomes available. In case the failover server fails, AxoSyslog attempts to connect the next failover server in the list in round-robin fashion.
In the following example AxoSyslog handles the logservers in round-robin fashion if the primary logserver becomes inaccessible (therefore failback() option is not set).
failback mode: If failback() is set, AxoSyslog attempts to return to the primary server.
After AxoSyslog connects a secondary server during a failover, it sends a probe every tcp-probe-interval() seconds towards the primary server. If the primary logserver responds with a TCP ACK packet, the probe is successful. When the number of successful probes reaches the value set in the successful-probes-required() option, AxoSyslog tries to connect the primary server using the last probe.
Note
AxoSyslog always waits for the result of the last probe before sending the next message. So if one connection attempt takes longer than the configured interval, that is, it waits for connection time out, you may experience longer intervals between actual probes.
In the following example AxoSyslog attempts to return to the primary logserver, as set in the failback() option: it will check if the server is accessible every tcp-probe-interval() seconds, and reconnect to the primary logserver after three successful connection attempts.
If AxoSyslog is restarted, it attempts to connect the primary server.
If AxoSyslog uses TLS-encryption to communicate with the remote server, AxoSyslog checks the certificate of the failover server as well. The certificates of the failover servers should match their domain names or IP addresses — for details, see Encrypting log messages with TLS. Note that when mutual authentication is used, the AxoSyslog client sends the same certificate to every server.
The primary server and the failover servers must be accessible with the same communication method: it is not possible to use different destination drivers or options for the different servers.
Note
Client-side failover works only for TCP-based connections (including TLS-encrypted connections), that is, the syslog() and network() destination drivers (excluding UDP transport).
Client-side failover is not supported in the sql() driver, even though it may use a TCP connection to access a remote database.
