Ubuntu Manpage: tsocks.conf - configuration file for tsocks(8)

NAME

       tsocks.conf - configuration file for tsocks(8)

OVERVIEW

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

CONFIGURATION SYNTAX

The basic structure of all lines in the configuration file is:

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.

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

UTILITIES

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.

AUTHOR

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

COPYRIGHT