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

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

Shaun Clowes                                                                                         TORSOCKS(8)