NAME

socksrc - Socks 5 configuration file

DESCRIPTION

/usr/local/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)[1] server. sockd will read the server configuration settings from /usr/local/etc/socksrc.

•Servers that run applications that use the Socks 5 protocol. The applications read a list of available Socks 5 servers from /usr/local/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. /usr/local/etc/socksrc may be either a single file, or a directory. If /usr/local/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 /usr/local/etc/socksrc are ignored. Comments are introduced by the '#' character, which are also ignored.

Client Configuration

proxy 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.

Note
/usr/local/etc/socksrc needs to be readable by any system application that uses Socks 5 proxies, so this file is usually globally readable.

noproxy netmask

Do not use a Socks 5 proxy when connecting to a network identified by netmask.

allowenv

Allow the SOCKS_PROXY environment variable to override proxy statements. “allowenv” may be specified anywhere in /usr/local/etc/socksrc (if /usr/local/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 /usr/local/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.

Server Configuration

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 /usr/local/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)[2] command, that contains a list of blacklisted IPv4 address ranges. Connections to the specified IP address ranges are blocked.

Note
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.

user 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 /usr/local/etc/socksrc.

group 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.

debug 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.

prefork 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.

EXAMPLE

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.

Note

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.

BINDING TO RESERVED PORTS

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.

CLIENT TROUBLESHOOTING

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 /usr/local/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.

128

Internal errors.

Multiple diagnostic messages may be selected by adding them together.

BUGS

The filename in “block4=filename” option may not have spaces.

AUTHORS

Double Precision, Inc.

NOTES

1.: sockd(1)

[set $man.base.url.for.relative.links]/sockd.html

2.: mkbl4(8)

[set $man.base.url.for.relative.links]/mkbl4.html

3.: socksify(1)

[set $man.base.url.for.relative.links]/socksify.html