Chapter 17 Using the Client Autoconfiguration File

If you have multiple proxy servers that support many clients, you can use a client autoconfiguration file to configure all of your browser clients. The autoconfiguration file contains a JavaScript function that determines which proxy, if any, the browser uses when accessing various URLs.

When the browser starts, it loads the autoconfiguration file. Each time the user clicks a link or types in a URL, the browser uses the configuration file to determine if it should use a proxy and, if so, which proxy it should use. This feature lets you provide an easy way to configure all instances of the browser in your organization. There are several ways you can get the autoconfiguration file to your clients.

• You can use the proxy server as a web server that returns the autoconfiguration file. You point the browser to the proxy’s URL. Having the proxy act as a web server enables you to keep the autoconfiguration file in one place so that when you need to make updates, you need to change only one file.

• You can store the file on a web server, an FTP server, or any network directory to which the browser has access. You configure the browser to find the file by providing the URL to the file, so any general URL is acceptable. If you need to do complex calculations, for example, if you have large proxy chains in your organization, you might write a web server CGI program that outputs a different file depending on who accesses the file.

• You can store the autoconfiguration file locally with each copy of the browser. However, if you need to update the file, you have to distribute copies of the file to each client.

You can create the autoconfiguration file in either of two ways: you can use a page in the Server Manager or you can create the file manually. Directions for creating the files appear later in this chapter.

This chapter contains the following sections:

• Understanding Autoconfiguration Files

• Using Server Manager Pages to Create Autoconfiguration Files

• Creating Autoconfiguration Files Manually

Understanding Autoconfiguration Files

As the person administering the Proxy Server, you will also create and distribute the client autoconfiguration files.

What the Autoconfiguration File Does

The autoconfiguration file is written in JavaScript, a compact, object-based scripting language for developing client and server Internet applications. The browser interprets the JavaScript file.

When the browser is first loaded, it downloads the autoconfiguration file. The file can be kept anywhere that the browser can get to it by using a URL. For example, the file can be kept on a web server. The file could even be kept on a network file system, provided the browser can get to it using a file:// URL.

The proxy configuration file is written in JavaScript. The JavaScript file defines a single function (called FindProxyForURL) that determines which proxy server, if any, the browser should use for each URL. The browser sends the JavaScript function two parameters: the host name of the system from which the browser is running and the URL it is trying to obtain. The JavaScript function returns a value to the browser that tells it how to proceed.

By using an autoconfiguration file, you can specify different proxies (or no proxy at all) for various types of URLs, various servers, or even various times of the day. In other words, you can have multiple specialized proxies so that, for example, one serves the .com domain, another the .edu domain, and yet another serves everything else. This method enables you to divide the load and use your proxies’ disks more effieciently because only a single copy of any file is stored in the cache instead of multiple proxies all storing the same documents.

Autoconfiguration files also support proxy failover, so if a proxy server is unavailable, the browser will transparently switch to another proxy server.

Accessing the Proxy as a Web Server

You can store one or more autoconfiguration files on the proxy server and have the proxy server act as a web server whose only documents are autoconfiguration files. This lets you, the proxy administrator, maintain the proxy autoconfiguration files needed by the clients in your organization. It also lets you keep the files in a central location, so if you have to update the files, you do it once and all browser clients automatically get the updates.

You keep the proxy autoconfiguration files in the server- root/proxy-serverid/pac/ directory. In the browser, you enter the URL to the proxy autoconfiguration file typing the URL to the file in the Proxies tab. The URL for the proxy has this format:

http://proxy.domain:port/URI

For example, the URL could be http://proxy.example.com. If you do use a URI, which is the part of the URL following the host:port combination, you can use a template to control access to the various autoconfiguration files. For example, if you create a URI called /test that contains an autoconfiguration file called /proxy.pac, you can create a template with the resource pattern http://proxy.mysite.com:8080/test/.*. You can then use that template to set up access control specifically to that directory.

You can create multiple autoconfiguration files and access them through different URLs. The following table lists some example URIs and the URLs the clients would use to access them.

Table 17–1 Sample URIs and corresponding URLs

URI (path)	URL to the proxy
/	http://proxy.mysite.com
/employees	http://proxy.mysite.com/employees
/group1	http://proxy.mysite.com/group1
/managers	http://proxy.mysite.com/managers

Using PAC Files With a Reverse Proxy

Because of the way a reverse proxy works, using a proxy server and a server for .pac files is difficult. When the the proxy server gets a request for a file, it would have to determine whether the request is for a local .pac file or for a remote document.

In order to have the proxy server act as a reverse proxy in addition to maintaining and serving a .pac file, edit the obj.conf file to make sure the order of the NameTrans functions is correct.

Create a regular mapping to have the proxy server act as a reverse proxy. This typically tells the proxy to route all requests to the remote content server. You can add a proxy autoconfiguration file and map it to a specific directory, such as /pac. In this case, any client who wants to get the .pac file would use a URL such as:

http://proxy.mysite.com/pac

---

Caution –

With this mapping, make sure that the remote content server does not have a similar directory.

---

Edit the obj.conf file to make sure that the directive and function for the proxy autoconfiguration file appear before any other mappings. This directive and function must be first because the proxy server normally runs through all NameTrans functions before servicing the request. However, with autoconfiguration files, the proxy immediately recognizes the path and returns the .pac file.

The following example is from an obj.conf file that uses a reverse proxy and maintains an autoconfiguration file.

<Object name="default">
NameTrans from="file:" fn="map" to="ftp:"
NameTrans from="/pac" fn="pac-map" name="file" 
	to="/ns-home/proxy/pac/proxy.pac"
NameTrans fn="redirect" from="http://foo.*" url="http://www.acme.com"
NameTrans from="/ns-icons" fn="pfx2dir" dir="/ns-home/ns-icons" name="file"
NameTrans fn="reverse-map" from="http://web.acme.com" 
	to="http://proxy.acme.com:8080"
NameTrans fn="map" from="http://proxy.acme.com:8080" 
	to="http://web.acme.com"
NameTrans fn="map" from="/" to="http://web.acme.com"
PathCheck fn="url-check"
Service fn="deny-service"
AddLog fn="flex-log" name="access"
AddLog fn="urldb-record"
</Object>

Using Server Manager Pages to Create Autoconfiguration Files

To Create an Autoconfiguration File using The Server Manager

1. Access the Server Manager, and select the Routing tab.

2. Click the Create/Edit Autoconfiguration File link.

   The page that appears lists any autoconfiguration files you have on your proxy’s system. You can click the autoconfiguration file to edit it. The remaining steps tell you how to create a new file.

3. Type an optional URI which is the path portion of a URL, that clients will use when getting the autoconfiguration file from the proxy.

   For example, type / to let clients access the file as the proxy’s main document (similar to an index.html file for a web server); clients would then use only the domain name when accessing the proxy for the autoconfiguration file. You can use multiple URIs and create separate autoconfiguration files for each URI.

4. Type a name for the autoconfiguration file using the .pac extension.

   If you have one file, you might call it simply proxy.pac (pac is short for proxy autoconfiguration). All autoconfiguration files are ASCII text files with a single JavaScript function.

5. Click OK. Another page appears.

   Use this page to create an autoconfiguration file. The items on the page are followed in order by the client. These are the items on the page:

   • Never Go Direct To Remote Server tells the browser to always use your proxy. You can specify a second proxy server to use in case your proxy server is not running.

   • Go Direct To Remote Server When determines when to bypass the proxy server. The browser determines those occasions in the order the options are listed on the page:

   • Connecting To Non-fully Qualified Host Names sends the browser directly to a server when the user specifies only the computer name. For example, if an internal web server is called winternal.mysite.com, the user might type only http://winternal instead of the fully qualified domain name. In this case, the browser goes directly to the web server instead of to the proxy.

   • Connecting To A Host In Domainenables you to specify up to three domain names that the browser can access directly. When specifying the domains, begin with the dot character. For example, you could type .example.com.

   • Connecting To A Resolvable Host sends the browser directly to the server when the client can resolve the host. This option is typically used when DNS is set to resolve only local (internal) hosts. The clients would use a proxy server when connecting to servers outside of the local network.

     ---

     Caution –

     This option negatively affects the performance witnessed by the client because the client must consult DNS for every request.

     ---

   • Connecting To A Host In Subnet sends the browser directly to the server when the client accesses a server in a particular subnet. This option is useful when an organization has many subnets in a geographical area. For example, some companies might have one domain name that applies to subnets around the world, but each subnet is specific to a particular region.

     ---

     Caution –

     This option negatively affects the performance witnessed by the client because the client must consult DNS for every request.

     ---

   • Except When Connecting To Hostsenables you to specify exceptions to the rule of going directly to a server. For example, if you type.example.com as a domain to which to go directly, you could make an exception for going to home.example.com. The browser would then use your proxy when going to home.example.com but go directly to any other server in the example.com domain.

   • Secondary Failover Proxy specifies a second proxy to use if your proxy server is not running.

   • Failover Direct sends the browser directly to the servers if your proxy server isn’t running. If you specify a secondary failover proxy, Navigator tries the second proxy server before going directly to the server.

6. Click OK to create the autoconfiguration file.

   The file is stored in the directory server-root/proxy-serverid/pac.

   A confirmation message appears saying that the file was created correctly. Repeat the preceding steps to create as many autoconfiguration files as you need.

   Once you create your autoconfiguration file, make sure you either tell all the people using your proxy server to point to the correct autoconfiguration file or configure the copies of the browser yourself.

Creating Autoconfiguration Files Manually

This section describes how to manually create autoconfiguration files.

The proxy autoconfiguration file is written using client-side JavaScript. Each file contains a single JavaScript function called FindProxyForURL() that determines which proxy server, if any, the browser should use for each URL. The browser sends the JavaScript function two parameters: the host name of the destination origin server and the URL it is trying to obtain. The JavaScript function returns a value to Navigator that tells it how to proceed. The following section describes the function syntax and the possible return values.

FindProxyForURL() Function

The syntax of the FindProxyFor() URL function is:

function FindProxyForURL(url, host){   ...}

For every URL the browser accesses, it sends the url and host parameters and calls the function in the following way:

ret = FindProxyForURL(url, host);

url is the full URL being accessed in the browser.

host is the host name extracted from the URL that is being accessed. This is only for convenience; it is the same string as between :// and the first : or / after that. The port number is not included in this parameter. It can be extracted from the URL when necessary.

ret (the return value) is a string describing the configuration.

Function Return Values

The autoconfiguration file contains the function FindProxyForURL(). This function uses the client host name and the URL it is accessing as parameters, . The function returns a single string that tells the browser how to proceed. If the string is null, no proxies should be used. The string can contain any number of the building blocks shown in the following table, separated by semicolons.

Table 17–2 FindProxyForURL() Return Values

Return Values	Resulting Action of the Browser
DIRECT	Make connections directly to the server without going through any proxies.
PROXY host:port	Use the specified proxy and port number. If multiple values are separated by semicolons, the first proxy is used. If that proxy fails, then the next proxy is used, and so on.
SOCKS host:port	Use the specified SOCKS server. If multiple values are separated by semicolons, the first proxy is used. If that proxy fails, then the next proxy is used, and so on.

If the browser encounters an unavailable proxy server, the browser will automatically retry the previously unresponsive proxy after 30 minutes, then after one hour, and so on, at 30-minute intervals. So, if you temporarily shut down a proxy server, your clients will resume using the proxy no later than 30 minutes after it was restarted.

If all of the proxies are down and the DIRECT return value is not specified, the browser will ask the user whether the browser should temporarily ignore proxies and attempt direct connections instead. The browser will ask if proxies should be retried after 20 minutes, then again in another 20 minutes, and so on at 20-minute intervals.

In the following example, the return value tells the browser to use the proxy called w3proxy.example.com on port 8080. If that proxy is unavailable, the browser uses the proxy called proxy1.example.com on port 8080:

PROXY w3proxy.example.com:8080; PROXY proxy1.example.com:8080

In the next example, the primary proxy is w3proxy.example.com:8080. If that proxy is unavailable, the browser uses proxy1.example.com:8080. If both proxies are unavailable, then the browser goes directly to the server. After 20 minutes, the browser asks the user whether it should retry the first proxy.

PROXY w3proxy.example.com:8080; PROXY proxy1.example.com:8080; DIRECT

JavaScript Functions and Environment

The JavaScript language has several predefined functions and environmental conditions that are useful with proxying. Each of these functions checks whether a certain condition is met and then returns a value of true or false. The related utility functions are an exception because they return a DNS host name or IP address. You can use these functions in the main FindProxyForURL() function to determine what return value to send to the browser. The examples later in this chapter provide ideas on using these functions.

Each of the functions or environmental conditions is described in this section. The functions and environmental conditions that apply to the browser integration with the proxy are:

• The host name functions are:

  • dnsDomainIs()()

  • isInNet()()

  • isPlainhost name()()

  • isResolvable()()

  • localHostOrDomainIs()()

• Utility functions:

  • dnsDomainLevels()

  • dnsResolve()

  • myIpAddress()

• URL/host name-based condition:

  • shExpMatch()

• Time-based conditions:

  • dateRange()

  • timeRange()

  • weekdayRange()

Hostname-Based Functions

The hostname-based functions let you use the host name or IP address to determine which proxy, if any, to use.

dnsDomainIs()(host, domain)

The dnsDomainIs()() function detects whether the URL host name belongs to a given DNS domain. This function is useful when you are configuring the browser not to use proxies for the local domain, as illustrated in Example 1: Proxy All Servers Except Local Hosts and Example 2: Proxy Local Servers Outside the Firewall.

This function is also useful when you are using multiple proxies for load balancing in situations where the proxy that receives the request is selected from a group of proxies based on which DNS domain the URL belongs to. For example, if you are load balancing by directing URLs containing .edu to one proxy and those containing .com to another proxy, you can check the URL host name using dnsDomainIs()().

Parameters

host is the host name from the URL.

domain is the domain name to test the host name against.

Return Values

true or false

Examples

The following statement would be true:

dnsDomainIs("www.example.com", ".example.com")

The following statements would be false:

dnsDomainIs("www", ".example.com") dnsDomainIs("www.mcom.com", 
	".example.com")

isInNet()(host, pattern, mask)

The isInNet()() function enables you to resolve a URL host name to an IP address and test whether it belongs to the subnet specified by the mask. This is the same type of IP address pattern matching that SOCKS uses. See Example 4: Connect Directly to a Subnet.

Parameters:

host is a DNS host name or IP address. If a host name is passed, this function will resolve it into an IP address.

pattern is an IP address pattern in the dot-separated format

mask is the IP address pattern mask that determines which parts of the IP address should be matched against. A value of 0 means ignore; 255 means match. This function is true if the IP address of the host matches the specified IP address pattern.

Return Values

true or false

Examples

This statement is true only if the IP address of the host matches exactly 198.95.249.79 exactly:

isInNet(host, "198.95.249.79", "255.255.255.255")

This statement is true only if the IP address of the host matches 198.95.*.*: isInNet(host, "198.95.0.0", "255.255.0.0")

isPlainhost name()(host)

The isPlainhost name()() function detects whether the host name in the requested URL is a plain host name or a fully qualified domain name. This function is useful if you want the browser to connect directly to local servers, as illustrated in Example 1: Proxy All Servers Except Local Hosts and Example 2: Proxy Local Servers Outside the Firewall.

Parameters

host is the host name from the URL, excluding the port number only if the host name has no domain name (no dotted segments).

Return Values

true if host is local; false if host is remote

Example

isPlainhost name("host")

If host is a string like www, then the function returns true. If host is a string like www.example.com, the function returns false.

isResolvable()(host)

If the DNS inside the firewall recognizes only internal hosts, you can use the isResolvable()() function to test whether a host name is internal or external to the network. Using this function, you can configure the browser to use direct connections to internal servers and to use the proxy only for external servers. This function is useful at sites where the internal hosts inside the firewall are able to resolve the DNS domain name of other internal hosts, but all external hosts are unresolvable. The isResolvable()() function consults DNS, attempting to resolve the host name into an IP address. See Example 3: Proxy Only Unresolved Hosts

Parameters

host() is the host name from the URL.

Return Values

true if the function can resolve the host name, false if it cannot

Example

isResolvable("host")

If host() is a string like www and can be resolved through DNS, then this function returns true.

localHostOrDomainIs()(host, hostdom)

ThelocalHostOrDomainIs()() function specifies local hosts that might be accessed by either the fully qualified domain name or the plain host name. See Example 2: Proxy Local Servers Outside the Firewall.

The localHostOrDomainIs()() function returns true if the host name matches the specified host name exactly or if there is no domain name part in the host name that the unqualified host name matches.

Parameters

host is the host name from the URL.

hostdom is the fully qualified host name to match.

Return Values

true or false

Examples

The following statement is true (exact match):

localHostOrDomainIs("www.example.com", "www.example.com")

The following statement is true (host name match, domain name not specified):

localHostOrDomainIs("www", "www.example.com")

The following statement is false (domain name mismatch):

localHostOrDomainIs("www.mcom.com", "www.example.com")

The following statement is false (host name mismatch):

localHostOrDomainIs("home.example.com", "www.example.com")

Utility Functions

The utility functions enable you to find out domain levels, the host on which the browser is running, or the IP address of a host.

dnsDomainLevels()(host)

The dnsDomainLevels()() function finds the number of DNS levels (number of dots) in the URL host name.

Parameters

host is the host name from the URL.

Return Value

number (integer) of DNS domain levels.

Examples

dnsDomainLevels("www") returns 0.

dnsDomainLevels("www.example.com") returns 2.

dnsResolve()(host)

The dnsResolve()() function resolves the IP address of the given host, typically from the URL. This function is useful if the JavaScript function has to do more advanced pattern matching than can be done with the existing functions.

Parameters

host is the host name to resolve. Resolves the given DNS host name into an IP address, and returns it in the dot-separated format as a string.

Return Value

dotted quad IP address as a string value

Example

The following example would return the string 198.95.249.79.

dnsResolve("home.example.com")

myIpAddress()()

The myIpAddress()() function is useful when the JavaScript function has to behave differently depending on the host on which the browser is running. This function returns the IP address of the computer that is running the browser.

Return Value

dotted quad IP address as a string value

Example:

The following example returns the string 198.95.249.79 if you are running Navigator on the computer home.example.com.

myIpAddress()

URL/Host-Name-Based Condition

You can match host names or URLs for load balancing and routing.

shExpMatch()(str, shexp)

The shExpMatch()() function matches either URL host names or URLs themselves. The main use of this function is for load balancing and intelligent routing of URLs to different proxy servers.

Parameters

str is any string to compare (for example, the URL or the host name).

shexp is a shell expression against which to compare.

This expression is true if the string matches the specified shell expression. See Example 6: Balance Proxy Load With shExpMatch()().

Returns Values

true or false

Examples

The first example returns true. The second example returns false.

shExpMatch("http://home.example.com/people/index.html",
            ".*/people/.*")
shExpMatch("http://home.example.com/people/yourpage/index.html",
            ".*/mypage/.*")

Time-Based Conditions

You can make the FindProxyForURL function behave differently depending on the date, time, or day of the week.

dateRange() (day, month, year...)

The dateRange()() function detects a particular date or a range of dates, such as April 19th, 1996 through May 3rd, 1996. This function is useful if you want the FindProxyForURL() function to act differently depending on the day week, for example, if maintenance down time is regularly scheduled for one of the proxies.

The date range can be specified several ways:

dateRange(day)dateRange(day1, day2)dateRange(mon)dateRange(month1, month2)dateRange(year)dateRange(year1, year2)dateRange(day1, month1, day2, month2)dateRange(month1, year1, month2, year2)dateRange(day1, month1, year1, day2, month2, year2)dateRange(day1, month1, year1, day2, month2, year2, gmt)

Parameters

day is an integer between 1 and 31 for the day of month.

month is one of the month strings: JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC

year is a four-digit integer for the year number (for example, 1996).

gmt is either the string “GMT”, which indicates that time comparisons should occur in Greenwich Mean Time, or is left blank so that times are assumed to be in the local time zone. The GMT parameter can be specified in any of the call profiles, always as the last parameter. If only a single value is specified from each category (day, month, year), the function returns a true value only on days that match that specification. If two values are specified, the result is true from the first time specified through the second time specified.

Examples

This statement is true on the first day of each month, local time zone: dateRange(1)

This statement is true on the first day of each month, Greenwich Mean Time: dateRange(1, "GMT")

This statement is true for the first half of each month: dateRange(1, 15)

This statement is true on the 24th of December each year: dateRange(24, "DEC")

This statement is true on the 24th of December, 1995: dateRange(24, "DEC", 1995)

This statement is true during the first quarter of the year: dateRange("JAN", "MAR")

This statement is true from June 1st through August 15th, each year: dateRange(1, "JUN", 15, "AUG")

This statement is true from June 1st, 1995, until August 15th, 1995: dateRange(1, "JUN", 15, 1995, "AUG", 1995)

This statement is true from October 1995 through March 1996: dateRange("OCT", 1995, "MAR", 1996)

This statement is true during the entire year of 1995: dateRange(1995)

This statement is true from the beginning of 1995 until the end of 1997: dateRange(1995, 1997)

timeRange (hour, minute, second...)

The timeRange() function detects a particular time of day or a range of time, such as 9 p.m. through 12 a.m. This function is useful if you want the FindProxyForURL() function to act differently depending on what time it is.

timeRange(hour)timeRange(hour1, hour2)timeRange(hour1, min1, hour2, min2)timeRange(hour1, min1, sec1, hour2, min2, sec2)

Parameters:

hour is the hour from 0 to 23. 0 is midnight, 23 is 11:00 p.m.

min is the number of minutes from 0 to 59.

sec is the number of seconds from 0 to 59.

gmt is either the string GMT for GMT time zone, or not specified for the local time zone. This parameter can be used with each of the parameter profiles and is always the last parameter.

Returns Values

true or false

Examples:

This statement is true from noon to 1:00 p.m: timerange(12, 13)

This statement is true noon to 12:59 p.m. GMT: timerange(12, "GMT")

This statement is true from 9:00 a.m. to 5:00 p.m: timerange(9, 17)

This statement is true between midnight and 30 seconds past midnight: timerange(0, 0, 0, 0, 0, 30)

weekdayRange()(wd1, wd2, gmt)

The weekdayRange() function detects a particular weekday or a range of weekdays, such as Monday through Friday. This is useful if you want the FindProxyForURL function to act differently depending on the day of the week.

Parameters

wd1and wd2are any one of these weekday strings: SUN MON TUE WED THU FRI SAT

gmt is either GMT for Greenwich Mean Time, or is left out for local time.

Only the first parameter, wd1, is mandatory. Either wd2, gmt, or both can be left out.

If only one parameter is present, the function returns a true value on the weekday that the parameter represents. If the string GMT is specified as a second parameter, times are given in GMT. Otherwise, the times are given in your local time zone.

If both wd1 and wd2 are defined, the condition is true if the current weekday is between those two weekdays. Bounds are inclusive. The order of parameters is important; “MON,” “WED” is Monday through Wednesday, but “WED,” “MON” is from Wednesday to the Monday of the next week.

Examples

This statement is true Monday through Friday (local time zone). weekdayRange("MON", "FRI")

This statement is true Monday through Friday, in Greenwich Mean Time. weekdayRange("MON", "FRI", "GMT")

This statement is true on Saturdays, local time.weekdayRange("SAT")

This statement is true on Saturdays, in Greenwich Mean Time.weekdayRange("SAT", "GMT")

This statement is true Friday through Monday (the order is important)weekdayRange("FRI", "MON")

Function Examples

This section provides detailed examples of the JavaScript functions.

Example 1: Proxy All Servers Except Local Hosts

In this example, the browser connects directly to all hosts that are not fully qualified and the ones that are in the local domain. All other hosts go through the proxy called w3proxy.example.com:8080.

---

Note –

If the proxy goes down, connections become direct automatically.

---

    function FindProxyForURL(url, host)
    {
        if (isPlainhost name(host) ||
            dnsDomainIs(host, ".example.com") ||
            dnsDomainIs(host, ".mcom.com"))
            return "DIRECT";
        else
            return "PROXY w3proxy.example.com:8080; DIRECT";
    }

Example 2: Proxy Local Servers Outside the Firewall

This example resembles Example 1: Proxy All Servers Except Local Hosts, but it uses the proxy for local servers that are outside the firewall. If hosts such as the main web server belong to the local domain but are outside the firewall and are only reachable through the proxy server, those exceptions are handled using the localHostOrDomainIs()() function:

    function FindProxyForURL(url, host)
    {
        if ((isPlainhost name(host) ||
        dnsDomainIs(host, ".example.com")) &&
        !localHostOrDomainIs(host, "www.example.com") &&
        !localHostOrDoaminIs(host, "merchant.example.com"))
            return "DIRECT";
        else
            return "PROXY w3proxy.example.com:8080; DIRECT";
    }

This example uses the proxy for all hosts except local hosts in the example.com domain. The hosts www.example.com and merchant.example.com also go through the proxy.

The order of the exceptions increases efficiency: localHostOrDomainIs()() functions get executed only for URLs that are in the local domain, not for every URL. In particular, notice the parentheses around the or expression before the and expression.

Example 3: Proxy Only Unresolved Hosts

This example works in an environment where internal DNS resolves only internal host names. The goal is to use a proxy only for hosts that aren’t resolvable.

    function FindProxyForURL(url, host)
    {
        if (isResolvable(host))
                return "DIRECT";
            else
                return "PROXY proxy.mydomain.com:8080";
    }

This example requires consulting the DNS every time. Therefore, you would group this example with other rules so that DNS is consulted only if other rules do not yield a result.

    function FindProxyForURL(url, host)
    {
        if (isPlainhost name(host) ||
            dnsDomainIs(host, ".mydomain.com") ||
            isResolvable(host))
            return "DIRECT";
        else
            return "PROXY proxy.mydomain.com:8080";
    }

Example 4: Connect Directly to a Subnet

In this example, all the hosts in a given subnet are connected to directly. Other hosts go through the proxy.

    function FindProxyForURL(url, host)
    {
        if (isInNet(host, "198.95.0.0", "255.255.0.0"))
            return "DIRECT";
        else
            return "PROXY proxy.mydomain.com:8080";
    }

You can minimize the use of DNS in this example by adding redundant rules in the beginning:

    function FindProxyForURL(url, host)
    {
        if (isPlainhost name(host) ||
            dnsDomainIs(host, ".mydomain.com") ||
            isInNet(host, "198.95.0.0", "255.255.0.0"))
            return "DIRECT";
        else
            return "PROXY proxy.mydomain.com:8080";
    }

Example 5: Balance Proxy Load With dnsDomainIs()()

This example is more sophisticated. The example uses four proxy servers, with one of them acting as a hot standby for the others. If any of the remaining three proxy servers goes down, the fourth one takes over. The three remaining proxy servers share the load based on URL patterns, which makes their caching more effective. Only one copy of any document exists on the three servers, as opposed to one copy on each of them. The load is distributed as shown in the following table.

Table 17–3 Balance Proxy Load

Proxy	Purpose
#1	.com domain
#2	.edu domain
#3	all other domains
#4	hot standby

All local accesses should be direct. All proxy servers run on port 8080. You can concatenate strings by using the + operator.

function FindProxyForURL(url, host)
{
    if (isPlainhost name(host) || dnsDomainIs(host, ".mydomain.com"))
        return "DIRECT";

    else if (dnsDomainIs(host, ".com"))
        return "PROXY proxy1.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";

    else if (dnsDomainIs(host, ".edu"))
        return "PROXY proxy2.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";

    else
        return "PROXY proxy3.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";
}

Example 6: Balance Proxy Load With shExpMatch()()

This example is essentially the same as Example 5: Balance Proxy Load With dnsDomainIs()(), but instead of using dnsDomainIs()(), this example uses shExpMatch()().

    function FindProxyForURL(url, host)
    {
    if (isPlainhost name(host) || dnsDomainIs(host, ".mydomain.com"))
        return "DIRECT";
    else if (shExpMatch(host, "*.com"))
        return "PROXY proxy1.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";
    else if (shExpMatch(host, "*.edu"))
        return "PROXY proxy2.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";
    else
        return "PROXY proxy3.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";
    }

Example 7: Proxying a Specific Protocol

You can set a proxy for a specific protocol. Most of the standard JavaScript functionality is available for use in the FindProxyForURL()() function. For example, to set different proxies based on the protocol, you can use the substring()() function.

    function FindProxyForURL(url, host)
    {
        if (url.substring(0, 5) == "http:") {
            return "PROXY http-proxy.mydomain.com:8080";
        }
        else if (url.substring(0, 4) == "ftp:") {
            return "PROXY ftp-proxy.mydomain.com:8080";
        }
        else if (url.substring(0, 7) == "gopher:") {
            return "PROXY gopher-proxy.mydomain.com:8080";
        }
        else if         (url.substring(0, 6) == "https:" ||
                url.substring(0, 6) == "snews:") {
            return "PROXY security-proxy.mydomain.com:8080";
        }
        else {
            return "DIRECT";
        }
    }

You can also accomplish this configuration by using the shExpMatch()() function; for example:

    ...
    if (shExpMatch(url, "http:*")) {
        return "PROXY http-proxy.mydomain.com:8080;
    }
    ...