
socks5.cfg - configuration file for OS2 socks version 5 server

DESCRIPTION
The socks5 configuration file contains information that is read by the socks
proxy server the first time it is invoked.  This file contains all the information
the server needs in determining which interface to use to reach a given address,
whether to connect directly to a given address or to use another proxy server,
and what requirements need to be met for a proxy connection to be made.
In each of the following sections, lines are read in order until a match is made
for that section, in other words, the order of the lines is *very* important.
For a line to match, each entry within a line must match.

There are five sections to the configuration file: authentication, routing,
variables/flags, proxies, and access control.  The following entries are used
within certain sections and deserve some clarification first.

SPECIFYING PORTS
Ports can be specified with either a name, number, or range.  Ranges begin with
either a [ or ( and end with either a ) or a ] depending on whether or not the
rang is inclusive.  Within the range delimiters should be two port specifiers
(names or numbers), separated by a comma.  The method of specifying ports is
referred to as the portpattern.  

SPECIFYING HOSTS
Host addresses and netmasks are often need for specifying which hosts apply
within a given rule.  There are several ways to specify the host/mask pair.
This method of specifying host is referred to as the hostpattern.

hostip/mask
to match, a host address "anded" with mask must be the same as hostip "anded"
with the mask.  This is usually used to "mask" out the host portion of the
address from the network or subnetwork portion.  

-
anything matches.  All hosts are allowed.

n1.
equivalent to n1.0.0.0/255.0.0.0

n1.n2.
equivalent to n1.n2.0.0/255.255.0.0

n1.n2.n3.
equivalent to n1.n2.n3.0/255.255.255.0

.domain.name
hostname must end with the string .domain.name.

a.host.name
hostname must match exactly with a.host.name.

There is also support for the older hostpattern syntax.  The older method
is still supported, but the newer method is recommended and easier to read.

hostip/a
all match, same as "-".  

hostip/n
network match.  Masks out the host and subnet portions of the address to leave
only the network portion.  The mask used to do this depends on the class of IP
address of hostip.

hostip/s
subnet match.  Masks out the host portion of the address to leave the subnetwork
and network portion.  The mask used to do this depends on the class of IP
address of hostip.

hostip/h
host match.  Equivalent to hostip.

SPECIFYING AUTHENTICATION METHODS
Authentication methods can be specified as a comma separated list of letters.
For a line to match, the chosen authentication method has to be reperesented by 
one of the letters in the list.  This syntax will be referred to later as a
authpattern.  The following letters correspond to the following methods.

n
No authentication.

u
Username/Password.

k
Kerberos 5 (GSS-API).

-
any authentication method.

SPECIFYING COMMANDS
Commands can also be specified as a comma separated list of letters.  This
syntax will be referred to later as a commandpattern.  The following 
letters correspond to the following commands.

c
for connect.

b
for bind.

u
for udp.

-
for any command.

AUTHENTICATION ENTRIES
The authentication entries indicate the type(s) of authentication that can be
used.  The lines in the configuration file to handle authentication have the
form: 

auth source-address source-port auth-methods

The keyword "auth" is used to denote authentication entries.  
source-address must be a valid hostpattern, source-port 
can must be a valid portpattern, and auth-methods must be a valid
auth-pattern.  

The keyword "ban" is used to denote that authentication should not even be
attempted with this host, it has no valid use of this server.  

If no auth or ban lines are specified, the default is that any authentication
will work.  The default permission however is to deny the connection, but this
would take place after authentication.  There has been a lot of confusion about
why auth lines exist at all.  The simples explanation is that in the socks5
protocol, authentication takes place before authorization.  Since this is the
case, you must decide based solely on the host how that host is to
authenticate.  This forces that decision to be obvious.

Another common question is how to make sure that usernames are supplied
since the first method chose by default is null authentication, which unless
configured to demand ident responses (see socks5.txt), supplies no user 
information.  One way to do this (and still allow Socks4 clients to use the
server) is to sett the auth order to be "un" instead of the default, so that
Socks5 will hopefully pick "u" instead of "n", but still allow Socks4 to succeed
with Null authentication.

ROUTING ENTRIES
On machines with multiple interfaces (hence IP addresses), it is sometimes
desirable to make sure that certain interfaces are used in conjunction with
certain addresses.  This prevents outside machines from pretending to be
inside ones by making sure that inside machines use the inside interface and
outside ones use the outside interface.  It is also used by the socks server in
determining what interface to bind on when accepting in a BIND request, or when
issueing a SENDTO request.  If no entry matches, INADDR_ANY is used to bind, and
a connection can be received on any interface.  Single-homed hosts need not have
routing entries -- they are only necessary for machines with more than one
interface.

route dest-addr dest-port interface-address

The keyword "route" is used to denote routing entries.  dest-addr
must be a valid hostpattern, dest-port must be a valid
portpattern, and interface-address can be either the ip address of
an interface card or the name of the interface (e.g. lan0).

VARIABLE ENTRIES
The amount and types of logging and informational messages can be 
controlled by certain variables and flags in the configuration file.
The lines in the configuration file to handle variables have the form: 

set variable value

The keyword "set" is used to denote entries which set environment
variables for internal use.  See the ENVIRONMENT section of Socks5.txt for 
a list of settable variables.

PROXY ENTRIES
Proxy entries describe the addresses accessible through other SOCKS servers.
These lines tell the server how to contact a given host.  If no lines match a
host, the host is contacted directly.   
 
proxy-type dest-addr dest-port proxy-addr proxy-port

The proxy-type specifies the type of proxy server.  Valid entries are: 

socks5
socks version 5.

socks4
socks version 4.

noproxy
no proxy.  i.e. direct connections.

The dest-addr must be a valid hostpattern and the dest-port
must be a valid portpattern.  The proxy-addr is the ip address or
name of the proxy server and the proxy-port is the port on the proxy
server that the socks daemon is accepting connections on. 

ACCESS CONTROL ENTRIES
The access control section determines if a request to establish a connection is
permitted or denied.  There are 2 types of lines, permit lines and
deny lines, which are self-explainatory. Each line has the form:

permit auth cmd src-host dest-host src-port dest-port [userlist]

deny auth cmd src-host dest-host src-port dest-port [userlist]

auth specifies a list of authentication methods one of which must have
succeeded for this line to match and is specified by a valid authpattern
auth entry.  command specifies which commands will be matched by this
line and must be a valid commandpattern.  source-host and
dest-host must be valid hostpatterns.  source-port and
dest-port must be valid portpatterns.  Finally, the userlist
must be a valid userpattern.  Each of the above entries must match for the
entire line to match.


SEE ALSO
libcfg.txt


