Description

Permissions

You must declare the "proxy" permission in theextension manifest to use the proxy settingsAPI. For example:

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

Concepts and usage

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

Proxy modes

A ProxyConfig object'smode attribute determines the overall behavior of Chrome with regards toproxy usage. It can take the following values:

direct

Indirect mode all connections are created directly, without any proxy involved. This mode allowsno further parameters in theProxyConfig object.

auto_detect

Inauto_detect mode the proxy configuration is determined by a PAC script that can be downloadedathttp://wpad/wpad.dat. This mode allows no further parameters in theProxyConfig object.

pac_script

Inpac_script mode the proxy configuration is determined by a PAC script that is either retrievedfrom the URL specified in theproxy.PacScript object or taken literally from thedata elementspecified in theproxy.PacScript object. Besides this, this mode allows no further parametersin theProxyConfig object.

fixed_servers

Infixed_servers mode the proxy configuration is codified in aproxy.ProxyRules object. Itsstructure is described inProxy rules. Besides this, thefixed_servers mode allows no furtherparameters in theProxyConfig object.

system

Insystem mode the proxy configuration is taken from the operating system. This mode allows nofurther parameters in theProxyConfig object. Note that thesystem mode is different fromsetting no proxy configuration. In the latter case, Chrome falls back to the system settings only ifno command-line options influence the proxy configuration.

Proxy rules

Theproxy.ProxyRules object can contain either asingleProxy attribute or a subset ofproxyForHttp,proxyForHttps,proxyForFtp, andfallbackProxy.

In the first case, HTTP, HTTPS and FTP traffic is proxied through the specified proxy server. Othertraffic is sent directly. In the latter case the behavior is slightly more subtle: If a proxy serveris configured for the HTTP, HTTPS or FTP protocol, the respective traffic is proxied through thespecified server. If no such proxy server is specified or traffic uses a different protocol thanHTTP, HTTPS or FTP, thefallbackProxy is used. If nofallbackProxy is specified, traffic is sentdirectly without a proxy server.

Proxy server objects

A proxy server is configured in aproxy.ProxyServer object. The connection to the proxy server(defined by thehost attribute) uses the protocol defined in thescheme attribute. If noscheme is specified, the proxy connection defaults tohttp.

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

Bypass list

Individual servers may be excluded from being proxied with thebypassList. This list may containthe following entries:

[SCHEME://]HOST_PATTERN[:PORT]

Match all hostnames that match the patternHOST_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, butwith 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]:80,https://[::1]:443

IP_LITERAL/PREFIX_LENGTH_IN_BITS

Match any URL containing an IP literal (IP_LITERAL) within the givenrange. The IP range (PREFIX_LENGTH_IN_BITS) is specified usingCIDRnotation.

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

<local>

The literal string<local> matches simple hostnames. A simple hostname is one that contains nodots and is not an IP literal. For instanceexample andlocalhost are simple hostnames,whereasexample.com,example., and[::1] are not.

Example:"<local>"

Examples

The following code sets a SOCKS 5 proxy for HTTP connections to all servers but foobar.com and usesdirect connections for all other protocols. The settings apply to regular and incognito windows, asincognito windows inherit settings from regular windows. See also theTypes APIdocumentation.

varconfig={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.

varconfig={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 current effective proxy settings. The effective proxy settings can bedetermined by another extension or by a policy. See theTypes API documentation for details.

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

Note that thevalue object passed toset() is not identical to thevalue object passed tocallback function ofget(). The latter will contain arules.proxyForHttp.port element.

chrome.proxy.onProxyError.addListener(
  callback: function,
)