Proxy Settings

Contents

1. Manifest
   1. h3Name
2. Objects and properties
   1. Proxy modes
   2. Proxy rules
   3. Proxy server objects
   4. Bypass list
3. Precedence
   1. h3Name
4. Examples
   1. h3Name
5. API reference: chrome.experimental.proxy
   1. Properties
      1. settings
   2. Methods
      1. methodName
   3. Events
      1. onProxyError
   4. Types
      1. ProxyServer
      2. ProxyRules
      3. PacScript
      4. ProxyConfig

Use the chrome.experimental.proxysettings module to manage Chrome's proxy settings. This module is still experimental. For information on how to use experimental APIs, see the chrome.experimental.* APIs page.

Manifest

You must declare the "proxy" permission in the extension manifest to use the proxy settings API. For example:

{
  "name": "My extension",
  ...
  "permissions": [
    "experimental", "proxy"
  ],
  ...
}

Objects and properties

Proxy settings are defined in a ProxyConfig object. Depending on Chrome's proxy settings, the settings may contain ProxyRules or a PacScript.

Proxy modes

A ProxyConfig object's mode attribute determines the overall behavior of Chrome with regards to proxy usage. It can take the following values:

direct

In direct mode all connections are created directly, without any proxy involved. This mode allows no further parameters in the ProxyConfig object.

auto_detect

In auto_detect mode the proxy configuration is determined by a PAC script that can be downloaded at http://wpad/wpad.dat. This mode allows no further parameters in the ProxyConfig object.

pac_script

In pac_script mode the proxy configuration is determined by a PAC script that is either retrieved from the URL specified in the PacScript object or taken literally from the data element specified in the PacScript object. Besides this, this mode allows no further parameters in the ProxyConfig object.

fixed_servers

In fixed_servers mode the proxy configuration is codified in a ProxyRules object. Its structure is described in Proxy rules. Besides this, the fixed_servers mode allows no further parameters in the ProxyConfig object.

system

In system mode the proxy configuration is taken from the operating system. This mode allows no further parameters in the ProxyConfig object. Note that the system mode is different from setting no proxy configuration. In the latter case, Chrome falls back to the system settings only if no command-line options influence the proxy configuration.

Proxy rules

The ProxyRules object can contain either a singleProxy attribute or a subset of proxyForHttp, proxyForHttps, proxyForFtp, and fallbackProxy.

In the first case, HTTP, HTTPS and FTP traffic is proxied through the specified proxy server. Other traffic is sent directly. In the latter case the behavior is slightly more subtle: If a proxy server is configured for the HTTP, HTTPS or FTP protocol, the respective traffic is proxied through the specified server. If no such proxy server is specified or traffic uses a different protocol than HTTP, HTTPS or FTP, the fallbackProxy is used. If no fallbackProxy is specified, traffic is sent directly without a proxy server.

Proxy server objects

A proxy server is configured in a ProxyServer object. The connection to the proxy server (defined by the host attribute) uses the protocol defined in the scheme attribute. If no scheme is specified, the proxy connection defaults to http.

If no port is defined in a ProxyServer object, the port is derived from the scheme. The default ports are:

Bypass list

Individual servers may be excluded from being proxied with the bypassList. This list may contain the following entries:

[<scheme>://]<host-pattern>[:<port>]

Match all hostnames that match the pattern <host-pattern>.
Examples: "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.*.y.com:99"

[<scheme>://]<ip-literal>[:<port>]

Match URLs that are IP address literals.
Conceptually this is the similar to the first case, but with special cases to handle IP literal canonicalization. For example, matching on "[0:0:0::1]" is the same as matching on "[::1]" because the IPv6 canonicalization is done internally.
Examples: "127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"

<ip-literal>/<prefix-length-in-bits>

Match any URL containing an IP literal within the given range. The IP range is specified using CIDR notation.
Examples: "192.168.1.1/16", "fefe:13::abc/33"

<local>

Match local addresses. An address is local if the host is "127.0.0.1", "::1", or "localhost".
Example: "<local>"

Precedence

Chrome manages settings on different layers. The following list describes the layers that may influence the effective proxy settings, in increasing order of precedence.

1. System settings provided by the operating system
2. Command line parameters
3. Preferences set by extensions
4. Policies

As the list implies, policies might overrule any changes that you specify with the proxy settings API.

Chrome allows using different proxy settings for regular windows and incognito windows. The following example illustrates the behavior. Assume that no policy overrides the proxy settings and that an extension can set proxy settings for regular windows (R) and proxy settings for incognito windows (I).

• If only (R) is set, these settings are effective for both regular and incognito windows.
• If only (I) is set, these settings are effective for only incognito windows. Regular windows use the proxy settings determined by the lower layers (command-line options and system settings).
• If both (R) and (I) are set, the respective settings are used for regular and incognito windows.

If two extensions want to set proxy settings, the extension installed last takes precedence over the other extensions. If the extension installed last sets only (I), the settings of regular windows can be defined by more recently installed extensions.

Examples

The following code sets a SOCKS 5 proxy for HTTP connections to all servers but foobar.com and uses direct connections for all other protocols. The settings apply to regular and incognito windows.

var config = {
  mode: "fixed_servers",
  rules: {
    httpProxy: {
      scheme: "socks5",
      host: "1.2.3.4"
    },
    bypassList: ["foobar.com"]
  }
};
chrome.experimental.proxy.settings.set(
    {'value': config, 'incognito': false},
    function() {});

The following code sets a custom pac script.

var config = {
  mode: "pac_script",
  pacScript: {
    data: "function FindProxyForURL(url, host) {\n" +
          "  if (host == 'foobar.com')\n" +
          "    return 'PROXY blackhole:80';\n" +
          "  return 'DIRECT';\n" +
          "}"
  }
};
chrome.experimental.proxy.settings.set(
    {'value': config, 'incognito': false},
    function() {});

The next snippet queries the current proxy settings.

chrome.experimental.proxy.settings.get(
    {'incognito': false},
    function(config) {console.log(JSON.stringify(config));});

Note that the value object passed to set() is not identical to the value object passed to callback function of get(). The latter will contain a rules.httpProxy.port element.