socks5.conf(5)socks5.conf(5)NAMEsocks5.conf - Configuration file for the socks5 daemon
SYNOPSIS
The socks5 daemon usually reads the configuration file in
/etc/socks5.conf. When you configure and build socks5 with
the
--with-srvconffile=filename
option, you can change the directory. Under FreeBSD's UNIX
port, the configuration file resides in
/usr/local/etc/socks5.conf.
DESCRIPTION
The socks5 daemon reads the configuration file when it
starts and each time it receives an HUP signal. The con
figuration file contains the information the server needs
to determine:
- the interface to use to reach an address
- when the server should connect directly to an
address
- when the server should use another proxy server
- the necessary requirements to make a proxy connec
tion
The configuration file contains six sections:
- ban host
- authentication
- interfaces
- variables and flags
- proxies
- access control
In each section, the socks5 daemon sequentially reads each
line until it encounters a matching line for that section.
The order of sections and the order of lines within a sec
tion are crucial to achieving the desired result. Every
entry in a line must match.
BAN HOST ENTRIES
Ban host entries identify hosts from which the socks5 dae
mon should not accept connections and use the syntax:
ban source-host source-port
ban Indicates not to attempt authentication
source-host Must be a valid hostpattern
source-port Must be a valid portpattern
The socks5 daemon refuses connections originating from
clients on source-port at source-host.
AUTHENTICATION ENTRIES
Authentication entries identify the types of authentica
tion the socks5 daemon can use. Authentication lines use
the syntax:
auth source-host source-port auth-methods
auth Identifies the entry as an authentication
entry
source-host Must be a valid hostpattern
source-port Must be a valid portpattern
auth-methods Must be a valid authpattern
The socks5 daemon authenicates clients that originate on
source-port at source-host using auth-methods.
When the configuration file does not contain auth lines,
any authentication works. Omitting auth lines is the same
as specifying an authpattern containing -, any authentica
tion. If auth lines are used, clients not matching will
be refused.
When the socks5 daemon does not require authentication, it
receives no user information unless socks5 configuration
requires ident responses. Use the SOCKS5_DEMAND_IDENT
environment variable to require ident responses. See
socks5(1) for a complete description of socks5 environment
variables.
To ensure that the socks5 daemon receives usernames from
the client, and to allow socks4 clients to use the server,
set the authpattern order to n,u. With socks5 clients, the
socks daemon chooses Username/Password authentication
before no authentication.
The socks5 daemon checks auth-methods in reverse order,
beginning with the last auth-method in authpattern.
INTERFACE ENTRIES
On machines with multiple interfaces, and therefore multi
ple IP addresses, frequently administrators want to ensure
that socks5 uses certain interfaces with certain
addresses. This prevents outside machines from impersonat
ing inside machines by requiring inside machines to use
the inside interface and outside machines to use the out
side interface. It also allows socks5 to determine on
which interface to bind when accepting a bind request, or
when issuing a sendto request.
When socks5 fails to find a match in the configuration
file, it uses INADDR_ANY to bind, and receives a connec
tion on any interface.
Single-homed hosts do not require interface entries. Only
machines with more than one interface should use interface
entries.
Use this format for interface entries in the socks5.conf
file:
interface hostpattern portpattern interface-address
interface Identifies interface entries
hostpattern Contains a source or destination host
for a connection
portpattern Contains a source or destination port
for a connection pattern
interface-address Identifies the IP address of an inter
face card or the name of the interface,
for example le0.
When hostpattern or portpattern specify a source address,
the patterns define the interface-address clients must use
to connect to the socks5 server when connecting from the
host defined in hostpattern or the port defined in port_
pattern. Connection attempts from interface addresses
other than interface-address fail.
When hostpattern or portpattern specify a destination
address, the patterns define the interface address the
socks5 daemon uses to connect to the host defined in host_
pattern or the port defined in portpattern.
The interface entry replaces the route entry of previous
releases. For the current release, the entries are equiv
alent. In future releases, support for route entries may
be removed.
VARIABLE ENTRIES
Variables and flags in the configuration file control the
amount and types of logging and information messages. The
configuration file syntax for initializing variables is:
set variable value
set Identifies entries that initialize environment
variables for internal use.
Refer to the socks5(1) ENVIRONMENT section for complete
details about socks5 environment variables and values.
PROXY ENTRIES
Proxy entries describe the addresses clients can only
reach through other SOCKS servers and identify how the
daemon contacts the host. The daemon contacts the host
directly when the configuration file does not contain an
entry for that host.
proxy-type dest-host dest-port proxy-list
proxy-type Specifies the type of proxy server. Valid
entries include:
socks5 SOCKSv5
socks4 SOCKS version 4
noproxy Make direct connection
dest-host Must be a valid hostpattern
dest-port Must be a valid portpattern
proxy-list Must be a valid proxypattern and identifies
the proxy server(s) to use.
The daemon uses the servers in proxy-list to connect to
dest-port on dest-host. The servers is proxy-list must be
the same type servers as proxy-type.
ACCESS CONTROL ENTRIES
The access control section determines when the server per
mits or denies a request to establish a connection. The
socks5 daemon denies a request if an access control line
does not match the request, even after it has authenti
cated the host.
There are two types of lines, permit lines and deny lines,
with this syntax:
permit auth cmd src-host dest-host \
src-port dest-port [user-list]
deny auth cmd src-host dest-host \
src-port dest-port [user-list]
auth Must be a valid authpattern and specifies a
list of authentication methods.
cmd Must be a valid commandpattern and specifies
the commands clients on src-host can execute
on dest-host.
src-host Must be a valid hostpattern
dest-host Must be a valid hostpattern
src-port Must be a valid portpattern
dest-port Must be a valid portpattern
user-list Must be a valid userpattern.
The entire line matches only when all the entries match.
PATTERNShostpattern
socks5 requires host addresses and netmasks to determine
the hosts that apply to a socks5.conf entry. Specify the
host/mask pair as a hostpattern, using the format:
hostip/mask Matches when a host address bitwise anded
with the mask equals the hostip anded with
the mask. Use the hostip/mask to mask the
host portion of the address from the net
work or subnetwork portion.
- all hosts match
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 .domain.name
a.host.name hostname must match exactly with
a.host.name.
If domain names are used, SOCKS5_REVERSEMAP must be set.
Because hostnames and domains depend on DNS, using IP
addresses and netmasks is recommended. In many cases,
reverse DNS maps are not implemented or incorrect.
Although socks5.conf supports older hostpattern syntax, we
recommend using the newer method. The newer method is also
easier to read. The older hostpattern syntax is:
hostip/a all hosts match, same as "-"
hostip/n network match. Masks the host and sub
net portions of the address, leaving
the network portion. The IP address
class for hostip determines the mask.
hostip/s subnet match. Masks the host portion
of the address, leaving the subnetwork
and network portion. The IP address
class for hostip determines the mask.
hostip/h host match, the same as hostip
portpattern
Specify ports in a portpattern as a service name, number,
or range. Enclose ranges in brackets to indicate the range
is inclusive, or parentheses to indicate the range is non-
inclusive. Specify the range as two port names or numbers,
separated by a comma, with no white space.
tftp the service port for tftp, usually
port 69
80 port 80
- all ports
[100,1000] ports 100 through 1000
(100,1000) ports 101 through 999
(100,1000] ports 101 through 1000
authpattern
Specify authentication methods in an authpattern as a
comma separated list of letters, with no white space. The
socks5 daemon checks auth-methods in reverse order,
beginning with the last auth-method in authpattern.
socks5.conf recognizes these authentication methods:
n No authentication. If you built the socks5
daemon with ident, the server authenticates
UNIX users.
u Username/Password
k Kerberos 5 (GSS-API)
- any authentication method
The last auth-method listed takes precedence over the
methods listed first. For example, if you list:
n,u,k
the server requests Kerberos authentication for socks5
clients. If the socks5 client is not set up to use Ker
beros, the server uses Username/Password authentication.
Since SOCKS4 clients can not use Kerberos or User
name/Password authentication, the server does not require
authentication for SOCKS4 clients.
If you list:
n,k,u
the server requests Username/Password authentication for
socks5 clients. Since SOCKS4 clients can not use User
name/Password or Kerberos authentication, the server does
not require authentication for SOCKS4 clients.
commandpattern
Specify commands in a commandpattern as a comma separated
list of letters, with no white space. socks5.conf recog
nizes these commands:
c connect
b bind
u UDP
p ping
t traceroute
- all commands
userpattern
Specify multiple users in a userpattern as a comma sepa
rated list of individual users, with no white space and no
wild card patterns.
The user type must match the authentication method. For
example, when you specify Username/Password authentica
tion, the socks5 daemon expects socks5 users. When you
specify Kerberos authentication, the socks5 daemon expects
Kerberos users. A dash, -, matches all users. When you
specify u and k in the authpattern, userpattern can con
tain valid Kerberos and socks5 users.
proxypattern
Specify socks5 daemons in a proxypattern as a comma sepa
rated list of server-entries, with no white space.
Specify servers in order of preference. The client
attempts to connect to servers in the order in which they
are listed in the proxypattern. It only attempts connec
tions to a server when the preceeding server is not avail
able.
server-entries
A server entry is a hostname or IP address, optionally
followed by a colon and the port number, with no white
space. When you omit the port number, socks5 uses the
default port.
host hostname, default port
host:port hostname, specified port
EXAMPLES
Refer to the examples directory for more complete exam
ples.
auth - - k
permit k - 111.111.111. - - -
Only kerberos authenticated users from the class C network
111.111.111.0 can use the server.
socks5 - - s5srv1,s5srv2
permit - - .mydomain.com - - -
All socks5 requests connect through s5srv1. If s5srv1 is
not available, all socks5 requests connect through s5srv2.
Only clients from .mydomain.com can use the server.
auth otherserver - k
noproxy .internal.net.com -
socks5 - - otherserver
permit - - .internal.net.com - - -
permit k - otherserver - - -
Clients from .internal.net.com can use the server without
kerberos authentication. The socks5 server will connect
directly to .internal.net.com hosts and proxy through
another socks5 server, otherserver, for other hosts. For
the other socks5 server, otherserver, to proxy through
this socks5 server, it must authenticate with kerberos.
POOR CONFIGURATIONS
As with any software that has security issues, proper con
figuration is a must. The line
permit - - - - - -
should never be used. With this configuration, malicious
users could use the socks5 server to hide their attack of
other systems. Always try to restrict based on source or
destination host.
SEE ALSOsocks5(1), libsocks5.conf(5), sockd4_to_5.pl(1)AUTHORS
NWSL SOCKS5 Development Team
Send comments to socks5-comments@socks.nec.com
02 May 1997 socks5.conf(5)