socks5.conf(5)

NAME
socks5.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 configuration 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 connection

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 section 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 daemon 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 authentication 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 authentication. 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 multiple IP addresses, frequently administrators want to ensure that socks5 uses certain interfaces with certain addresses. This prevents outside machines from impersonating inside machines by requiring inside machines to use the inside interface and outside machines to use the outside 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 connection 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 interface 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 portpattern. 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 hostpattern or the port defined in portpattern. The interface entry replaces the route entry of previous releases. For the current release, the entries are equivalent. 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 permits 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 authenticated 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.

PATTERNS

hostpattern
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 network 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 subnet 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 Kerberos, the server uses Username/Password authentication.

Since SOCKS4 clients can not use Kerberos or Username/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 Username/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 recognizes these commands:

    c   connect

    b   bind

    u   UDP

    p   ping

    t   traceroute

    -   all commands

userpattern
Specify multiple users in a userpattern as a comma separated 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 authentication, 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 contain valid Kerberos and socks5 users.

proxypattern
Specify socks5 daemons in a proxypattern as a comma separated 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 connections to a server when the preceeding server is not available.

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

    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 configuration 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 ALSO
socks5(1), libsocks5.conf(5), sockd4_to_5.pl(1)

AUTHORS
NWSL SOCKS5 Development Team

Send comments to socks5-comments@socks.nec.com