Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
TSOCKS(8)							     TSOCKS(8)

       tsocks  -  Library  for	intercepting  outgoing network connections and
       redirecting them	through	a SOCKS	server.

       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=/usr/local/lib/

       C Shell -

       setenv LD_PRELOAD=/usr/local/lib/

       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 automati-
       cally use it, a very useful configuration. For more information on this
       configuration see the CAVEATS section of	this manual page.

       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 /usr/local/etc/tsocks.conf) and determines if	the IP address	speci-
       fied  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.

       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    /usr/lo-
       cal/etc/tsocks.conf). The structure  of	this  file  is	documented  in

       Some  configuration options can be specified at run time	using environ-
       ment variables as follows:

	      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	 envi-
	      ronment  variable	 can be	compiled out of	tsocks with the	--dis-
	      able-envconf argument to configure at build time

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

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

	      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.

	      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.

       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  com-
       pile time, please consult the INSTALL file for more information.

       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.

       Linuxspecific:  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/	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.

       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 ap-
       plication 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 authentica-
       tion' authentication methods. The RFC specifies	GSSAPI	must  be  sup-
       ported  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

       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 executa-
       bles, or	executables that make system calls directly  with  the	system
       call trap or through the	syscall() routine.

       /usr/local/etc/tsocks.conf - default tsocks configuration file

       tsocks.conf(5) tsocks(1)

       Shaun Clowes (

       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 J.	Richter) and can be had	from pub/dist/pkg

Shaun Clowes							     TSOCKS(8)


Want to link to this manual page? Use this URL:

home | help