Minimal server configuration

This page describes a recommended minimal server configuration, offering basic SOCKS functionality without any authentication.

The configuration described in this document is not the smallest possible configuration, but is structured to make debugging and later extension easier. Each section of the configuration file is discussed separately. The complete file is listed at the end of the page. Subsequent pages extend the minimal configuration listed here to support more advanced usage scenarios.

Logging

errorlog: /var/log/sockd.errlog
logoutput: /var/log/sockd.log
#debug: 2

These statements control the logs generated by the server, with logoutput specifying the file that the logs are written to. It is alternatively possible to send log output via syslog, or stdin/stdout. The commented out debug keyword can be enabled to increase the verbosity of the information written to the logfile. The errorlog keyword can be used to only log error messages and warnings.

The access rules later in the configuration file include additional log statements that can be used to provide more information on specific actions performed by the server.

Server address specification

internal: 192.0.2.1 port = 1080
external: eth1

The internal and external keywords are used to specify the addresses that the server should bind to. Each argument can be an IP address, an interface name, or a hostname. The server receives SOCKS requests from SOCKS clients on the internal address, and uses the external interface when forwarding data from the SOCKS clients to the external network. Typically, the internal interface is connected to a LAN, while the external interface is connected to the Internet, but in a "reverse proxy" setup, the opposite will be true.

The internal and external server addresses might be different if the SOCKS server is running on a gateway machine with two different interfaces, but they can also have the same address.

The port number that the server accepts SOCKS requests on can be changed, but 1080 is the standard SOCKS port number.

Server identities

#user.privileged: root
user.notprivileged: socks
#user.libwrap: libwrap

This section is not needed on Solaris, where the Solaris privileges API is used instead.

These keywords specify the identities that the SOCKS server should use for different types of operations. We recommended that a special user, such as socks is created for the SOCKS server. For this minimal configuration, none of the keywords are required, but specifying the user.notprivileged user ensures that the server will try to avoid running as the root user, even if started by root.

No special privileges are usually required to bind to the default SOCKS port; the user.privileged keyword is generally only required to use some of the authentication methods, or if the server needs to bind privileged TCP/UDP-ports (port numbers lower than 1024). The user.libwrap keyword can be included if libwrap is used in the configuration (for e.g., RFC931 username lookups). More information on how to configure authentication is provided in the authentication section.

Authentication methods

clientmethod: none
socksmethod: none

There are two types of authentication rules. The clientmethod keyword lists the methods that can be used in the client pass/client block rules, which are applied before or during the SOCKS protocol negotiation. The socksmethod keyword lists the authentication methods that are accepted by the SOCKS server and can be used in the socks pass/socks block rules, which are applied after SOCKS protocol negotiation has completed. For more information see the SOCKS overview page.

No authentication methods are used in the minimal configuration described in this page, so the value of both keywords are set to none. The use of these keywords is described in more detail in the authentication section.

Interaction with libwrap

If compiled with libwrap, it is possible to use several of the operations provided by the libwrap library, such as access control based on /etc/hosts.allow. This is covered in more detail in the libwrap page.

SOCKS client access rules

#block access to socks server from 192.0.2.22 (exception for pass rule below)
client block {
        #block connections from 192.0.2.22/32
        from: 192.0.2.22/24 to: 0.0.0.0/0
        log: error # connect disconnect
}

#allow connections from local network (192.0.2.0/24)
client pass {
        from: 192.0.2.0/24 to: 0.0.0.0/0
	log: error # connect disconnect
}

The first set of rules controls access to the SOCKS server from internal clients, which connect to the address and port combination specified with the internal keyword. These rules are applied before any data is read from the client.

The Dante SOCKS server will by default block all incoming connections, so at least one client pass rules is needed. For each connection request received from a client, all the rules are applied by the SOCKS server in order, until one matches. The corresponding operation is then applied. If the rule is a client block rule, the request will be denied, and conversely, if it is a client pass rule, the request will be accepted and protocol processing will start. Note however that the actual SOCKS operation requested by the client might still be denied by the SOCKS command rules (see below).

The value of the log keyword controls the information that will be included in log file. As is, this example only logs errors, the part of the line that is commented out shows some additional actions that can be added for more detailed log output.

The rule syntax supports subnetwork specifications (e.g., 192.0.2.22/24), single addresses (192.0.2.22/32), host names (e.g. ftp.example.org), or domain names (e.g., .example.org). A domain name specification will match any host in that domain.

srchost: nodnsmismatch

If domain names are used for access control, it might be useful to set the global srchost option to the value nodnsmismatch, which will use a reverse-dns lookup to verify that the IP address actually belongs to the domain. The verification step is off by default. To use this option, Dante must be compiled with libwrap enabled, but as long as the server is not started as root it is not necessary to set user.libwrap.

SOCKS command rules

#block communication with www.example.org
socks block {
       from: 0.0.0.0/0 to: www.example.org
       command: bind connect udpassociate
       log: error # connect disconnect iooperation
}

#generic pass statement - bind/outgoing traffic
socks pass {  
       from: 0.0.0.0/0 to: 0.0.0.0/0
       command: bind connect udpassociate
       log: error # connect disconnect iooperation
}

#block incoming connections/packets from ftp.example.org 
socks block {
       from: 0.0.0.0/0 to: ftp.example.org
       command: bindreply udpreply
       log: error # connect disconnect iooperation
}

#generic pass statement for incoming connections/packets
socks pass {
       from: 0.0.0.0/0 to: 0.0.0.0/0
       command: bindreply udpreply
       log: error # connect disconnect iooperation
}

The SOCKS client access rules control access to the SOCKS server, while the SOCKS command rules control access through it. The former can limit the machines that can connect on the internal side, and the latter how they can communicate with the external machines.

As with the client access rules, rule evaluation is performed for each client request until a rule matches, starting with the first rule. The corresponding socks pass/socks block action is then applied to the request. The command rules are performed after authentication, which means that the identity of the client can be used in the rules. For more information on this see the authentication section, the minimal configuration described in this page does not make use of authentication. At least one socks pass rule is required to allow access through the proxy. All client requests are blocked by default if no socks pass rule is matched.

The Dante SOCKS server supports five commands that can be used in the rule statements (bind, connect, udpassociate, bindrepy, udpreply). Conceptually, these fall into two groups; the first three correspond to requests made by the internal clients. The from address will be the address of the internal client and the to address will be the address of the external machine the client wishes to communicate with. The remaining two (bindreply and udpreply) correspond to the result of communication made by external hosts, either a TCP connection made to a port binding created with bind, or an UDP packet sent to a port bound with udpassociate. For these two commands, the from address will correspond to the external host, and the to address to the internal client. For this reason, separate rules have been created for the two sets of commands.

The rule syntax gives a high degree of control over how the proxy can be used. As with the client access rules, there are two general ways to construct the rules. Either by adding socks pass statements for each of the machines or users that should have access, or by having explicit socks block rules followed by a generic pass statement. The recommended minimal configuration uses the latter approach, with a generic pass statement for both outgoing and incoming traffic.

The rule statements can additionally contain a proxyprotocol keyword to limit the protocols that are accepted. None of these rules use the keyword, implying that both version 4 and version 5 is accepted. This is recommended unless user authentication is required, which is only properly available in SOCKS version 5. Accepting both version 4 and 5 is recommended for both compatibility with clients that only support version 4 and performance reasons. The overhead of the SOCKS version 5 protocol negotiation process is bigger than that of version 4, and having both available makes it possible for clients to choose version 4 when none of the features of version 5 are required.

Full minimal template

Combining the elements discussed above results in the following server configuration, which should be placed in a file readable by the server, typically as /etc/sockd.conf.

#logging
#errorlog: /var/log/sockd.errlog
logoutput: /var/log/sockd.log
#debug: 2

#server address specification
internal: 192.0.2.1 port = 1080
external: eth1

#server identities (not needed on solaris)
#user.privileged: root
user.notprivileged: socks
#user.libwrap: libwrap

#reverse dns lookup
#srchost: nodnsmismatch

#authentication methods
clientmethod: none
socksmethod: none

##
## SOCKS client access rules
##
#rule processing stops at the first match, no match results in blocking

#block access to socks server from 192.0.2.22 (exception for pass rule below)
# client block {
#       #block connections from 192.0.2.22/32
#       from: 192.0.2.22/24 to: 0.0.0.0/0
#       log: error # connect disconnect
# }

#allow connections from local network (192.0.2.0/24)
client pass {
        from: 192.0.2.0/24 to: 0.0.0.0/0
	log: error # connect disconnect
}

##
## SOCKS command rules
##
#rule processing stops at the first match, no match results in blocking

#block communication with www.example.org
# socks block {
#        from: 0.0.0.0/0 to: www.example.org
#        command: bind connect udpassociate
#        log: error # connect disconnect iooperation
# }

#generic pass statement - bind/outgoing traffic
socks pass {  
        from: 0.0.0.0/0 to: 0.0.0.0/0
        command: bind connect udpassociate
        log: error # connect disconnect iooperation
}

#block incoming connections/packets from ftp.example.org 
# socks block {
#        from: ftp.example.org to: 0.0.0.0/0
#        command: bindreply udpreply
#        log: error # connect disconnect iooperation
# }

#generic pass statement for incoming connections/packets
socks pass {
        from: 0.0.0.0/0 to: 0.0.0.0/0
        command: bindreply udpreply
        log: error # connect disconnect iooperation
}