Provided by: tork_0.30-2_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´  as  well  as  a
       default SOCKS server.

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

       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