Lines Matching full:proxy
1 # Proxy support in Chrome
3 This document establishes basic proxy terminology and describes Chrome-specific
4 proxy behaviors.
8 ## Proxy server identifiers
10 A proxy server is an intermediary used for network requests. A proxy server can
11 be described by its address, along with the proxy scheme that should be used to
17 The PAC format is how one names a proxy server in [Proxy
20 * `PROXY foo:2138`
33 See the [Proxy server schemes](#Proxy-server-schemes) section for details on
37 formatted proxy server identifiers. However outside of Chrome, proxy servers
38 are generally identified less precisely by just an address -- the proxy
41 In Windows' proxy settings there are host and port fields for the
42 "HTTP", "Secure", "FTP", and "SOCKS" proxy. With the exception of "SOCKS",
43 those are all identifiers for insecure HTTP proxy servers (proxy scheme is
46 ## Proxy resolution
51 to send the request to. This can be either a proxy server, or the target host.
53 This is called proxy resolution. The input to proxy resolution is a URL, and
54 the output is an ordered list of [proxy server
55 identifiers](#Proxy-server-identifiers).
59 * [Manual proxy settings](#Manual-proxy-settings) - proxy resolution is defined
61 URL scheme to proxy server identifier(s), and a list of proxy bypass rules for
62 when to go DIRECT instead of using the mapped proxy.
64 * PAC script - proxy resolution is defined using a JavaScript program, that is
65 invoked whenever fetching a URL to get the list of proxy server identifiers
71 ## Proxy server schemes
73 When using an explicit proxy in the browser, multiple layers of the network
75 of the proxy scheme are:
77 * Is communication to the proxy done over a secure channel?
78 * Is name resolution (ex: DNS) done client side, or proxy side?
79 * What authentication schemes to the proxy server are supported?
80 * What network traffic can be sent through the proxy?
82 Chrome supports these proxy server schemes:
84 * [DIRECT](#DIRECT-proxy-scheme)
85 * [HTTP](#HTTP-proxy-scheme)
86 * [HTTPS](#HTTPS-proxy-scheme)
87 * [SOCKSv4](#SOCKSv4-proxy-scheme)
88 * [SOCKSv5](#SOCKSv5-proxy-scheme)
89 * [QUIC](#QUIC-proxy-scheme)
91 ### DIRECT proxy scheme
97 This is a pseudo proxy scheme that indicates instead of using a proxy we are
100 It is imprecise to call this a "proxy server", but it is a convenient abstraction.
102 ### HTTP proxy scheme
105 * Example identifier (PAC): `PROXY proxy:8080`, `proxy` (non-standard; don't use)
106 * Example identifiers (URI): `http://proxy:8080`, `proxy:8080` (can omit scheme)
108 Generally when one refers to a "proxy server" or "web proxy", they are talking
109 about an HTTP proxy.
111 When using an HTTP proxy in Chrome, name resolution is always deferred to the
112 proxy. HTTP proxies can proxy `http://`, `https://`, `ws://` and `wss://` URLs.
114 Communication to HTTP proxy servers is insecure, meaning proxied `http://`
116 HTTP proxy, the TLS exchange is forwarded through the proxy using the `CONNECT`
118 tunnel, the hostname of the target URL is sent to the proxy server in the
124 ### HTTPS proxy scheme
127 * Example identifier (PAC): `HTTPS proxy:8080`
128 * Example identifier (URI): `https://proxy:8080`
130 This works like an [HTTP proxy](#HTTP-proxy-scheme), except the
131 communication to the proxy server is protected by TLS, and may negotiate
134 Because the connection to the proxy server is secure, https:// requests
135 sent through the proxy are not sent in the clear as with an HTTP proxy.
143 regular HTTP proxy due to higher connection limits (HTTP/1.1 proxies in Chrome
149 Specifying an HTTPS proxy is generally not possible through system proxy
150 settings. Instead, one must use either a PAC script or a Chrome proxy setting
154 proxies](http://dev.chromium.org/developers/design-documents/secure-web-proxy)
155 for tips on how to run and test against an HTTPS proxy.
157 ### SOCKSv4 proxy scheme
160 * Example identifiers (PAC): `SOCKS4 proxy:8080`, `SOCKS proxy:8080`
161 * Example identifier (URI): `socks4://proxy:8080`
163 SOCKSv4 is a simple transport layer proxy that wraps a TCP socket. Its use
165 handshake when connecting the TCP socket (to the proxy), the rest of the
168 No proxy authentication methods are supported for SOCKSv4.
170 When using a SOCKSv4 proxy, name resolution for target hosts is always done
174 There are extensions to SOCKSv4 that allow for proxy side name resolution, and
181 ### SOCKSv5 proxy scheme
184 * Example identifier (PAC): `SOCKS5 proxy:8080`
185 * Example identifiers (URI): `socks://proxy:8080`, `socks5://proxy:8080`
187 [SOCKSv5](https://tools.ietf.org/html/rfc1928) is a transport layer proxy that
188 wraps a TCP socket, and allows for name resolution to be deferred to the proxy.
190 In Chrome when a proxy's scheme is set to SOCKSv5, name resolution is always
191 done proxy side (even though the protocol allows for client side as well). In
192 Firefox client side vs proxy side name resolution can be configured with
193 `network.proxy.socks_remote_dns`; Chrome has no equivalent option and will
194 always use proxy side resolution.
199 A handy way to create a SOCKSv5 proxy is with `ssh -D`, which can be used to
202 In Chrome SOCKSv5 is only used to proxy TCP-based URL requests. It cannot be
205 ### QUIC proxy scheme
208 * Example identifier (PAC): `QUIC proxy:8080`
209 * Example identifier (URI): `quic://proxy:8080`
211 A QUIC proxy uses QUIC (UDP) as the underlying transport, but otherwise
212 behaves as an HTTP proxy. It has similar properties to an [HTTPS
213 proxy](#HTTPS-proxy-scheme), in that the connection to the proxy server
218 URLs through a QUIC proxy is [disabled by
225 ## Manual proxy settings
227 The simplest way to configure proxy resolution is by providing a static list of
230 1. A mapping of URL schemes to [proxy server identifiers](#Proxy-server-identifiers).
231 2. A list of [proxy bypass rules](#Proxy-bypass-rules)
233 We refer to this mode of configuration as "manual proxy settings".
235 Manual proxy settings can succinctly describe setups like:
237 * Use proxy `http://foo:8080` for all requests
238 * Use proxy `http://foo:8080` for all requests except those to a `google.com`
240 * Use proxy `http://foo:8080` for all `https://` requests, and proxy
243 Although manual proxy settings are a ubiquituous way to configure proxies
246 Chrome's manual proxy settings most closely resembles that of WinInet. But it
251 When defining manual proxy settings in Chrome, we specify three (possibly
252 empty) lists of [proxy server identifiers](#Proxy-server-identifiers).
254 * proxies for HTTP - A list of proxy server identifiers to use for `http://`
256 * proxies for HTTPS - A list of proxy server identifiers to use for
258 * other proxies - A list of proxy server identifiers to use for everything
261 There are a lot of ways to end up with manual proxy settings in Chrome
265 `--proxy-server=XXX` (and optionally `--proxy-bypass-list=YYY`)
267 Example: To use proxy `http://foo:8080` for all requests we can launch
268 Chrome with `--proxy-server="http://foo:8080"`. This translates to:
274 With the above configuration, if the proxy server was unreachable all requests
277 `--proxy-server="http://foo:8080,direct://"` (note the comma separated list).
284 If instead we wanted to proxy only `http://` URLs through the
285 HTTPS proxy `https://foo:443`, and have everything else use the SOCKSv5 proxy
287 `--proxy-server="http=https://foo:443;socks=socks5://mysocks:1080"`. This now
294 The command line above uses WinInet's proxy map format, with some additional
297 * Instead of naming proxy servers by just a hostname:port, you can use Chrome's
298 URI format for proxy server identifiers. In other words, you can prefix the
299 proxy scheme so it doesn't default to HTTP.
301 subsequent proxy list can include proxies of any scheme, however if the
304 ### Mapping WebSockets URLs to a proxy
306 [Manual proxy settings](#Manual-proxy-settings) don't have mappings for `ws://`
309 Selecting a proxy for these URL schemes is a bit different from other URL
321 ### Proxy credentials in manual proxy settings
323 Most platforms' [manual proxy settings](#Manual-proxy-settings) allow
324 specifying a cleartext username/password for proxy sign in. Chrome does not
325 implement this, and will not use any credentials embedded in the proxy
328 Proxy authentication will instead go through the ordinary flow to find
331 ## Proxy bypass rules
333 In addition to specifying three lists of [proxy server
334 identifiers](#proxy-server-identifiers), Chrome's [manual proxy
335 settings](#Manual-proxy-settings) lets you specify a list of "proxy bypass
338 This ruleset determines whether a given URL should skip use of a proxy all
339 together, even when a proxy is otherwise defined for it.
342 "no proxy list".
344 Proxy bypass rules can be written as an ordered list of strings. Ordering
347 When manual proxy settings are specified from the command line, the
348 `--proxy-bypass-list="RULES"` switch can be used, where `RULES` is a semicolon
352 supports. They can be used when defining a Chrome manual proxy settings from
355 When using system proxy settings, one should use the platform's rule format and
456 the "Don't use proxy server for local (intranet) addresses" on Windows.
469 *Subtracts* the [implicit proxy bypass rules](#Implicit-bypass-rules)
474 use the proxy, this rule has the opposite effect and tells the browser to
475 instead *use* the proxy.
483 The IP address range bypass rules in manual proxy settings applies only to URL
488 Say we have have configured a proxy for all requests, but added a bypass rule
490 to `192.168.1.5` in our setup) will the browser connect directly (bypass proxy)
493 It will go through the proxy.
496 actually does a name resolution for `foo`. Proxy resolution happens before
497 name resolution, and depending on what proxy scheme is subsequently chosen,
500 The usefulness of IP range proxy bypass rules is rather limited, as they only
503 If proxy decisions need to be made based on the resolved IP address(es) of a
508 Requests to certain hosts will not be sent through a proxy, and will instead be
527 This concept of implicit proxy bypass rules is consistent with the
528 platform-level proxy support on Windows and macOS (albeit with some differences
532 Why apply implicit proxy bypass rules in the first place? Certainly there are
535 ability to proxy it grants extra powers. This is [especially
537 proxy settings are externally controllable, as when using PAC scripts.
541 * Prior to M71 there were no implicit proxy bypass rules, except if using
542 [`--winhttp-proxy-resolver`](#winhttp_proxy_resolver-command-line-switch).
543 * In M71 Chrome applied implicit proxy bypass rules to PAC scripts
544 * In M72 Chrome generalized the implicit proxy bypass rules to manually
549 If you want traffic to `localhost` to be sent through a proxy despite the
550 security concerns, it can be done by adding the special proxy bypass rule
556 --proxy-bypass-list="<-loopback>"
559 Note that there currently is no mechanism to disable the implicit proxy bypass
560 rules when using a PAC script. Proxy bypass lists only apply to manual
562 proxy for localhost URLs.
564 ## Evaluating proxy lists (proxy fallback)
566 Proxy resolution results in a _list_ of [proxy server
567 identifiers](#Proxy-server-identifiers) to use for a
568 given request, not just a single proxy server identifier.
575 return "PROXY proxy1; HTTPS proxy2; SOCKS5 proxy3";
582 What proxy will Chrome use for connections to `www.example.com`, given that
583 we have a choice of three separate proxy server identifiers to choose from
594 Proxy fallback is stateful. The actual order of proxy attempts made be Chrome
595 is influenced by the past responsiveness of proxy servers.
598 resolves to a list of three proxy server identifiers:
609 other proxy server identifiers (including `direct://`) that are not marked as
620 What constitutes a "failure" when it comes to triggering proxy fallback depends
621 on the proxy type. Generally speaking, only connection level failures
622 are deemed eligible for proxy fallback. This includes:
624 * Failure resolving the proxy server's DNS
625 * Failure connecting a TCP socket to the proxy server
631 CONNECT tunnel as an error eligible for proxy fallback. This policy [resulted
635 establishment. The problem would occur when a working proxy fallback option
636 like DIRECT was given, since the failing proxy would then be marked as bad.
638 Currently there are no options to configure proxy fallback (including disabling
643 To investigate issues relating to proxy fallback, one can [collect a NetLog
651 * The "Proxy" tab will show which proxies (if any) were marked as bad at the
653 * The "Events" tab notes what the resolved proxy list was, and what the
654 re-ordered proxy list was after taking into account bad proxies.
655 * The "Events" tab notes when a proxy is marked as bad and why (provided the
661 [chrome://net-internals/#proxy](chrome://net-internals/#proxy). Note the UI
818 Proxy resolving via PAC works differently on Android than other desktop Chrome
832 PAC, Android WebView's net code will see the proxy settings as being a
833 single HTTP proxy on `localhost`. The system localhost proxy will in turn
835 proxy. This translation has a number of effects, including what proxy
836 schemes are supported, the maximum connection limits, how proxy fallback
848 When a network context is configured to use a PAC script, proxy resolution will
858 * Are never fetched through a proxy
874 * A user explicitly invalidates PAC through `chrome://net-internals#proxy`
876 Once considered stale, the PAC URL will be re-fetched the next time proxy
881 When the proxy settings are configured to use a PAC URL, and that PAC URL
882 cannot be fetched, proxy resolution will fallback to the next option, which is
885 * If using system proxy settings, and the platform supports fallback to manual
886 proxy settings (e.g. Windows), the specified manual proxy servers will be
888 * If using Chrome's proxy settings, and the PAC script was marked as
889 [mandatory](https://developer.chrome.com/extensions/proxy), fallback to
890 `DIRECT` is not permitted. Subsequent network requests will fail proxy
892 * Otherwise proxy resolution will silently fall back to `DIRECT`.
905 incoming proxy resolution request, so it will not trigger work when the browser
909 whenever the network changes, the proxy settings change, or it was manually
910 invalidated via `chrome://net-internals#proxy`.
923 `application/x-ns-proxy-autoconfig` or `application/x-javascript-config`.
926 ## Capturing a Net Log for debugging proxy resolution issues
928 Issues in proxy resolution are best investigated using a Net Log.
936 3. In a new tab, navigate to `chrome://net-internals/#proxy` and click both
946 ## Analyzing Net Logs for proxy issues
950 ### Proxy overview tab
952 Start by getting a big-picture view of the proxy settings by clicking to the
953 "Proxy" tab on the left. This summarizes the proxy settings at the time the
956 * Does the _original_ proxy settings match expectation?
957 The proxy settings might be coming from:
959 * Command line flags (ex: `--proxy-server`)
960 …* (per-profile) Chrome extensions (ex: [chrome.proxy](https://developer.chrome.com/extensions/prox…
961 * (per-network) System proxy settings
963 * Was [proxy autodetect (WPAD)](#Web-Proxy-Auto_Discovery-WPAD) specified? In
967 * Internally, proxy settings are per-NetworkContext. The proxy
971 show different proxy settings here than a net-export capture initiated by a
974 capture and hence no proxy settings will be shown in this overview.
981 field trials. A find-in-page for `proxy` is a good starting point. Be on the lookout for
982 [`--winhttp-proxy-resolver`](#winhttp_proxy_resolver-command-line-switch) which
987 To deep dive into proxy resolution, switch to the Events tab.
991 trace the proxy resolution steps and outcome.
999 Network change events can also be key to understanding proxy issues. After
1000 switching networks (ex VPN), the effective proxy settings, as well as content
1003 ## Web Proxy Auto-Discovery (WPAD)
1005 When configured to use WPAD (aka "autotmaticaly detect proxy settings"), Chrome
1022 as part of the system proxy settings. So effectively when Chrome is configured
1023 to "use system proxy settings" it may behave as if it supports DHCP-based WPAD.
1038 funnel the user's traffic through a proxy server of their choice. The
1044 ## --winhttp-proxy-resolver command line switch
1046 Passing the `--winhttp-proxy-resolver` command line argument instructs Chrome
1047 to use the system libraries for *one narrow part of proxy resolution*: evaluating
1052 can break Chrome extensions (`chrome.proxy` API), the interpretation of
1053 Proxy policies, hurt performance, and doesn't ensure full fidelity
1054 interpretation of system proxy settings.
1063 Although Chrome would like full fidelity with Windows proxy settings, there are
1064 limits to those integrations. Dependencies like NRPT for proxy
1065 resolution necessitate using Windows proxy resolution libraries directly