Table of Contents

Shortnote

This article explores the proxy auto-discovery feature that has been somewhat "commonly" neglected by system administrators. We explain what is required to set-up proxy auto-discovery on a Mac machine and refer to other systems where this option can be enabled. The reason we chose a Mac is that due to webkit, Mac systems set a global proxy that is available for all applications instead of leaving the proxy up to the application layer.

Requirements

We assume that your local zone is called local (the TLD itself), so that machines are a prefix of that TLD. For example, the machine named radagast will have radagast.internal as its FQDN. Additionally, we assume that the proxy server is located on oberon.internal.

Design

Varying between applications, proxy auto-discovery is performed by either a browser or the system (on a Mac) by fetching an URL based on its local name. This happens either using DNS only, or sometimes using DHCP as well. For example, the machine located at radagast.internal will attempt to fetch the following file:

http://wpad.internal/wpad.dat

and based on that wpad.dat file, it will set-up the proxy configuration.

The WPAD File

The WPAD file is a javascript file that contains hints where the proxy is located and on what port. An example thereof is the following WPAD file:

wpad.dat
function FindProxyForURL(url, host) {
    var proxy = "PROXY oberon.internal:8080; DIRECT";
    var direct = "DIRECT";
 
    // no proxy for local hosts without domain:
    if(isPlainHostName(host)) return direct;
 
    //We only cache http
     if (
         url.substring(0, 4) == "ftp:"   ||
         url.substring(0, 6) == "rsync:"
        )
    return direct;
 
    // proxy everything else:
    return proxy;
}

which hints that the FTP and RSYNC protocols will not be proxied but everything else will (for example HTTP).

The line from the file above:

var proxy = "PROXY oberon.internal:8080; DIRECT";

indicates that the proxy server is at oberon.internal and listening on port 8080.

DHCP Configuration

To hint that the local network has a proxy, we can edit /etc/dhcp/dhcpd.conf and add the following options:

option proxy-auto-discovery code 252 = text;
option proxy-auto-discovery "http://wpad.internal/wpad.dat"; 

these have to be outside of subnet declarations.

DNS Configuration

Since the clients will be querying wpad.internal, we set-up the DNS zone file to include a CNAME pointer to our server oberon.internal. The following is an excerpt from a zone file that serves the internal zone:

oberon                    A       192.168.0.1
wpad                    CNAME   oberon

Our server, called oberon is located at 192.168.0.1 and we have set-up a wpad CNAME pointer from wpad to oberon. When clients with automatic proxy discovery query wpad.internal they will be redirected to our server oberon.internal that will have an Apache server serving wpad.dat.

Apache Configuration

Since the clients will be querying wpad.internal, we set-up a virtual host based on the wpad.internal hostname that will serve the wpad.dat file above. This varies between distributions but the following configuration should cover serving the file:

<VirtualHost *:80>
        ServerAdmin webmaster@localhost
        ServerName wpad.internal
 
        DocumentRoot /var/www/default
        <Files "wpad.dat">
                AddType application/x-ns-proxy-autoconfig dat
        </Files>
</VirtualHost>

Debugging

Provided you already have a proxy server listening on port 8080 as the wpad.dat file suggests, the best tools to use are tcpdump and checking the access log on the Apache server.

On the server one would issue:

tcpdump -i any port 8080

in order to sniff the traffic to port 8080 where the proxy will be listening.