Developers Documentation



301 error for file:

User Tools

Site Tools

Web Proxy Auto-detection Configuration

This document demonstrates how to configure web proxy auto-detection (WPAD) on ClearOS for enterprise style deployments. WPAD is useful as a strategy for proxy or content filtration because of the following:

  • Provides ease of configuration
  • Provides ease of management of configurations
  • Useful for deployments at sites that want to filter HTTPS
  • Compatible with web filtering authentication mechanisms.
  • Works well with native ClearOS Directory or with AD Connector.
  • ClearOS can filter while running as the gateway or off to the side (ideal for existing environments.)
  • Active/Active capable services framework suitable for mission critical deployments while providing full use of all members

WPAD files are the same as PAC files. WPAD refers to the auto discovery and PAC is the Proxy auto-configuration. We can use these terms somewhat interchangeably.

For WPAD to function, you must configure your server to use non-transparent mode. In non-transparent mode it is necessary to configure proxy server settings for web browsers to use ClearOS as their proxy server. That is the point of WPAD, it will distribute these settings

What you will need

At a minimum you will need:

  • A ClearOS server configured for use as a non-transparent proxy server.
  • A workstation that is tested to work well if proxy server settings are programmed into its interface. You must test and prove the functionality of a workstation to use the proxy server if the configuration is manual.
  • A web server (ClearOS can fill this role)
  • Either or both of:
    • Control over the DNS server of the network for the creation of the wpad or proxy hostname.
    • Control over Active Directory Group Policies.

Optimally, you can configure WPAD in this configuration:

  • Multiple ClearOS servers configured for use as a non-transparent proxy server. These server may also have Content Filtration.
  • User authentication through NTLM tested which allows for users to be identified with groups assigned to Content Filtration policies. This can use Active Directory in the backend (through the Active Directory Connector), use the Directory of the builtin accounts, or even use Account Synchronization to a master ClearOS server.
  • A workstation that is tested to work well if proxy server settings are programmed into its interface. You must test and prove the functionality of a workstation to use the proxy server if the configuration is manual.
  • Multiple web servers (ClearOS can fill this role but this role can also be shared among non-ClearOS servers, e.g. IIS)
  • Control over the DNS server of the network for the creation of the wpad or proxy hostname(s) or hostname pool(s).


As a prerequisite, you should enable access to the WPAD web server in ALL of your exception lists. Additionally, you should add the WPAD web server to the Proxy Server Bypass settings in the Web proxy module

Network Configuration

There are three main ways in which a browser will locate the configuration file via WPAD:

  • GPO issued configuration script
  • DHCP
  • DNS

Due to security reasons, methods for WPAD detection using DNS and DHCP are less secure than using setting put forward by a Group Policy Object. If you are using the AD connector and/or Windows 7 or greater workstations, you should probably use the GPO method.

GPO method

If you have an Active Directory server (for example, you are using the AD connector to tie in your content filter with your directory services) and you want to distribute the WPAD script in the most secure method, create a Group Policy object that will essentially assign the proxy server configuration script to use.

Navigate through your Group Policy editor to the following:

User Configuration » Policies » Windows Settings » Internet Explorer Maintenance » Connection » Automatic Browser Configuration

Check the box for “Enable Automatic Configuration”

In the text field entitled “Automatic Proxy URL”, enter the URL for the WPAD or PAC file. (e.g. http://webserver.corporate.example.lan/wpad.dat)

Some may notice options to push specific proxy servers via GPO. Generally, we recommend against this because GPO objects are loaded at login time. Which means if you have any need to change the settings, the users must log all the way off and back on again for the updated configuration. The nature of WPAD and PAC is that you can make changes to the file at will. Anytime that the user's browser suffers a connection problem, it will refetch the file which may have your new instructions in it (for example, temporarily sending all traffic direct or using a backup proxy server instead).

DHCP method

If you want to use DHCP to hand out the address to your WPAD file you will need to set up the custom option 252 with the text to the URL of your WPAD file. The entry might look like this in /etc/dnsmasq.d/dhcp.conf:


You can configure the DHCP server through the Webconfig > Network > Infrastructure > DHCP Server > Your LAN Interface > Edit, then complete the WPAD entry. This should be either:


With your ClearOS's interface LAN IP or you can use any FQDN which resolves to your interface's LAN IP:


If your_ClearOS_LAN_FQDN does not resolve to your interface's LAN IP, if you set up the DNS method below, you can use http://wpad.your_ClearOS_domain/wpad.dat instead of http://your_ClearOS_LAN_FQDN/wpad.dat.

DNS method

For security reasons, it is important that your network addresses DHCP and DNS promulgation in order to prevent an attacker from using either to hijack your browsers into using their proxy or querying their web servers for the WPAD file.

A workstation will start a DHCP request to the DHCP server to see if there is any WPAD configuration available. Next, it will look at the domain name statically assigned to itself, or the one provided already to it by the domain. For example, if your workstation has the hostname of, it will use as that name. It will prepend the name wpad to that name and make a request off of the server Failing a lookup to that webserver it will next try:

Please note that many modern Windows workstations and servers may resist this method.

In ClearOS (simple method, no HotLAN)

The simple method is just setting a DNS entry in Webconfig > Network > Infrastructure > DNS Server which maps your ClearOS LAN IP to wpad.your_LAN_domain.

In ClearOS (strict method, essential with HotLAN, preferable with multiple LAN's)

The strict method allows ClearOS to give out a different LAN IP for each LAN interface. This is essential if you have a HotLAN as communication is not allowed between the HotLAN and normal LAN so wpad.your_LAN_domain needs to resolve the to ClearOS HotLAN IP on the HotLAN and LAN IP on the LAN. To do this, set up multiple entries in Webconfig > Network > Infrastructure > DNS Server which map wpad.your_LAN_domain to each ClearOS LAN IP.
These entries go to into /etc/hosts where you may then see something like: server.domain.lan server mailserver imap smtp wpad wpad.domain.lan server.domain.lan server mailserver imap smtp wpad wpad.domain.lan server.domain.lan server mailserver imap smtp wpad wpad.domain.lan

Then create a file /etc/dnsmasq.d/anything and in it put:


Then restart dnsmasq with a:

systemctl restart dnsmasq.service

Putting it together

Many web browsers are configured to automatically look for proxy server settings. Before going to its first page, the web browser will attempt to download the proxy server settings file from http://wpad.example.lan The example.lan domain name is typically automatically set via your DHCP server settings. It can also be set manually in your network settings.

The next step is to add the DNS record for wpad.example.lan. If you are using the ClearOS Local DNS Server for your network, then go to Network|Settings|Local DNS Server in the web-based administration tool. Add wpad.example.lan as a new alias for the IP address of your ClearOS system.

As a sanity check, you can try going to http://wpad.example.lan:82/index.php in your web browser. If you do not see a login screen, then double check your DNS server setup.

As an additional sanity check, go to http://wpad:82/index.php in your web browser. If you do not see a login screen, then make sure your client operating system is configured with the default domain example.lan. If you are using the DHCP server for configuring the default domain, check those settings too.

WPAD - Proxy Configuration File

Now it's time to create the wpad.dat file for your ClearOS system. A very basic example is as follows:


    //Don't use the proxy if the site is behind the firewall
    if (isPlainHostName(host) ||
        shExpMatch(host, "*.local") ||
        isInNet(dnsResolve(host), "", "") ||
        isInNet(dnsResolve(host), "",  "") ||
        isInNet(dnsResolve(host), "",  "") ||
        isInNet(dnsResolve(host), "", ""))
        return "DIRECT";

    // allow my servers and printers between .8 and .15 to bypass the proxy
    if (isInNet(myIpAddress(), "", ""))
        return "DIRECT";

    // catch all
    return "PROXY";

The wpad.dat file should go into the /var/webconfig/htdocs on the ClearOS system. As a sanity check, you should see a plain file or a download button when you go to http://example.lan:82/wpad.dat in your web browser.

You can also put it in /var/www/html/ and check it at http://example.lan/wpad.dat

Finishing Off

Fire up the web proxy from the Gateway|Proxy and Filtering|Proxy Server page. Try running the proxy with:

  • Transparent mode disabled
  • Content filter enabled

If you are using password authentication for either the web proxy or if you are using profiles in the content filter, set NTLM authentication.

You can watch the content by watching the end or tail of the following files with these commands:

tail -f /var/log/squid/access.log

or if using authentication or the content filter use:

tail -f /var/log/dansguardian/access.log

As yet another sanity check for the content filter, go to Fark. This page gets blocked by the content filter typically!

Advanced Options

If you want to perform some more advanced functions, check the links at the bottom of the page for more information.


If you have Windows Servers perfoming DNS on your network, you will need to add wpad.example.lan to that DNS server. You may then run into a problem with EventID 6268 and the global query blocklist preventing modification of the wpad host name. To fix the issue do the following:

To allow WPAD entries to be returned, remove the WPAD entry from the blocklist by using these steps:

  1. Open the Registry Editor and navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\DNS\Parameters
  2. Double-click on the GlobalQueryBlockList value to open the editor.
  3. Highlight the wpad entry and press the delete key
  4. Click 'OK' and 'OK' again to return to the main window
  5. Restart the 'DNS Server' service

Important: By default, a wpad and isatap value will be present. Do not delete the isatap value.

content/en_us/kb_o_web_proxy_auto-detection_configuration.txt · Last modified: 2019/01/19 03:01 by nickh