TSOCKS.CONF(5)							File Formats Manual						    TSOCKS.CONF(5)

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 net-
       works 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  installa-
       tions  have several different SOCKS servers to be used to access different internal (and external) networks. For this reason the configura-
       tion 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 con-
       nect 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:

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

   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 vari-
	      able  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 vari-
	      able 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 net-
	      work (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 pro-
	      tects the user against accidentally establishing unwanted unsockified (ie. direct) connection.

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

SEE ALSO

       tsocks(8)

AUTHOR

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

COPYRIGHT

       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 pub-
       lished 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

Shaun Clowes															    TSOCKS.CONF(5)