Provided by: tsocks_1.8beta5-9.1_i386 bug

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:

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

       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.

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