Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the BSD License.
©2012 Google
Use the chrome.proxy module to manage Chrome's
proxy settings. This module relies on the
ChromeSetting prototype of the type API for getting and setting the proxy
configuration.
You must declare the "proxy" permission in the extension manifest to use the proxy settings API. For example:
{
"name": "My extension",
...
"permissions": [
"proxy"
],
...
}
Proxy settings are defined in a
ProxyConfig object. Depending on
Chrome's proxy settings, the settings may contain
ProxyRules or a PacScript.
A ProxyConfig object's mode attribute determines the overall
behavior of Chrome with regards to proxy usage. It can take the following
values:
directdirect mode all connections are created directly, without
any proxy involved. This mode allows no further parameters in the
ProxyConfig object.auto_detectauto_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_scriptpac_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_serversfixed_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.systemsystem 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.
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.
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:
| Scheme | Port |
|---|---|
| http | 80 |
| https | 443 |
| socks4 | 1080 |
| socks5 | 1080 |
Individual servers may be excluded from being proxied with the
bypassList. This list may contain the following entries:
[<scheme>://]<host-pattern>[:<port>]"foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99",
"https://x.*.y.com:99"[<scheme>://]<ip-literal>[:<port>]"127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"<ip-literal>/<prefix-length-in-bits>"192.168.1.1/16", "fefe:13::abc/33"<local>"<local>"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.
Notifies about proxy errors.