Provided by: libdontdie0_1.2.0-1_amd64 bug

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.