Merge branch 'doc/2.0.0-beta3' (with doc regen)

doc/configure/base_directives.html

@@ -429,7 +429,7 @@ <h3><a href="configure/base_directives.html#num-name-resolution-threads"><code>"
 <dt>Description:</dt>
 <dd>
 <p>
-Number of threads to run for name resolution.
+Maximum number of threads to run for name resolution.
 </p>
 
 </dd>
@@ -440,6 +440,34 @@ <h3><a href="configure/base_directives.html#num-name-resolution-threads"><code>"
 </dl>
 
 
+<div id="num-ocsp-updaters" class="directive-head">
+<div class="directive-since">since v2.0</div>
+<h3><a href="configure/base_directives.html#num-ocsp-updaters"><code>"num-ocsp-updaters"</code></a></h3>
+</div>
+
+<dl class="directive-desc">
+<dt>Description:</dt>
+<dd>
+<p>
+Maximum number of OCSP updaters.
+</p>
+
+<p>
+<a href="https://en.wikipedia.org/wiki/OCSP_stapling">OSCP Stapling</a> is an optimization that speeds up the time spent for establishing a TLS connection.
+In order to <i>staple</i> OCSP information, a HTTP server is required to periodically contact the certificate authority.
+This directive caps the number of the processes spawn for collecting the information.
+</p>
+<p>
+The use and the update interval of OCSP can be configured using the <a href="configure/base_directives.html#listen-ssl">SSL attributes</a> of the <a href="configure/base_directives.html#listen"><code>listen</code></a> configuration directive.
+</p>
+
+</dd>
+<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
+<dd>global</dd>
+<dt>Default:</dt>
+<dd><code><pre>num-ocsp-updaters: 10</pre></code>
+</dl>
+
 <div id="num-threads" class="directive-head">
 <h3><a href="configure/base_directives.html#num-threads"><code>"num-threads"</code></a></h3>
 </div>
@@ -502,6 +530,127 @@ <h3><a href="configure/base_directives.html#tcp-fastopen"><code>"tcp-fastopen"</
 <dd>global</dd>
 </dl>
 
+<div id="send-server-name" class="directive-head">
+<div class="directive-since">since v2.0</div>
+<h3><a href="configure/base_directives.html#send-server-name"><code>"send-server-name"</code></a></h3>
+</div>
+
+<dl class="directive-desc">
+<dt>Description:</dt>
+<dd>
+<p>
+A boolean flag (<code>ON</code> or <code>OFF</code>) indicating whether if the <code>server</code> response header should be sent.
+</p>
+
+
+</dd>
+<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
+<dd>global</dd>
+<dt>Default:</dt>
+<dd><code><pre>send-server-name: ON</pre></code>
+<dt>See also:</dt>
+<dd><a href="configure/base_directives.html#server-name"><code>server-name</code></a>
+</dd>
+</dl>
+
+<div id="server-name" class="directive-head">
+<div class="directive-since">since v2.0</div>
+<h3><a href="configure/base_directives.html#server-name"><code>"server-name"</code></a></h3>
+</div>
+
+<dl class="directive-desc">
+<dt>Description:</dt>
+<dd>
+<p>
+Lets the user override the value of the <code>server</code> response header.
+</p>
+
+The default value is <code>h2o/VERSION-NUMBER</code>.
+
+</dd>
+<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
+<dd>global</dd>
+<dt>See also:</dt>
+<dd><a href="configure/base_directives.html#send-server-name"><code>send-server-name</code></a>
+</dd>
+</dl>
+
+<div id="setenv" class="directive-head">
+<div class="directive-since">since v2.0</div>
+<h3><a href="configure/base_directives.html#setenv"><code>"setenv"</code></a></h3>
+</div>
+
+<dl class="directive-desc">
+<dt>Description:</dt>
+<dd>
+<p>
+Sets one or more environment variables.
+</p>
+
+<p>
+Environment variables are a set of key-value pairs containing arbitrary strings, that can be read from applications invoked by the standalone server (e.g. <a href="configure/fastcgi_directives.html">fastcgi handler</a>, <a href="configure/mruby_directives.html">mruby handler</a>) and the access logger.
+</p>
+<p>
+The directive is applied from outer-level to inner-level.
+At each level, the directive is applied after the <a href="configure/base_directives.html#unsetenv"><code>unsetenv</code></a> directive at the corresponding level is applied.
+</p>
+<p>
+Environment variables are retained through internal redirections.
+</p>
+<div class="example">
+<div class="caption">Example. Setting an environment variable named <code>FOO</code></div>
+<pre><code>setenv:
+  FOO: &quot;value_of_FOO&quot;
+</code></pre>
+</div>
+
+
+</dd>
+<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
+<dd>global, host, path, extension</dd>
+<dt>See also:</dt>
+<dd><a href="configure/base_directives.html#unsetenv"><code>unsetenv</code></a>
+</dd>
+</dl>
+
+<div id="unsetenv" class="directive-head">
+<div class="directive-since">since v2.0</div>
+<h3><a href="configure/base_directives.html#unsetenv"><code>"unsetenv"</code></a></h3>
+</div>
+
+<dl class="directive-desc">
+<dt>Description:</dt>
+<dd>
+<p>
+Unsets one or more environment variables.
+</p>
+
+<p>
+The directive can be used to have an exception for the paths that have an environment variable set, or can be used to reset variables after an internal redirection.
+</p>
+<div class="example">
+<div class="caption">Example. Setting environment variable for <code>example.com</code> excluding <code>/specific-path</code></div>
+<pre><code>hosts:
+  example.com:
+    setenv:
+      FOO: &quot;value_of_FOO&quot;
+    paths:
+      /specific-path:
+        unsetenv:
+          - FOO
+      ...
+</code></pre>
+</div>
+
+
+</dd>
+<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
+<dd>global, host, path, extension</dd>
+<dt>See also:</dt>
+<dd><a href="configure/base_directives.html#setenv"><code>setenv</code></a>
+</dd>
+</dl>
+
 <div id="ssl-session-resumption" class="directive-head">
 <h3><a href="configure/base_directives.html#ssl-session-resumption"><code>"ssl-session-resumption"</code></a></h3>
 </div>
@@ -628,6 +777,8 @@ <h4 id="ssl-session-resumption-other">Other Attributes</h4>
 <dd>
 specifies the location of memcached used by the <code>memcached</code> stores.
 The value must be a mapping with <code>host</code> attribute specifying the address of the memcached server, and optionally a <code>port</code> attribute specifying the port number (default is <code>11211</code>).
+By default, the memcached client uses the <a href="https://github.com/memcached/memcached/blob/master/doc/protocol-binary.xml">BINARY protocol</a>.
+Users can opt-in to using the legacy <a href="https://github.com/memcached/memcached/blob/master/doc/protocol.txt">ASCII protocol</a> by adding a <code>protocol</code> attribute set to <code>ASCII</code>.
 </dd>
 
 </dd>

doc/configure/http2_directives.html

@@ -88,13 +88,30 @@ <h3 id="server-push">Server push</h3>
 <p>
 H2O recognizes <code>link</code> headers with <a href="https://w3c.github.io/preload/">preload</a> keyword sent by a backend application server (reverse proxy or FastCGI) or an mruby handler, and pushes the designated resource to a client.
 </p>
-<p>
-When pushing the resources, the priority is determined using the <a href="configure/file_directives.html#file.mime.addtypes"><code>priority</code> attribute</a> of the MIME-type configuration.  If the priority is set to <code>highest</code> then the resource will be sent to the client before anything else; otherwise the resource will be sent to client after the main content, as per defined by the HTTP/2 specification.
+<div class="example">
+<div class="caption">Example. A link response header triggering HTTP/2 push</div>
+<pre><code>link: &lt;/assets/jquery.js&gt;; rel=preload
+</code></pre>
+</div>
+
+
+<p>When the HTTP/2 driver of H2O recognizes a <code>link</code> response header with <code>rel=preload</code> attribute set, and if all of the following conditions are met, the specified resource is pushed to the client.
 </p>
+<ul>
+<li>the <code>link</code> header does not have the <code>nopush</code> attribute set</li>
+<li>the <code>link</code> header is <i>not</i> part of a pushed response</li>
+<li>the client does not disable HTTP/2 push</li>
+<li>number of the pushed responses in-flight is below the negotiated threshold</li>
+<li>authority of the resource specified is equivalent to the request that tried to trigger the push</li>
+<li>(for handlers that return the status code synchronously) the status code of the response to be pushed does not indicate an error (i.e. 4xx or 5xx)</li>
+</ul>
 <p>
 The server also provides a mechanism to track the clients' cache state via cookies, and to push the resources specified with the <code>link</code> header only when it does not exist within the clients' cache.  For details, please refer to the documentation of <a href="configure/http2_directives.html#http2-casper"><code>http2-casper</code></a> configuration directive.
 </p>
 <p>
+When a resource is pushed, the priority is determined using the <a href="configure/file_directives.html#file.mime.addtypes"><code>priority</code> attribute</a> of the MIME-type configuration.  If the priority is set to <code>highest</code> then the resource will be sent to the client before anything else; otherwise the resource will be sent to client after the main content, as per defined by the HTTP/2 specification.
+</p>
+<p>
 Pushed responses will have <code>x-http2-push: pushed</code> header set; by looking for the header, it is possible to determine if a resource has been pushed.
 It is also possible to log the value in the <a href="configure/access_log_directives.html#access-log">access log</a> by specifying <code>%{x-http2-push}o</code>, push responses but cancelled by CASPER will have the value of the header logged as <code>cancelled</code>.
 </p>

doc/configure/mruby.html

@@ -233,6 +233,9 @@ <h3 id="http-client">Using the HTTP Client</h3>
 <p>
 Since the API provides an asynchronous HTTP client, it is possible to effectively issue multiple HTTP requests concurrently and merge them into a single response.
 </p>
+<p>
+When HTTPS is used, servers are verified using the properties of <a href="configure/proxy_directives.html#proxy.ssl.cafile"><code>proxy.ssl.cafile</code></a> and <a href="configure/proxy_directives.html#proxy.ssl.verify-peer"><code>proxy.ssl.verify-peer</code></a> specified at the global level.
+</p>
 
 
 

doc/configure/proxy_directives.html

@@ -70,7 +70,8 @@ <h2>
 </ul>
 </p>
 <p>
-The HTTP client only supports plain text HTTP/1; neither HTTP/2 nor HTTPS are supported for the time being.
+The HTTP client only supports HTTP/1.
+Support for HTTPS has been introduced in version 2.0.
 </p>
 <p>
 Following sections describe the configuration directives defined for the module.
@@ -94,7 +95,6 @@ <h3><a href="configure/proxy_directives.html#proxy.reverse.url"><code>"proxy.rev
 </div>
 
 <p>
-At the moment, only HTTP is supported.
 If you want load balancing multiple backends, replace 127.0.0.1 with hostname witch returns IP addresses via DNS or /etc/hosts.
 </p>
 <p>
@@ -125,6 +125,82 @@ <h3><a href="configure/proxy_directives.html#proxy.preserve-host"><code>"proxy.p
 <dt>Default:</dt>
 <dd><code><pre>proxy.preserve-host: OFF</pre></code>
 </dl>
+
+
+<div id="proxy.preserve-x-forwarded-proto" class="directive-head">
+<div class="directive-since">since v2.0</div>
+<h3><a href="configure/proxy_directives.html#proxy.preserve-x-forwarded-proto"><code>"proxy.preserve-x-forwarded-proto"</code></a></h3>
+</div>
+
+<dl class="directive-desc">
+<dt>Description:</dt>
+<dd>
+<p>
+A boolean flag(<code>ON</code> or <code>OFF</code>) indicating if the server preserve the received <code>x-forwarded-proto</code> request header.
+</p>
+
+<p>
+By default, when transmitting a HTTP request to an upstream HTTP server, H2O removes the received <code>x-forwarded-proto</code> request header and sends its own, as a precautios measure to prevent an attacker connecting through HTTP to lie that they are connected via HTTPS.
+However in case H2O is run behind a trusted HTTPS proxy, such protection might not be desirable, and this configuration directive can be used to modify the behaviour.
+</p>
+
+</dd>
+<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
+<dd>global</dd>
+<dt>Default:</dt>
+<dd><code><pre>proxy.preserve-x-forwarded-proto: OFF</pre></code>
+</dl>
+
+<div id="proxy.ssl.cafile" class="directive-head">
+<div class="directive-since">since v2.0</div>
+<h3><a href="configure/proxy_directives.html#proxy.ssl.cafile"><code>"proxy.ssl.cafile"</code></a></h3>
+</div>
+
+<dl class="directive-desc">
+<dt>Description:</dt>
+<dd>
+<p>
+Specifies the file storing the list of trusted root certificates.
+</p>
+
+<p>
+By default, H2O uses <code>share/h2o/ca-bundle.crt</code>.  The file contains a set of trusted root certificates maintained by Mozilla, downloaded and converted using <a href="https://curl.haxx.se/docs/mk-ca-bundle.html">mk-ca-bundle.pl</a>.
+</p>
+
+</dd>
+<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
+<dd>global, host, path</dd>
+<dt>See also:</dt>
+<dd><a href="configure/proxy_directives.html#proxy.ssl.verify-peer"><code>proxy.ssl.verify-peer</code></a>
+</dd>
+</dl>
+
+<div id="proxy.ssl.verify-peer" class="directive-head">
+<div class="directive-since">since v2.0</div>
+<h3><a href="configure/proxy_directives.html#proxy.ssl.verify-peer"><code>"proxy.ssl.verify-peer"</code></a></h3>
+</div>
+
+<dl class="directive-desc">
+<dt>Description:</dt>
+<dd>
+<p>
+A boolean flag (<code>ON</code> or <code>OFF</code>) indicating if the server certificate and hostname should be verified.
+</p>
+
+<p>
+If set to <code>ON</code>, the HTTP client implementation of H2O verifies the peer's certificate using the list of trusted certificates as well as compares the hostname presented in the certificate against the connecting hostname.
+</p>
+
+</dd>
+<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
+<dd>global, host, path</dd>
+<dt>Default:</dt>
+<dd><code><pre>proxy.ssl.verify-peer: ON</pre></code>
+<dt>See also:</dt>
+<dd><a href="configure/proxy_directives.html#proxy.ssl.cafile"><code>proxy.ssl.cafile</code></a>
+</dd>
+</dl>
+
 <div id="proxy.timeout.io" class="directive-head">
 <h3><a href="configure/proxy_directives.html#proxy.timeout.io"><code>"proxy.timeout.io"</code></a></h3>
 </div>