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

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

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.