Proxy auto-config

The proxy auto-config file defines how web browsers can automatically choose the appropriate proxy server for fetching a given URL:

A PAC file contains a JavaScript function "FindProxyForURL(url, host)". This function returns a string with one or more proxy specifications: multiple specifications provide a fallback when a proxy fails to respond. The browser fetches this PAC file before retrieving other pages. The URL of the PAC file is either configured manually or determined automatically by the Web Proxy Autodiscovery Protocol.

Context

Modern web browsers implement several levels of automation; you can choose the level that is appropriate to your needs. The following methods are commonly implemented:

• Manual proxy selection: Specify a hostname and a port number to be used for all URLs. Most browsers allow you to specify a list of domains (such as localhost) that will bypass this proxy.

• Proxy auto-configuration (PAC): Specify the URL for a PAC file with a JavaScript function that determines the appropriate proxy for each URL. This method is discussed in this article.

• Web Proxy Autodiscovery Protocol (WDAP): Let the browser guess the location of the PAC file. This is discussed in a separate article.

The first option is the simplest (and most secure). The second option (PAC) is more flexible (allowing many different proxies to be used). Still, you have to set the URL of the PAC file once manually. The third option (WDAP) builds on top of PAC and removes this requirement of manual configuration: You can instruct all browsers within your organisation to use the same PAC configuration.

The PAC File

To use PAC, you publish a PAC file on a Web server and instruct your browser to read it (either by entering the URL in the proxy connection settings of your browser or by using the WPAD protocol).

A PAC file is a text file that defines one JavaScript function FindProxyForURL(url, host). By convention, this file is often named proxy.pac, but when using the WPAD standard, it's often called wpad.dat. You must instruct your web server to declare the mime type of this file to be: application/x-ns-proxy-autoconfig.

A very simple example of a PAC file is:

  function FindProxyForURL(url, host) { return "PROXY proxy.foo.com:8080; DIRECT"; }

This function instructs the browser to retrieve all pages through the proxy on port 8080 of the server proxy.foo.com. Should this proxy fail to respond, the browser contacts the WWW directly, without using a proxy.

Here is a more complicated example demonstrating some available JavaScript functions to be used in the FindProxyForURL function:

  function FindProxyForURL(url, host) {
     // our local URLs from the domains below foo.com don't need a proxy:
     if (shExpMatch(url,"*.foo.com/*"))                  {return "DIRECT";}
     if (shExpMatch(url, "*.foo.com:*/*"))               {return "DIRECT";}
     
     // URLs within this network are accessed through 
     // port 8080 on fastproxy.foo.com:
     if (isInNet(host, "10.0.0.0",  "255.255.248.0"))    {
        return "PROXY proxy.foo.com.8080"
     }
     
     // All other reqests go through port 8080 of proxy.foo.com.
     // should that fail to respond, go directly to the WWW:
     return "PROXY proxy.foo.com:8080; DIRECT";
  }

Here is a Lists of predefined functions available for use.

Limitations

The function isInNet (and similar other functions) perform a DNS lookup that can block your browser if the DNS server does not respond.

Proxy caching in Microsoft's Internet Explorer limits the flexibility of the PAC standard. In effect, you can choose the proxy based on the domain name, but not on the path of the URL. Alternatively, you need to disable Proxy caching. Read the excellent "Frequently Given Answer" Automatic proxy HTTP server configuration in web browsers for more details.

External links

• Lists of predefined functions available for use
• Excellent "Frequently Given Answer" Automatic proxy HTTP server configuration in web browsers