SIMPLE SOLUTIONS

LIBDONTDIE(7) - Linux man page online | Overview, conventions, and miscellany

A library that sets the TCP keep-alive flag when applications call socket(2).

Chapter
2015-03-07
libdontdie(7) TCP keepalive support lib libdontdie(7)

NAME

libdontdie - a library that sets the TCP keep-alive flag when applications call socket(2)

DESCRIPTION

libdontdie is a shared library that can be injected into any application with the LD_PRELOAD mechanism. It is completely transparent to the application and therefore works equally well with closed-source programs and with languages like Java that do not natively allow changing the TCP keep-alive parameters.

BACKGROUND

In theory, a TCP connection that is not explicitly closed remains open forever. In prac‐ tice, this does not work out when connection-tracking firewalls along the way drop their state, and all further traffic, for a connection that was idle for a certain time. The result is that both the TCP client and server believe the connection to be open but the firewall inhibits all further communication. This kind of connection failure will be reported to the participating applications only after they attempt to send further data and all TCP timeouts and retransmits expire. In situation where only one of the communication partners ever sends anything, e.g. the client waiting for HTTP chunked data, it can be impossible to distinguish between a con‐ nection closed by a firewall and connected-but-idle. To handle and/or prevent this kind of situation, TCP has a keep-alive mechanism. It con‐ sists of TCP packets sent periodically over an otherwise idle connection to "refresh" the associated state along the whole path. If not acknowledged the same retry-mechanism is used as for regular data packets, however independent of whether there is any data to send. Finally all unanswered keep-alive packets leads to a TCP error that can be detected by the application. By default the first TCP KEEP ALIVE packet is send after two hours, which is too long for most scenarios. The Linux kernel offers the possibility to change the TCP keep-alive timeout globally for the whole system. However this solution requires root privileges and does not work when different applications require different timeouts on the same machine. In some programming languages an appropriate API call can be used to enable TCP keep-alive (e.g. setsockopt(2) in C). Other languages like Java do not support changing these param‐ eters. libdontdie can be used for applications that are written in languages that do not support setting the TCP KEEP ALIVE parameters. It can also be used to enable TCP keep-alive for closed-source or commercial applications. libdontdie can be used on a case-by-case basis, selectively enabling TCP keep-alive for some application instances without changing any source code. All parameters are passed to libdontdie in the form of environment variables.

TCP KEEP ALIVE PARAMETERS

Three parameters are used to change the TCP keep-alive behaviour. All parameters are in seconds. The variable names are taken from the Linux kernel configuration with a 'DD_' prefix for 'libDontDie'. The corresponding kernel parameters can be found in '/proc/sys/net/ipv4/'. DD_TCP_KEEPALIVE_TIME The time between the last TCP data packet sent and the first TCP KEEP ALIVE packet / probe. DD_TCP_KEEPALIVE_INTVL The interval between two TCP KEEP ALIVE packets / probes. DD_TCP_KEEPALIVE_PROBES The number of keep-alive probes sent before the socket enters an error state.

LIBDONTDIE PARAMETERS

Two additional parameters change the behaviour of libdontdie itself: libdontdie: DD_DEBUG If this is set to '1', each 'socket(2)' call will be logged to syslog - including all parameters and actions performed by libdontdie. DD_EVAL_ENVIRONMENT_ONCE If this is set to '1' or not specified at all, all parameters are only evaluated once dur‐ ing startup. If this parameter is set to '0', each time a socket call is executed, all parameters are evaluated again. This makes it possible to change parameters at runtime. When setting this to '0', there is a bigger per socket call overhead therefore the perfor‐ mance will decrease. In languages that do not support setting the TCP KEEP ALIVE parameters, this is a work‐ around to enable different setting for different sockets. setenv("DD_TCP_KEEPALIVE_TIME", 60); socket(...); .... setenv("DD_TCP_KEEPALIVE_TIME", 180); socket(...);

INSTALLATION LOCATION

Depending on the installation method or the distribution, the installation directory of libdontdie might differ. One way to get the installation directory is using the packet manager to list all files of the packet (like 'dpkg -L <package_name>'). Typically the library is installed in a directory under /usr/lib, /usr/lib64, or /usr/lib/<triple>. A typical triple is 'x86_64-linux-gnu'. Under Debian it is possible to get the triple with the command dpkg-architecture -qDEB_HOST_GNU_TYPE

USAGE

All parameters are passed in as environment variables. The libdontdie itself is pre‐ loaded. The example assumes, that the library is installed under '/usr/lib/libdontdie.so'. This might be replaced by the real installation path. Example: to run the java program EchoClient with special TCP KEEP ALIVE setting, use: DD_DEBUG=1 DD_TCP_KEEPALIVE_TIME=4 DD_TCP_KEEPALIVE_INTVL=5 \ DD_TCP_KEEPALIVE_PROBES=6 LD_PRELOAD=/usr/lib/libdontdie.so \ java EchoClient 127.0.0.1 22

SEE ALSO

socket(2), setsockopt(2)

HISTORY

The idea was first implemented in libkeepalive by Fabio Busatto. Because of some limita‐ tions regarding functionality and license, it was completely rewritten, corrected and extended.

AUTHOR

Written by Andreas Florath (@florath.net)
Copyright © 2015 by Andreas Florath (@florath.net). License MIT.
TCP keepalive support lib 2015-03-07 libdontdie(7)
This manual Reference Other manuals
libdontdie(7) referred by
refer to getsockopt(2) | socket(2)
Download raw manual
Index TCP keepalive support lib (+1) TCP keepalive support lib (+1) № 7 (+1560)
Go top