Provided by: libdontdie0_1.2.0-1_amd64 
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 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
SEE ALSO
socket(2), setsockopt(2)
HISTORY
The idea was first implemented in libkeepalive by Fabio Busatto. Because of some limitations regarding
functionality and license, it was completely rewritten, corrected and extended.
AUTHOR
Written by Andreas Florath (andreas@florath.net)
COPYRIGHT
Copyright © 2015 by Andreas Florath (andreas@florath.net). License MIT.