Writing and Testing Proxy Auto-Configuration (PAC) Files

Similar to web browsers, ThousandEyes Enterprise Agents can use a proxy auto-config (PAC) file to select a proxy server based on the requested URL and other variables. A PAC file contains a single JavaScript function named FindProxyForURL, which will return an object containing one or more proxies, or indicate that the client should not use a proxy and instead connect directly to the web server. Each request by a Web Layer test (HTTP Server, Page Load, Transaction and FTP Server) will be parsed by the PAC file to select a proxy or direct access for that request.

This article discusses creation of PAC files for various use cases. If the PAC file has many lines or complex logic, the pactester utility can be used to check the syntax of PAC file.

PAC File Composition

A PAC file is a text file defining a single JavaScript function: FindProxyForURL(url, host). The FindProxyForURL function is run in a restricted JavaScript environment, with only a limited set of standard JavaScript functions available to define FindProxyForURL. A list of supported functions can be found here.

ThousandEyes does not recommend the use of the myIpAddress function. This condition returns the IP address of the host machine. However, there is no standardized implementation of the function, and this could result in different behavior between the agent and Browserbot.

PAC files are cached for a limited time, and reloaded on a five minute interval.

If the PAC file is updated with invalid content, the Enterprise Agent may fail (even if it was previously working). In this case, the agent will continue to fail until the PAC file error is corrected and the agent reloads the valid file.

FindProxyForUrl arguments

• url: The URL of the request, in the form protocol://hostname:port/path. The hostname can be a domain name or IP address. The port number is optional if the default port is used for the given protocol (e.g port 80 for http URLs or port 443 for https URLs).

  Example: https://www.example.com:8443/mypage.htm

• host: The hostname extracted from the URL string.

  Example: For the URL in the example above, the host would be "www.example.com"

The url and host variables are populated by the calling program (in the case of an Enterprise Agent, a process that runs a test, uploads data, performs package upgrades, or other functions) and are available for use within the definition of FindProxyForURL.

FindProxyForUrl return values

The return value of the FindProxyForUrl function is the value specified by the JavaScript return function inside the FindProxyForUrl function. The value must be comprised of one or more of the following strings:

Return value (string)	Result
DIRECT	Request in the url variable will be sent directly to the web server in the host variable (see FindProxyForUrl arguments above).
PROXY host:port	Request in the url variable will use proxy host on port number port.

Specifying more than one string as a return value provides a fallback mechanism. For example, in the following return statement:

return "PROXY proxy1.example.com; PROXY proxy2.example.com; DIRECT";

if "proxy1.example.com" is unresponsive, the next method specified by the subsequent string will be used, in this case proxying through "proxy2.example.com". If that proxy does not respond, the next request method, "DIRECT" is tried. Multiple strings must be separated by semi-colons. The request method keywords "DIRECT", and "PROXY" are case-sensitive (must be upper-case).

NOTES:

• Proxy fallback is only supported for Page Load and Transaction tests (BrowserBot). HTTP Server and FTP Server tests, as well as administrative connections from the Agent to the ThousandEyes platform do not support any fallback proxy or proxies in the PAC file.

• ThousandEyes tests do not currently support SOCKS-based proxies.

PAC File Example - Basic

A typical PAC file contains multiple if statements, each with a return function within the execution block of the if statement. When the conditions of the if statement are met, the block's return statement is executed and the FindProxyForUrl function terminates. No further evaluation is performed. If the conditions of an if statement are not met, processing continues. The last line of a PAC file is typically a return statement without an enclosing if statement, which acts as a "clean-up" or "catch-all" rule. JavaScript comments are permitted using "//" and "/*" syntax. A basic example of a PAC file:

function FindProxyForURL(url,host)

{

    // Access the internet directly for one site

    if (dnsDomainIs(host, "www.example.com")) {

        return "DIRECT";

    }

    // No proxy for private (RFC 1918) IP addresses (intranet sites)

    if (isInNet(dnsResolve(host), "10.0.0.0", "255.0.0.0") ||

        isInNet(dnsResolve(host), "172.16.0.0", "255.240.0.0") ||

        isInNet(dnsResolve(host), "192.168.0.0", "255.255.0.0")) {

         return "DIRECT";

    }

    // No proxy for localhost

    if (isInNet(dnsResolve(host), "127.0.0.0", "255.0.0.0")) {

        return "DIRECT";

    }

    // Clean-up rule. Everything else uses a proxy. Note semi-colon delimiter between strings.

    return "PROXY proxy1.example.com:8080; PROXY proxy2.example.com:8080; DIRECT";

}

This example demonstrates the basic PAC file constructs for accessing web sites directly using a return value string of "DIRECT", and for accessing web sites using one or more proxies by returning a string containing the proxy or proxies. The example tests the value of the "host" parameter passed to the function using two functions, dnsDomainIs and dnsResolve, in "if" statements.

This example also demonstrates a clean-up rule which returns three access methods: two proxies and then the direct access. If the first proxy in the list is not available, the second with be tried after the first request times out. If neither of the two proxies is available, the request will be sent directly to the web server.

PAC File Example - JavaScript Variables and Methods

PAC files can declare and use JavaScript variables. Additionally, methods for the allowed JavaScript functions can be used.

function FindProxyForURL(url,host)

{

    // Declare a variable to store the result of DNS resolution

    // Avoids multiple lookups (even from cache) and DNS A records with multiple mappings

    var host_ip = dnsResolve(host);

    // Declare a variable to store the protocol of the request

    // Extract the protocol from the URL using the substring and indexOf methods

    var protocol = url.substring(0, url.indexOf(":") - 1);


    // No proxy for private (RFC 1918) IP addresses (intranet sites)

    // Using host_ip variable simplifies code for easier reading

    if (isInNet(host_ip, "10.0.0.0", "255.0.0.0") ||

        isInNet(host_ip, "172.16.0.0", "255.240.0.0") ||

        isInNet(host_ip, "192.168.0.0", "255.255.0.0")) {

         return "DIRECT";

    }

    // No proxy for localhost

    if (isInNet(host, "127.0.0.0", "255.0.0.0")) {

        return "DIRECT";

    }

    //Choose a proxy based on the URL's protocol

    if (protocol == "ftp" || protocol == "ftps") {

       return "PROXY ftpproxy.example.com:8021";

    } else if (protocol == "https") {

       return "PROXY sslproxy.example.com:8443";

    } else {

       return "PROXY proxy.example.com:8080";

    }

}

In this example, we used methods of the allowed JavaScript functions to extract portions of the URL requested, and assigned values to variables which were used to increase the readability and efficiency of the code.

PAC File Example - Shell Expressions

The shExpMatch function can be used to match the host or url inputs against a shell regular expression. Shell regular expression characters are similar to regular expressions, but have some differences. Be sure to review the syntax of shell expressions if the differences are not familiar.

function FindProxyForURL(url,host)

{

   // For HTTPS URLs, choose a proxy based on the URL's protocol

    if (shExpMatch(url, "https://*")) return "PROXY sslproxy.example.com:8443";


    // For HTTP URLs, choose a proxy based on content in the URL's path (file extension)

    if (shExpMatch(url, "http://*/*.jpg")  || 

        shExpMatch(url, "http://*/*.gif")  ||

        shExpMatch(url, "http://*/*.png")) { 

         return "PROXY imgproxy.example.com:8080";

    } else {

         return "PROXY proxy.example.com:8080";

    }
}

In this example, the value of url is compared to shell expressions in two if statements. The first looks for https URLs, and the second for image file extensions, in order to choose the proxy to which the request is sent. Shell expressions can match any part of a URL, such as the URL parameters.