1TSOCKS(8) System Manager's Manual TSOCKS(8)
2
6 tsocks - Library for intercepting outgoing network connections and
7 redirecting them through a SOCKS server.
8
11 Set LD_PRELOAD to load the library then use applications as normal
12 The syntax to force preload of the library for different shells is
14 specified below:
15 Bash, Ksh and Bourne shell -
17 export LD_PRELOAD=libtsocks.so
19 C Shell -
21 setenv LD_PRELOAD=libtsocks.so
23 This process can be automated (for Bash, Bourne and Korn shell users)
25 for a single command or for all commands in a shell session by using
26 the tsocks(1) script
27 You can also setup tsocks in such a way that all processes automati‐
29 cally use it, a very useful configuration. For more information on this
30 configuration see the CAVEATS section of this manual page.
31
34 tsocks is a library to allow transparent SOCKS proxying. It wraps the
35 normal connect() function. When a connection is attempted, it consults
36 the configuration file (which is defined at configure time but defaults
37 to /etc/tsocks.conf) and determines if the IP address specified is
38 local. If it is not, the library redirects the connection to a SOCKS
39 server specified in the configuration file. It then negotiates that
40 connection with the SOCKS server and passes the connection back to the
41 calling program.
42 tsocks is designed for use in machines which are firewalled from then
44 internet. It avoids the need to recompile applications like lynx or
45 telnet so they can use SOCKS to reach the internet. It behaves much
46 like the SOCKSified TCP/IP stacks seen on other platforms.
47 ARGUMENTS
50 Most arguments to tsocks are provided in the configuration file (the
51 location of which is defined at configure time by the --with-
52 conf=<file> argument but defaults to /etc/tsocks.conf). The structure
53 of this file is documented in tsocks.conf(8)
54 Some configuration options can be specified at run time using environ‐
56 ment variables as follows:
57 TSOCKS_CONF_FILE
60 This environment variable overrides the default location of the
61 tsocks configuration file. This variable is not honored if the
62 program tsocks is embedded in is setuid. In addition this envi‐
63 ronment variable can be compiled out of tsocks with the --dis‐
64 able-envconf argument to configure at build time
65 TSOCKS_DEBUG
68 This environment variable sets the level of debug output that
69 should be generated by tsocks (debug output is generated in the
70 form of output to standard error). If this variable is not
71 present by default the logging level is set to 0 which indicates
72 that only error messages should be output. Setting it to higher
73 values will cause tsocks to generate more messages describing
74 what it is doing. If set to -1 tsocks will output absolutely no
75 error or debugging messages. This is only needed if tsocks out‐
76 put interferes with a program it is embedded in. Message output
77 can be permanently compiled out of tsocks by specifying the
78 --disable-debug option to configure at build time
79 TSOCKS_DEBUG_FILE
82 This option can be used to redirect the tsocks output (which
83 would normally be sent to standard error) to a file. This vari‐
84 able is not honored if the program tsocks is embedded in is
85 setuid. For programs where tsocks output interferes with normal
86 operation this option is generally better than disabling mes‐
87 sages (with TSOCKS_DEBUG = -1)
88 TSOCKS_USERNAME
91 This environment variable can be used to specify the username to
92 be used when version 5 SOCKS servers request username/password
93 authentication. This overrides the default username that can be
94 specified in the configuration file using 'default_user', see
95 tsocks.conf(8) for more information. This variable is ignored
96 for version 4 SOCKS servers.
97 TSOCKS_PASSWORD
100 This environment variable can be used to specify the password to
101 be used when version 5 SOCKS servers request username/password
102 authentication. This overrides the default password that can be
103 specified in the configuration file using 'default_pass', see
104 tsocks.conf(8) for more information. This variable is ignored
105 for version 4 SOCKS servers.
106 DNS ISSUES
109 tsocks will normally not be able to send DNS queries through a SOCKS
110 server since SOCKS V4 works on TCP and DNS normally uses UDP. Version
111 1.5 and up do however provide a method to force DNS lookups to use TCP,
112 which then makes them proxyable. This option can only enabled at com‐
113 pile time, please consult the INSTALL file for more information.
114 ERRORS
117 tsocks will generate error messages and print them to stderr when there
118 are problems with the configuration file or the SOCKS negotiation with
119 the server if the TSOCKS_DEBUG environment variable is not set to -1 or
120 and --disable-debug was not specified at compile time. This output may
121 cause some problems with programs that redirect standard error.
122 CAVEATS
125 tsocks will not in the above configuration be able to provide SOCKS
126 proxying to setuid applications or applications that are not run from a
127 shell. You can force all applications to LD_PRELOAD the library by
128 placing the path to libtsocks in /etc/ld.so.preload. Please make sure
129 you correctly enter the full path to the library in this file if you do
130 this. If you get it wrong, you will be UNABLE TO DO ANYTHING with the
131 machine and will have to boot it with a rescue disk and remove the file
132 (or try the saveme program, see the INSTALL file for more info). THIS
133 IS A ***WARNING***, please be careful. Also be sure the library is in
134 the root filesystem as all hell will break loose if the directory it is
135 in is not available at boot time.
136
139 tsocks can only proxy outgoing TCP connections
140 tsocks does NOT work correctly with asynchronous sockets (though it
142 does work with non blocking sockets). This bug would be very difficult
143 to fix and there appears to be no demand for it (I know of no major
144 application that uses asynchronous sockets)
145 tsocks is NOT fully RFC compliant in its implementation of version 5 of
147 SOCKS, it only supports the 'username and password' or 'no authentica‐
148 tion' authentication methods. The RFC specifies GSSAPI must be sup‐
149 ported by any compliant implementation. I haven't done this, anyone
150 want to help?
151 tsocks can force the libc resolver to use TCP for name queries, if it
153 does this it does it regardless of whether or not the DNS to be queried
154 is local or not. This introduces overhead and should only be used when
155 needed.
156 tsocks uses ELF dynamic loader features to intercept dynamic function
158 calls from programs in which it is embedded. As a result, it cannot
159 trace the actions of statically linked executables, non-ELF executa‐
160 bles, or executables that make system calls directly with the system
161 call trap or through the syscall() routine.
162
165 /etc/tsocks.conf - default tsocks configuration file
166
169 tsocks.conf(5) tsocks(1)
170
173 Shaun Clowes (delius@progsoc.uts.edu.au)
174
177 Copyright 2000 Shaun Clowes
178 tsocks and its documentation may be freely copied under the terms and
180 conditions of version 2 of the GNU General Public License, as published
181 by the Free Software Foundation (Cambridge, Massachusetts, United
182 States of America).
183 This documentation is based on the documentation for logwrites, another
185 shared library interceptor. One line of code from it was used in tsocks
186 and a lot of the documentation :) logwrites is by adam@yggdrasil.com
187 (Adam J. Richter) and can be had from ftp.yggdrasil.com pub/dist/pkg
188Shaun Clowes TSOCKS(8)