Chat now with support
Chat with Support

syslog-ng Premium Edition 6.0.17 - Administration Guide

Preface Chapter 1. Introduction to syslog-ng Chapter 2. The concepts of syslog-ng Chapter 3. Installing syslog-ng Chapter 4. The syslog-ng PE quick-start guide Chapter 5. The syslog-ng PE configuration file Chapter 6. Collecting log messages — sources and source drivers Chapter 7. Sending and storing log messages — destinations and destination drivers Chapter 8. Routing messages: log paths, reliability, and filters Chapter 9. Global options of syslog-ng PE Chapter 10. TLS-encrypted message transfer Chapter 11. FIPS-compliant syslog-ng Chapter 12.  Reliable Log Transfer Protocol™ Chapter 13. Reliability and minimizing the loss of log messages Chapter 14. Manipulating messages Chapter 15. Parsing and segmenting structured messages Chapter 16. Processing message content with a pattern database Chapter 17. Statistics and metrics of syslog-ng Chapter 18. Multithreading and scaling in syslog-ng PE Chapter 19. Troubleshooting syslog-ng Chapter 20. Best practices and examples

RLTP™ options

RLTP™ options

The following options are specific to the RLTP™ protocol. Note that when using RLTP™ in a source or a destination, the options of the syslog() or the network() driver can be used as well.

allow-compress()
Accepted values: yes | no
Default: no

Description: Enable on-the-wire compression in the RLTP communication. Note that this option must be enabled both on the server and the client side to have any effect. Enabling compression can significantly reduce the bandwidth required to transport the messages, but can slightly decrease the performance of syslog-ng PE, reducing the number of transferred messages. The allow-compress() option can be used in source and destination drivers as well. Available in syslog-ng PE5.0 and later.

message-acknowledgement-timeout()
Type: number (seconds)
Default: 900

Description: When the receiver (syslog-ng PE server) receives and successfully processes a message, it sends an acknowledgement to the sender (the syslog-ng PE client). If the receiver does not acknowledge receiving the messages within this period, the sender terminates the connection with the receiver. Use this option only in destination drivers.

response-timeout()
Type: number (seconds)
Default: 60

Description: If syslog-ng PE does not receive any protocol-related message in the given timeframe (except for message acknowledgement, which is governed by the message-acknowledgement-timeout() option), syslog-ng PE terminates the connection with the peer, and the "Connection broken" message appears in the logs of the sender (the syslog-ng PE client). This is normal, and happens when the sender does not send any new message to the receiver.

Under normal circumstances, you should not change the value of this option. The response-timeout() option can be used in source and destination drivers as well.

tls-required()
Type: yes, optional, no
Default: optional

Description: Determines whether STARTTLS is to be used during communication. If the option is set to yes, you must also configure the tls() option to specify other parameters of the TLS connection (for example, the authentication of the server and the client).

The tls-required() option can be used in source and destination drivers as well.

For example, if you configure tls-required(yes) on server side and tls-required(no) on client side, the connection is dropped. If one of them is set to optional, the configuration of the other side will decide if TLS is used or not. If both sides are set to optional, and the tls() option is properly configured, TLS encryption will be used. The following table summarizes the possible options and their results.

Note that the various parameters of the tls() option are considered in the connection only if the tls-required() settings of the peers result in TLS-encryption in the following table. In other words: the tls-required() option of RLTP™ determines if TLS should be used at all, while the peer-verify() option of the tls()setting determines if the TLS connection can be actually established.

tls-required() setting on the server
yes no optional
tls-required() setting on the client yes TLS-encryption rejected connection TLS-encryption
no rejected connection unencrypted connection unencrypted connection
optional TLS-encryption unencrypted connection TLS-encryption if the tls() option is set, unencrypted connection otherwise

Setting tls-required(optional) on your server allows you to receive both encrypted and unencrypted connections on the same port.

Examples for using RLTP™

Examples for using RLTP

Example 12.1. Simple RLTP™ connection

The sender and the receiver use RLTP™ over the network() protocol. Since the tls() option is not configured neither on the sender nor on the receiver, the communication will be unencrypted.

Receiver configuration (syslog-ng PE server):

source s_network_rltp {
        network(
            ip("127.0.0.1")
            port("5555")
            transport(rltp)
            ip-protocol(4)
        );
};

Sender configuration (syslog-ng PE client):

destination d_network_rltp {
        network(
            "127.0.0.1"
            port("5555")
            transport(rltp)
            ip-protocol(4)
        );
};

Example 12.2. RLTP™ with TLS encryption

The following example configure a sender and a receiver to communicate using RLTP™. Since the tls-required() option is set to optional on the receiver and yes on the sender, and the tls() option is configured, the communication will be TLS-encrypted. For the sender (syslog-ng PE client), reliable disk-buffering is enabled to prevent data loss.

Receiver configuration (syslog-ng PE server):

source s_syslog_rltp {
        syslog(
            ip("127.0.0.1")
            port("4444")
            transport(rltp(tls-required(optional)))
            ip-protocol(4)
            tls(
                peer-verify(required-trusted)
                ca-dir("/var/tmp/client/")
                key-file("/var/tmp/server/server_priv.key")
                cert-file("/var/tmp/server/server.crt")
            )
        );
};

Sender configuration (syslog-ng PE client):

destination d_syslog_rltp {
        syslog(
            "127.0.0.1"
            port("4444")
            transport(rltp(tls-required(yes)))
            ip-protocol(4)
            disk-buffer( mem-buf-size(200000) disk-buf-size(2000000) reliable(yes) )
            tls(
                peer-verify(required-trusted)
                ca-dir("/var/tmp/server/")
                key-file("/var/tmp/client/client_priv.key")
                cert-file("/var/tmp/client/client.crt")
            )
        );
};

Chapter 13. Reliability and minimizing the loss of log messages

Introduction

Reliable Log Transfer Protocol™ (RLTP™) interacts with flow control and disk buffering to ensure that the loss of log messages is minimized or is prevented completely. This section explains how each loss prevention method contributes to reliability and minimizing log message loss. Flow control, disk buffering, and RLTP are explained in detail elsewhere in the document. In this section, we present a high-level overview of all of these mechanisms and highlight considerations such as:

  • What best practices exist in various scenarios, how to set key parameters

  • When is a log message considered "delivered"

  • Under what circumstances can log loss occur

Each of the following sections discusses a different scenario and uses figures to aid comprehension.

NOTE:

Each figure depicts a scenario in which the volume of incoming messages makes it necessary to use all buffers and control windows at maximum capacity.

Important information: 

Any of the mechanisms that syslog-ng PE uses to prevent or minimize the loss of log messages only works if the hardware and operating system work normally. When there is an issue with the hardware or operating system that the application and syslog-ng PE run on, log loss may occur. Issues include operating system crash (for example, kernel panic), memory errors, disk errors, power outage, and so on.

Flow control, no disk buffering, no RLTP™

Flow control, no disk buffering, no RLTP

How it works: 

log-iw-size() sets a control window that tracks how many messages syslog-ng PE can accept. Every source has its own control window. If the window gets full, syslog-ng PE stops reading messages from the sources until some messages are successfully sent to the destination(s).

Figure 13.1. Flow control, no disk buffering, no RLTP

Flow control, no disk buffering, no RLTP™

How to set key parameters: 

Set flags(flow-control) in the log path.

The output buffer must be large enough to store the incoming messages of every connected source:

log-fifo-size() > sum of log-iw-size() of sources connected to this destination

Benefits: 

This configuration minimizes the loss of log messages in the following situations:

  • Unreachable destination server(s): Only as many incoming log messages are read as can be "delivered". When flow control is used, those messages are considered delivered that have been written to the output buffer. When the output buffer is full, syslog-ng PE stops reading messages from the connected sources. This means that no log messages get lost.

    NOTE:

    In case the application is sending its log messages through a blocking I/O socket, then it is the application that stops sending new log messages and waits until the previous batch has been delivered. If the application is not sending logs through a blocking I/O socket, then it will keep sending messages (regardless of whether or not the previous batch has been delivered), and this can result in the loss of log messages. For example, it is not possible to apply flow control in the case of a UDP source.

Drawbacks: 

While this configuration gives you the fastest processing time, it has some limitations. It does not provide protection against the loss of log messages in the following situations:

  • TCP error: In the case of a TCP connection, when messages are sent from the destination drivers to the destination servers, messages are written to the TCP socket. The TCP socket sends an acknowledgement to the destination drivers once it has successfully processed messages. A message is considered "delivered" when no error occurs during the process of writing the data to the socket, and the acknowledgement is received. Note, however, that if something goes wrong after messages have been successfully written to the TCP socket, log messages can still get lost. Also note that TCP errors can occur on both the source and the destination side, and both can cause the loss of log messages.

  • Message loss outside of syslog-ng PE: Because syslog-ng PE stores only a small number of log messages in the memory, it is possible to lose messages outside of syslog-ng. For example, if the output buffer is full because the server is not reachable, syslog-ng PE will not read the source, meaning that the external application that generates the logs can drop the logs. If you want to minimize the risk, use disk buffering. For details, see the section called “Flow control, normal disk buffering, no RLTP™” and the section called “Flow control, reliable disk buffering, no RLTP™”.

  • Message loss when syslog-ng PE is stopped or restarted: When syslog-ng is stopped or restarted, the contents of the output buffers are lost. If you want to minimize the risk, use disk buffering. For details, see the section called “Flow control, normal disk buffering, no RLTP™” and the section called “Flow control, reliable disk buffering, no RLTP™”.

  • When syslog-ng PE is not able to operate normally (for example, when syslog-ng PE crashes due to some unforeseen event): Log messages that were in the output buffer when the issue occurred get lost because those messages are stored in the memory.

Related Documents