chrome/common/extensions/docs/templates/intros/proxy.html

   1 <h2 id="manifest">Manifest</h2>
   2 <p>You must declare the "proxy" permission
   3 in the <a href="manifest">extension manifest</a>
   4 to use the proxy settings API.
   5 For example:</p>
   6 <pre data-filename="manifest.json">
   7 {
   8   "name": "My extension",
   9   ...
  10   <b>"permissions": [
  11     "proxy"
  12   ]</b>,
  13   ...
  14 }
  15 </pre>
  16
  17 <h2 id="description">Objects and properties</h2>
  18
  19 <p>
  20 Proxy settings are defined in a
  21 $(ref:proxy.ProxyConfig) object. Depending on
  22 Chrome's proxy settings, the settings may contain
  23 $(ref:proxy.ProxyRules) or a
  24   $(ref:proxy.PacScript).
  25 </p>
  26
  27 <h3 id="proxy_modes">Proxy modes</h3>
  28
  29 <p>
  30 A ProxyConfig object's <code>mode</code> attribute determines the overall
  31 behavior of Chrome with regards to proxy usage. It can take the following
  32 values:
  33 <dl>
  34   <dt><code>direct</code></dt>
  35   <dd>In <code>direct</code> mode all connections are created directly, without
  36   any proxy involved. This mode allows no further parameters in the
  37   <code>ProxyConfig</code> object.</dd>
  38
  39   <dt><code>auto_detect</code></dt>
  40   <dd>In <code>auto_detect</code> mode the proxy configuration is determined by
  41   a PAC script that can be downloaded at
  42   <a href="http://wpad/wpad.dat">http://wpad/wpad.dat</a>.
  43   This mode allows no further parameters in the <code>ProxyConfig</code>
  44   object.</dd>
  45
  46   <dt><code>pac_script</code></dt>
  47   <dd>In <code>pac_script</code> mode the proxy configuration is determined by
  48   a PAC script that is either retrieved from the URL specified in the
  49   $(ref:proxy.PacScript) object or
  50   taken literally from the <code>data</code> element specified in the
  51   $(ref:proxy.PacScript) object.
  52   Besides this, this mode allows no further parameters in the
  53   <code>ProxyConfig</code> object.</dd>
  54
  55   <dt><code>fixed_servers</code></dt>
  56   <dd>In <code>fixed_servers</code> mode the proxy configuration is codified in
  57   a $(ref:proxy.ProxyRules)
  58   object. Its structure is described in <a href="#proxy_rules">Proxy rules</a>.
  59   Besides this, the <code>fixed_servers</code> mode allows no further parameters
  60   in the <code>ProxyConfig</code> object.</dd>
  61
  62   <dt><code>system</code></dt>
  63   <dd>In <code>system</code> mode the proxy configuration is taken from the
  64   operating system. This mode allows no further parameters in the
  65   <code>ProxyConfig</code> object. Note that the <code>system</code> mode is
  66   different from setting no proxy configuration. In the latter case, Chrome
  67   falls back to the system settings only if no command-line options influence
  68   the proxy configuration.</dd>
  69 </dl>
  70 </p>
  71
  72 <h3 id="proxy_rules">Proxy rules</h3>
  73
  74 <p>
  75 The $(ref:proxy.ProxyRules) object can contain
  76 either a <code>singleProxy</code> attribute or a subset of
  77 <code>proxyForHttp</code>, <code>proxyForHttps</code>, <code>proxyForFtp</code>,
  78 and <code>fallbackProxy</code>.
  79 </p>
  80
  81 <p>
  82 In the first case, HTTP, HTTPS and FTP traffic is proxied through the specified
  83 proxy server. Other traffic is sent directly. In the latter case the behavior is
  84 slightly more subtle: If a proxy server is configured for the HTTP, HTTPS or FTP
  85 protocol, the respective traffic is proxied through the specified server. If no
  86 such proxy server is specified or traffic uses a different protocol than HTTP,
  87 HTTPS or FTP, the <code>fallbackProxy</code> is used. If no
  88 <code>fallbackProxy</code> is specified, traffic is sent directly without a
  89 proxy server.
  90 </p>
  91
  92 <h3 id="proxy_server_objects">Proxy server objects</h3>
  93
  94 <p>
  95 A proxy server is configured in a
  96 $(ref:proxy.ProxyServer) object. The connection
  97 to the proxy server (defined by the <code>host</code> attribute) uses the
  98 protocol defined in the <code>scheme</code> attribute. If no <code>scheme</code>
  99 is specified, the proxy connection defaults to <code>http</code>.
 100 </p>
 101
 102 <p>
 103 If no <code>port</code> is defined in a
 104 $(ref:proxy.ProxyServer) object, the port is
 105 derived from the scheme. The default ports are:
 106 <table>
 107   <tr><th>Scheme</th><th>Port</th></tr>
 108   <tr><td>http</td><td>80</td></tr>
 109   <tr><td>https</td><td>443</td></tr>
 110   <tr><td>socks4</td><td>1080</td></tr>
 111   <tr><td>socks5</td><td>1080</td></tr>
 112 </table>
 113 </p>
 114
 115 <h3 id="bypass_list">Bypass list</h3>
 116
 117 <p>
 118 Individual servers may be excluded from being proxied with the
 119 <code>bypassList</code>. This list may contain the following entries:
 120 <dl>
 121   <dt><code>[<em>&lt;scheme&gt;</em>://]<em>&lt;host-pattern&gt;</em>[:<em>&lt;port&gt;</em>]</code></dt>
 122   <dd>Match all hostnames that match the pattern <em>&lt;host-pattern&gt;</em>.
 123   A leading <code>"."</code> is interpreted as a <code>"*."</code>.<br>
 124   Examples: <code>"foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99",
 125     "https://x.*.y.com:99"</code>.<br>
 126   <table>
 127     <tr>
 128       <th>Pattern
 129       <th>Matches
 130       <th>Does not match
 131     <tr>
 132       <td><code>".foobar.com"</code>
 133       <td><code>"www.foobar.com"</code>
 134       <td><code>"foobar.com"</code>
 135     <tr>
 136       <td><code>"*.foobar.com"</code>
 137       <td><code>"www.foobar.com"</code>
 138       <td><code>"foobar.com"</code>
 139     <tr>
 140       <td><code>"foobar.com"</code>
 141       <td><code>"foobar.com"</code>
 142       <td><code>"www.foobar.com"</code>
 143     <tr>
 144       <td><code>"*foobar.com"</code>
 145       <td><code>"foobar.com"</code>, <code>"www.foobar.com"</code>,
 146           <code>"foofoobar.com"</code>
 147       <td>
 148   </table>
 149   </dd>
 150
 151   <dt><code>[<em>&lt;scheme&gt;</em>://]<em>&lt;ip-literal&gt;</em>[:<em>&lt;port&gt;</em>]</code></dt>
 152   <dd>Match URLs that are IP address literals.<br>
 153   Conceptually this is the similar to the first case, but with special cases
 154   to handle IP literal canonicalization. For example, matching
 155   on "[0:0:0::1]" is the same as matching on "[::1]" because
 156   the IPv6 canonicalization is done internally.<br>
 157   Examples: <code>"127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"</code></dd>
 158
 159   <dt><code><em>&lt;ip-literal&gt;</em>/<em>&lt;prefix-length-in-bits&gt;</em></code></dt>
 160   <dd>Match any URL containing an IP literal within the given range. The IP
 161   range is specified using CIDR notation.<br>
 162   Examples: <code>"192.168.1.1/16", "fefe:13::abc/33"</code></dd>
 163
 164   <dt><code>&lt;local&gt;</code></dt>
 165   <dd>Match local addresses. An address is local if the host is "127.0.0.1",
 166   "::1", or "localhost".<br>
 167   Example: <code>"&lt;local&gt;"</code></dd>
 168 </dl>
 169
 170
 171 <h2 id="overview-examples">Examples</h2>
 172
 173 <p>
 174 The following code sets a SOCKS 5 proxy for HTTP connections to all servers but
 175 foobar.com and uses direct connections for all other protocols. The settings
 176 apply to regular and incognito windows, as incognito windows inherit settings
 177 from regular windows. Please also consult the <a
 178   href="types#ChromeSetting">Types API</a> documentation.
 179 </p>
 180
 181 <pre>
 182 var config = {
 183   mode: "fixed_servers",
 184   rules: {
 185     proxyForHttp: {
 186       scheme: "socks5",
 187       host: "1.2.3.4"
 188     },
 189     bypassList: ["foobar.com"]
 190   }
 191 };
 192 chrome.proxy.settings.set(
 193     {value: config, scope: 'regular'},
 194     function() {});
 195 </pre>
 196
 197 <p>
 198 The following code sets a custom PAC script.
 199 </p>
 200
 201 <pre>
 202 var config = {
 203   mode: "pac_script",
 204   pacScript: {
 205     data: "function FindProxyForURL(url, host) {\n" +
 206           "  if (host == 'foobar.com')\n" +
 207           "    return 'PROXY blackhole:80';\n" +
 208           "  return 'DIRECT';\n" +
 209           "}"
 210   }
 211 };
 212 chrome.proxy.settings.set(
 213     {value: config, scope: 'regular'},
 214     function() {});
 215 </pre>
 216
 217 <p>
 218 The next snippet queries the currently effective proxy settings. The effective
 219 proxy settings can be determined by another extension or by a policy. See the <a
 220   href="types#ChromeSetting">Types API</a> documentation for details.
 221 </p>
 222
 223 <pre>
 224 chrome.proxy.settings.get(
 225     {'incognito': false},
 226     function(config) {console.log(JSON.stringify(config));});
 227 </pre>
 228
 229 <p>
 230 Note that the <code>value</code> object passed to <code>set()</code> is not
 231 identical to the <code>value</code> object passed to callback function of
 232 <code>get()</code>. The latter will contain a
 233 <code>rules.proxyForHttp.port</code> element.
 234 </p>