Go to the table of contents Go to the previous page You are at the end of the document View or print as PDF
PAC file best practices
PAC File Best Practices | Web Security Gateway (Anywhere) | Version 7.x
*
*
*
*
*
*
JavaScript best practices for PAC files
The Javascript skills needed for most PAC file development are modest. Occasionally, an advanced understanding is needed. A good Internet resource is the website www.findproxyforurl.com.
Whether you are creating a new PAC file or assuming responsibilities for an existing file, these best practices are worth consideration. The list is inspired by and incorporates many entries from a blog post by Lee Harvey titled "Proxy Automatic Config (PAC) File Tips".
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
JavaScript functions most commonly used in a PAC file
From 'PAC Functions Explained'
(
http://findproxyforurl.com/pac-functions)
isPlainHostName()
This function returns true if the hostname contains no dots. Example: http://intranet
Useful when applying exceptions for internal websites that may not require resolution of a hostname to IP address to determine if local.
Example:
if (isPlainHostName(host)) return "DIRECT";
dnsDomainIs()
Evaluates hostnames and returns true if hostnames match. Used mainly to match and exception individual host names.
Example:
if (dnsDomainIs(host, ".google.com")) return "DIRECT";
localHostOrDomainIs()
Evaluates hostname and only returns true if an exact hostname match is found.
Example:
if (localHostOrDomainIs(host, "www.google.com")) return "DIRECT";
isResolvable()
Attempts to resolve a hostname to an IP address and returns true if successful. WARNING - This may cause a browser to temporarily hang if a domain is not resolvable.
Example:
if (isResolvable(host)) return "PROXY proxy1.example.com:8080";
isInNet()
This function evaluates the IP address of a hostname and if a specified subnet returns true. If a hostname is passed, the function will resolve the hostname to an IP address.
Example:
if (isInNet(host, "172.16.0.0", "255.240.0.0")) return "DIRECT";
dnsResolve()
Resolves hostnames to an IP address. This function can be used to reduce the number of DNS lookups.
Example:
var resolved_ip = dnsResolve(host);
if (isInNet(resolved_ip, "10.0.0.0", "255.0.0.0") ||
isInNet(resolved_ip, "172.16.0.0", "255.240.0.0") ||
isInNet(resolved_ip, "192.168.0.0", "255.255.0.0") ||
isInNet(resolved_ip, "127.0.0.0", "255.255.255.0"))
return "DIRECT";
myIpAddress()
Returns the IP address of the host machine.
Example:
if (isInNet(myIpAddress(), "10.10.1.0", "255.255.255.0")) return "DIRECT";
dnsDomainLevels()
This function returns the number of DNS domain levels (number of dots) in the hostname. Can be used to exception internal websites which use short DNS names, such as: http://intranet
Example:
if (dnsDomainLevels(host) > 0)
return "PROXY proxy1.example.com:8080";
else return "DIRECT";
shExpMatch()
Attempts to match hostname or URL to a specified shell expression and returns true if matched.
Example:
if (shExpMatch(url, "*vpn.domain.com*") ||
shExpMatch(url, "*abcdomain.com/folder/*"))
return "DIRECT";
weekdayRange()
Can be used to specify different proxies for a specific day range. Note: the example employs 'proxy1.example.com' Monday through Friday.
Example:
if (weekdayRange("MON", "FRI"))
return "PROXY proxy1.example.com:8080";
else return "DIRECT";
dateRange()
Can be used to specify different proxies for a specific date range. Note: The example employs 'proxy1.example.com' January through March.
Example:
if (dateRange("JAN", "MAR"))
return "PROXY proxy1.example.com:8080";
else return "DIRECT";
timeRange()
Can be used to specify different proxies for a specific time range. Note: The example employs 'proxy1.example.com' 8 AM to 6 PM.
Example:
if (timeRange(8, 18))
return "PROXY proxy1.example.com:8080";
else return "DIRECT";
Potential PAC function issues
From the Wikipedia article titled "Proxy auto-config" (http://en.wikipedia.org/wiki/Proxy_auto-config) with additions from the Websense knowledge base.
A PAC file may have the following limitations:
dnsResolve
The function dnsResolve (and similar other functions) performs a DNS lookup that can block your browser for a long time if the DNS server does not respond.
If you cache proxy auto-configuration results by domain name in your browser (such as Microsoft's Internet Explorer 5.5 or higher) instead of the path of the URL, it limits the flexibility of the PAC standard. Alternatively, you can disable caching of proxy auto-configuration results by editing the registry.
It is recommended to always use IP addresses instead of host domain names in the isInNet function for compatibility with other Windows components that make use of the Internet Explorer PAC settings, such as .NET 2.0 Framework. For example,
if (isInNet(host, dnsResolve(sampledomain) , "255.255.248.0"))
// .NET 2.0 will resolve proxy properly
if (isInNet(host, sampledomain, "255.255.248.0"))
// .NET 2.0 will not resolve proxy properly
The current convention is to fail over to the direct connection when a PAC file is unavailable.
When switching quickly between network configurations (for example, when entering or leaving a VPN), dnsResolve may give outdated results due to DNS caching.
For instance, Firefox usually keeps 20 domain entries cached for 60 seconds. This may be configured via the network.dnsCacheEntries and network.dnsCacheExpiration preference variables. Flushing the system's dns cache may also help, (such as by using the sudo service dns-clean start in Linux).
myIpAddress
The myIpAddress function has often been reported to give wrong or unusable results (for example, 127.0.0.1, the IP address of the localhost). It may help to remove any lines referring to the machine hostname on the system's host file (such as /etc/hosts on Linux).
Also, when the browser is Firefox 3 or higher, and the operating system has IPv6 enabled, which is the default in Windows 7 and Vista, the myIpAddress function returns the IPv6 address, which is not usually expected nor programed for in the PAC file. For a discussion of solutions, see this Mozilla forum discussion.
Others
Further limitations are related to the JavaScript engine on the local machine.
 
Note 
How do I restrict the browsers allowed in my network to only those that can be configured with a PAC or WPAD file?
If you are using Microsoft Active Directory and Internet Explorer, the recommended approach is to use a Group Policy Object (GPO). Windows Group Policy is designed for centralized IT control and configuration of Windows computers that are members of Active Directory Domain Services.
For configuration details, see How do I configure a Group Policy so that Internet Explorer uses the PAC file? For an introduction to Group Policy, see these Microsoft TechNet articles: Group Policy for Beginners and Managing Browser Settings with Group Policy Tools.
Most other browsers will consume a PAC file but do not provide support for GPO. This makes it much more challenging for administrators to control the configuration and use of alternate browser (Firefox 3 offered a GPO add-on, but Firefox 3 is long gone). Search the Internet for tools and strategies available for your organization's chosen browser.
 
Note 
How do I configure a Group Policy so that Internet Explorer uses the PAC file?
1.
Log on to a server in the domain, and, with administrative permissions, open Start > Programs > Administrative Tools > Active Directory Users & Computers and expand your domain.
2.
Right click the top-level domain or Organizational Unit where the policy should be applied, select Properties, and then select the Group Policy tab.
3.
4.
Edit the GPO from the following location: User configuration > Windows Settings > Internet Explorer Maintenance > Connection > Automatic Browser Configuration
5.
Select Enable Automatic Configuration.
6.
Under Auto-proxy URL (.JS, .JVS, or .PAC file), enter the path to the PAC file.
*
If you are running Websense Web Security Gateway Anywhere (hybrid) you will find the path for the PAC file located in the Web Security manager under Settings > Hybrid Configuration > User Access > Proxy Auto-Configuration (PAC). It will look something like this:
http://hybrid-web.global.blackspider.com:8082/proxy.pac?p=
7.
In Automatically configure every field, specify how often the web browser should query for the auto-configuration. For example, if you enter 240 minutes, every 4 hours the web browser checks for an updated PAC file. If you leave this field blank or set it to "0" the web browser is only configured when it is started.
 
Note 
What is Internet Explorer Automatic Proxy Result Cache?
With most browsers, the PAC file FindProxyForURL() function is called every time a request is made. However, versions of Internet Explorer since 5.5 include a feature called Automatic Proxy Result Cache that caches the hostname of the requested URL and the proxy that is returned by the FindProxyForURL() function (as <hostname, server>). This has the advantage of minimizing calls to FindProxyForURL(), but imposes 2 important limits:
1.
2.
Because Automatic Proxy Result Cache caches the hostname/first_server pair, rather than the full results of the FindProxyForURL() function (full URL and multiple servers, if so scripted), the failover from one proxy to another does not occur in the event of a problem, even if the FindProxyForURL() function returned a list of proxy servers.
This feature is discussed in more detail in the Microsoft knowledge base article titled How to disable automatic proxy caching in Internet Explorer.
How do I specify a URL in a PAC file to bypass Content Gateway?
PAC files are easily modified to specify any number of URLs that will bypass the proxy. Such entries are often referred to as exceptions.
Most PAC files already have 1 or more exceptions. A common exception is for internal networks. For example:
if (isInNet(host, "192.168.0.0", "255.255.0.0"))
{return "DIRECT";}
An entry for an external site might look like:
if (shExpMatch(url, "*.webex.com/*"))
{return "DIRECT";}
Warning 
Some versions of Java have had problems with common proxy PAC file functions such as isInNet(). Please review the Java open issues in the release notes for the versions of Java used by your client browsers.
 

Go to the table of contents Go to the previous page You are at the end of the document View or print as PDF
Copyright 2016 Forcepoint LLC. All rights reserved.