Writing and Testing Proxy Auto-Configuration (PAC) Files
Last updated
Last updated
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. Additionally, if the PAC file has many lines or complex logic, the pactester
utility can be used to check the syntax of PAC file. Information for installation and use of pactester is also presented.
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).
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 |
---|---|
Specifying more than one string as a return value provides a fallback mechanism. For example, in the following return statement:
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.
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:
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 files can declare and use JavaScript variables. Additionally, methods for the allowed JavaScript functions can be used.
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.
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.
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.
Before installing a PAC file into an Enterprise Agent, the pactester
utility can be employed to validate the PAC file. The pactester utility uses the pacparser library, which can be installed on Linux, Mac OS X and Windows. Instructions for installing on Linux operating systems which can support Enterprise Agents are found below. Consult the pacparser documentation for installation on other operating systems.
Ubuntu Linux provides repositories with the libpacparser1 package, which can be installed with the following steps.
Update repository metadata: sudo apt-get update
Install the libpacparser1 package: sudo apt-get install libpacparser1
Installation of libpacparser1 will install the pactester utility in the /usr/bin directory.
Red Hat Enterprise Linux and RHEL-based distributions do not provide a compiled package for pacparser/pactester. Installation requires building the project from source:
If needed, install the required build tools: sudo yum install -y gcc make unzip git
sudo yum clean all
Clone the project from the git repository: git clone https://github.com/pacparser/pacparser.git
Build pacparser: cd pacparser
make -C src
make -C src install
ldconfig
Clean up: cd ..
rm -rf pacparser
Copy your PAC file to the system with pactester
, and run the following command:
Where pacfile is the path to the PAC file to be tested, and URL is the test URL. The output will be the return value chosen for URL. For example, when using the PAC file from the PAC file example - shell expressions section, the following command:
returns:
Repeat as needed with different URLs until all return values have been tested.