Proxy Automatic Configuration

Introducion

The Proxy Automatic Configuration file describes how client software (a web browser or a network-enabled application) should access to Internet. It can configure direct access or access via proxy. Configuring proxy via the PAC file is easier for user (see screenshot below) and allows custom configuration for different websites or protocols.

PAC scripts also sometimes called WPAD - Windows Proxy Auto Discovery. This is a feature of Windows Internet stack, used by Microsoft Internet Explorer from 5 to 11 versions.

Useful articles:

• ℹ️ https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file
• ℹ️ https://en.wikipedia.org/wiki/Web_Proxy_Auto-Discovery_Protocol

Syntax

The PAC script is a JavaScript file with a single function, which returns connection method for requested URL. To differ it from regular JS files, it have application/x-ns-proxy-autoconfig MIME content type.

Example

An easiest example of the script:

function FindProxyForURL(url, host)
{ return 'PROXY 192.168.1.46:8080'; }

The example is enabling 192.168.1.46:8080 HTTP proxy for all requests. However, this does not differs protocols, used by browser. If client want to go to a FTP or Gopher site, browser still will try open that site via 192.168.1.46:8080. So if the proxy don't support the protocol, we'll got an error. In most cases it is need to configure access mode depending on the request URL or host. Also if the 192.168.1.46:8080 is inaccessible, there will be no Internet access at all.

Return values

The FindProxyForURL function of PAC returns a set of proxies for the specified request. The list looks as TYPE1 ADDRESS1; TYPE2 ADDRESS2; TYPEn ADDRESSn. So the browser will try to use proxies by the order. If first is inaccessible, second will be used, then third, fourth and until browser experience success or the list ends.

Types of proxy:

• PROXY, HTTP - a HTTP proxy.
• HTTPS - a HTTPS proxy (an HTTP proxy with support for CONNECT method and raw SSL/TLS gateway mode).
• SOCKS, SOCKS4, SOCKS5 - a SOCKS proxy with specified or unspecified version.
• DIRECT - direct connection to WWW, bypassing any proxies. A following URL is not need in this case.

Example: PROXY 192.168.1.46:8080; PROXY w3proxy.netscape.com:8091; SOCKS 192.168.5.55:1080; DIRECT.

What can be used in the script

PAC scripts can utilize almost full JavaScript capabilities, which can be used outside Web pages. The limitation is that JS functions used for interaction with user or configure the Navigator are inaccessible in PAC.

There also additional JS functions, available only in PAC scripts:

• Hostname based conditions
  • isPlainHostName(host)
  • dnsDomainIs(host, domain)
  • localHostOrDomainIs(host, hostdom)
  • isResolvable(host)
  • isInNet(host, pattern, mask)
• Related utility functions
  • dnsResolve(host)
  • convert_addr(ipaddr)
  • myIpAddress()
  • dnsDomainLevels(host)
• URL/hostname based conditions
  • shExpMatch(str, shexp)
• Time based conditions
  • weekdayRange(wd1, wd2, [gmt])
  • dateRange([7 overloads])
  • timeRange(hour1, min1, sec1, hour2, min2, sec2, [gmt])
• Logging utility
  • alert(message)

Configuring PAC in WebOne

To configure PAC script in WebOne, comment the [PAC] section in webone.conf and write your own. Or edit the existing section.

It is possible to use %PACProxy%, %ProxyHost%, %ProxyPort% substition masks in the script. They will be replaced with public server IP:Port pair, a DefaultHostName option value and Port option value of WebOne configuration.

The default PAC script checks URL for protocol, and returns the proxy server IP or default host name:

function FindProxyForURL(url, host){
if (url.substring(0, 5) == 'http:')
{ return 'PROXY %PACProxy%'; }
} /*WebOne PAC*/

WPAD

WPAD also supported by WebOne. To use it, configure your local DNS server or edit C:\WINDOWS\SYSTEM32\DRIVERS\ETC\HOSTS file, and enter such line:

192.168.1.46      wpad

(with real IP of proxy server instead of 192.168.1.46).

Then Microsoft Internet Explorer 5.0-11 will automatic find WebOne in the network, and install the auto-configuration script from proxy. Also all Windows software, which uses system/Microsoft Internet stack will use the configuration too.

IPv6

Seems that IPv6 is not supported in PAC scripts in Netscape, Firefox, and IE 4/5/6. IE 7+ have some support.

Browser-specific notes

Older versions of Netscape

The alert(string) function can display real message boxes. In later versions of Netscape (and Mozilla too) it only prints to browser's console.

Internet Explorer 6 SV1 and Windows XP SP2

Sometimes the browser tries to load http://wpad/wpad.da file instead of http://wpad/wpad.dat. However, WebOne have a workaround for this, and WPAD still works as expected. This also related to software, using Windows XP SP2 Internet feature stack.

Internet Explorer 6/7/8 and Windows XP SP2/SP3 & Windows Server 2003

• A PAC script is not permitted to execute for longer than 60 seconds, after which script execution is terminated.
• WinHTTP rejects PAC files larger than 1MB. A typical PAC file is usually no more than a few kilobytes in size.