Configuring Dante | Tuning and Customizing a Linux System

< Free Open Study >

The installation of Dante as described earlier in this chapter will include both the Dante SOCKS server and the Dante client libraries. However, the Dante SOCKS server is a fairly typical server installation, and its configuration is very similar to those of the other servers discussed in this chapter (such as Apache and the OpenSSH server). Consequently, this chapter focuses on the Dante client libraries, and this section focuses on configuring them.

Recall that the Dante client libraries are a binary-compatible replacement for the standard BSD sockets API. This is the API used by almost all Unix network programs. The Dante version of these libraries are "aware" of the SOCKS protocol, and so programs that use the Dante version will automatically have access to a SOCKS server, even though they have no idea that they're not using the standard BSD libraries. The Dante client libraries themselves use a configuration file to locate the SOCKS server and retrieve other required settings. This section discusses this configuration.

Locating the Configuration File

The standard Unix location for configuration files is a subdirectory of the installation path named "etc"; if you installed Dante from source code as described in the previous section, then the location of the Dante configuration file will be /usr/local/etc. (If you're using an installation of Dante that was included with your distribution, then the configuration directory can vary but is most likely simply /etc.) The standard name of the configuration file is socks.conf, though this can be changed via a compile-time option to the ./configure program. So, the name of the file in this example should be /usr/local/etc/socks.conf. Dante's default installation process, however, does not actually install a configuration file—not even a default copy—so one will have to be created from scratch.

Fortunately, Dante does include example configuration files; they're just not installed by default. They are located in the "examples" subdirectory of the Dante source code package. The configuration file for the client programs is named socks.conf, but there are other examples, such as socks-simple.conf. To use one of these files as a template for creating your own configuration file, simply copy it to /usr/local/etc/socks.conf . For example, the following command will use the simpler example file as a starting point:

 $ cp examples/socks-simple.conf /usr/local/etc/socks.conf

You can also create a socks.conf file from scratch, though it's probably easier to start with one of the example templates. In either case, you can now alter the configuration simply by editing /usr/local/etc/socks.conf.

Obtaining Network Settings

Configuring Dante correctly requires a bit of knowledge of how the network is configured. For example, since the SOCKS protocol requires the presence of a SOCKS server, the host name and port number of the SOCKS server must be known. Additionally, the version of the SOCKS protocol supported by the server must be known. Table 10-1 lists the required data fields and briefly explains their meanings; typically, you'll have to ask your local network administrator for this information. However, this isn't a book on networking or the SOCKS protocol, so if you require more detail, please consult the documentation for Dante.

Table 10-1: Typical Dante Configuration Fields
OPTION	POSSIBLE VALUES	MEANING
SOCKS version	v4, v5, or msproxy	The version of the protocol to use; typically, SOCKS v4 or SOCKS v5 is used, or alternately the msproxy protocol.
Local network mask	A standard "dotted quad" IP mask	The range of IP addresses in use on the protected, local network (inside the firewall).
IP address of server	a standard IP address	The IP address (not host name) of the SOCKS server.
Server port number	Usually 1080	The port number on the server machine on which the SOCKS server process itself is actually running.

Conceptually, Dante's functioning is fairly simple. For each connection, it compares the destination IP address to see if it matches a pattern (the network mask), and if so it routes the connection through the SOCKS server (or not) depending on the configuration. For most networks, the network mask is the local network, and local requests are not routed through the SOCKS server, while nonlocal (i.e., Internet) connections are. So, once the relevant information is gathered on local network, server address and port, and so on, the configuration file can be modified.

Format of the Configuration File

Dante's configuration file is a bit more complex than many other software's, but it is still fairly straightforward. It consists of sections delimited by braces (that is, the { and } characters), where each section enables or disables a particular feature or defines a "route." Each line within each such "route block" configures a particular option for that route. There are also a set of optional one-line parameters that can be placed outside a block to configure things such as logging support and debugging support. The configuration file also permits comments in the file, which are for human consumption such as documentation purposes, and are ignored. Like most Unix config files, any line that starts with a pound (#) character is considered a comment and ignored.

Setting Global Options

Dante supports a few global options—that is, options that are general and exist outside any particular route. These global options configure where to print logging information, whether to enable debugging support, and the type of network nameserver in use. Typically, you won't want to turn on debugging support, and letting the software log to the standard location is just fine. So, these options can be left as the defaults (which means they are not present or are commented out); however, if they are required they can be enabled, as shown here:

 debug: 1 logoutoutput: stdout

Watch Out for File Formats

Observant readers may notice the format for options in Dante's /usr/local/etc/socks.conf is "option: value"; for example, debugging is activated via debug: 1. (A value of 1 is common in configuration files to mean "true" or "enabled.") Compare this format with the OpenSSH format described earlier, where each line has a format of "option value" (such as StrictHostKeyChecking no). Unfortunately, there's no standard way of setting values in Unix configuration files, so you must be careful to get the format correct when working with a particular file. If you encounter a bug with your software that you think is related to the configuration, it's good to check the file to make sure the format is correct.

The remaining option is resolveprotocol, which tells Dante whether to use a TCP (stream-based), UDP (datagram-based), or no protocol for resolving host names. This is a somewhat arcane issue, and it varies according to the SOCKS server and network in use. Usually, SOCKS v5 servers should have resolveprotocol: tcp, SOCKS v4 servers should use resolveprotocol: udp, and configurations without a network nameserver at all should use resolveprotocol: fake. There are exceptions, though, so if you need more information, you'll have to consult the actual Dante documentation.

The three options of debug, logoutput, and resolveprotocol are all the global options. If they're not needed (as debug and logoutput usually are not), they can be omitted or commented in /usr/local/etc/socks.conf. The example in the next section shows an actual sample configuration, including these options.

Creating a Route Block

The most important parts of a Dante socks.conf configuration file are the route blocks. A route block consists of a number of lines enclosed between the lines route { and }. (The use of braces to indicate "blocks" of related lines is fairly common; later in this chapter, you'll see that the xinetd program uses a similar format.) Each line within a block configures a different option for that block. Table 10-2 summarizes the options that can be set within a block.

Table 10-2: Common Dante Route Block Options
OPTION NAME	MEANING
`from`	The IP pattern used to match the origin of a connection
`to`	The IP pattern used to match the destination of a connection
`via`	The IP address of a SOCKS server to be used to handle the connection
`port`	A TCP/IP port number; can be used with `from`, `to`, or `via`
`proxyprotocol`	The protocol to be used (such as SOCKS v4 or v5) for the route block

There are a few additional route block options that are somewhat less common than the ones in Table 10-2; however, they're not discussed here for the sake of simplicity. If you need more information, please consult the documentation for Dante, and especially the manual page for the socks.conf file (which can be obtained via the command man socks.conf) and the detailed example configuration file named example/socks.conf in the Dante source code package.

Recall that the basic gist of a route block is to tell Dante which SOCKS server (if any) to use for a given connection. The from and to options define the origin and destination, and the via option specifies the SOCKS server (if any) to use. The remaining options simply indicate which SOCKS protocol to use.

A Sample File

This section will present a sample socks.conf file to illustrate the points discussed previously. Other example configurations are included with the Dante source code package itself in the example subdirectory. You should also consult those samples, since this one doesn't cover all the nuances of Dante configuration. Instead, this example is intended to illustrate the configuration for a common network setup. Specifically, this example handles the following case:

The local network is on the IP range 192.168.0.0, and all computers on the local network are behind the firewall.
The firewall computer is on the IP address 192.168.0.1.
The firewall runs a SOCKS v4 server on port 1080.
All connections to the local network should be direct connections (i.e., bypassing the SOCKS server), and all other connections should go through the SOCKS server.
Debugging should be disabled, and the log output can be left at the default.

Listing 10-1 is a sample socks.conf file that meets these criteria. This setup is actually fairly typical of a small home or office network that is protected by a firewall. (The 192.168.0.0 address range is frequently used by Network Address Translation [NAT] firewalls.)

Listing 10-1: Example socks.conf File

 debug: 0 # logoutput: stdout resolveprotocol: tcp # all nameserver traffic (i.e. port=domain) should BYPASS the SOCKS server route {        from: 0.0.0.0 to: 192.168.0.9 port=domain via: direct } # all traffic to the local machine should BYPASS the SOCKS server route {        from: 0.0.0.0 to: 127.0.0.0/8 via: direct } # all traffic to the local LAN should BYPASS the SOCKS server route {        from: 0.0.0.0 to: 192.168.0.0/8 via: direct } # all other traffic should go through the proxy server route {        from: 0.0.0.0 to: 0.0.0.0 via: 192.168.0.1 port=1080 proxyprotocol: socks_v4 }

For the example installation of Dante, you could place the contents of Listing 10-1 in the file /usr/local/etc/socks.conf. However, chances are that won't work, because it's unlikely your network exactly matches the one reflected in Listing 10-1. Be sure you have your network data correct before attempting to create any Dante configuration file, or you'll probably end up wasting a lot of time.

< Free Open Study >