Team LiB
Previous Section Next Section

Hack 15. Work with Web Proxies

Make Firefox automatically discover the settings it should use for accessing the Web.

The Web is full of proxy and cache servers. Firefox only has to reach the one nearest to you in order to provide connectivity. If your environment includes web servers hidden behind complex security arrangements, this hack will help you point Firefox at the right proxies.

2.6.1. Overview of Proxy Options

There are four strategies for proxy access: none, static, PAC, and WPAD. Setting up proxies is not the same thing as implementing full server control of Firefox configuration items [Hack #29] . However, it does have some features that are similar to remote configuration.

The Firefox Options dialog box is the starting point for proxy configuration. The General panel holds the Connection configuration item. Depending on your desktop arrangements, such as if your window is slightly too small, you might not see that item. To fix that and expose the Connection Settings... button, just enlarge the window by dragging its bottom right corner outward.

Figure 2-2 shows the Connection Settings subdialog.

Figure 2-2. Proxy connections dialog box

The four radio buttons in Figure 2-2 are alternative values for a single preference:

network.proxy.type  /* an integer, default = 0 */

Table 2-1 shows the relationship between the dialog options, preference values, and their associated standards.

Table 2-1. Dialog options, preference values, and associated standards

Radio option


Standards used to implement

Direct connection


Plain DNS, sockets, and ports

Auto-detect proxy settings


Web Proxy Auto-Discovery Protocol (WPAD). IETF draft standard draft-ietf-wrec-wpad-01.txt plus PAC

Manual proxy configuration


Plain DNS, sockets and ports

Automatic proxy configuration URL


HTTP plus nonstandard Proxy Auto-Configuration (PAC) file format.



For backwards compatibility, same as 0 (zero). Do not use.

The other items in Figure 2-2 also map directly to preferences. Type the URL about:config into Firefox and filter on the word proxy to find them.

2.6.2. Setting Up Direct Connects and Static Proxies

Direct connection and static proxies rely only on the underlying TCP/IP network and access to the Domain Name System (DNS). If you avoid domain names and use only TCP/IP v4 addresses, such as, then you don't even need DNS.

If you choose direct connection in the Connection Settings dialog box, you have immediate access to the Internet and the Web. All that is required is optional access to DNS and a default TCP/IP route. Everything you do is passed through the default route, which presumably has the Internet at the other end. Dial-up connections provide both DNS and routes automatically; corporate PCs usually acquire both at boot time, courtesy of the local network administrator (see him for details). Direct-connected Firefox uses the standard port numbers for all necessary protocols (i.e., 80 for HTTP, 20 for FTP and 110 for POP3; on Linux/Unix, see the /etc/services file for details). These can be overridden for specific URLs, such as

If you choose manual proxy configuration and fill in some proxy hosts, the situation is the same as a direct connection, except that Firefox will connect to the hosts specified on a per-protocol basis, rather than blindly going through the default route. For many network topologies, this is no different from a direct connection, but it does allow for load sharing if the number of desktops is large. Desktops can alternate in their use of HTTP servers, for example. Any nontrivial LAN switch can be configured to perform per-protocol and per-port redirections, so manual proxy configuration is not widely useful in a fixed setting. Simple-minded, shrink-wrapped, low-end hubs, repeaters, and switches generally aren't powerful enough for this, though. If you access work remotely via a virtual private network (VPN) or a WiFi hotspot, then manual configuration might suit the access requirements dictated by your organization. Make a second Firefox profile with manual proxies and use that for phoning home.

One further use of manual configuration is to reduce load on the web gateway of an organization with a slow link. By blacklisting local networks, requests to hosts on those local networks go direct. That means the local intranet can be served fast and transparently, leaving the web gateway server to be used only for external requests.

2.6.3. Setting Up Scripted PAC Proxies

proxy.pac files were an initiative of the Netscape Navigator 2.0 browser and have been supported by Netscape and Mozilla ever since. Such a file resides at a URL and is downloaded when Firefox starts. This preferences indicates where the file should be accessed:

network.proxy.autoconfig_url    /* set to a full URL */

Once it is downloaded, the script in the file tells Firefox which proxies to use for which URLs. It is therefore a more powerful mechanism than manual configuration, which knows nothing about specific URLs requested. Since the file resides on the server, it can be configuration-controlled by the server administrator. That's useful if services provided by the server change at short notice. Firefox regularly checks to see if a required proxy.pac file has changed. If so, it is downloaded again and rerun.

There is no standard for the file's format, except that it should contain JavaScript. (Internet Explorer supports a similar but not identical format that has the same purpose.) The file should be delivered over the Web with this MIME type:


Don't use this other content type, which is old and not supported:


What do you put in the proxy.pac file? Implement this JavaScript function:

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

Firefox calls this function each time it attempts to retrieve a URL. The URL argument is the full URL supplied; the host argument is the domain name or TCP/IP address subpart of the URL. The function returns a list of proxy options to the browser as a single, semicolon-separated string. Firefox then goes through the list, trying each option in turn. Here's a simple example of this function:

function FindProxyForURL (url, host) {
  if ( url.match("https:")  ) {
    return "SOCKS secure:99";
  else if ( host.match("google") ) {
    return "PROXY gateway:80";
  else {
    return "DIRECT; PROXY gateway:8080";

In this example, the regular expression methods that are part and parcel of the JavaScript String object are used to analyze the URL. If it's a Secure HTTP URL, a host named secure and port 99 are used. If it happens to be a Google web page, then the proxy host named gateway is used. If it's anything else, Firefox first tries DIRECT (i.e., no proxy), and if that fails, it tries the gateway host, but on a different port. The preceding example illustrates all syntax options for the return string. Note that return values are semi-colon separated when more than one option is returned.

Because the proxy.pac file is a JavaScript script, you can make the content as complicated as you like. The script runs inside a special, secure sandbox, however, so there is a limited range of features to exploit.

Of the features available, a few are available only within the proxy.pac scripting environment. Three special functions are provided; there are also some trivial utility functions that do string processing. Here are the three main function signatures:

String tcpip_v4 address myIpAddress(  )
String tcpip_v4_address dnsResolve(String domain)
void                    proxyAlert(String message)

The proxy system is written as an XPCOM component defined in JavaScript. This means you can look at it; see the nsProxyAutoConfig.js file in the Firefox install area, in the components directory. This file makes advanced use of JavaScript, and it's easy to be confused when reading it: refresh yourself on JavaScript first. To spot the utility functions available in the proxy.pac runtime environment, find the variable in that file named pacUtils. It is transformed a bit like this just before the proxy.pac file is read:


The set of utility functions defined in the big pacUtils string are then available to proxy scripts. No other facilities are, however. Use the proxyAlert() function for debugging.

2.6.4. Setting Up WPAD Proxies

WPAD is an extension to the proxy.pac system. Instead of the proxy script being retrieved from a user-specified URL, it's retrieved from a known URL that requires no user data. All the work is done by the server administrator. The user merely chooses "automatic proxy configuration" (WPAD) when Firefox is first installed, or picks that option at a later time. Firefox expects the proxy script to be located at this URL:


Since this string is fixed, the setup game consists of making sure that this URL points to a real host. You must set up a web server, copy the proxy script to the top of the web site, and then make the right domain name point to the whole thing. The last bit is the only hard part. Here's how to do it for Linux/Unix.

First, you can hack the required configuration files by hand. You need root access.

Beware that some tools, such as RedHat's bindconf, manage important files for you and might overwrite your changes. If you use bindconf, go via the GUI; don't follow these instructions.

If you don't have DNS configured, then your /etc/resolv.conf probably doesn't exist, and you must be relying on the /etc/hosts file or a Network Information Services (NIS) equivalent. In that case, all you need to do is add a line for the new web server:         wpad

Add wpad as a new alternate name if the web server already has a name.

If you do have DNS configured, then it's trickier. In your DNS host's /etc/named.conf file, you should already have a record for the current domain. It should look something like this (if your domain is called

zone "" {
  type master;
  file "";

The file called probably resides at:


You need to edit this file. Add a line at the end like this:

wpad IN A

Save the file and restart named. You've just added the fully qualified domain name (FQDN) You should be able to ping it and download the WPAD URL normally afterwards.

Firefox has Class 0 (minimally compliant) WPAD support. That means DNS support only, with no DHCP support. There is one exceptional feature. A security hobble prevents failed requests from being passed to higher level (more generic) domains if the first attempt at fetching the proxy script fails. You don't want to accidentally download instead of

Ignore this preference if you see it, since it is left over from older Mozilla versions:

network.enablePad /* default = false, Pad = Proxy auto-detect */

    Team LiB
    Previous Section Next Section