bionic (8) tsocks.8.gz

Provided by: tsocks_1.8beta5+ds1-1ubuntu1_amd64 bug

NAME

       tsocks  -  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/libtsocks.so

       C Shell -

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

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

       tsocks 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 ~/.tsocks.conf and if that file cannot be accessed, to /etc/tsocks.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.

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

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

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

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

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

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

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

   DNS ISSUES
       tsocks 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
       tsocks  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 TSOCKS_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
       tsocks 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 libtsocks 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

       tsocks can only proxy outgoing TCP connections

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

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

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

       tsocks  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/tsocks.conf - default tsocks configuration file

SEE ALSO

       tsocks.conf(5) tsocks(1)

AUTHOR

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

       Copyright 2000 Shaun Clowes

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