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 practice, 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 connection closed by a firewall and connected-but-idle.
To handle and/or prevent this kind of situation, TCP has a keep-alive mechanism. It consists 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 parameters.
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 during 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 performance will decrease.In languages that do not support setting the TCP KEEP ALIVE parameters, this is a workaround 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 preloaded.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