libdontdie - a library that sets the TCP keep-alive flag when applications call
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
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
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
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.
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.
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
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
The time between the last TCP data packet sent and the first TCP KEEP ALIVE
packet / probe.
The interval between two TCP KEEP ALIVE packets / probes.
The number of keep-alive probes sent before the socket enters an error state.
Two additional parameters change the behaviour of libdontdie itself:
If this is set to '1', each 'socket(2)' call will be logged to syslog -
including all parameters and actions performed by libdontdie.
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.
Depending on the installation method or the distribution, the installation
directory of libdontdie
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
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
Example: to run the java program EchoClient with special TCP KEEP ALIVE setting,
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
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.
Written by Andreas Florath (firstname.lastname@example.org)
Copyright © 2015 by Andreas Florath (email@example.com). License