Chat now with support
Chat mit Support

syslog-ng Premium Edition 7.0.18 - Administration Guide

Preface Introduction to syslog-ng The concepts of syslog-ng Installing syslog-ng The syslog-ng PE quick-start guide The syslog-ng PE configuration file Collecting log messages — sources and source drivers
How sources work default-network-drivers: Receive and parse common syslog messages internal: Collecting internal messages file: Collecting messages from text files wildcard-file: Collecting messages from multiple text files linux-audit: Collecting messages from Linux audit logs network: Collecting messages using the RFC3164 protocol (network() driver) office365: Fetching logs from Office 365 osquery: Collect and parse osquery result logs pipe: Collecting messages from named pipes program: Receiving messages from external applications python: writing server-style Python sources python-fetcher: writing fetcher-style Python sources snmptrap: Read Net-SNMP traps sun-streams: Collecting messages on Sun Solaris syslog: Collecting messages using the IETF syslog protocol (syslog() driver) system: Collecting the system-specific log messages of a platform systemd-journal: Collecting messages from the systemd-journal system log storage systemd-syslog: Collecting systemd messages using a socket tcp, tcp6, udp, udp6: Collecting messages from remote hosts using the BSD syslog protocol udp-balancer: Receiving UDP messages at very high rate unix-stream, unix-dgram: Collecting messages from UNIX domain sockets windowsevent: Collecting Windows event logs
Sending and storing log messages — destinations and destination drivers
elasticsearch2: Sending messages directly to Elasticsearch version 2.0 or higher (DEPRECATED) elasticsearch-http: Sending messages to Elasticsearch HTTP Event Collector file: Storing messages in plain-text files hdfs: Storing messages on the Hadoop Distributed File System (HDFS) http: Posting messages over HTTP kafka: Publishing messages to Apache Kafka logstore: Storing messages in encrypted files mongodb: Storing messages in a MongoDB database network: Sending messages to a remote log server using the RFC3164 protocol (network() driver) pipe: Sending messages to named pipes program: Sending messages to external applications python: writing custom Python destinations smtp: Generating SMTP messages (email) from logs splunk-hec: Sending messages to Splunk HTTP Event Collector sql: Storing messages in an SQL database stackdriver: Sending logs to the Google Stackdriver cloud syslog: Sending messages to a remote logserver using the IETF-syslog protocol syslog-ng(): Forward logs to another syslog-ng node tcp, tcp6, udp, udp6: Sending messages to a remote log server using the legacy BSD-syslog protocol (tcp(), udp() drivers) unix-stream, unix-dgram: Sending messages to UNIX domain sockets usertty: Sending messages to a user terminal — usertty() destination Client-side failover
Routing messages: log paths, flags, and filters Global options of syslog-ng PE TLS-encrypted message transfer Advanced Log Transfer Protocol Reliability and minimizing the loss of log messages Manipulating messages parser: Parse and segment structured messages Processing message content with a pattern database Correlating log messages Enriching log messages with external data Monitoring statistics and metrics of syslog-ng Multithreading and scaling in syslog-ng PE Troubleshooting syslog-ng Best practices and examples The syslog-ng manual pages Glossary

Flow control, no disk-buffer option, no ALTP

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 33: Flow control, no disk-buffer option, no ALTP

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: With 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 acknowledgment 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 acknowledgment 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 the disk-buffer option. For details, see Flow control, normal disk-buffer option, no ALTP and Flow control, reliable disk-buffer option, no ALTP.
  • 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 the disk-buffer option. For details, see Flow control, normal disk-buffer option, no ALTP and Flow control, reliable disk-buffer option, no ALTP.
  • 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.

Flow control, normal disk-buffer option, no ALTP

How it works
  1. syslog-ng PE puts messages into the disk-buffer file (set via disk-buf-size()) when the destination becomes unavailable or when it is not able to process logs as fast as they arrive through the sources.
  2. When the disk-buffer file is full, syslog-ng PE puts messages into the memory buffer (set via mem-buf-length()). When the memory buffer gets full too, then syslog-ng PE stops the source (flow-control mechanism).

Figure 34: Flow control, normal disk buffering, no ALTP

How to set key parameters

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

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

mem-buf-length() > sum of log-iw-size() of sources connected to this destination

Configure the disk-buffer option. For details, see Example: Example configuration of the normal disk-buffer option.

Example: Example configuration of the normal disk-buffer option
disk-buffer(
	mem-buf-length(20000) # storing 20000 messages in memory, sum log-iw-size of sources should be less than 20000 to use flow-control
	disk-buf-size(2147483648) # storing 2 GB of messages on disk
	reliable(no)
)
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 in combination with disk buffering, messages that have been written to the disk-buffer file and/or the memory buffer are considered delivered. When the memory buffer becomes full, syslog-ng PE stops reading messages from the configured sources. This means that no log messages get lost.
  • Message loss outside of syslog-ng PE: The greatest advantage of this configuration over when the disk-buffer option is not used at all is that when the log-iw-size() control window is full, the flow-control mechanism stops reading logs from the sources much later. This is because when it is not possible to send logs directly to the destinations, they are first written to the disk and then the memory buffer. It is only after both the disk-buffer file and the memory buffer have been filled to their full capacity that the sources are stopped. This enables you to minimize the loss of log messages during peak hours or when the network is temporarily down.
  • Message loss when syslog-ng PE is stopped or restarted: When syslog-ng is stopped or restarted, the contents of the memory buffer and the disk-buffer file are flushed to disk, meaning that no log loss occurs.

    NOTE:

    In rare cases, the buffers stored on the disk can become corrupted, in which case syslog-ng PE may not able to process all the logs stored in the disk-buffer file.

Drawbacks

One drawback of using the disk-buffer option is that the processing of log messages by syslog-ng PE is slower.

This configuration does not provide protection against the loss of log messages in the following situations:

  • TCP error: With 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 acknowledgment 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 acknowledgment 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.
  • 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.

Flow control, reliable disk-buffer option, no ALTP

How it works

syslog-ng puts messages into the disk-buffer file, until the disk-buffer file size reaches disk-buf-size(). Above that size, flow control is triggered. syslog-ng PE completely stops reading incoming messages from the source, making the control window (governed by log_iw_size()) fill up and blocking the sources.

In this configuration, log messages are stored on the disk (and not in the memory), which increases reliability.

Figure 35: Flow control, reliable disk-buffer, no ALTP

How to set key parameters

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

Configure the disk-buffer option. For details, see Example: Example configuration of the reliable disk-buffer.

Example: Example configuration of the reliable disk-buffer
disk-buffer(
	mem-buf-size(10485760) # storing 10 MB messages in memory and on disk
	disk-buf-size(2147483648) # storing 2 GB of messages only on disk
	reliable(yes)
)
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 in combination with the disk-buffer option, those messages are considered delivered that have been written to the disk-buffer file. As soon as the disk-buffer file is full, syslog-ng PE stops reading messages. This means that no log messages get lost.
  • Message loss outside of syslog-ng PE: One of the advantages of this configuration over when the disk-buffer option is not used at all is that when the log-iw-size() control window is full, the flow-control mechanism stops reading logs from the sources much later. This is because when it is not possible to send logs directly to the destinations, they are written to the disk. It is only after the disk-buffer file has been filled to its full capacity that the sources are stopped. This allows you to minimize the loss of log messages during peak hours or when the network is temporarily down.
  • Message loss when syslog-ng PE is stopped or restarted: When syslog-ng is stopped or restarted, the contents of the disk-buffer file do not get lost, greatly increasing reliability.

    Also note that the memory buffer is only used as a cache in this configuration. Any data stored in the memory has already been written to the disk-buffer file, which, again, results in more reliability.

    NOTE:

    In rare cases, the buffers stored on the disk can become corrupted, in which case syslog-ng PE may not able to process all the logs stored in the disk-buffer file.

  • When syslog-ng PE is not able to operate normally (for example, when syslog-ng PE crashes due to some unforeseen event): No messages get lost because the disk-buffer option is persistent and when the disk-buffer file is full, syslog-ng PE stops reading messages from the sources. When syslog-ng PE is restarted after a crash, it automatically recovers any unsent messages from the disk-buffer file and the output buffer. After the restart, syslog-ng PE sends the saved messages to the destination.
Drawbacks

One drawback of using the reliable disk-buffer option is that the processing of log messages by syslog-ng PE is slower than when messages are stored in the output buffer only, or when using the normal disk-buffer option.

This configuration does not provide protection against the loss of log messages in the following situations:

  • TCP error: With 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 acknowledgment 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 acknowledgment 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.

Flow control, reliable disk-buffer option, ALTP

How it works
NOTE:

The example presented here is set in a client-relay-server scenario.

  1. The sender sends messages in batches (set via batch-size()).
  2. The relay writes messages to the disk-buffer file.
  3. Once messages have been written to the disk-buffer file, the relay returns an acknowledgment to the client.

  4. The relay sends messages to the server in batches (set via batch-size()).
  5. When the server has successfully received and processed the messages in the batch, it sends an acknowledgment of the processed messages to the relay.

    It is only at this point that the relay removes log messages from the disk-buffer file because this is when logs are considered "delivered" to the server.

    After receiving the acknowledgment, the sender sends another batch of messages.

This configuration gives you the greatest degree of protection against log message loss. ALTP provides acknowledgment about the successful processing of log messages at the level of the application layer. Even if the reception of log messages has been acknowledged by TCP at the transport layer, log messages are considered delivered only when the syslog-ng PE application has received an acknowledgment from the other syslog-ng PE instance about the successful delivery of log messages.

This mechanism guarantees that log messages are not lost between the client and the relay, or between the relay and the server, or on the relay itself. To minimize the risk of message loss on the client or the server, use flow control and reliable disk-buffer.

Figure 36: Flow control, reliable disk-buffer, ALTP

How to set key parameters

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

Configure the disk-buffer option. For details, see Example: Example configuration of the reliable disk-buffer.

Example: Example configuration of the reliable disk-buffer
disk-buffer(
	mem-buf-size(10485760) # storing 10 MB messages in memory and on disk
	disk-buf-size(2147483648) # storing 2 GB of messages only on disk
	reliable(yes)
)

Enable ALTP by setting transport(rltp). For details, see ALTP options.

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 in combination with reliable disk buffering and ALTP, those messages are considered delivered by the very first source driver that have been written to the disk buffer. syslog-ng PE will not read new messages until the previous batch has been written to the disk buffer.
  • TCP error: With 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 acknowledgment to the destination drivers once it has successfully processed messages. However, while the acknowledge messages sent by the TCP socket implement flow control at the transport layer, ALTP introduces flow control at the application layer. This means that log messages are only considered delivered when the ALTP acknowledge message is returned at the level of the syslog-ng application. That is to say, when a TCP error occurs, messages that have been written to the disk-buffer file do not get lost.
  • Message loss outside of syslog-ng PE: One of the advantages of this configuration over when the disk-buffer option is not used at all is that when the log-iw-size() control window is full, the flow-control mechanism stops reading logs from the sources much later. This is because when it is not possible to send logs directly to the destinations, they are written to the disk. It is only after the disk-buffer file has been filled to its full capacity that the sources are stopped. This allows you to minimize the loss of log messages during peak hours or when the network is temporarily down.
  • Message loss when syslog-ng PE is stopped or restarted: When syslog-ng is stopped or restarted, the contents of the disk-buffer file do not get lost, greatly increasing reliability.

    Also note that the memory buffer is only used as a cache in this configuration. Any data stored in the memory has already been written to the disk-buffer file, which, again, results in more reliability.

    NOTE:

    In rare cases, the buffers stored on the disk can become corrupted, in which case syslog-ng PE may not able to process all the logs stored in the disk-buffer file.

  • When syslog-ng PE is not able to operate normally (for example, when syslog-ng PE crashes due to some unforeseen event): No messages get lost because the disk-buffer option is persistent and when the disk-buffer file is full, syslog-ng PE stops reading messages from the sources. When syslog-ng PE is restarted after a crash, it automatically recovers any unsent messages from the disk-buffer file and the output buffer. After the restart, syslog-ng PE sends the saved messages to the destination.
Drawbacks

This configuration results in the slowest processing time out of all the options described in this chapter.

Verwandte Dokumente