tsocks.conf - configuration file for tsocks(8)
The configuration for tsocks can be anything from two lines to
hundreds of lines based on the needs at any particular site. The basic idea
is to define any networks the machine can access directly (i.e without the
use of a SOCKS server) and define one or many SOCKS servers to be used to
access other networks (including a 'default' server).
Local networks are declared using the 'local' keyword in the
configuration file. When applications attempt to connect to machines in
networks marked as local tsocks will not attempt to use a SOCKS server to
negotiate the connection.
Obviously if a connection is not to a locally accessible network
it will need to be proxied over a SOCKS server. However, many installations
have several different SOCKS servers to be used to access different internal
(and external) networks. For this reason the configuration file allows the
definition of ´paths´ as well as a default SOCKS server.
Paths are declared as blocks in the configuration file. That is,
they begin with a 'path {' line in the configuration file and end with a '}'
line. Inside this block directives should be used to declare a SOCKS server
(as documented later in this manual page) and 'reaches' directives should be
used to declare networks and even destination ports in those networks that
this server should be used to reach. N.B Each path MUST define a SOCKS
server and contain one or more 'reaches' directives.
SOCKS server declaration directives that are not contained within
a 'path' block define the default SOCKS server. If tsocks needs to connect
to a machine via a SOCKS server (i.e it isn't a network declared as 'local')
and no 'path' has declared it can reach that network via a 'reaches'
directive this server is used to negotiate the connection.
The basic structure of all lines in the configuration file is:
<directive> = <parameters>
The exception to this is 'path' blocks which look like:
path {
<directive> = <parameters>
}
Empty lines are ignored and all input on a line after a '#'
character is ignored.
The following directives are used in the tsocks configuration
file:
- server
- The IP address of the SOCKS server (e.g "server = 10.1.4.253").
Only one server may be specified per path block, or one outside a path
block (to define the default server). Unless --disable-hostnames was
specified to configure at compile time the server can be specified as a
hostname (e.g "server = socks.nec.com")
- server_port
- The port on which the SOCKS server receives requests. Only one server_port
may be specified per path block, or one outside a path (for the default
server). This directive is not required if the server is on the standard
port (1080).
- server_type
- SOCKS version used by the server. Versions 4 and 5 are supported (but both
for only the connect operation). The default is 4. Only one server_type
may be specified per path block, or one outside a path (for the default
server).
You can use the inspectsocks utility to determine the type of
server, see the 'UTILITIES' section later in this manual page.
- default_user
- This specifies the default username to be used for username and password
authentication in SOCKS version 5. In order to determine the username to
use (if the socks server requires username and password authentication)
tsocks first looks for the environment variable TSOCKS_USERNAME, then
looks for this configuration option, then tries to get the local username.
This option is not valid for SOCKS version 4 servers. Only one
default_user may be specified per path block, or one outside a path (for
the default server)
- default_pass
- This specified the default password to be used for username and password
authentication in SOCKS version 5. In order to determine the password to
use (if the socks server requires username and password authentication)
tsocks first looks for the environment variable TSOCKS_PASSWORD, then
looks for this configuration option. This option is not valid for SOCKS
version 4 servers. Onle one default_pass may be specified per path block,
or one outside a path (for the default server)
- local
- An IP/Subnet pair specifying a network which may be accessed directly
without proxying through a SOCKS server (e.g "local =
10.0.0.0/255.0.0.0"). Obviously all SOCKS server IP addresses must be
in networks specified as local, otherwise tsocks would need a SOCKS server
to reach SOCKS servers.
- reaches
- This directive is only valid inside a path block. Its parameter is formed
as IP[:startport[-endport]]/Subnet and it specifies a network (and a range
of ports on that network) that can be accessed by the SOCKS server
specified in this path block. For example, in a path block "reaches =
150.0.0.0:80-1024/255.0.0.0" indicates to tsocks that the SOCKS
server specified in the current path block should be used to access any
IPs in the range 150.0.0.0 to 150.255.255.255 when the connection request
is for ports 80-1024.
- fallback
- This directive allows one to fall back to direct connection if no default
server present in the configuration and fallback = yes. If fallback = no
or not specified and there is no default server, the tsocks gives an error
message and aborts. This parameter protects the user against accidentally
establishing unwanted unsockified (ie. direct) connection.
tsocks will search first for $HOME/.tsocks.conf then
/etc/tsocks.conf
tsocks comes with two utilities that can be useful in creating and
verifying the tsocks configuration file.
- inspectsocks
- inspectsocks can be used to determine the SOCKS version that a server
supports. Inspectsocks takes as its arguments the ip address/hostname of
the SOCKS server and optionally the port number for socks (e.g
'inspectsocks socks.nec.com 1080'). It then inspects that server to
attempt to determine the version that server supports.
- validateconf
- validateconf can be used to verify the configuration file. It checks the
format of the file and also the contents for errors. Having read the file
it dumps the configuration to the screen in a formatted, readable manner.
This can be extremely useful in debugging problems.
validateconf can read a configuration file from a location
other than the location specified at compile time with the -f
<filename> command line option.
Normally validateconf simply dumps the configuration read to
the screen (in a nicely readable format), however it also has a useful
'test' mode. When passed a hostname/ip on the command line like -t
<hostname/ip>, validateconf determines which of the SOCKS servers
specified in the configuration file would be used by tsocks to access
the specified host.
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