socksrc — Socks 5 configuration file
/etc/socksrc
is a unified configuration file
for both the Socks 5 server, sockd, and applications
that use the Socks 5 protocol to contact a Socks 5 server, such as
sockd.
This configuration file may be installed on:
Firewalls that run the sockd(1)
server.
sockd will read the server configuration settings from
/etc/socksrc
.
Servers that run applications that use the Socks 5 protocol.
The applications read a list of available Socks 5 servers from
/etc/socksrc
, and determine the address of the
Socks 5 server to use for a particular network connection.
This manual page describes both the client and the server-related settings
in this configuration file.
/etc/socksrc
may be either a single file, or
a directory.
If /etc/socksrc
is a directory, its contents
are read and concatenated together, to form the actual configuration file.
Files in this directory whose names contain periods
or tildes, and any file named “CVS”, are ignored.
Everything else is concatenated together and read as a single configuration
file.
Blank lines in /etc/socksrc
are ignored.
Comments are introduced by the '#' character, which are also ignored.
netmask
hostname[:port][/ipv4][/redirect=domain[:port]]
[ userid
password
]
Connections to netmask
, which is a network
address in CIDR format (n.n.n.n/l), should be proxied via a Socks 5 server
running on hostname
.
Multiple “proxy” statements are used to select different
proxies based on the destination network address.
hostname
can be optionally followed by a colon
and a port number, to use a Socks 5 server that's running on a port other
than the default port 1080.
The following options may follow, separated by a forward-slash
character:
/ipv4
The Socks server does not have IPv6 connectivity, and IPv4-mapped addresses must be converted to native IPv4 addresses.
/redirect=
domain[:port]
Redirect the connection.
After contacting the Socks server, do not request a proxy connection
to the original destination IP address.
The proxy connection is established
to domain
instead.
The original destination port will be used by default, unless
domain
is followed by “:port”.
Use a comma-separated list to specify multiple available Socks 5 servers. Each listed server will be tried, in turn, until a succesful connection is established to a server.
userid
and
password
are optional.
They are required when the Socks 5 proxy requires authentication, and they
specify the authentication credentials.
/etc/socksrc
needs to be readable by any system
application that uses Socks 5 proxies, so this file is usually globally
readable.
netmask
Do not use a Socks 5 proxy when connecting to a network identified by
netmask
.
Allow the SOCKS_PROXY
environment variable
to override proxy statements.
“allowenv” may be specified anywhere in
/etc/socksrc
(if /etc/socksrc
is a directory,
“allowenv” may appear in any file in the directory).
When
“allowenv” is specified, if the
SOCKS_PROXY
environment variable is defined, it disables all
“proxy” statements, and replaces them with the contents of
the environment variable.
If the SOCKS_PROXY
environment is not defined,
the “proxy” statements are read as usual.
The “noproxy” statements are always processed.
When
“allowenv” is specified and
SOCKS_PROXY
environment variable is defined, all connections
to any IP address are proxied through the server defined by
SOCKS_PROXY
, except for IP addresses listed in the
“noproxy”.
SOCKS_PROXY
's contents follow the same format as the
“proxy” statement.
In other words, the contents of SOCKS_PROXY
are parsed as if
all “proxy” statements in
/etc/socksrc
are replaced with the single statement
“proxy 0.0.0.0/0 $SOCKS_PROXY”.
When multiple proxy
and noproxy
statements match a destination address, the one with the longest
CIDR prefix is selected.
The physical order of proxy
and noproxy
statements is irrelevant, the longest CIDR prefix will be selected from all
the available candidates.
It is an error to have the same network prefix listed more than once.
port
address[:port]
Accept connection on “address”.
“address” must be an IP address, like
192.168.0.10
, and not a domain.
The Socks 5 server creates a socket for each “port” statement
in /etc/socksrc
.
At least one “port” statement is required, the Socks 5 server
will not create any default ports.
Use the “port” statement to enumerate all internal IP addresses
on the firewall.
Do not specify any external IP addresses, because that would be a
security hole.
“address” is optionally followed by a colon and a port number.
The server defaults to the “socks” port, port 1080
(the “socks” service must be listed in the
/etc/services
file).
anonproxy
netmask1
[netmask2
] [bind=
address
] [block4=
filename
]
Accept proxy connections from the IP address specified by
netmask1
, which should be a network address in
CIDR format (n.n.n.n/l), without requiring authentication.
By default, the connecting client may open a proxy connection to any IP
address.
netmask2
is optional, if specified the proxy
connections may only be opened to the specified IP address range.
“bind=address
” is optional.
If specified, netmask2
must also be provided, and
must be a single IP address (usually “0.0.0.0/32”),
and not a CIDR netmask.
If “bind=address
” is present,
a connection attempt from netmask1
to
netmask2
is redirected to
address
, which must also be an IP address.
This is used to properly implement proxies for incoming connections.
See the example below for more information.
“block4=filename
” is optional.
filename
must be a binary database file, created
by the
mkbl4(8)
command,
that contains a list of blacklisted IPv4 address ranges.
Connections to the specified IP address ranges are blocked.
netmask2
must be present if either
the “bind” or the “block4” option is present.
Use 0.0.0.0/0
to specify the default, global IP address
range.
Example:
anonproxy 10.0.0.0/8 0.0.0.0/0 block4=/etc/blacklist.dat
authproxy
netmask1
[netmask2
] [bind=
address
] [block4=
filename
]Like the “anonproxy” command, except that the connecting client must provide an acceptable userid and password, before the proxy connection is allowed.
username
Run the Socks server as user “username”
(default: nobody
).
The Socks server cannot bind to privileged ports unless it runs as
root
.
If you choose to do so, “user root” needs to be added
to /etc/socksrc
.
groupname
Run the Socks server as group “groupname”.
If not specified, the user
's group
gets used. The group
option must appear
after the user
option.
n
Enables debugging messages from the Socks server.
The debugging messages are sent to syslog
(as “daemon” facility log messages).
Consult the syslog
documentation for information on
where the actual log files are.
“n” controls which activites are logged. It should be set to the following values:
Log configuration file parsing.
Log connection requests from Socks clients.
Log only completed, established proxy connections.
n
Create “n” (default: 5
) processes that listen
for incoming connections from Socks clients.
The socks server first creates a socket for each IP address specified by the “port” entry, and begins accepting proxy connection requests. For each connection request the server searches the list of all “anonproxy” and “authproxy” entries until it finds a statement that matches the source and the destination IP address, taking into account whether the Socks client supplied a valid userid and password. The proxy connection request is rejected unless a matching entry is found.
proxy 0.0.0.0/0 brimstone noproxy 127.0.0.0/8 noproxy 192.168.0.0/24
This example specifies the proxy server brimstone
,
except for 127.0.0.0/8
(the loopback interface), and
192.168.0.0/24
, the internal LAN.
127.0.0.0/8
should always be specified as
“noproxy” (otherwise the results will be rather
interesting).
proxy 0.0.0.0/0 brimstone:1100,hellraiser noproxy 127.0.0.0/8 noproxy 10.0.0.0/8 proxy 192.168.5.0/24 portal daphne sys64738
This example uses a default proxy server on
brimstone
, port 1100.
If this server cannot be contacted,
hellraiser
will be the backup proxy
(on the default port 1080).
Connections to the 127
and 10
networks
are not proxied, and the 192.168.5
network is reachable
via the proxy server daphne
, logging in as
userid daphne
, password sys64738
.
port 192.168.0.5 port 192.168.1.5:1100 anonproxy 192.168.0.0/24 authproxy 192.168.1.0/24 192.168.0.0/24 authproxy 192.168.1.0/24 0.0.0.0/32 bind=192.168.0.8
This example configures the Socks 5 server to listen on two IP addresses,
192.168.0.5
and on port 1100 of
192.168.1.5
.
Clients from the IP address range
192.168.0.0/24
are allowed to establish a proxy connection to any IP address without
requiring authentication.
Clients from the IP address range
192.168.1.0/24
are allowed to establish a proxy connection only to
192.168.0.0/24
, and they must authenticate.
Connection requests from any other IP address is rejected.
The second “authproxy” entry needs more explanation. The Socks 5 protocol provides a limited ability for a Socks client to establish an incoming connection. The Socks 5 client requests the server to listen on a local port, then any incoming connection is the forwarded to the client.
The wildcard IP address, supplied by the Socks client when binding the
port for a listening socket, is represented by the IP address
0.0.0.0
, which therefore must be matched by some
“authproxy” or “anonproxy” entry
(take care to specify 0.0.0.0/32
and
NOT 0.0.0.0/0
).
The Socks client can also specify an external, or public, IP address
instead of the 0.0.0.0/32
, so in most cases additional
entries will be needed.
If the Socks client does not explicitly specify an external IP address,
and uses 0.0.0.0
, the external IP address can be
supplied automatically.
This is what “bind” does.
In this example, the Socks proxy server's external IP address is
192.168.0.8
.
If the Socks client tries to listen on address 0.0.0.0
,
the “bind” option causes the Socks server to bind on the IP
address 192.168.0.8
instead.
Under the default configuration, the Socks server cannot listen to reserved
ports (ports 1-1023).
Only a root
process can do that, and the Socks server
does not run as root in the default configuration.
If the Socks server is configured to run as root it will be able to bind
to a reserved port, provided that the client is also connecting from a
reserved port.
Setting the SOCKS_DEBUG
environment variable before
running a Socks 5 client enables
diagnostic messages which will be sent to standard error.
Socks 5 clients use SOCKS_DEBUG
instead of the “debug” setting from
/etc/socksrc
.
SOCKS_DEBUG
should be set to the following values:
Configuration settings.
Proxy connection establishment.
Intercepted select(2) and poll(2) system calls.
Miscellaneous proxy logic.
Internal errors.
Multiple diagnostic messages may be selected by adding them together.