chrome.proxy

Description: Use the chrome.proxy API to manage Chrome's proxy settings. This API relies on the ChromeSetting prototype of the type API for getting and setting the proxy configuration.
Availability: Since Chrome 13.
Permissions: "proxy"

Manifest

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

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

Objects and properties

Proxy settings are defined in a proxy.ProxyConfig object. Depending on Chrome's proxy settings, the settings may contain proxy.ProxyRules or a proxy.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 proxy.PacScript object or taken literally from the data element specified in the proxy.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 proxy.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 proxy.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 proxy.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 proxy.ProxyServer object, the port is derived from the scheme. The default ports are:

SchemePort
http80
https443
socks41080
socks51080

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>. A leading "." is interpreted as a "*.".
Examples: "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.*.y.com:99".
Pattern Matches Does not match
".foobar.com" "www.foobar.com" "foobar.com"
"*.foobar.com" "www.foobar.com" "foobar.com"
"foobar.com" "foobar.com" "www.foobar.com"
"*foobar.com" "foobar.com", "www.foobar.com", "foofoobar.com"
[<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>"

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, as incognito windows inherit settings from regular windows. Please also consult the Types API documentation.

      var config = {
        mode: "fixed_servers",
        rules: {
          proxyForHttp: {
            scheme: "socks5",
            host: "1.2.3.4"
          },
          bypassList: ["foobar.com"]
        }
      };
      chrome.proxy.settings.set(
          {value: config, scope: 'regular'},
          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.proxy.settings.set(
          {value: config, scope: 'regular'},
          function() {});
      

The next snippet queries the currently effective proxy settings. The effective proxy settings can be determined by another extension or by a policy. See the Types API documentation for details.

      chrome.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.proxyForHttp.port element.

Summary

Types
ProxyServer
ProxyRules
PacScript
ProxyConfig
Properties
settings
Events
onProxyError

Types

ProxyServer

An object encapsulating a single proxy server's specification.
properties
enum of "http", "https", "quic", "socks4", or "socks5" (optional) scheme

The scheme (protocol) of the proxy server itself. Defaults to 'http'.

string host

The URI of the proxy server. This must be an ASCII hostname (in Punycode format). IDNA is not supported, yet.

integer (optional) port

The port of the proxy server. Defaults to a port that depends on the scheme.

ProxyRules

An object encapsulating the set of proxy rules for all protocols. Use either 'singleProxy' or (a subset of) 'proxyForHttp', 'proxyForHttps', 'proxyForFtp' and 'fallbackProxy'.
properties
ProxyServer (optional) singleProxy

The proxy server to be used for all per-URL requests (that is http, https, and ftp).

ProxyServer (optional) proxyForHttp

The proxy server to be used for HTTP requests.

ProxyServer (optional) proxyForHttps

The proxy server to be used for HTTPS requests.

ProxyServer (optional) proxyForFtp

The proxy server to be used for FTP requests.

ProxyServer (optional) fallbackProxy

The proxy server to be used for everthing else or if any of the specific proxyFor... is not specified.

array of string (optional) bypassList

List of servers to connect to without a proxy server.

PacScript

An object holding proxy auto-config information. Exactly one of the fields should be non-empty.
properties
string (optional) url

URL of the PAC file to be used.

string (optional) data

A PAC script.

boolean (optional) mandatory

If true, an invalid PAC script will prevent the network stack from falling back to direct connections. Defaults to false.

ProxyConfig

An object encapsulating a complete proxy configuration.
properties
ProxyRules (optional) rules

The proxy rules describing this configuration. Use this for 'fixed_servers' mode.

PacScript (optional) pacScript

The proxy auto-config (PAC) script for this configuration. Use this for 'pac_script' mode.

enum of "direct", "auto_detect", "pac_script", "fixed_servers", or "system" mode

'direct' = Never use a proxy
'auto_detect' = Auto detect proxy settings
'pac_script' = Use specified PAC script
'fixed_servers' = Manually specify proxy servers
'system' = Use system proxy settings

Properties

object chrome.proxy.settings An interface that allows access to a Chrome browser setting. See accessibilityFeatures for an example.

get

settings.get(object details, function callback)

Since Chrome 21.

Gets the value of a setting.

Functions
Parameters
object details

Which setting to consider.

boolean (optional) incognito

Whether to return the value that applies to the incognito session (default false).

function callback

The callback parameter should be a function that looks like this:

function(object details) {...};
object details

Details of the currently effective value.

any value

The value of the setting.

enum of "not_controllable", "controlled_by_other_extensions", "controllable_by_this_extension", or "controlled_by_this_extension" levelOfControl

One of

  • not_controllable: cannot be controlled by any extension
  • controlled_by_other_extensions: controlled by extensions with higher precedence
  • controllable_by_this_extension: can be controlled by this extension
  • controlled_by_this_extension: controlled by this extension

boolean (optional) incognitoSpecific

Whether the effective value is specific to the incognito session.
This property will only be present if the incognito property in the details parameter of get() was true.

set

settings.set(object details, function callback)

Since Chrome 21.

Sets the value of a setting.

Parameters
object details

Which setting to change.

any value

The value of the setting.
Note that every setting has a specific value type, which is described together with the setting. An extension should not set a value of a different type.

enum of "regular", "regular_only", "incognito_persistent", or "incognito_session_only" (optional) scope

Where to set the setting (default: regular). One of

  • regular: setting for the regular profile (which is inherited by the incognito profile if not overridden elsewhere),
  • regular_only: setting for the regular profile only (not inherited by the incognito profile),
  • incognito_persistent: setting for the incognito profile that survives browser restarts (overrides regular preferences),
  • incognito_session_only: setting for the incognito profile that can only be set during an incognito session and is deleted when the incognito session ends (overrides regular and incognito_persistent preferences).

function (optional) callback

Called at the completion of the set operation.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

clear

settings.clear(object details, function callback)

Since Chrome 21.

Clears the setting, restoring any default value.

Parameters
object details

Which setting to clear.

enum of "regular", "regular_only", "incognito_persistent", or "incognito_session_only" (optional) scope

Where to clear the setting (default: regular). One of

  • regular: setting for the regular profile (which is inherited by the incognito profile if not overridden elsewhere),
  • regular_only: setting for the regular profile only (not inherited by the incognito profile),
  • incognito_persistent: setting for the incognito profile that survives browser restarts (overrides regular preferences),
  • incognito_session_only: setting for the incognito profile that can only be set during an incognito session and is deleted when the incognito session ends (overrides regular and incognito_persistent preferences).

function (optional) callback

Called at the completion of the clear operation.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

Events

onProxyError

Notifies about proxy errors.

addListener

chrome.proxy.onProxyError.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(object details) {...};
object details
boolean fatal

If true, the error was fatal and the network transaction was aborted. Otherwise, a direct connection is used instead.

string error

The error description.

string details

Additional details about the error such as a JavaScript runtime error.