dante   Frontpage - Dante - Download - Status - Support - Modules - Docs - Links - Survey
 

Minimal client configuration

This page describes the recommended minimal configuration for a Dante SOCKS client. Some applications have built-in SOCKS support. To configure these consult the appropriate application configuration instructions; the focus in this document is the Dante client.

Dante client modes

The Dante client library can be used in several different ways. Either by being compiled into an application, or through on-the-fly socksification with the socksify script included in the Dante distribution. This page assumes the latter scenario, but client configuration will generally be identical for both scenarios.

Using socksify

Most networking applications do not have built in support for the SOCKS standard. Rather than having to modify or recompile the client application, it is possible to use the socksify script to automatically make most dynamically linked networking applications use the SOCKS protocol. A socksified application will communicate with other machines through a SOCKS server rather than directly.

From the shell, a networking application can be socksified in this way:

socksify application

Some information is however required for this to work, including a specification of the address of the SOCKS server. There are two ways to provide this information, either through the shell environment, or via the socks.conf client configuration file.

Shell environment -- SOCKS client

To configure the Dante client via the environment it is only necessary to set the SOCKS_SERVER environment value to the address of the SOCKS server. For the Bourne shell and variants (such as bash, ksh, etc.), this can be done in the following way:

export SOCKS_SERVER=192.0.2.1:1080
socksify application

Use of the SOCKS_SERVER variable implies that the SOCKS server accepts both version 4 and version 5 of the SOCKS protocol. If only one version is supported, either of the SOCKS4_SERVER or SOCKS5_SERVER values can be used instead.

It is not possible to control all aspects of the client behavior via the environment, but specifying only the server address should be sufficient in many usage scenarios. Of particular noteworthiness, is that there is currently no way to specify that connections to the DNS-server should be direct, which can negatively impact the performance of the client.

All supported authentication methods will be offered to the server when the client is configured in this way.

Shell environment -- Other proxy protocols

In addition to SOCKS, the Dante client supports several other proxy protocols that also can be configured via the shell environment.

  • HTTP_PROXY - Connections can be made via an HTTP proxy server by setting the HTTP_PROXY environment variable. The proxy needs to support and allow use of the CONNECT command. Note that only outgoing TCP connections can be made through an HTTP proxy (i.e., no UDP support or reception of incoming connections).
  • UPNP_IGD - Use of an UPnP IGD is also supported by Dante (if compiled with miniupnpc). This type of proxy supports binding of ports on the device in order to receive incoming connections. It can also provide information on the external IP address (but not port) that will be used by the UPnP router, so that this information can be provided to peers that need it (a client behind a NAT router will normally not know which address will be used by the NAT router, and then seen by the remote peer). The UPNP_IGD value is used to specify how the device should be reached. There are three alternatives:
    • UPNP_IGD=broadcast
    • UPNP_IGD=interface name (e.g., eth0)
    • UPNP_IGD=http://192.0.2.2:1900/InternetGatewayDevice.xml

The simplest way to configure UPnP is with the broadcast keyword or interface name. This is however also significantly slower than the third method above because a broadcast operation on the local network is needed in order to discover the address of the UPnP device. Specifying the address avoids the broadcast, but requires the address to be known. One way to determine this address is by first setting the variable to broadcast and enabling debug output in this way:

SOCKS_LOGOUTPUT=socks.log
SOCKS_DEBUG=1

After running socksify with a networking application, a line like this should appear in the socks.log file if a usable UPnP device is found:

IGD found at http://192.0.2.2:1900/InternetGatewayDevice.xml

After the URL has been discovered, it can then be set in the UPNP_IGD variable, or socks.conf file, for better performance next time.

The Dante client previously also supported the msproxy protocol, but it is now deprecated.

Minimal Dante client configuration file

Using the environment is simple, but using a configuration file is more suited for permanent setups, or when greater control of the client behavior is needed.

The configuration described in this document is not the smallest possible configuration, but is structured to make debugging and later expansion easier. Each section of the configuration file is discussed separately. The complete file is listed at the end of the page.

Logging

logoutput: socks.log
debug: 1

The logoutput and debug keywords can be enabled to provide information about the operation of the client. Logging is not needed for normal usage and both statements are commented out below.

DNS resolution

resolveprotocol: udp

The resolveprotocol keyword can be used to change how DNS resolution is performed. Alternatives to udp are tcp and fake, but changing the default should generally not be necessary.

Proxy routes

This is the only required part of the client configuration file, and is used to control how the application should communicate with other hosts. Two types of routes can be configured. The first are direct routes, specifying hosts or networks to which connections should be made directly, as opposed to going through a proxy server. The second are routes for which traffic should use a specified proxy server and proxy protocol.

There is no limit to the number of routes that can be included, but a typical usage scenario will normally involve one route to a proxy server, and optionally one direct route to a DNS server.

Rule evaluation is performed for each networking operation, starting from the beginning of the file. The first matching rule with the requisite priority is used to decide how a given operation should be handled.

The priority in which rules are matched is that a direct route is searched for first, then a SOCKS v5 route, then a SOCKS v4 route, than a HTTP route, and lastly an UPNP route.

A configuration file will typically end with a generic route to the proxy server, and any exceptions to this rule, such as a direct route, should precede the route to the proxy server. If no rule matches, the default is to connect directly (this can be changed with the SOCKS_DIRECTROUTE_FALLBACK variable).

The from and to keywords in the route syntax support sub-network 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.

Note that the address of the proxy server in the route statements should use the IP address of the server rather than a symbolic host name. If the client needs to communicate with the proxy server in order to do DNS resolution it will not be possible to determine the address of the proxy server if it is specified symbolically.

Direct routes

#direct route to dns server running on 10.1.1.1.
route {                                                                        
        from: 0.0.0.0/0 to: 10.1.1.1/32 port = domain via: direct              
}                                                                              

Direct routes can be used to improve the performance of communication with hosts that can be reached directly by the client, without going through the proxy server. An internal DNS server is a typical example of this. Note that as of Dante 1.2.0, direct routes will automatically be added for hosts on the same local network as the client, as indicated by the IP-address and netmask of the machine the client is running on. Manually specifying direct routes is thus almost never needed any longer (and this direct route is commented out below).

SOCKS routes

#route to SOCKS server which supports both SOCKS version 4 and 5
route {                                                                        
        from: 0.0.0.0/0 to: 0.0.0.0/0 via: 192.0.2.1 port = 1080            
        proxyprotocol: socks_v4 socks_v5
        method: none
}

To communicate through a SOCKS server it is necessary to specify the address of the SOCKS server. The from address matches the address of the client, and it will rarely be necessary to have this set to anything but a wildcard address. The to address matches the destination address, such as the address used in a connect() call by the client. The example above uses a wildcard destination address, but is it possible to use the to keyword to e.g., send traffic going to different subnets via different proxy servers.

The SOCKS protocol supports several authentication methods, but the example specifies that no authentication method should be used. More information about how to configure authentication is provided in the authentication section.

Proxy routes -- other protocols

As described above, the Dante client supports several other proxy protocols in addition to SOCKS. These can be used instead of a SOCKS server or in addition. The route syntax allows different proxy protocols and proxy servers to be used depending on destination address, communication protocol, or other factors. The route syntax is the same for the other protocols, with the proxyprotocol keyword specifying the protocol to use, and via specifying the server address (which might be in the format of an URI).

#route to UPnP server
route {
        from: 0.0.0.0/0 to: .example.org
        via: http://192.0.2.2:1900/InternetGatewayDevice.xml
        proxyprotocol: upnp
}

The example above will cause communication with hosts in the .example.org domain to go via the UPnP IGD at 192.0.2.2 (note that the URI format varies between UPnP devices). The proxyprotocol keyword specifies that the UPnP protocol should be used, which does not support any authentication methods. As with the UPNP_IGD variable described above, it is possible to specify broadcast or an interface name, but for a socks.conf file it is recommended that the full URI is specified for better performance.

#route to HTTP proxy
route {                                                                        
        from: 0.0.0.0/0 to: 0.0.0.0/0 via: 10.1.1.1 port = 3128
        command: connect # only operation supported by a http proxy
        protocol: tcp
        proxyprotocol: http_v1.0                                               
}               

To connect via an HTTP proxy such as squid, the configuration above can be used. This example shows two additional keywords, command and protocol. They are not strictly necessary, but are used here to illustrate the limitations that exist with this proxy protocol. Either keyword can be used in any route statement to create very specific routes, but will not be necessary in most typical usage scenarios.

Other proxy protocols might be supported in a similar way by Dante in the future.

Complete minimal client configuration

Combining the elements discussed above results in the following client configuration, which should be placed in a file readable by normal users. The default name of this file is /etc/socks.conf, but might be different depending on the platform.

The configuration below will make all connections to hosts on the local network directly. All other networking operations will be made via the SOCKS server expected to be running at 192.0.2.1. Keywords not required for this, and routes using other proxy protocols have been commented out.

##logging
#logoutput: socks.log
#debug: 1

##dns resolution
#resolveprotocol: udp # default                                                

##
## Client communication routing (first matched route is used)
##

##direct route to dns server (only needed if on a different subnet)
#route {
#        from: 0.0.0.0/0 to: 10.1.1.1/32 port = domain via: direct
#}

## routes to proxy servers, generally only one is needed

#route to SOCKS server which supports both SOCKS version 4 and 5
route {                                                                        
        from: 0.0.0.0/0 to: 0.0.0.0/0 via: 192.0.2.1 port = 1080
        proxyprotocol: socks_v4 socks_v5
        method: none
}

##route to UPnP device
#route {
#        from: 0.0.0.0/0 to: .example.org
#            via: http://192.0.2.2:1900/InternetGatewayDevice.xml
#        proxyprotocol: upnp
#        method: none
#}

##route to HTTP proxy
#route {                                                                        
#        from: 0.0.0.0/0 to: 0.0.0.0/0 via: 10.1.1.1 port = 3128
#        command: connect # only operation supported by a http proxy
#        protocol: tcp
#        proxyprotocol: http_v1.0
#}               

Copyright © 1998-2017 Inferno Nettverk A/S