Loading...

Knowledge Center


How to use PAC files with Web Gateway
Technical Articles ID:   KB67177
Last Modified:  12/20/2018
Rated:


Environment

McAfee Web Gateway (MWG) 7.x

Summary

About PAC files

Proxy Automatic Configuration (PAC) is a proxy mode where the proxy configuration is described in a file using JavaScript, called a PAC file, with .pac as the file extension. The file is maintained by the network administrator and requires no user updating (hence it is "automatic"). As a browser user, you need only a URL provided by your administrator.

PAC has two advantages over normal configurations:
  • Network-based .pac files are centrally administered and easy to update. Network administrators usually share the .pac files using HTTP. If there are server changes or network outages, the .pac file can be changed, and your browser configuration will be automatically updated when the new .pac file is loaded.
     
  • You can use complicated network environments with a single configuration. PAC has support for load balancing and failover.
All browsers have the facility to use .pac files. The JavaScript contained within a .pac file can perform tasks and make decisions based on the URL to which you are browsing, the IP address of your browser, which proxy should service the traffic, and which other proxies should be used alternatively. The file defines the function FindProxyForURL(url,host). When you enter a URL into a browser, the URL and domain are sent as parameters to the function and a proxy setting is returned based on that data.

Using a PAC file with Web Gateway

Browsers must retrieve a PAC file from a web server. Web Gateway can host the PAC file, but that is the limit of its deployment participation. You still need some external method to tell the browser to use it. This is typically done using WPAD (Web Proxy Autodiscovery Protocol) or GPO (Group Policy Objects), both of which are discussed later in this article.

The PAC file is typically named proxy.pac, and Web Gateway uses this naming convention when hosting the PAC file, except when used in conjunction with WPAD, when it is renamed to wpad.dat (it is the same exact file with a different name).

Solution

This section discusses the following PAC file topics:

PAC Examples:

The contents of the PAC file will vary depending on your environment and preferences. By putting more complexity in the PAC file logic, you can granularly regulate the behavior of the browser's proxy usage. Below are some example PAC file contents. More documentation for PAC file options is available on the Internet.
  • This is the simplest example of a PAC file. It directs all requests to the proxy (Web Gateway). In this example, Web Gateway's IP address is 192.168.0.222.
     
    function FindProxyForURL(url, host) {return "PROXY 192.168.0.222:9090";}
     
    This is identical to configuring the following Internet Explorer proxy settings:

      
     
  • This example directs all requests to Web Gateway (192.168.0.222), and fails over to a second proxy (192.168.0.223) if Web Gateway is unavailable. (This failover functionality cannot be emulated directly within a browser's proxy settings.)
     
    function FindProxyForURL(url, host) {return "PROXY 192.168.0.222:9090; PROXY 192.168.0.223:9090";}
     
  • This example tells the browser to make a direct connection, rather than using a proxy, if both proxies (192.168.0.222 and 192.168.0.223) are unavailable.
     
    function FindProxyForURL(url, host) {return "PROXY 192.168.0.222:9090; PROXY 192.168.0.223:9090; DIRECT";}
     
  • This example tells the browser to use the proxy for all URLs except those within the *.company.com domain.
     
    function FindProxyForURL(url, host) { if (dnsDomainIs(host, ".company.com")) return "DIRECT"; else return "PROXY proxy01.company.com:9090"; }
     
  • This example tells the browser to use the proxy for all URLs except those with an IP address within the internal subnet 10.1.1.0/24.
     
    function FindProxyForURL(url, host) { if (isInNet(host, "10.1.1.0", "255.255.255.0")) return "DIRECT"; else return "PROXY proxy01.company.com:9090"; }
     
  • This example is more complex. If your local address is in the subnet 10.1.1.0/24, use proxy01. Use proxy03 if you are anywhere else on the network. proxy02 is a standby if either proxy01 or proxy03 fails. If the destination is within the local subnets or *.company.com, do not use a proxy.
     
    function FindProxyForURL(url, host) { if (dnsDomainIs(host, ".company.com") || isInNet(host, "10.1.1.0", "255.255.255.0") || isInNet(host, "192.168.1.0", "255.255.255.0")) return "DIRECT"; else if (isInNet(myIPAddress(), "10.1.1.0", "255.255.255.0")) return "PROXY proxy01.company.com:9090; proxy02.company.com:9090"; else return "PROXY proxy03.company.com:9090; proxy02.company.com:9090"; }

PAC Considerations when used with Web Gateway

McAfee recommends that you do not proxy the following types of connections:
  • internal to internal
  • to Web Gateway
Web proxies were originally used as a simple gateway mechanism to cache the flow of traffic to the Internet. A request would be made to a proxy server, which would service that request and respond with the page. It is common practice not to proxy connections that are destined for an internal web server in your private network. Because Web Gateway performs many security functions (for example, caching, content scanning, authentication, and SSL decryption), this reduces network traffic overall by creating a single session from the client to the server, rather than the client to the Web Gateway proxy to the server. 

Because Web Gateway uses techniques like page redirection, session injection, and JavaScript insertion, it is important that traffic to Web Gateway is not proxied. For example, you should not proxy the administration session to the Web Gateway user interface because it may intercept and filter important information out of the session.

You can define these exceptions in the PAC file the browser will use. You may need to specify the exceptions differently depending on browser because not all browsers interpret the PAC file in the same manner.

Suppose you have the following network:
  • The local DNS domain of the network is company.local. Any host within this domain is resolved to an internal private IP address.
  • The domain company.com is contained within a DMZ that is accessible from the Internet; however, when an internal user resolves that domain, the private DMZ addresses are returned, not the public addresses (common in a split-DNS environment).
  • The LAN IP addresses are split between two physical locations and subnets:
    • Location A: 10.1.0.0/16
    • Location B: 10.2.0.0/16
  • There are two Web Gateways, one at each location:
    • Location A: proxy01.company.local = 10.1.0.222
    • Location B: proxy02.company.local = 10.2.0.222
  • The DMZ IP addresses are 172.16.0.0/16.
  • There are some Guest Wireless networks with the IP addresses 192.168.0.0/16.
  • There is a third proxy, Squid proxy, used only by the Wireless network. It is in the DMZ with other servers. The DMZ Squid proxy is squid.company.com = 172.16.0.222.
Below are some examples of how to create the exceptions:
  • Excluding the local domains
    Use these statements to exclude the local domain (for example, http://company.com, http://host.company.com, http://host.company.com:8888, http://company.local, http://host.company.local, and http://host.company.local:8888) from being proxied.
     
    if (dnsDomainIs(host,"company.com")) {return "DIRECT";} if (dnsDomainIs(host,"company.local")) {return "DIRECT";}
     
  • Excluding all private subnets
    Check whether the URL specified is an IP address that matches any of your private subnets. The following statement uses a shExpMatch to perform a string lookup of the address. If the subnets are on non-octet boundaries (not /8, /16, or /24), this will not work.
     
    if ((shExpMatch(host,"127.0.0.1")) || (shExpMatch(host,"10.*.*.*")) || (shExpMatch(host,"172.16.*.*")) || (shExpMatch(host,"192.168.*.*")) ) {return "DIRECT";}
     
    Alternatively, you can use the isInNet function, but it will attempt to resolve everything that is not an IP address. The browser will perform a DNS lookup for every request. If your client cannot resolve Internet addresses, there will be a long delay before it times out and a page is returned. So, it is not recommended to do this unless your internal DNS can resolve Internet addresses.
     
    if ((isInNet(host, "127.0.0.1", "255.255.255.255")) || (isInNet(host, "10.0.0.0", "255.0.0.0")) || (isInNet(host, "172.16.0.0", "255.240.0.0")) || (isInNet(host, "192.168.0.0", "255.255.0.0")) ) {return "DIRECT";}
     
  • Excluding plain hostnames
    There will be occasions when you specify a short hostname (a host with no dots in its name) instead of a Fully Qualified Domain Name (FQDN) in the URL. Examples of this include http://localhost, http://localhost:8888, http://intranet, http://webmail/, http://server:8888, and https://proxy01:10000. Although your local computer may be able to resolve that name using DNS or WINS, it will be unlikely that Web Gateway will be able to. Use the following statement to exclude a short hostname:
     
    if (isPlainHostName(host)) {return "DIRECT";}
     
    This is the same as selecting Bypass proxy server for local addresses in the browser. You are able to have DNS search suffixes appended to a hostname in Web Gateway, so if you sometimes want Web Gateway to resolve short names, you can edit file /etc/resolv.conf and change the search entry. 
     
  • Excluding Web Gateway itself from being proxied
    This is the most important part of a PAC file when used in conjunction with Web Gateway. Because Web Gateway has many techniques to manipulate traffic for security and authentication, it is imperative that any session directed to Web Gateway under any port number be excluded. When it is not, unpredictable results may happen due to proxy loop conditions occurring. The above statements may cover the conditions in which local traffic is excluded from being proxied, but as a last resort you should explicitly exclude the proxies by IP address, host, and FQDN to ensure they are covered. If the Squid proxy is using some filtering too, you should include it in this list to ensure that block pages are displayed properly. In the network described above, this is how you would do that:  
     
    if (shExpMatch(host,"10.1.0.222")) {return "DIRECT";} //proxy01's IP address if (shExpMatch(host,"10.2.0.222")) {return "DIRECT";} //proxy02's IP address if (shExpMatch(host,"172.16.0.222")) {return "DIRECT";} //squids's IP address if (shExpMatch(host,"proxy01")) {return "DIRECT";} //proxy01's host name if (shExpMatch(host,"proxy02")) {return "DIRECT";} //proxy02's host name if (shExpMatch(host,"squid")) {return "DIRECT";} //sqids's host name if (shExpMatch(host,"proxy01.company.local")) {return "DIRECT";} //proxy01's FQDN if (shExpMatch(host,"proxy02.company.local")) {return "DIRECT";} //proxy02's FQDN if (shExpMatch(host,"squid.company.com")) {return "DIRECT";} //squid's FQDN
     
  • Deciding which proxy to use
    The statements above determine which conditions will bypass the proxy entirely. Now you need to determine which proxy to use for other traffic. You can use conditional statements to determine which proxy based on the destination host, URL, and the source IP address of the user. For localization of proxy usage according to your IP address you can include statements like these:
     
    if(isInNet(myIpAddress(),"10.1.0.0","255.255.0.0")) {return "PROXY proxy01.company.local:9090";} if(isInNet(myIpAddress(),"10.2.0.0","255.255.0.0")) {return "PROXY proxy02.company.local:9090";} if(isInNet(myIpAddress(),"192.168.0.0","255.255.0.0")) {return "PROXY squid.company.com:3128";}
     
    This specifies that if you are in the 10.1.0.0/16 subnet, use proxy01. If you are in the 10.2.0.0/16 subnet, use proxy02. And, if you are using wireless on 192.168.0.0/16, use Squid. This method tells the browser to use the closest proxy according to subnet.
     
  • Redundancy/Failover
    Specifying a single proxy as above does not allow for an alternative when the proxy is not online. The return PROXY results are allowed to specify multiple proxies to fail over to if the first one is not available. If you want to try proxy01 first, then proxy02, then Squid, use return statements like this:
     
    {return "PROXY proxy01.company.local:9090; PROXY proxy02.company.local:9090; PROXY squid.company.com:3128";}
     
    Each returned list of proxies can be unique so the local proxy is used first, the other remote proxy is tried second, and as a last resort the Squid proxy is used.
Complete PAC file example
Using all of the components described above, the full PAC file might look like this:

function FindProxyForURL(url, host) { if (dnsDomainIs(host,"company.com")) {return "DIRECT";} //check for local domains if (dnsDomainIs(host,"company.local")) {return "DIRECT";} //check for local IP addresses if ((shExpMatch(host,"127.0.0.1")) || (shExpMatch(host,"10.*.*.*")) || (shExpMatch(host,"172.16.*.*")) || (shExpMatch(host,"192.168.*.*")) ) {return "DIRECT";} if (isPlainHostName(host)) {return "DIRECT";} //check for short host names //make absolutely sure the sessions to theses servers are in no way proxied if (shExpMatch(host,"10.1.0.222")) {return "DIRECT";} //proxy01's IP address if (shExpMatch(host,"10.2.0.222")) {return "DIRECT";} //proxy02's IP address if (shExpMatch(host,"172.16.0.222")) {return "DIRECT";} //squids's IP address if (shExpMatch(host,"proxy01")) {return "DIRECT";} //proxy01's host name if (shExpMatch(host,"proxy02")) {return "DIRECT";} //proxy02's host name if (shExpMatch(host,"squid")) {return "DIRECT";} //sqids's host name if (shExpMatch(host,"proxy01.company.local")) {return "DIRECT";} //proxy01's FQDN if (shExpMatch(host,"proxy02.company.local")) {return "DIRECT";} //proxy02's FQDN if (shExpMatch(host,"squid.company.com")) {return "DIRECT";} //squid's FQDN//if you get this far, then decide which proxy to use//use proxy01, proxy02, squid if in the 10.1.0.0 subnetif(isInNet(myIpAddress(),"10.1.0.0","255.255.0.0")) {return "PROXY proxy01.company.local:9090; PROXY proxy02.company.local:9090; PROXY squid.company.com:3128";}//use proxy02, proxy01, squid if in the 10.2.0.0 subnetif(isInNet(myIpAddress(),"10.2.0.0","255.255.0.0")) {return "PROXY proxy02.company.local:9090";} {return "PROXY proxy02.company.local:9090; PROXY proxy01.company.local:9090; PROXY squid.company.com:3128";}//only try squid. if on wireless network.if(isInNet(myIpAddress(),"192.168.0.0","255.255.0.0")) {return "PROXY squid.company.com:3128";}//as a last resort if no other conditions apply, use proxy01, proxy02, squidreturn "PROXY proxy01.company.local:9090; PROXY proxy02.company.local:9090; PROXY squid.company.com:3128";}

Uploading a PAC File to Web Gateway

To host the PAC file on Web Gateway:
  1. Log on to the Web Gateway user interface.
  2. Go to Configuration, Backup & Restore, Proxy PAC.
  3. Browse to and select the PAC file.
  4. Click Upload.
Now you can configure the browsers to use the PAC file.
  • Example Internet Explorer setting:
    Select Use automatic configuration script.
    Address: http://10.1.0.222:4713/files/proxy.pac
  • Example Firefox setting:
    Select Automatic proxy configuration URL and specify http://10.1.0.222:4713/files/proxy.pac.
Using Group Policy Objects (GPO) to Tell Browsers to use the PAC File

The challenge most network administrators have is how to configure the browser settings to utilize a proxy without having to touch each desktop. In a Microsoft Active Directory environment, you can use the Group Policy feature to make this managed change. Group Policy Objects permit you to propagate centralized settings to individual systems or users. A comprehensive guide to GPO is beyond the scope of this article; therefore you should consult Microsoft documentation for planning and implementation of GPO. In its simplest terms, the Group Policy Editor creates Group Policy Objects and these objects are assigned to Active Directory containers.

Internet Explorer
The browser settings are maintained in the Internet Explorer Maintenance\Connection menu, and a typical setting for use with a PAC file would be in the Automatic Browser Configuration menu: 



When using PAC files, Internet Explorer internally caches the proxy server's relationship with the destination website that is being viewed. When Web Gateway inserts block pages, coaching pages, advertising image replacements, proactive scanning script mitigation, or uses Transparent Authentication with the built-in Authentication server, it hosts the injected files on its own interface on port 9999 (or others) whereas the proxied content is usually delivered using port 9090.

Internet Explorer always uses the proxy server through which the first connection to a specific hostname is made, regardless of the settings in the PAC file. If the response from the destination website has port 9999 included code within the contents, or a transparent authentication does a redirect to 9094, subsequent requests for that site attempt to use that alternative port instead of the proxy port of 9090.

When this condition occurs, the user sees symptoms of broken pages with graphics and style sheets not being loaded and error messages that state "Invalid Proxy Request". Other browsers do not exhibit these symptoms.

You can correct this condition by turning off the automatic proxy caching feature using one of the following options:
  • Update the following registry entry:
     
    HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\CurrentVersion\Internet Settings

    Value: EnableAutoproxyResultCache
    Type: REG_DWORD
    Data value:
    <0 = disable caching; 1 (or key not present) = enable automatic proxy caching (this is the default behavior)>
     
  • Use Group Policy at Console Root\Local Computer Policy\User Configuration\Administrative Templates\Windows Components\Internet Explorer\Disable caching of Auto-Proxy scripts.
You can find more information about this issue in the following Microsoft articles:
http://support.microsoft.com/kb/271361/
http://support.microsoft.com/kb/304112/  

Mozilla Firefox
Third-party browsers like Firefox usually do not have the mechanisms built-in to support Active Directory Group Policies. A special version of Firefox is packaged along with a GPO administrative template to assist in the deployment and management of Firefox. You can retrieve this version of Firefox at http://www.frontmotion.com/fmfirefoxce/.

Here is an example of the template and settings that you can deploy:

 

Using Web Proxy Auto Discovery Protocol (WPAD) to Tell Browsers to use the PAC File

You can use WPAD to configure browser settings to utilize a proxy. Most standard browsers support this feature using auto-detect settings (Internet Explorer: Automatically detect settings / Firefox: Auto-detect proxy settings for this network).

WPAD is most useful in the case of laptop users where a different proxy setting is needed depending on location. While in an office location, one PAC file is used, while in a different location a different PAC file is used, but while at home or on the road proxy settings are not necessary. This reduces the need for a user to constantly change proxy settings at different locations.

The WPAD protocol attempts to discover proxy settings in the following order:
  1. Use DHCP Option 252.
  2. Use DNS to find wpad.dat.
  3. Connect directly.
DHCP Option 252
If the client system is using a DHCP server to assign its IP address, before fetching its first page, a web browser makes a DHCPINFORM query to the DHCP server asking for option 252. Option 252 is reserved by Microsoft for a string value containing the URL for a PAC file.

See Microsoft documentation for instructions to set up this option in a Microsoft DHCP server. Here are the basic steps.
  1. Create a Predefined Option for the server.
  2. Add the definition for option 252.
    Example:
    Name: WPAD
    Data type: String
    Code: 252
    Description: URL for Proxy Autodiscovery
  3. Define the URL to use.
    Example:
    Option Class: DHCP Standard Options
    Option name: 252 WPAD
    String: http://10.1.0.222:4713/files/proxy.pac
  4. Assign the option to a DHCP scope.
If the DHCP server does not supply the needed information, WPAD proceeds to the DNS method. 

NOTE: Firefox does not support proxy auto discover using DHCP. For more information, see https://bugzilla.mozilla.org/show_bug.cgi?id=356831.

DNS for WPAD
The WPAD protocol defines a method in which a specific URL is used to locate the WPAD file. This URL is located on a web server within the internal domain of the network. This web server is typically an IIS server, but can be any server type.

The hardcoded URL used is in the form of: http://wpad.company.local:80/wpad.dat

Below is an explanation of each element of this URL:
  • http:// -This must reside on an HTTP server, not an HTTPS-only server.
  • wpad - The hostname of the server hosting the file must have a DNS A record or CNAME aliasing it to the name of wpad.
  • company.local - The operating system must provide the correct domain name (domain suffix) to append to the hostname (WPAD) before sending a query to the WPAD server. By default, the domain used is the client's primary domain suffix (the domain in which the client is located, or is configured to use). If the primary domain suffix does not work, the connection-specific DNS suffix is tried. If the WPAD server is not found in the domain name, subdomains are removed from the domain until a WPAD server is located, or until the third-level domain is reached. For example, in the a.b.company.local domain, the following searches will be made:
    • wpad.a.b.company.local
    • wpad.b.company.local
    • wpad.company.local

    If a WPAD server is not located by the third-level domain, automatic discovery fails.

    The easiest way to tell what domain name is in use is to check the Primary DNS suffix from a command prompt on one of the user's systems.
     
    C:\>ipconfig /all

    Windows IP Configuration
    Host Name . . . . . . . . . . . . : mycomputer
    Primary Dns Suffix . . . . . . . : company.local
     
  • :80 - The web server must be published on port 80.
  • wpad.dat - The wpad.dat file must be in the root folder, and you should not modify the file name. The wpad.dat file contains the same information as the proxy.pac file described above but with a different name. When hosting the wpad.dat file on a web server, the MIME type must be set as application/x-ns-proxy-autoconfig.
In summary, a wpad.dat file must be hosted on a web server published on port 80 with a DNS name of wpad.domain.local. It is common to use one or more intranet servers already existing on a network to support this method, but a technique of hosting the wpad.dat file on the Web Gateway appliance is described below.

Direct Connection
If the two previous methods fail to produce a PAC file for use by the browser, the browser will connect directly to the destination site. This is the desired behavior when a laptop is connected to a home or remote network that does not provide any proxy information.

Rate this document

Beta Translate with

Select a desired language below to translate this page.

Glossary of Technical Terms


 Highlight Glossary Terms

Please take a moment to browse our Glossary of Technical Terms.