xenial (5) tsocks.conf.5.gz

Provided by: tsocks_1.8beta5-9.3_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