|
|
Caution:
Note that in earlier versions of syslog-ng Premium Edition, Advanced Log Transport Protocol is called Reliable Log Transfer Protocol (RLTP). |
The syslog-ng PE application can send and receive log messages in a reliable way over the TCP transport layer using the Advanced Log Transport Protocol (ALTP). ALTP is a proprietary transport protocol that prevents message loss during connection breaks. The transport is used between syslog-ng PE hosts (for example, a client and a server, or a client-relay-server), and interoperates with the mechanisms of syslog-ng PE's flow-control and the reliable disk-buffer option, thus providing the best way to prevent message loss. The sender detects which messages the receiver has successfully received. If messages are lost during the transfer, the sender resends the missing messages, starting from the last successfully received message. Therefore, messages are not duplicated at the receiving end in case of a connection break (however, in failover mode, this is not completely ensured).
ALTP also allows for encrypted and non-encrypted connections to be received on the same port, using a single source driver.
NOTE: Because of the communication overhead, the ALTP protocol is slower than other transport protocols, which might be a problem if you need to collect a high amount (over 200000 messages per second) of log messages on your log server. For performance details of syslog-ng PE see the syslog-ng Premium Edition Performance Guideline at the syslog-ng Premium Edition Documentation page.
NOTE: Make sure that you have set the value of the log_msg_size() parameter large enough in your configuration. If its size is less than the size of the sent messages, it might result in disk fill-up and no incoming logs.
|
|
Caution:
In the following cases, it is possible to lose log messages even if you use ALTP:
-
If you use ALTP together with the non-reliable disk-buffer option, it is possible to lose logs.
-
When sending logs through a relay that is using the non-reliable disk-buffer option, it is possible to lose logs if the relay crashes.
-
When sending logs through a relay that is using the non-reliable disk-buffer option, it is possible that logs are duplicated if the relay crashes, or it is stopped.
-
If the underlying disk system of syslog-ng PE fails to write the log messages to the disk, but it does not return a write error, or some other hardware or operating-system error happens. |
The ALTP protocol works on top of TCP, and can use STARTTLS for encryption. ALTP supports IPv4 and IPv6 addresses. Inside the ALTP message, the message can use any format, for example, RFC3164 (BSD-syslog) or RFC5424 (IETF-syslog). The default port of ALTP is 35514.
ALTP can be added to the configuration like a transport protocol within the syslog() driver and the network() driver.
This procedure summarizes how two syslog-ng PE hosts (a sender and a receiver) communicate using the Advanced Log Transport Protocol (ALTP).
Prerequisites
The sender (also called the client) is the host that has ALTP configured in its destination driver. The receiver (also called the server) is the host that has ALTP configured in its source driver.
-
The sender initiates the connection to the receiver.
-
The sender and the receiver negotiate whether to encrypt the connection and to use compression or not.
-
If the connection should be encrypted, the sender and the receiver perform authentication (as configured in the tls() options of their configuration).
-
If the sender and the receiver have communicated earlier using ALTP, the receiver indicates which was the last message received from the sender.
-
The sender starts sending messages in batches. Batch size depends on the batch-size() parameter of the sender.
For optimal performance when sending messages to a syslog-ng PE server, make sure that the batch-size() is smaller than the window size set using the log-iw-size() option in the source of your server.
-
When the receiver has successfully processed the messages in the batch, it sends an acknowledgment of the processed messages to the sender.
What "successfully processed" means depends on the configuration of the receiver, for example, written to disk in a destination, forwarded to a remote destination using not ALTP, dropped because of filter settings, or written to the disk-buffer. (If the messages are forwarded using ALTP, see Using ALTP in a client-relay-server scenario.)
-
After receiving the acknowledgment, the sender sends another batch of messages.
|
|
Caution:
Note that in earlier versions of syslog-ng Premium Edition, Advanced Log Transport Protocol is called Reliable Log Transfer Protocol (RLTP). |
You can use ALTP between multiple syslog-ng PE hosts, for example, in a client-relay-server scenario. In this case, the communication described in How ALTP connections work applies both between the client and the relay, and the relay and the server. However, note the following points:
-
Unless you use disk-buffer on the relay, the relay waits for acknowledgment from the server before acknowledging the messages to the client. If you send the messages in large batches, and the server can process the messages slowly (or the network connection is slow), you might have to adjust the message-acknowledgment-timeout() on the client.
-
If you use reliable disk-buffer on the relay, the relay will acknowledge the messages when the messages are written to the disk-buffer. That way, the client does not have to wait for the server to acknowledge the messages.
The following options are specific to the ALTP protocol. Note that when using ALTP in a source or a destination, the options of the syslog() or the network() driver can be used as well.
|
|
Caution:
Note that in earlier versions of syslog-ng Premium Edition, Advanced Log Transport Protocol is called Reliable Log Transfer Protocol (RLTP). |
allow-plain-compress()
| Accepted values: |
yes | no |
| Default: |
no |
Description: Enable on-the-wire compression in the ALTP 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-plain-compress() option can be used in source and destination drivers as well. Available in syslog-ng PE 7.0.12 and later. Note that in earlier versions, the name of this option was allow-compress().
batch-size()
| Accepted values: |
number |
| Default: |
1000 |
Description: Specifies the number of lines that are sent to a destination at a time. The syslog-ng PE application waits for this number of lines to accumulate and sends them off in a single batch. Setting this number high increases throughput as fully filled frames are sent to the network, but also increases message latency. Available in syslog-ng PE 7.0.10 and later.
message-acknowledgment-timeout()
| Type: |
number (seconds) |
| Default: |
900 |
Description: When the receiver (syslog-ng PE server) receives and successfully processes a message, it sends an acknowledgment 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 acknowledgment, which is governed by the message-acknowledgment-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 the server side and tls-required(no) on the 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 ALTP 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 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.
