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

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 consults the configuration file (which is
defined at configure time but defaults to /etc/torsocks.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.

torsocks is designed for use in machines which are firewalled from the 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 --disable-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 interferes 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 torsocks.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 torsocks.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. 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
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 difficult 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 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/torsocks.conf - default torsocks configuration file

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 published 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