From 53c9f468dc86bad581f785231c34a8bec4445cf7 Mon Sep 17 00:00:00 2001 From: Abilio Marques Date: Sun, 21 Feb 2021 10:19:10 +0100 Subject: [PATCH] network: add documentation for TCP keepalive probes Signed-off-by: Abilio Marques --- administration/networking.md | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/administration/networking.md b/administration/networking.md index 4049f7de6..8802c716d 100644 --- a/administration/networking.md +++ b/administration/networking.md @@ -18,20 +18,38 @@ On environments with multiple network interfaces, might be desired to choose whi The `net.source_address` allows to specify which network address must be used for a TCP connection and data flow. -### TCP Keepalive +### Connection Keepalive TCP is a _connected oriented_ channel, to deliver and receive data from a remote end-point in most of cases we use a TCP connection. This TCP connection can be created and destroyed once is not longer needed, this approach has pros and cons, here we will refer to the opposite case: keep the connection open. -The concept of `TCP Keepalive` refers to the ability of the client \(Fluent Bit on this case\) to keep the TCP connection open in a persistent way, that means that once the connection is created and used, instead of close it, it can be recycled. This feature offers many benefits in terms of performance since communication channels are always established before hand. +The concept of `Connection Keepalive` refers to the ability of the client \(Fluent Bit on this case\) to keep the TCP connection open in a persistent way, that means that once the connection is created and used, instead of close it, it can be recycled. This feature offers many benefits in terms of performance since communication channels are always established before hand. Any component that uses TCP channels like HTTP or [TLS](security.md), can take advantage of this feature. For configuration purposes use the `net.keepalive` property. -### TCP Keepalive Idle Timeout +### Connection Keepalive Idle Timeout -If a TCP connection is keepalive enabled, there might be scenarios where the connection can be unused for long periods of time. Having an idle keepalive connection is not helpful and is recommendable to keep them alive if they are used. +If a connection is keepalive enabled, there might be scenarios where the connection can be unused for long periods of time. Having an idle keepalive connection is not helpful and is recommendable to keep them alive if they are used. In order to control how long a keepalive connection can be idle, we expose the configuration property called `net.keepalive_idle_timeout`. +### TCP Keepalive + +An open TCP connection to a remote server is subject to be _silently dropped_ by intermediate equipment in the network (e.g., routers) if it's quiet for too long. What _too long_ means depends on manufacturers and configurations outside of the control of fluentbit. + +If you're using the _Connection Keepalive_ feature, but not achieving the desired connectivity rates, you might want to try setting `net.tcp_keepalive` to `on`. This will configure the socket to periodically send _keepalive probes_ if the connection is silent. These probes will be sent all the way to the server, making the equipment in between consider the connection as active. Is then expected that the server will acknowledge the probe, allowing fluentbit to detect a broken connection right away. + +### TCP Keepalive Time + +If TCP keepalive is used, `net.tcp_keepalive_time` allows to override the OS default configuration with the desired period to wait between the last data packet is sent and TCP keepalive probing starts. + +### TCP Keepalive Interval + +If TCP keepalive is used, `net.tcp_keepalive_interval` allows to override the OS default configuration with the desired period between probes if the first one fails to be acknowledged. + +### TCP Keepalive Probes + +If TCP keepalive is used, `net.tcp_keepalive_probes` allows to override the OS default configuration with the desired number of unacknowledged probes before deeming a connection dead. + ## Configuration Options For plugins that relies on networking I/O, the following section describes the network configuration properties available and how they can be used to optimize performance or adjust to different configuration needs: @@ -40,9 +58,12 @@ For plugins that relies on networking I/O, the following section describes the n | :--- | :--- | :--- | | `net.connect_timeout` | Set maximum time expressed in seconds to wait for a TCP connection to be established, this include the TLS handshake time. | 10 | | `net.source_address` | Specify network address \(interface\) to use for connection and data traffic. | | -| `net.keepalive` | Enable or disable TCP keepalive support. Accepts a boolean value: on / off. | on | +| `net.keepalive` | Enable or disable connection keepalive support. Accepts a boolean value: on / off. | on | | `net.keepalive_idle_timeout` | Set maximum time expressed in seconds for an idle keepalive connection. | 30 | - +| `net.tcp_keepalive` | Enable or disable TCP keepalive support. Accepts a boolean value: on / off. | off | +| `net.tcp_keepalive_time` | Interval between the last data packet sent and the first TCP keepalive probe. | | +| `net.tcp_keepalive_interval` | Interval between TCP keepalive probes when no response is received on a keepidle probe. | | +| `net.tcp_keepalive_probes` | Number of unacknowledged probes to consider a connection dead. | | ## Example As an example, we will send 5 random messages through a TCP output connection, in the remote side we will use `nc` \(netcat\) utility to see the data.