Sun Java System Web Proxy Server 4.0.2 2005Q4 Administration Guide

Understanding Autoconfiguration Files

This feature is documented in this book because it is likely that you, as the person administering the Proxy Server, 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.

The autoconfiguration file makes it possible to 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 lets you divide the load and get more efficient use of your proxies’ disks because there is only a single copy of any file 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. You do not need to specify a URI (part of the URL following the host:port combination); however, if you do use a URI, you can then 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 have them accessed through different URLs. Accessing the Proxy as a Web Server 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, it can be very difficult to have a proxy server work as a reverse proxy and server .pac files. This is because the proxy server gets a request for a file and it needs to determine if the request is for a local .pac file or if the request is 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, you need to manually 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 – Caution –

With this mapping, however, you must be 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.

Here is an example 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>