TSOCKS(8)						      System Manager's Manual							 TSOCKS(8)

NAME

       tsocks - Library for intercepting outgoing network connections and redirecting them through a SOCKS server.

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=/lib/libtsocks.so

       C Shell -

       setenv LD_PRELOAD=/lib/libtsocks.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 tsocks(1) script

       You can also setup tsocks 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

       tsocks  is  a  library to allow transparent SOCKS proxying. It wraps the normal connect() function. When a connection is attempted, it con-
       sults the configuration file (which is defined at configure time but defaults to ~/.tsocks.conf and if that file  cannot  be  accessed,	to
       /etc/tsocks.conf) and determines if the IP address specified is local. If it is not, the library redirects the connection to a SOCKS server
       specified in the configuration file. It then negotiates that connection with the SOCKS server and passes the connection back to the calling
       program.

       tsocks  is  designed for use in machines which are firewalled from then internet. It avoids the need to recompile applications like lynx or
       telnet so they can use SOCKS to reach the internet. It behaves much like the SOCKSified TCP/IP stacks seen on other platforms.

   ARGUMENTS
       Most arguments to tsocks  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/tsocks.conf). The structure of this file is documented in tsocks.conf(8)

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

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

       TSOCKS_DEBUG
	      This  environment  variable sets the level of debug output that should be generated by tsocks (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 tsocks to generate more messages describing what it is
	      doing. If set to -1 tsocks will output absolutely no error or debugging messages. This is only needed if	tsocks	output	interferes
	      with  a program it is embedded in. Message output can be permanently compiled out of tsocks by specifying the --disable-debug option
	      to configure at build time

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

       TSOCKS_USERNAME
	      This environment variable can be used to specify the username to be used when version  5	SOCKS  servers	request  username/password
	      authentication.  This  overrides	the  default  username	that  can be specified in the configuration file using 'default_user', see
	      tsocks.conf(8) for more information. This variable is ignored for version 4 SOCKS servers.

       TSOCKS_PASSWORD
	      This environment variable can be used to specify the password to be used when version  5	SOCKS  servers	request  username/password
	      authentication.  This  overrides	the  default  password	that  can be specified in the configuration file using 'default_pass', see
	      tsocks.conf(8) for more information. This variable is ignored for version 4 SOCKS servers.

   DNS ISSUES
       tsocks will normally not be able to send DNS queries through a SOCKS server since SOCKS V4 works on TCP and DNS normally uses UDP.  Version
       1.5  and  up  do however provide a method to force DNS lookups to use TCP, which then makes them proxyable. This option can only enabled at
       compile time, please consult the INSTALL file for more information.

   ERRORS
       tsocks will generate error messages and print them to stderr when there are problems with the configuration file or the	SOCKS  negotiation
       with  the  server  if the TSOCKS_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
       tsocks will not in the above configuration be able to provide SOCKS 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 libtsocks 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

       tsocks can only proxy outgoing TCP connections

       tsocks  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)

       tsocks is NOT fully RFC compliant in its implementation of version 5 of SOCKS, it only supports the 'username and password' or 'no  authen-
       tication'  authentication  methods. The RFC specifies GSSAPI must be supported by any compliant implementation. I haven't done this, anyone
       want to help?

       tsocks can force the libc resolver to use TCP for name queries, if it does this it does it regardless of whether  or  not  the  DNS  to	be
       queried is local or not. This introduces overhead and should only be used when needed.

       tsocks  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/tsocks.conf - default tsocks configuration file

SEE ALSO

       tsocks.conf(5) tsocks(1)

AUTHOR

       Shaun Clowes (delius@progsoc.uts.edu.au)

COPYRIGHT

       Copyright 2000 Shaun Clowes

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

       This documentation 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

Shaun Clowes																 TSOCKS(8)