Setting up WPAD Autoconfigure for the Squid Package

pfSense® software can be configured to serve up automatic proxy configuration data to clients to point users to squid running either on pfSense software or another local system, assuming their systems settings are configured for this behavior. Though the data can be served from the firewall, the task is better suited for another local web server if one is available.


To use the web server on the firewall to serve this data, the GUI must run in HTTP mode, or the vhosts package may be used to setup an alternate HTTP server on port 80. Neither of these are recommended as much as running a separate local web server for this task.

This process is known as WPAD, short for Web Proxy AutoDiscovery Protocol. If a web browser is configured for autodiscovery, it will try a few methods to figure out a proxy’s location.

A WPAD host may be supplied via DHCP numbered option 252 (string value containing the entire URL to the WPAD file) or DNS, which is easy to do with the built-in DNS forwarder.

Why would this be done?

To use squid authentication, squid cannot be used in transparent mode. HTTPS traffic also cannot be filtered using transparent mode. When squid is run in normal mode, a proxy IP and port must be configured on each client machine, which can be tedious. This can also cause problems on road warrior laptops that come in and out of the network. Rather than resetting their proxy configuration each time they enter and leave, autoconfigure will let them come and go without much trouble.

Most, if not all, modern browsers ship with the autoconfigure setting turned off, so it may still be necessary to push/enter this setting to client PCs. Even so, another advantage of using autoconfigure is that should squid move to another IP address, only one file must be changed to inform the clients of the updated IP address. (This may be easy to pull off in a windows domain with AD, but not for many others!)


This recipe assumes squid is already operating in a non-transparent configuration. For help with that, look in A Brief Introduction to Web Proxies and Reporting: Squid, SquidGuard, and Lightsquid and on the Netgate Forum.

Create wpad.dat

Before starting, a wpad.dat file must be crafted. This is a single file with a JavaScript function which tells the browser how to find a proxy hostname and port. This function can be as simple or as complex as desired, there are many examples on the web. In this example, all clients will be directed to the squid instance on the firewall.

The contents of the example wpad.dat file are:

function FindProxyForURL(url,host)
return "PROXY";

The function in that file tells the browser to look for a proxy on at port 3128.

Now upload that file to the firewall or another locally accessible web server with SCP, or create it using the built-in file editor. The file must go in /usr/local/www/.

Due to the different ways that various browser versions try to access the file, this same code should exist in at least three different places:



Advanced users might do this from the shell and use ln to link the files.

The best practice is to serve wpad.* from an internal web server which can answer requests for the wpad.dat and associated files. It can be any web server, but typically must be served from both the default virtual host as well as one named wpad, due to differences in how browsers request the file.

To make this work using a firewall running pfSense software to serve the file, local IP addresses will need to be able to access the local interface IP address of the firewall. They do not need to access the GUI with a password, this file will be served without authentication. The GUI must also be run in HTTP mode, which is less secure. If the GUI is set to use HTTP, never open up access to the GUI over the WAN.

Configure DNS

Now to setup the DNS portion. WPAD will take the domain name given to the machine, likely assigned by DHCP, and prepend wpad.. If the domain is, it will look for This task may be accomplished with the DNS Forwarder/DNS Resolver on pfSense software or with another internal DNS server.

A client browser will ultimately try to access - among others. More details on the hostnames tried by WPAD are available in the WPAD article on Wikipedia.

To add the entry using the DNS forwarder on pfSense software:

  • Navigate to Services > DNS Forwarder

  • Click fa-plus to add a new Host Override

  • Enter the following settings, replacing the domain and IP address with their actual values:




    IP Address


    WPAD Autoconfigure Host

  • Click Save.

Block Port 80 Out from LAN

Create a firewall rule at the TOP of the LAN tab (or appropriate interface) that blocks anything from the internal subnet to Any destination on port 80.


If the firewall is used to serve WPAD and the GUI anti-lockout rule has been disabled, web traffic must also be allowed to the firewall GUI port. If this is not acceptable, point wpad. to another internal web server which can answer requests for the wpad.dat and associated files.

Test Clients

Start a browser on a client behind the firewall and see what happens. If squid is configured for authentication, the client will be greeted with a login prompt. Otherwise, check squid’s logs to ensure traffic is going through the proxy. A proxy test site such as can also be useful.

If nothing happened, check the browser settings. Many modern browsers ship with the autoconfigure settings off.


  • Click Tools (Or the three bar icon)

  • Click Options

  • Click Advanced

  • Click the Network tab

  • Click the Settings button

  • Select Auto-detect proxy settings for this network

  • Click OK