Ubuntu Manpage: tnat64 - Library for intercepting outgoing network connections and redirecting them

NAME

       tnat64  -  Library  for  intercepting  outgoing  network  connections and redirecting them
       through the NAT64.

SYNOPSIS

       Set LD_PRELOAD to load the library then use applications as normal

       The syntax to force preload of the library for different shells is specified below:

       Bash, Ksh and Bourne shell -

       export LD_PRELOAD=/usr/lib/tnat64/libtnat64.so

       C Shell -

       setenv LD_PRELOAD=/usr/lib/tnat64/libtnat64.so

       This process can be automated (for Bash, Bourne and Korn shell users) for a single command
       or for all commands in a shell session by using the tnat64(1) script

       You  can  also  setup tnat64 in such a way that all processes automatically use it, a very
       useful configuration. For more information on this configuration see the  CAVEATS  section
       of this manual page.

DESCRIPTION

tnat64 is a library to allow IPv4-only application to access IPv4 hosts on IPv6-only
systems by using NAT64. It wraps the normal connect() function. When a connection is
attempted, it consults the configuration file (which is defined at configure time but
defaults to /etc/tnat64.conf) and determines if the IP address specified is local. If it
is not, the library redirects the connection to an IPv6 address inside the NAT64 prefix
that is specified in the configuration file. The redirection is performed only if the
destination host is unreachable (when there's no route to host). Also, after the first
successful redirection all the following connection attempts are redirected immediately
without even trying to connect to the host via IPv4. When the destination host cannot be
reached via IPv6, the redirection is disabled.

tnat64 avoids the need to recompile applications so they can use reach hosts even if they
do not support IPv6 and there's no IPv4 connectivity.

tnat64 is heavily based on the source code of tsocks, a library that intercepts outgoing
TCP connections and redirects them though SOCKS proxy. Many thanks for tsocks author,
Shaun Clowes!

ARGUMENTS
Most arguments to tnat64 are provided in the configuration file (the location of which is
defined at configure time by the --with-conf=<file> argument but defaults to
/etc/tnat64.conf). The structure of this file is documented in tnat64.conf(8)

Some configuration options can be specified at run time using environment variables as
follows:

TNAT64_CONF_FILE
This environment variable overrides the default location of the tnat64
configuration file. This variable is not honored if the program tnat64 is embedded
in is setuid. In addition this environment variable can be compiled out of tnat64
with the --disable-envconf argument to configure at build time

TNAT64_DEBUG
This environment variable sets the level of debug output that should be generated
by tnat64 (debug output is generated in the form of output to standard error). If
this variable is not present by default the logging level is set to 0 which
indicates that only error messages should be output. Setting it to higher values
will cause tnat64 to generate more messages describing what it is doing. If set to
-1 tnat64 will output absolutely no error or debugging messages. This is only
needed if tnat64 output interferes with a program it is embedded in. Message output
can be permanently compiled out of tnat64 by specifying the --disable-debug option
to configure at build time

TNAT64_DEBUG_FILE
This option can be used to redirect the tnat64 output (which would normally be sent
to standard error) to a file. This variable is not honored if the program tnat64 is
embedded in is setuid. For programs where tnat64 output interferes with normal
operation this option is generally better than disabling messages (with
TNAT64_DEBUG = -1)

ERRORS
tnat64 will generate error messages and print them to stderr when there are problems with
the configuration file if the TNAT64_DEBUG environment variable is not set to -1 or and
--disable-debug was not specified at compile time. This output may cause some problems
with programs that redirect standard error.

CAVEATS
tnat64 will not in the above configuration be able to provide proxying to setuid
applications or applications that are not run from a shell. You can force all applications
to LD_PRELOAD the library by placing the path to libtnat64 in /etc/ld.so.preload. Please
make sure you correctly enter the full path to the library in this file if you do this. If
you get it wrong, you will be UNABLE TO DO ANYTHING with the machine and will have to boot
it with a rescue disk and remove the file (or try the saveme program, see the INSTALL file
for more info). THIS IS A ***WARNING***, please be careful. Also be sure the library is
in the root filesystem as all hell will break loose if the directory it is in is not
available at boot time.

BUGS

       tnat64 can only proxy outgoing TCP connections

       tnat64 does NOT work correctly with asynchronous sockets (though it  does  work  with  non
       blocking  sockets).  This  bug  would  be very difficult to fix and there appears to be no
       demand for it (I know of no major application that uses asynchronous sockets)

       tnat64 uses ELF dynamic loader features to intercept dynamic function calls from  programs
       in  which  it  is embedded.  As a result, it cannot trace the actions of statically linked
       executables, non-ELF executables, or executables that make system calls directly with  the
       system call trap or through the syscall() routine.

FILES

       /etc/tnat64.conf - default tnat64 configuration file

AUTHORS

       Andrew O. Shadura (bugzilla@tut.by), Shaun Clowes (delius@progsoc.uts.edu.au)

COPYRIGHT

       Copyright 2011 Andrew O. Shadura

       Original tsocks manual page, copyright 2000 Shaun Clowes

       tnat64  and  its  documentation  may  be  freely  copied under the terms and conditions of
       version 2 of the GNU General Public License, as published by the Free Software  Foundation
       (Cambridge, Massachusetts, United States of America).

       This  documentation  is  heavily  based  on  the  documentation  for  tsocks,  transparent
       SOCKSification library, whose documentation itself  is  based  on  the  documentation  for
       logwrites, another shared library interceptor. One line of code from it was used in tsocks
       and a lot of the documentation :) logwrites is by adam@yggdrasil.com (Adam J. Richter) and
       can be had from ftp.yggdrasil.com pub/dist/pkg