![]() |
|
||
Minimal client configurationThis 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 modesThe 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 socksifyMost 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 clientTo 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:1082 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 protocolsIn addition to SOCKS, the Dante client supports several other proxy protocols that also can be configured via the shell environment.
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=2 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 fileUsing 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. Loggingerrorlog: socks.errlog logoutput: socks.log debug: 2 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. The errorlog keyword can be used to only log error messages and warnings. DNS resolutionresolveprotocol: 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 routesThis 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 protocolsAs 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. Socksified system callsThe SOCKS protocol supports three commands: connect, bind and udpassociate. These correspond to outgoing TCP connections (connect), reception of TCP connections (bind) and UDP requests (udpassociate). In practice, several different system calls/library functions need to be socksified for socksify to work, but the functionality provided by the client library primarily corresponds to the three operations connect, bind and udpassociate. By default, all commands supported by a protocol will be activated, which corresponds to the following:
In some usage scenarios it might be necessary to limit the number of commands that are socksified. This can be done with the commands keyword. For example, to socksify only outgoing TCP connections, a command keyword with only connect can be specified: #route to SOCKS 4/5 server for outgoing TCP connections 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 command: connect method: none } The above rule will ignore bind() system calls and UDP related operations, causing only TCP connect operations to be socksified. A configuration with no other route keywords that match bind or udpassociate will result in these operations being performed locally, without being socksified. Complete minimal client configurationCombining 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 #errorlog: socks.errlog #logoutput: socks.log #debug: 2 ##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 #} |