DansGuardian Documentation Wiki

You are here: Main Index » automatic_proxy_configuration


Wiki Information

Using WPAD/PAC For Automatic Proxy Configuration

If computers can find and use the web proxy automatically, an "explicit-proxy" configuration can become significantly more convenient. In fact, in some cases there may no longer any reason to use a "transparent-intercepting" configuration.

Such a configuration may in fact be possible, using a combination of WPAD and PAC. The first part, WPAD, “Web Proxy Autodiscovery Protocol”, is how the browser locates the proxy configuration. The second part, PAC, “Proxy Auto-Configuration” is what the browser uses to determine where to send its requests.

A possibly bigger advantage is much less typing and clicking. Enabling this option in a browser often takes just one click (and if any text then only one line).

Another advantage is once the proxy settings are centralized like this, you can change the use or location of the proxy immediately any time it's necessary, without re-touching every computer and without worrying about computers that have been temporarily removed.

WPAD/PAC is known to work with DansGuardian (it's not just a theoretical possiblilty). Some DansGuardian users have already done this.

A good place to learn more is the encyclopedia articles http://en.wikipedia.org/wiki/Wpad and http://en.wikipedia.org/wiki/Proxy_auto-config (To learn even more, follow the “External References” from these articles.)

(Note that if you have a more general way of centrally managing browser settings, such as “group policy”, you probably don't need to set up the WPAD/PAC subset.)


WPAD/PAC isn't perfect though. It has these known limitations:

  1. Never Became An Internet Standard
    WPAD/PAC has never become an Internet standard. It's implementation in new products is spotty; specifically it tends to be restricted to derivatives of IE and Netscape. Documentation about WPAD/PAC can be a bit difficult to locate. And a couple details are more hazy than they should be.
  2. Problematic Security
    WPAD/PAC is not particularly secure, and its use may bring an unacceptable risk. The thought of partially hijacking a whole bunch of browsers is a very inviting target for crackers.
     If the DNS method of location is used, one common method of attack is allowed by the DNS search, which keeps shortening the domain name until it's only two segments long. This works well in the U.S. where the last name tried (wpad.domain.tld) is still within the organization, but it may not work so well where the last name tried (wpad.co.uk, wpad.org.au, etc.) is under someone else's control and might be cracked.
     Two things are prudent to protect against this common attack. First, be sure your end user computers cannot access the web directly via port 80. If you have DansGuardian and you've already taken steps to prevent skipping around, you've already done this. And second, disallow any access of a proxy configuration file through DansGuardian. Specifically, add to “bannedurllist”

     (If your severs are separate computers, all you need to prevent skipping around is a few IPtables rules on your gateway/firewall. If web server, DansGuardian, and the gateway/firewall are all really the same computer, the IPtables rules need to be a bit fancier to allow legitimate functions while still disallowing skipping around.)

  3. Full JavaScript Required
    The browser must provide a full implementation of JavaScript. PAC uses JavaScript even if it's otherwise been turned off. The resulting large memory footprint may be an issue on some smaller/mobile devices.
  4. Limited Browser Support
    Versions of IE and descendants of Netscape browsers fully support WPAD/PAC. But other browsers don't; some support only the DNS method but not the DHCP method, and some (such as Opera) don't support either method. It's unknown whether Safari (and descendants such as on mobile devices such as the iPhone) supports only the DNS method or doesn't support any WPAD/PAC method at all.
  5. Some Configuration Still Required
    Each browser's use of WPAD/PAC can be turned on or off, probably so you can eliminate any performance issues or security issues when it's not set up. You will need to turn it on in each browser. So even though WPAD/PAC makes configuration of individual computers in an “explicit proxy” environment much simpler, you still have to touch each individual computer a little bit.
Example Assumptions

Throughout this description we'll assume the following configuration. Of course if you implement this, you'll need to change most of the details (and perhaps change a few more significant items too).

We assume your firewall is already set up and already working well. For example we assume it's already impossible for external users to access your internal web servers. (Firewall configuration is outside and beyond the scope of this document.)

In this example, your network's domain name is your domain.tld, so your end user computers have names like foopc.your.domain.tld. You have an internal web server, which is on a different computer than either DansGuardian or your gateway/firewall function. The web server's Apache-style configuration is in /etc/httpd/conf/httpd.conf, and we'll create a special data root just for this web server at /var/www/http/proxy-conf. Your DansGuardian is on a different computer than your gateway/firewall. (Again this is not necessary; it's used here simply to make this example clearer.) Each computer's “gateway” (last line displayed by ipconfig) is already configured to point to your gateway/firewall. And if you're going to choose the DNS method of implementing WPAD, you already have an internal DNS system. The specific computer names and addresses are:	gateway gateway.your.domain.tld # gateway/firewall	proxy proxy.domain.tld # proxy machine where DansGuardian runs	web1 web1.your.domain.tld # internal web server running Apache	dhcp dhcp.your.domain.tld # DHCP server	ns1 ns1.your.domain.tld # internal DNS 1/2	ns2 ns2.your.domain.tld # internal DNS 2/2

Remember, this is the configuration used for illustration in this example. It does not reflect requirements.

Implementation Part II: PAC

We'll take the two parts in reverse order, describing PAC first.

Configuration Content

We want to get browsers to access a file that looks like this:

(Note the two arguments the browser passes in to FindProxyForURL(…) are the same thing - “host” is pre-extracted from “url” for your convenience. Both refer to the destination; neither refers to the client system running the browser.)

// Proxy auto-config script

function FindProxyForURL(url, host)
    if (shExpMatch( host, "*.your.domain.tld" )) { return "DIRECT"; }
    if (shExpMatch( host, "*.domain.tld" ))      { return "DIRECT"; }

        { return "DIRECT"; }

    return "PROXY proxy.your.domain.tld:8080"; 

(Here's a simpler example which just always sends all requests to DansGuardian. You might be able to use this if you don't have any internal web servers [other than those used to set up WPAD/PAC].)

// Proxy auto-config script

function FindProxyForURL(url, host)
    return "PROXY proxy.your.domain.tld:8080"; 

These examples are just one style of coding; they may not be either the best or the most succinct or the most correct way to express the desired operation. Many other styles would be equally effective.

Some function names are pre-defined and cannot be changed. The function called will always be the one named FindProxyForURL. Both arguments are the web destination to be accessed next. url is the hostname, port, and path portions of the destination; host is only the hostname portion of the destination. Most likely this function should only call shExpMatch and isInNet, which are always available when JavaScript executes this function.

Configuration Availability

This file needs to be available to all browsers (before WPAD/PAC is set up) via direct access to an internal, unfiltered web server.

Depending on their viewpoint, some references call the file wpad.dat and others call it proxy.pac. Rather than try to choose which name is “more correct”, it's prudent to simply allow both filenames by using a symbolic link as follows:

prompt# cd /var/www/html
prompt# mkdir proxy-conf
prompt# cd proxy-conf
prompt#  ... create file proxy.pac ...
prompt# ln -s proxy.pac wpad.dat

There are reports that some versions of Windows accidentally omit the last character from the request. If you need to allow for these, also

prompt# ln -s proxy.pac proxy.pa
prompt# ln -s proxy.pac wpad.da

Make this file available via web service by adding this configuration to your internal web server:

NameVirtualHost *:80

<VirtualHost *:80>
Options +FollowSymLinks
ServerAdmin support@your.domain.tld
VirtualDocumentRoot /var/www/html/proxy-conf
ServerName wpad.your.domain.tld
ServerAlias wpad

Some browsers also expect the proxy configuration script file to be served with the MIME type  application/x-ns-proxy-autoconfig (most browsers may not actually require this - try it first and only take action if it's clear you have this problem). If a browser does require it, one way to meet the requirement is to edit the file /etc/mime.types to associate the extension  .dat  with the MIME type  application/x-ns-proxy-autoconfig  (you may need to insert a line), then restart your web server.

(If you're modifying an existing WPAD.DAT, you may have a problem that your changes don't seem to have any effect. If so, it's probably because browsers such as IE have cached a copy of the old WPAD.DAT. You might need to clear the browser's “temp” files.)

Implementation Part I: WPAD

Now that the proxy configuration is available directly from an internal web server, individual browsers need to find it. Choose one of the three methods below for how this should happen. (Note that the method you select will be the only one used. WPAD does not “failover” from one method to another.)

(Before doing any of these, test that the proxy configuration file is indeed accessible from the computer you're working on. Be sure the browser's connection setting is something like UNchecked“Use a proxy server”UNchecked or “Direct connection to the Internet”. Then in the browser's address bar type http://wpad.your.domain.tld/wpad.dat and be sure the file comes up on the screen.)

WPAD Method 1: Hard Coded

Go to each computer, start each browser, and select its “Connection” or “LAN Settings” or “Conection Settings” list of options. Select or check the option called something like “Use automatic configuration script” or “Automatic Proxy Configuration URL”. In the box provided for the details of the selected option, type in

WPAD Method 2: DHCP

If your computers use DHCP and your DHCP server is configurable, you may be able to use this method. Note though there are reports this method does not work with some versions of the Firefox browser.

First go to each computer, start each browser, and select its “Connection” or “LAN Settings” or “Conection Settings” list of options. Select or check the option called something like “Auto-detect proxy settings for this network” or “Automatically detect settings”.

Next enhance the DHCP service to include the “site-local” option 252 (possibly the option already exists and is named “auto-proxy-config”) with a string value of  http://wpad.your.domain.conf/wpad.dat.

(Using this DHCP method avoids the security problems of the DNS method. On the other hand, it has its own security vulnerabilities. And worse, a “rogue” duplicate DHCP server could raise havoc with your network.)

WPAD Method 3: DNS

If you use (or will use) an internal DNS to enhance external DNS service, you can use this method.


Next, we assume your existing internal DNS contains a “zone” file something like this one:

@               IN      SOA     ns1.your.domain.tld support.gateway.your.domain.tld. (
gateway			IN A
firewall		IN CNAME	gateway

proxy			IN A
dansguardian		IN CNAME	proxy
squid			IN CNAME	proxy

web1			IN A

dhcp			IN A

Even though the details of setting up an internal DNS system are beyond and outside the scope of this document, here's a quick outline of what's required:

  • identify two server computers (DNS pretty much requires at least two)
    • set up their kernel
    • set up their network connectivity
    • set up their names
  • install DNS server software
    • configure DNS server software
    • extend the configuration with a “zone” file for your own network
  • tell all your computers where your DNS servers are
    If you use “static” network configuration, you can set the IP addresses of your DNS servers into each computer. The settings are very close to the place where you set the IP address of the machine itself; you might have to select the TCP/IP protocol and click “Properties”.
     On the other hand if you use DHCP, you don't need to do anything more to your end user computers, instead you just need to set a couple options in your DHCP server:
    option domain-name-servers,;
    option domain-name           "your.domain.tld"; 

Assuming you already have internal DNS service configured as above, for WPAD just add this one line to your zone:

wpad				IN CNAME	web1

Single System Alternative

To have all the functions run on just one computer, you only need to change a few things (this example builds on the DNS method). First tweak your zone definition to look like this:

@               IN      SOA     ns1.your.domain.tld support.gateway.your.domain.tld. (
gateway			IN A
firewall		IN CNAME	gateway

proxy			IN CNAME	gateway
dansguardian		IN CNAME	gateway
squid			IN CNAME	gateway

web1			IN CNAME	gateway
wpad			IN CNAME	gateway

dhcp			IN A

And second change your IPtables rules to allow internal access to the web server while continuing to disallow skipping around the filter.

User Aids

If a user brings a new computer onto your network that's never been there before, it won't know anything about WPAD/PAC, so none of this will help. The computer simply won't be able to access the web, and it may not be very clear to the user what to do about it.

In this situation, it's reasonably likely (but by no means certain) the user will eventually browse to http://gateway.your.domain.tld to see if there are any instructions there. So you may be able to assist user “self-help” by posting as the default document of a web server running on your gateway/firewall a webpage of detailed instructions about how to set up WPAD/PAC for your environment in each supported browser.

A really thorough way to do this, which isn't contingent on your guest eventually browsing to http://gateway.your.domain.tld but rather will work no matter what web address is requested, is to set up a Network Billboard.