TORSOCKS

NAME

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

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

ERRORS

CAVEATS

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

SEE ALSO

AUTHOR

COPYRIGHT

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

Index

NAME

SYNOPSIS

DESCRIPTION

ARGUMENTS

DNS ISSUES

ERRORS

CAVEATS

BUGS

FILES

SEE ALSO

AUTHOR

COPYRIGHT