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