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

NAME

       torsocks - 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/libtorsocks.so

       C Shell -

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

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

       torsocks  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 /etc/torsocks.conf) and determines if the IP address spec-
       ified  is  local. If it is not, the library redirects the connection to a SOCKS server specified in the configuration file. It then negoti-
       ates that connection with the SOCKS server and passes the connection back to the calling program.

       torsocks 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  torsocks  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/torsocks.conf). The structure of this file is documented in torsocks.conf(8)

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

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

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

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

       TORSOCKS_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  tor-
	      socks.conf(8) for more information. This variable is ignored for version 4 SOCKS servers.

       TORSOCKS_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  tor-
	      socks.conf(8) for more information. This variable is ignored for version 4 SOCKS servers.

   DNS ISSUES
       torsocks  will  normally not be able to send DNS queries through a SOCKS server since SOCKS V4 works on TCP and DNS normally uses UDP. Ver-
       sion 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
       torsocks 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 TORSOCKS_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
       torsocks 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 libtorsocks  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

       torsocks can only proxy outgoing TCP connections

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

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

       torsocks  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.

       torsocks uses ELF dynamic loader features to intercept dynamic function calls from programs in which it is embedded.  As a result, it  can-
       not 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/torsocks.conf - default torsocks configuration file

SEE ALSO

       torsocks.conf(5) torsocks(1) usewithtor(1)

AUTHOR

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

COPYRIGHT

       Copyright 2000 Shaun Clowes

       Renamed for use by torsocks to avoid conflict with tsocks by Robert Hogan.

       torsocks 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
       torsocks 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															       TORSOCKS(8)