Provided by: tork_0.26-0ubuntu3_i386 bug

NAME

       torksocks.conf - configuration file for torksocks(8)

OVERVIEW

       The  configuration  for  torksocks  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  torksocks  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  torksocks  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 torksocks 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 inspectorksocks 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) torksocks first looks  for
              the environment variable TORKSOCKS_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) torksocks first looks  for
              the environment variable TORKSOCKS_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 torksocks
              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  torksocks  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.

       tordns_enable
              This enables the use of the ’tordns’ feature in torksocks, which
              overrides  the  standard  C library name resolution calls to use
              SOCKS.    The default value is

       tordns_deadpool_range
              Tor hidden sites do not have real IP addresses.  This  specifies
              what  range of IP addresses will be handed to the application as
              "cookies" for .onion names.  Of course, you should pick a  block
              of  addresses  which  you  aren’t going to ever need to actually
              connect to. The default value is ’127.0.69.0/255.255.255.0’.

       tordns_cache_size
              This specifies the number of  IP  addresses  looked  up  through
              SOCKS  to cache.  The default value is 256.  Each entry consumes
              260 bytes of  memory,  so  the  default  adds  66,560  bytes  of
              overhead  to  each ’torified’ process. NOTE: if the number of IP
              addresses  in  tordns_deadpool_range  is  less  than  the  value
              specified  for  tordns_cache_size, then the cache will be shrunk
              to fit the deadpool range. This is to prevent duplicate deadpool
              addresses from ever appearing in the cache.

UTILITIES

       torksocks  comes  with two utilities that can be useful in creating and
       verifying the torksocks configuration file.

       inspectorksocks
              inspectorksocks can be used to determine the SOCKS version  that
              a  server  supports.  Inspectorksocks takes as its arguments the
              ip address/hostname of the SOCKS server and optionally the  port
              number  for socks (e.g ’inspectorksocks 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 torksocks to access the specified host.

SEE ALSO

       torksocks(8)

AUTHOR

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

COPYRIGHT

       Copyright 2000 Shaun Clowes Renamed for use by Tork to  avoid  conflict
       with tsocks by Robert Hogan.

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