webapps/docs/config/http2.xml - tomcat - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
 <!DOCTYPE document [
   <!ENTITY project SYSTEM "project.xml">
 ]>
 <document url="http2.html">

   &project;

   <properties>
     <title>The HTTP2 Upgrade Protocol</title>
   </properties>

 <body>

 <section name="Table of Contents">
 <toc/>
 </section>

 <section name="Introduction">

   <p>The <strong>HTTP Upgrade Protocol</strong> element represents an
   <strong>Upgrade Protocol</strong> component that supports the HTTP/2 protocol.
   An instance of this component must be associated with an existing
   <a href="http.html">HTTP/1.1 Connector</a>.</p>

   <p>HTTP/2 connectors use non-blocking I/O, only utilising a container thread
   from the thread pool when there is data to read and write. However, because
   the Servlet API is fundamentally blocking, each HTTP/2 stream requires a
   dedicated container thread for the duration of that stream.</p>

 </section>


 <section name="Attributes">

   <subsection name="Common Attributes">

   <p>All implementations of <strong>Upgrade Protocol</strong> support the
   following attributes:</p>

   <attributes>

     <attribute name="className" required="true">
       <p>This must be <code>org.apache.coyote.http2.Http2Protocol</code>.</p>
     </attribute>

   </attributes>

   </subsection>

   <subsection name="Standard Implementation">

   <p>The HTTP/2 <strong>Upgrade Protocol</strong> implementation supports the
   following attributes in addition to the common attributes listed above.</p>

   <attributes>

     <attribute name="allowedTrailerHeaders" required="false">
       <p>By default Tomcat will ignore all trailer headers when processing
       HTTP/2 connections. For a header to be processed, it must be added to this
       comma-separated list of header names.</p>
     </attribute>

     <attribute name="compressibleMimeType" required="false">
       <p>The value is a comma separated list of MIME types for which HTTP
       compression may be used.
       The default value is
       <code>
       text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json,application/xml
       </code>.
       </p>
     </attribute>

     <attribute name="compression" required="false">
       <p>The HTTP/2 protocol may use compression in an attempt to save server
       bandwidth. The acceptable values for the parameter is "off" (disable
       compression), "on" (allow compression, which causes text data to be
       compressed), "force" (forces compression in all cases), or a numerical
       integer value (which is equivalent to "on", but specifies the minimum
       amount of data before the output is compressed). If the content-length is
       not known and compression is set to "on" or more aggressive, the output
       will also be compressed. If not specified, this attribute is set to
       "off".</p>
       <p><em>Note</em>: There is a tradeoff between using compression (saving
       your bandwidth) and using the sendfile feature (saving your CPU cycles).
       If the connector supports the sendfile feature, e.g. the NIO2 connector,
       using sendfile will take precedence over compression. The symptoms will
       be that static files greater that 48 Kb will be sent uncompressed.
       You can turn off sendfile by setting <code>useSendfile</code> attribute
       of the protocol, as documented below, or change the sendfile usage
       threshold in the configuration of the
       <a href="../default-servlet.html">DefaultServlet</a> in the default
       <code>conf/web.xml</code> or in the <code>web.xml</code> of your web
       application.
       </p>
     </attribute>

     <attribute name="compressionMinSize" required="false">
       <p>If <strong>compression</strong> is set to "on" then this attribute
       may be used to specify the minimum amount of data before the output is
       compressed. If not specified, this attribute is defaults to "2048".</p>
     </attribute>

     <attribute name="initialWindowSize" required="false">
       <p>Controls the initial size of the flow control window for streams that
       Tomcat advertises to clients. If not specified, the default value of
       <code>65535</code> is used.</p>
     </attribute>

     <attribute name="keepAliveTimeout" required="false">
       <p>The time, in milliseconds, that Tomcat will wait between HTTP/2 frames
       when there is no active Stream before closing the connection. Negative
       values will be treated as an infinite timeout. If not specified, a default
       value of <code>20000</code> will be used.</p>
     </attribute>

     <attribute name="maxConcurrentStreamExecution" required="false">
       <p>The controls the maximum number of streams for any one connection that
       can be allocated threads from the container thread pool. If more streams
       are active than threads are available, those streams will have to wait
       for a stream to become available. If not specified, the default value of
       <code>20</code> will be used.</p>
     </attribute>

     <attribute name="maxConcurrentStreams" required="false">
       <p>The controls the maximum number of active streams permitted for any one
       connection. If a client attempts to open more active streams than this
       limit, the stream will be reset with a <code>STREAM_REFUSED</code> error.
       If not specified, the default value of <code>200</code> will be used.</p>
     </attribute>

     <attribute name="maxHeaderCount" required="false">
       <p>The maximum number of headers in a request that is allowed by the
       container. A request that contains more headers than the specified limit
       will be rejected. A value of less than 0 means no limit.
       If not specified, a default of 100 is used.</p>
     </attribute>

     <attribute name="maxHeaderSize" required="false">
       <p>The maximum total size for all headers in a request that is allowed by
       the container. Total size for a header is calculated as the uncompressed
       size of the header name in bytes, plus the uncompressed size of the header
       value in bytes plus an HTTP/2 overhead of 3 bytes per header. A request
       that contains a set of headers that requires more than the specified limit
       will be rejected. A value of less than 0 means no limit. If not specified,
       a default of 8192 is used.</p>
     </attribute>

     <attribute name="maxTrailerCount" required="false">
       <p>The maximum number of trailer headers in a request that is allowed by
       the container. A request that contains more trailer headers than the
       specified limit will be rejected. A value of less than 0 means no limit.
       If not specified, a default of 100 is used.</p>
     </attribute>

     <attribute name="maxTrailerSize" required="false">
       <p>The maximum total size for all trailer headers in a request that is
       allowed by the container. Total size for a header is calculated as the
       uncompressed size of the header name in bytes, plus the uncompressed size
       of the header value in bytes plus an HTTP/2 overhead of 3 bytes per
       header. A request that contains a set of trailer headers that requires
       more than the specified limit will be rejected. A value of less than 0
       means no limit. If not specified, a default of 8192 is used.</p>
     </attribute>

     <attribute name="noCompressionUserAgents" required="false">
       <p>The value is a regular expression (using <code>java.util.regex</code>)
       matching the <code>user-agent</code> header of HTTP clients for which
       compression should not be used,
       because these clients, although they do advertise support for the
       feature, have a broken implementation.
       The default value is an empty String (regexp matching disabled).</p>
     </attribute>

     <attribute name="overheadCountFactor" required="false">
       <p>The factor to apply when counting overhead frames to determine if a
       connection has too high an overhead and should be closed. The overhead
       count starts at <code>-10</code>. The count is decreased for each
       data frame sent or received and each headers frame received. The count is
       increased by the <code>overheadCountFactor</code>for each setting
       received, priority frame received and ping received. If the overhead count
       exceeds zero, the connection is closed. A value of less than
       <code>1</code> disables this protection. In normal usage a value of
       <code>3</code> or more will close the connection before any streams can
       complete. If not specified, a default value of <code>1</code> will be
       used.</p>
     </attribute>

     <attribute name="readTimeout" required="false">
       <p>The time, in milliseconds, that Tomcat will wait for additional data
       when a partial HTTP/2 frame has been received. Negative values will be
       treated as an infinite timeout. If not specified, a default value of
       <code>5000</code> will be used.</p>
     </attribute>

     <attribute name="streamReadTimeout" required="false">
       <p>The time, in milliseconds, that Tomcat will wait for additional data
       frames to arrive for the stream when an application is performing a
       blocking I/O read and additional data is required. Negative values will be
       treated as an infinite timeout. If not specified, a default value of
       <code>20000</code> will be used.</p>
     </attribute>

     <attribute name="streamWriteTimeout" required="false">
       <p>The time, in milliseconds, that Tomcat will wait for additional window
       update frames to arrive for the stream and/or conenction when an
       application is performing a blocking I/O write and the stream and/or
       connection flow control window is too small for the write to complete.
       Negative values will be treated as an infinite timeout. If not specified,
       a default value of <code>20000</code> will be used.</p>
     </attribute>

     <attribute name="useSendfile" required="false">
       <p>Use this boolean attribute to enable or disable sendfile capability.
       The default value is <code>true</code>.</p>
     </attribute>

     <attribute name="writeTimeout" required="false">
       <p>The time, in milliseconds, that Tomcat will wait to write additional
       data when an HTTP/2 frame has been partially written. Negative values will
       be treated as an infinite timeout. If not specified, a default value of
       <code>5000</code> will be used.</p>
     </attribute>

   </attributes>

   <p>The HTTP/2 upgrade protocol will also inherit the following limits from the
   <a href="http.html">HTTP Connector</a> it is nested with:</p>

   <ul>
     <li>maxCookieCount</li>
     <li>maxParameterCount</li>
     <li>maxPostSize</li>
     <li>maxSavePostSize</li>
   </ul>

   </subsection>

 </section>

 <section name="Nested Components">

   <p>This component does not support any nested components.</p>

 </section>


 <section name="Special Features">

   <p>This component does not support any special features.</p>

 </section>

 </body>

 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<!DOCTYPE document [
	<!ENTITY project SYSTEM "project.xml">
	]>
	<document url="http2.html">

	&project;

	<properties>
	<title>The HTTP2 Upgrade Protocol</title>
	</properties>

	<body>

	<section name="Table of Contents">
	<toc/>
	</section>

	<section name="Introduction">

	<p>The <strong>HTTP Upgrade Protocol</strong> element represents an
	<strong>Upgrade Protocol</strong> component that supports the HTTP/2 protocol.
	An instance of this component must be associated with an existing
	<a href="http.html">HTTP/1.1 Connector</a>.</p>

	<p>HTTP/2 connectors use non-blocking I/O, only utilising a container thread
	from the thread pool when there is data to read and write. However, because
	the Servlet API is fundamentally blocking, each HTTP/2 stream requires a
	dedicated container thread for the duration of that stream.</p>

	</section>


	<section name="Attributes">

	<subsection name="Common Attributes">

	<p>All implementations of <strong>Upgrade Protocol</strong> support the
	following attributes:</p>

	<attributes>

	<attribute name="className" required="true">
	<p>This must be <code>org.apache.coyote.http2.Http2Protocol</code>.</p>
	</attribute>

	</attributes>

	</subsection>

	<subsection name="Standard Implementation">

	<p>The HTTP/2 <strong>Upgrade Protocol</strong> implementation supports the
	following attributes in addition to the common attributes listed above.</p>

	<attributes>

	<attribute name="allowedTrailerHeaders" required="false">
	<p>By default Tomcat will ignore all trailer headers when processing
	HTTP/2 connections. For a header to be processed, it must be added to this
	comma-separated list of header names.</p>
	</attribute>

	<attribute name="compressibleMimeType" required="false">
	<p>The value is a comma separated list of MIME types for which HTTP
	compression may be used.
	The default value is
	<code>
	text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json,application/xml
	</code>.
	</p>
	</attribute>

	<attribute name="compression" required="false">
	<p>The HTTP/2 protocol may use compression in an attempt to save server
	bandwidth. The acceptable values for the parameter is "off" (disable
	compression), "on" (allow compression, which causes text data to be
	compressed), "force" (forces compression in all cases), or a numerical
	integer value (which is equivalent to "on", but specifies the minimum
	amount of data before the output is compressed). If the content-length is
	not known and compression is set to "on" or more aggressive, the output
	will also be compressed. If not specified, this attribute is set to
	"off".</p>
	<p><em>Note</em>: There is a tradeoff between using compression (saving
	your bandwidth) and using the sendfile feature (saving your CPU cycles).
	If the connector supports the sendfile feature, e.g. the NIO2 connector,
	using sendfile will take precedence over compression. The symptoms will
	be that static files greater that 48 Kb will be sent uncompressed.
	You can turn off sendfile by setting <code>useSendfile</code> attribute
	of the protocol, as documented below, or change the sendfile usage
	threshold in the configuration of the
	<a href="../default-servlet.html">DefaultServlet</a> in the default
	<code>conf/web.xml</code> or in the <code>web.xml</code> of your web
	application.
	</p>
	</attribute>

	<attribute name="compressionMinSize" required="false">
	<p>If <strong>compression</strong> is set to "on" then this attribute
	may be used to specify the minimum amount of data before the output is
	compressed. If not specified, this attribute is defaults to "2048".</p>
	</attribute>

	<attribute name="initialWindowSize" required="false">
	<p>Controls the initial size of the flow control window for streams that
	Tomcat advertises to clients. If not specified, the default value of
	<code>65535</code> is used.</p>
	</attribute>

	<attribute name="keepAliveTimeout" required="false">
	<p>The time, in milliseconds, that Tomcat will wait between HTTP/2 frames
	when there is no active Stream before closing the connection. Negative
	values will be treated as an infinite timeout. If not specified, a default
	value of <code>20000</code> will be used.</p>
	</attribute>

	<attribute name="maxConcurrentStreamExecution" required="false">
	<p>The controls the maximum number of streams for any one connection that
	can be allocated threads from the container thread pool. If more streams
	are active than threads are available, those streams will have to wait
	for a stream to become available. If not specified, the default value of
	<code>20</code> will be used.</p>
	</attribute>

	<attribute name="maxConcurrentStreams" required="false">
	<p>The controls the maximum number of active streams permitted for any one
	connection. If a client attempts to open more active streams than this
	limit, the stream will be reset with a <code>STREAM_REFUSED</code> error.
	If not specified, the default value of <code>200</code> will be used.</p>
	</attribute>

	<attribute name="maxHeaderCount" required="false">
	<p>The maximum number of headers in a request that is allowed by the
	container. A request that contains more headers than the specified limit
	will be rejected. A value of less than 0 means no limit.
	If not specified, a default of 100 is used.</p>
	</attribute>

	<attribute name="maxHeaderSize" required="false">
	<p>The maximum total size for all headers in a request that is allowed by
	the container. Total size for a header is calculated as the uncompressed
	size of the header name in bytes, plus the uncompressed size of the header
	value in bytes plus an HTTP/2 overhead of 3 bytes per header. A request
	that contains a set of headers that requires more than the specified limit
	will be rejected. A value of less than 0 means no limit. If not specified,
	a default of 8192 is used.</p>
	</attribute>

	<attribute name="maxTrailerCount" required="false">
	<p>The maximum number of trailer headers in a request that is allowed by
	the container. A request that contains more trailer headers than the
	specified limit will be rejected. A value of less than 0 means no limit.
	If not specified, a default of 100 is used.</p>
	</attribute>

	<attribute name="maxTrailerSize" required="false">
	<p>The maximum total size for all trailer headers in a request that is
	allowed by the container. Total size for a header is calculated as the
	uncompressed size of the header name in bytes, plus the uncompressed size
	of the header value in bytes plus an HTTP/2 overhead of 3 bytes per
	header. A request that contains a set of trailer headers that requires
	more than the specified limit will be rejected. A value of less than 0
	means no limit. If not specified, a default of 8192 is used.</p>
	</attribute>

	<attribute name="noCompressionUserAgents" required="false">
	<p>The value is a regular expression (using <code>java.util.regex</code>)
	matching the <code>user-agent</code> header of HTTP clients for which
	compression should not be used,
	because these clients, although they do advertise support for the
	feature, have a broken implementation.
	The default value is an empty String (regexp matching disabled).</p>
	</attribute>

	<attribute name="overheadCountFactor" required="false">
	<p>The factor to apply when counting overhead frames to determine if a
	connection has too high an overhead and should be closed. The overhead
	count starts at <code>-10</code>. The count is decreased for each
	data frame sent or received and each headers frame received. The count is
	increased by the <code>overheadCountFactor</code>for each setting
	received, priority frame received and ping received. If the overhead count
	exceeds zero, the connection is closed. A value of less than
	<code>1</code> disables this protection. In normal usage a value of
	<code>3</code> or more will close the connection before any streams can
	complete. If not specified, a default value of <code>1</code> will be
	used.</p>
	</attribute>

	<attribute name="readTimeout" required="false">
	<p>The time, in milliseconds, that Tomcat will wait for additional data
	when a partial HTTP/2 frame has been received. Negative values will be
	treated as an infinite timeout. If not specified, a default value of
	<code>5000</code> will be used.</p>
	</attribute>

	<attribute name="streamReadTimeout" required="false">
	<p>The time, in milliseconds, that Tomcat will wait for additional data
	frames to arrive for the stream when an application is performing a
	blocking I/O read and additional data is required. Negative values will be
	treated as an infinite timeout. If not specified, a default value of
	<code>20000</code> will be used.</p>
	</attribute>

	<attribute name="streamWriteTimeout" required="false">
	<p>The time, in milliseconds, that Tomcat will wait for additional window
	update frames to arrive for the stream and/or conenction when an
	application is performing a blocking I/O write and the stream and/or
	connection flow control window is too small for the write to complete.
	Negative values will be treated as an infinite timeout. If not specified,
	a default value of <code>20000</code> will be used.</p>
	</attribute>

	<attribute name="useSendfile" required="false">
	<p>Use this boolean attribute to enable or disable sendfile capability.
	The default value is <code>true</code>.</p>
	</attribute>

	<attribute name="writeTimeout" required="false">
	<p>The time, in milliseconds, that Tomcat will wait to write additional
	data when an HTTP/2 frame has been partially written. Negative values will
	be treated as an infinite timeout. If not specified, a default value of
	<code>5000</code> will be used.</p>
	</attribute>

	</attributes>

	<p>The HTTP/2 upgrade protocol will also inherit the following limits from the
	<a href="http.html">HTTP Connector</a> it is nested with:</p>

	<ul>
	<li>maxCookieCount</li>
	<li>maxParameterCount</li>
	<li>maxPostSize</li>
	<li>maxSavePostSize</li>
	</ul>

	</subsection>

	</section>

	<section name="Nested Components">

	<p>This component does not support any nested components.</p>

	</section>


	<section name="Special Features">

	<p>This component does not support any special features.</p>

	</section>

	</body>

	</document>