trusty (5) tsocks.conf.5.gz

Provided by: tsocks_1.8beta5-9.2_amd64 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 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